The functions in this chapter provide access to the Netware broadcast message system. With the utility SEND, Netware allows you to send messages between workstations. The NNETSN() functions of CA-Clipper Tools make it possible to send messages from within a CA-Clipper application.

Each Netware user knows the problem of getting a message during a running application: the application is usually interrupted when a message is received. CA-Clipper Tools provide two possibilities to solve this problem: suppressing incoming messages with the NNETBRDCST() function (corresponding to the Novell utility CASTOFF) or using the CA-Clipper Tools broadcast system. The broadcast system allows you to receive messages in the background and read the messages later from the broadcast buffer.

The functions of this chapter allow the start and termination of capture processes from within a CA-Clipper application. Additionally, the most important parameters for a capture process can be set.

The Print Job Definition chapter can be substituted for these functions. When working with print job definitions you do not have to worry about the settings of capture processes. You only have to activate a print job definition that can be created and maintained with the Novell utility PRINTCON.EXE.

This chapter provides functions that return information about the connection between workstations and file servers and allow you to set up or terminate connections. Even the login of a user from within a CA-Clipper application is possible. With the functions in this chapter, you can create a list of file servers within the internal network and all attached file servers, and you can determine the network address of a workstation.

Important! The term "attach" in conjunction with CA-Clipper Tools only describes the setup of a logical connection between a workstation and a file server and does not include a login, as is the case with the Novell utility ATTACH.EXE.

This section contains functions that make many date computations easier to perform. Date-type values have been a feature of the xBASE language standard, and is preserved in CA-Clipper. In spite of this, it is always necessary to develop UDFs to execute certain technical financial computations. CA-Clipper Tools offers an alternative that not only spares you the work of writing a UDF, but also provides implementation in Assembler to guarantee fast execution.

This chapter also contains clock time functions. These include time changes, time span computations, time control of loops, and memory- resident clock display.

Please note that valid date tests are already carried out in CA-Clipper. CA-Clipper internal date tests cannot be canceled, so it is impossible to implement an individual UDF for error handling , if there is an invalid date.

CA-Clipper always replaces an invalid date with a null date. These internal tests are carried out by keyboard input, as well as by CToD() allocation. For this reason, there are no examples with invalid dates in the date function descriptions. Rather, the result of a function with a null date is shown.

Fundamental to the disk functions

Fault tolerance and more

One of the biggest problems in stable application development is how to handle errors. Errors that occur during hard or floppy disk operations are especially frustrating. You may also encounter critical errors, which disable the program or operating system. The result, known to all CA-Clipper programmers, are the DOS error choices: (A)bort, (R)etry, (I)gnore.

Avoiding Errors

Error trap functions allow you to react to this type of error, but a strategy to avoid them completely is better. Therefore, CA-Clipper Tools includes functions to make it easier to handle floppy and hard disk errors.

Backup Systems

Backup systems, another component of the CA-Clipper application, are also discussed in this chapter. The recursive FileSeek() system, which allows you to format disks with DISKFORMAT(), is particularly useful. Complete directories can be scanned recursively, and queries regarding detailed information for every file can be made. The ideal time to carry out this process is during source and target drive back ups, because only the information that has changed is copied.

To avoid the annoying and not particularly fault-tolerant "RUN FORMAT", you can format the file disks directly from the application in all commonly available formats. Since the control UDF for DISKFORMAT() uses a concept similar to dbEdit(), you can display the format procedures on the screen as desired.

You can also determine a good deal of varied information about disk drives, files, and other things. This information far exceeds that of the FileSeek() system.

File Attributes

Following is the coding for each function where a file can be designated:

Table 1:

If multiple attributes are implemented for a file, then the table values are added accordingly. For example, if the HIDDEN and SYSTEM attributes are implemented, the function must pass a 6 (2 + 4) as the attribute mask.

All file attributes do not behave the same. To initiate a file into the process, you must explicitly specify the HIDDEN, SYSTEM, VOLUME and DIR attributes. However, if either no attribute, R/O, or ARCHIVE is implemented with a file, it does not matter which value is passed. These rules for attribute handling are grounded in DOS, which compares the specified value with the actual file attributes in this way. Since in some circumstances this may lead to problems, the FileSeek() function allows you to switch on an additional EXACT ATTRIBUTE MATCHING.

Share Modes

For DOS version 3.0 or higher, if a function uses the DOS OPEN FILE call internally, it must pass a share mode. This way, one station determines how all other stations in the network can access the open file. This is valid for as long as the file remains open. The following variations exist:

Table 3: Share Mode

With the basic setting, all files are opened in the compatibility mode (relating to older DOS). As a rule, the share mode depends on file attributes or the network software setting.

Also in this chapter is the SETSHARE() function, which determines the share mode that enables all CA-Clipper Tools functions to open a file. CA-Clipper commands or functions are not affected in any way.

CSetSafety()

Use the CSetSafety() function as a safety switch to protect existing files from unwanted overwriting during file operations with CA-Clipper Tools functions. You will find this function in the chapter on Switches and Status Information, since it concerns all CA-Clipper Tools file operations.

The functions in this chapter let you manipulate the drive mapping of workstations. New mappings can be executed, and existing mappings can be deleted. Furthermore, you can query information about current mappings. The basic function of this group of functions is NNETMAP(). NNETMAP() is used to create or delete an allocation. All extended possibilities, such as search drives and fake roots, are supported. Drive mappings can be defined temporarily. Temporary mappings are deleted automatically at the end of an application.

In conjunction with the ability to log in a user with NNETLOGIN(), the functions of this chapter allow you to set up the complete network environment of a workstation within an application.

In addition to supporting the window functions, the CTUS.LIB extended driver contains a series of independent functions, all of which are described in this chapter.

We are concerned here with functions that relate directly to CA-Clipper keyboard input, screen and printer output, or other internal functions. To use these internal functions, the driver must be linked in. The use of CTUS.LIB does not mean that all the code for all the functions contained in CTUS.LIB is linked to your application. An intensive modularization effort causes RTLINK to link only those portions that are actually needed.

b>The Use of CTUS.LIB

The extended driver is delivered as an .OBJ file (CTUS.OBJ) to allow replacement of the CA-Clipper driver module in CLIPPER.LIB during linking. The extended driver must be included in the list of object files.

b>Video Modes

Some functions which relate to screen adapters are found in the Video Modes chapter rather than in the Video Functions chapter.

b>Changing Modes

Some settings are reset by a mode change:

Cursor position to: Line 0, Column 0

Screen page 0: SETPAGE()

All font information: SetFont(), FONTLOAD(), FONTSELECT()

All palette information: EGAPALETTE(), VGAPalette()

Border settings: SET COLOR TO

b>DSETWINDOW()/External Screen Output

This is a very important switch for CA-Clipper Tools that impacts many functions and other modules. DSETWINDOW() determines whether or not the output of external programs or modules is redirected to a window. (CA-Clipper Tools functions are considered "external").

The default setting for this switch (.T.) redirects the output. To make this possible, the driver changes the interrupt vector 10H. Under certain circumstances external programs will not accept changes in particular interrupt vectors, which is why you must call DSETWINDOW(.F.) before you call the RUN function.

Certain other functions, like ISANSI() or NUMCOL(), return false or differing values in conjunction with DSETWINDOW(). Pay attention to the accompanying notes in the function descriptions.

b>System Settings Are Saved

When you end an application under CA-Clipper's control (normal program termination, Alt-C, or ending after a CA-Clipper error message), the cursor type, color attribute, and interrupt vectors 0 to 127 are restored.

However, if you exit a program in any other way (usually with an external module containing errors) then the extended driver system settings cannot be restored. Previously changed interrupt vectors are probably still changed, which sooner or later result in a system crash. If this occurs, reboot as soon as possible.

b>The QUIT File

A QUIT file can be added to any of the extended driver functions. The QUIT file provides information at the next program start as to whether the previous run ended correctly. Additionally, the user's keyboard input is also recorded.

The default name for this file is the same name as your CA-Clipper program except that it has a .Q extension instead of a .EXE extension. However, you can select another name for the file. For more information, please see DSETQFILE(), DSETQNAME() and KEYREAD().

This chapter includes network functions for IBM PC LAN/Microsoft MS-NET software.

b>PC LAN/MS-NET

PC LAN/MS-NET is software that has been offered for networks by IBM and Microsoft. Both programs are based upon the NETBIOS protocol; CA-Clipper does not directly affect the NETBIOS protocol. All internal function calls to the network software occur under DOS, which requires version 3.1 or higher. The functions in this group are in the format NETXXX().

An exception is the NetDisk() function. It can also determine whether a drive is local or remote under other network software. This assumes that the network software properly supports DOS in the background.

CA-Clipper enables you to program nested GET/READ masks. The functions in this chapter are retained in CA-Clipper Tools for compatibility reasons and to make them easy to use.

The active GET is saved with the help of a character string and restored through this string later. This allows you to newly query inputs without losing your main input mask. You can save KEYTRAP() definitions the same way and redefine them as you wish.

Important! It is impossible to use the saved information any longer that the runtime of an application. The character string that results cannot be saved to a file and reloaded later.

Other functions in this chapter return information about GET fields, such as screen position, the names of the accompanying variables, or information about whether a field is currently active.

Requirements

CA-Clipper Tools was designed for use with the CA-Clipper compiler. Therefore it should only be used on IBM PC/XTs, PC/ATs, or completely compatible systems. The screen functions may not work on a system where a modified CA-Clipper driver module has been used. (The string functions, on the other hand, are generally hardware independent.)

CA-Clipper Tools requires PC-DOS or MS-DOS, version 2.10 or higher, but some functions work with system calls which are not supported until PC/MS-DOS version 3.1 or higher. This applies, for example, to network functions: if you work with network functions under a DOS version earlier than 3.1, the functions will not work properly.

We cannot guarantee that CA-Clipper Tools will work under any operating system other than PC-DOS or MS-DOS.

Installation Program

CA-Clipper Tools is supplied with an installation program, located on Disk 1. To install CA-Clipper Tools, perform the following steps:

■ Insert Disk 1 in drive A

■ Type A: and press Return to change the default drive to A

■ Type INSTALL and press Return to start the installation

procedure

The installation procedure is self-explanatory. You will be prompted to insert other disks as the installation program needs them. (Some of the files are compressed; therefore you cannot use the DOS COPY command to copy them to your hard disk. You must use the installation program.)

When the installation is complete, read the READ.ME file (located on disk 1) to learn about any last minute changes or enhancements.

Compatibility

CA-Clipper Tools is generally compatible with previous versions, but there are some deviations. If you require full compatibility for existing applications developed under CA-Clipper S'87, you must link in the #include file ct.ch. Notice, however, that we do not recommend this procedure for development of new applications.

As CA-Clipper develops, some of the functions in previous versions of the CA-Clipper Tools program are no longer meaningful. These functions remain unchanged in CA-Clipper Tools to avoid problems during the compilation of existing applications, but they have been flagged with asterisks (*) at the function name. Again, we do not recommend that you use these functions to develop new applications.

Documentation

All of the CA-Clipper Tools functions are described in detail in this four-volume Reference Guide. To allow you to find the function you need in a particular situation, the Reference Guide is divided into chapters. Each chapter presents a group of functions that serve a particular purpose, such as date functions, database functions, or system functions. Each function is then described in detail on a separate page. Appendixes provide keyboard tables, DOS error codes, and Novell network error codes.

A Quick Reference Guide gives the complete syntax and a short description of every function. In this booklet, the functions are organized in alphabetical order for quick reference. A chapter and page number tells you where to look in this four-volume Reference Guide for a complete description of the function.

The CA-Clipper Tools software contains a text retrieval system that lets you search online for the expression you need. This text retrieval system finds the appropriate function for your purpose in seconds — even if you don't know what that function is — and provides complete documentation on that function online.

CA-Clipper Tools contains over 800 functions which you can use to develop CA-Clipper applications and system-level routines. These functions give CA-Clipper programmers capabilities previously reserved for C or Assembler programmers with detailed system knowledge.

In order to use working memory as economically as possible, virtually all the functions are written in Assembler and are highly optimized. This guarantees high speed with a minimal use of memory. This efficiency is further supported by the modularity of the software within the CA-Clipper Tools library.

Each Netware file server maintains a database of users and resources available on the network. This special-purpose database is called the bindery. The bindery contains objects uniquely specified by an object name and an object type. Possible object types are: users, user groups, print queues, or print servers. Each object has associated with it a number of properties that can be addressed with names and contain information about the object. For example, the property GROUPS_I'M_IN contains a list of user groups of which a user is a member.

The functions of this chapter allow a low level access to the bindery. This provides you with maximum flexibility for programming within Novell. The low level functions allow the creation of your own bindery objects as well as the development of bindery analyzers.

However, even though the bindery concept has a high security level, incorrect use of the low level bindery functions can be very dangerous if you have supervisor or equivalent access rights. The network could be brought to a standstill. You should use these functions only with extensive knowledge of the bindery concept, the Novell API, and bindery management. For example, you must know the terms object, item, and set property.

For frequent, complex purposes that require bindery access, like adding a user to a group, CA-Clipper Tools provides high level functions that can be used without a problem. These functions are based on the low level functions and are available in CA-Clipper source code.

Netware internally uses a high low sequence to store numeric values, which is contrary to the standard format of the 80x86 processor family (low high sequence). For efficiency reasons, the Netware functions of CA-Clipper Tools expect numeric values that are passed to Netware (object types or object IDs) in the high low sequence. However, this will not affect the practical work with the CA-Clipper Tools because symbolic constants are defined in the high-low format in the header file CTNNET.CH for the most important object types.

This chapter offers an array of interesting mathematical functions to implement in CA-Clipper. It includes trigonometric functions, finance- oriented math computations, and functions to determine the factorial, sign, or the next-largest integer of a value.

SetPrec() is important for trigonometric functions. With this function you can specify the precision as a number of places to the right of the decimal. However, if it is less accurate, the speed is greater.

Functions that do not belong in any other module are assembled in this group under the Miscellaneous heading. However, this does not imply they are less useful. For example, use KeyTime() or KeySec() to activate a CA-Clipper procedure at a specific time, after a delay of seconds, implement file saves, or control demo programs.

This module enables you to determine complements, determine data types, and query keyboard scan codes.

b>Passing Parameters by Reference

Finally, this chapter discusses functions that permit you to pass parameters by reference. To find more information on this subject, see Chapter 4, String Manipulations.

Number and Bit Manipulation

This module discusses number and bit manipulation. Specifically, the numeric section deals with conversions between two different number systems, and the creation of random numbers.

The bit manipulation section covers such required binary operations as AND, OR, XOR, and NOT, and how to test, set and clear bits. The NumLow() and NumHigh() functions are important for CA-Clipper Tools functions that take two 8-bit values and return them as combined 16-bit numbers. An example is the GETCURSOR() function from the Extended Drivers module.

Many of the functions in this module have a value parameter type. In this case, a number can be in the range of 0 to 65535 (or 4 294 967 295) and/or a hexadecimal string in the range of "0000" to "FFFF" (or "FFFFFFFF").

Despite the many capabilities of CA-Clipper Tools, there are times when direct port or memory access is needed. The functions in this chapter serve this purpose. For example, you can read memory regions by byte, word, or as a string through the PEEK function. POKE functions enable you to write a byte or word to working memory, but not a string.

Warning! POKE functions can be very dangerous. If you write to the wrong area in memory it can cause a lot of problems you may not foresee. Use POKE functions ONLY if you have extensive system knowledge.

This also applies to all the IN/OUT functions in this chapter, which allow you to directly manipulate a port. For example, if you address a disk controller improperly, the result may lead to data loss.

Point-To-Point Communication

The CA-Clipper Tools contain functions that allow direct communication between workstations in Novell or NetBIOS compatible networks by bypassing the file server. This type of communication is called Point- To-Point communication.

The data exchange between two workstations is interrupt controlled. Incoming data is copied in the background to a receiving buffer and can then be read with CA-Clipper Tools functions. As soon as the receiving buffer is full, incoming data is discarded. Outgoing data is copied to a sending buffer. While the CA-Clipper application continues, data is sent in the background from the sending buffer to the target address. Interrupt controlled sending of data is necessary to avoid a long wait when you send large datasets. When you use IPX/SPX communication or one of two possible NetBIOS communication variants, the data is broken up into packets internally. The packet size depends on the protocol used (IPX: 546 bytes, SPX: 534 bytes, NetBIOS: 512 bytes). The packets are sent sequentially.

Normally, the packet structure of the transmitted data is transparent and does not affect the handling of the data. The receiving buffer of the target workstation receives the data in the same way that the data has been written to the sending buffer. When you use IPX/SPX protocols in addition to the data, a header that is included in each IPX or SPX packet can be transmitted to the receiving buffer. This header makes a number of packet specific functions possible. The tables 31.1 and 31.2 describe the structure of the IPX and SPX header. The header positions start with 1, corresponding to string functions.

The NetBIOS communication variants have no similar mechanism available.

Table 31.1: IPX Packet Header

Table 31.2: SPX Packet Header

When you install a communication buffer (a communication buffer can contain a sending and a receiving buffer), you receive a communication handle as a return value. You should store this handle in a variable as it is absolutely necessary for further operations with the communication buffer.

The functions for Point-To-Point communication fall into two groups: protocol specific functions and functions that can be used for any kind of communication buffer. Protocol specific functions are functions for a connection setup: (IPXOPEN(), SPXESTBCON(), SPXLISTCON(), NBDOPEN(), NBSCALL(), and NBSLISTCON()). The name of a protocol specific function always starts with three characters that describe the respective protocol (IPX, SPX, NBD: NetBIOS Datagram, NBS: NetBIOS Session).

Functions that write or read a buffer, or query the buffer status, are not protocol specific and can be used for any kind of communication buffer. The names of these functions start with PPC (Point-To-Point Communication). For example, the function PPCWRITE() is used to write data to a communication buffer. The protocol specific process of the data is regulated internally.

IPX/SPX Communication

Novell Netware (including Netware Lite) allows the direct use of the IPX and SPX communication functions. By loading the Novell NetBIOS emulator (NETBIOS.EXE), you can also use NetBIOS communication functions in Novell networks. However, the use of the emulator compared to IPX/SPX reduces the performance and the available memory. Therefore, you should use the IPX/SPX communication functions for applications running only in Novell networks.

IPX (Internetwork Packet Exchange Protocol) is a rudimentary protocol whose main advantage is that data can be sent to all waiting workstations in an internal network with only one call. However, IPX has no suitable handshake mechanism available that guarantees a successful delivery and a correct process of the sent data on the destination workstation. (Related mechanisms can be implemented with the IPX functions of CA-Clipper Tools. However, these mechanisms are application specific and have no general validity.)

The SPX protocol (Sequenced Packet Exchange Protocol) only allows communication between two workstations within an internal network. SPX has mechanisms available that guarantee the successful delivery of sent data.

Unlike SPX, which can be seen as real Point-To-Point communication protocol, the IPX communication is implemented as a pseudo Point-To- Point communication. When you use IPX, data for a specific workstation can be received by any workstation. However, a destination address is defined for interrupt controlled sending. (This address can specify all workstations within an internal network.) The destination address is not defined by the protocol, so it is not necessary to specify the destination address each time you access the send buffer. When you use the SPX protocol, a connection between two workstations is established.

The IPX/SPX communication between two workstations is based on two sockets on each side of the connection that can be opened and closed, similar to files. Sockets are represented by numeric values between 1 and 65535. Some socket numbers are reserved either by the Netware operating system or by Novell for third party vendors. The sockets between 16384 and 20480 (4000h - 5000h) are the dynamic sockets, meaning there are no reserved sockets in this range. A collision with socket numbers reserved by Netware can be avoided by using sockets out of that range.

NetBIOS Communication

The NetBIOS communication functions can be used in all networks that are based on NetBIOS specifications. In CA-Clipper Tools, two kinds of NetBIOS communication have been implemented: NetBIOS datagram and NetBIOS session communication. The NetBIOS datagram communication can be compared to the IPX communication; a successful delivery of sent data on the destination workstation is not guaranteed by the protocol. Like IPX, the datagram connection can also be implemented as pseudo Point-To- Point communication between two workstations. Additionally, a workstation can communicate with a group of workstations or with all workstations in a network.

Like an SPX connection, a session connection is a fixed connection between two workstations. The dataflow between two workstations is supervised internally by a protocol that guarantees the delivery of sent data on the destination workstation.

For the communication with other workstations in a NetBIOS network, NetBIOS names are used. A NetBIOS name can be up to 15 characters long and is case sensitive. NetBIOS differentiates between two kinds of names: station names that specify a workstation and are unique in a network, and group names that can be assigned to any number of stations. Each workstation contains a local name table with up to 20 NetBIOS names. A workstation can be addressed with each name in the name table. Once you have defined single or group names, messages can be sent easily to a station or a group of stations.

Because of the importance of NetBIOS names for the Point-To-Point communication, CA-Clipper Tools not only includes functions for the sending and receiving of data, but also functions for creating and deleting NetBIOS names.

With the Novell utility PRINTCON.EXE, print job definitions that contain the settings for a capture process can be created. The functions in this chapter allow you to control the print job definitions of the current users and all other users on a file server. You can create new job definitions and query or modify settings in existing definitions. It is possible to read the settings of a job definition and to directly start a capture process (NNETPJCAPF()). This function call is equivalent to a call of the CAPTURE utility with the parameter /J=.

Important! Within the Netware documentation the term "job" is used to describe a print job within a queue and also a set of capture parameters (print job definition). Within this chapter the term "job" or "job definition" only describes the definition of capture parameters.

The functions in this chapter cover the entire area of print queue control under Netware. Print queues can be created or deleted. Users, operators, and print servers for a print queue can be defined or removed. The queue functions allow you to manipulate jobs within a queue. All settings for a print job can be queried or modified if the job is not currently processed (provided that you have sufficient access rights). Jobs can be deleted or moved within a queue.

Important! Within the Netware documentation the term "job" is used to describe a print job within a queue and also to describe a set of capture parameters (print job definition). Within this chapter the term "job" only describes a print job.

This chapter discusses printer output. Although CA-Clipper handles printer errors with an error trap, it is always better to avoid them completely. As a result, error traps for printer output will not become superfluous, since errors also occur during output. You can also determine a wide variety of information, such as the number of available printers or the printer status.

This chapter also describes functions that support DOS print spoolers. To implement these functions, prior to starting the respective application, you must run the DOS PRINT program to make the print spooler memory resident. Files can then be exclusively passed from a program to the spooler. However, you must first reroute your print output to a file (SET PRINTER TO file), before you can output it in the background.

A semaphore controls certain states: for example, the states between two applications that run on different workstations. To enable all stations to access existing semaphores, each Netware file server has a table available to manage these semaphores.

Semaphores can be interpreted as variables kept on the file server. Each semaphore is assigned a name when it is created. A semaphore name can be up to 127 characters long and is not case sensitive. An application can access a semaphore by opening the semaphore with its name (NNETSEMOPN()).

A semaphore can be opened by any number of workstations. For each workstation, the semaphore has the same value. The semaphore value cannot be modified; however, by using specific functions it can be incremented (NNETSEMSNG()) or decrements (NNETSEMWAI()) by 1.

Each semaphore is assigned information in addition to the semaphore value. For each semaphore, the file server counts the number of stations currently accessing the semaphore. This information can be determined with the function NNETSEMOPC(). For example, a semaphore named after an application can be used to limit a resource to this application.

Semaphores are often used to implement logical lockings for any kind of resource. A semaphore is assigned to each resource. Before the resource is accessed, the application tries to decrement the semaphore's value by one (NNETSEMWAI()). If the resulting value is negative, the resource is locked by another station. When an application is finished using a semaphore's resource, the function NNETSEMSNG() must be called to increment the semaphore's value.

There are a number of ways that the serial port can be used. Modems, bar code readers, and many other devices deliver data over this port or are regulated by it. Although standards do exist, in the final analysis, the type of communication is different every time.

The functions in this chapter offer possibilities for data transmission and allow you to influence control signals. These functions do not support any particular protocol or any specific instrument. For a few expanded applications, like the XMODEM protocol, you should find sufficient information in the example programs for CA-Clipper Tools.

b>Port Parameters

All the parameters for the port, like baud rate, parity, file length, and stop bits, are fully adjustable. It is possible to change the settings for a port without closing it. In this way the transmission speed can be changed without losing the contents of the buffer or terminating an existing connection (DTR-signal).

b>Data Transmission

Using CA-Clipper Tools, you can use up to four serial ports simultaneously. You can create a sending and a receiving buffer of up to 64kB in size. The characters for the background transmission mode are placed in the sending buffer, while characters received through the port are stored using an interrupt handler. You can determine the number of characters in the receive buffer from your CA-Clipper program, and as many of the available characters as you like can be read. Additional special control functions exist for the sending buffer that give the governing program full control. It is also possible to engage a software or hardware handshake that is performed completely in the background.

b>Handshake

As previously mentioned, CA-Clipper Tools functions support both a hardware and software handshake. As soon as the receiving buffer threatens to overflow by at least one page, a special handshake character is transmitted that tells the other side that no further data should be transmitted. Whether you implement the hardware or software handshake depends upon the type of data transmission. Hardware handshakes use physical port controls. These port controls are usually RTS and CTS, so within the scope of CA-Clipper Tools functions, these control ports cannot be used for modem transmission. Modems are generally not able to reproduce port controls directly over the transmission route (i.e. telephone connection). A software handshake must be implemented in such cases.

A software handshake uses characters from the ASCII character set to control the data flow. The ASCII character set is a standard which defines the XOFF (stop data, transmission off) as Chr(19) and the XON (continue transmission, transmission on) as Chr(17). (You will recognize the similarity to your keyboard since Chr(19) corresponds to Ctrl-S, and Chr(17) corresponds to Ctrl-Q).

If one of the handshake processes is implemented, the software must test both sides to see if the receiving buffer has been filled. The software then either deactivates the CTS controls or sends an XOFF character. By contrast, when sending data you must constantly test to see if the RTS input from the remote station has been deactivated or if an XOFF character has been received. In both cases transmission must stop immediately.

Since you can never be sure if the remote stations stop immediately after receiving an XOFF character, the internal handshake becomes active when the buffer is 75% full. If the remote stations ignore the handshake, the 75% limit is probably insufficient at a set buffer size of 100 byte (which equals a 25 byte reserve).

The techniques described here for the handshake are managed completely by the CA-Clipper Tools routines. They do not concern themselves with the interface cards or the Universal Asynchronous Receiver Transmitters (UARTS). It is sufficient to activate the selected method, which allows your program to regulate the status of the sending and receiving buffers on an ongoing basis.

b>Protocols

As previously mentioned, remote data transmission is, as a rule, implemented only through a software handshake. A significant disadvantage to this method is that the characters used for flow control, CHR (19) and Chr(17) can no longer appear in the original data. Because these characters appear in binary files, remote data transmission is not possible — transmission protocols must be used. You find XMODEM routines written in CA-Clipper in the example programs. Using the CA-Clipper Tools port functions and this example as a basis, other protocols can be developed fairly simply.

Firm protocols are not provided within CA-Clipper Tools because their realization in CA-Clipper code presents no real advantage. It is more important that you have the ability to create your own protocols so that you are not locked into whatever protocol is within CA-Clipper Tools.

b>Control Signals

You can set or query all important port connector control signals, like CD (carrier detect), DTR (data terminal ready), etc.. To simplify your programming, there is a separate function for each signal. For all other status and control information, which is seldom required in serial communications, you can read or describe the corresponding UARTS register of the port directly.

b>Direct Hardware Access

All CA-Clipper Tools port functions directly address the hardware. Working over BIOS or even DOS calls would be impractical or even impossible. We therefore presuppose 100% hardware compatibility with the established IBM personal computer industry standard.

In order to guarantee that everything is functioning properly, both ports must be equipped with either UART 8250 or the compatible 16450. When you use the 8250, interrupt controlled transmission is only possible up to 2400 baud. Technical details regarding the ports and the UART registers can be found in the corresponding technical instructions, like the IBM Technical Reference Manuals.

b>I/O Addresses and Interrupt Requests

CA-Clipper Tools assumes the following basic settings for the four ports:

Table 1: Standard Port Settings

In contrast to COM1 and COM2, the I/O addresses and IRQs for other ports are often different. If you want to use hardware that is not entirely compatible, CA-Clipper Tools has additional functions that you can use: com_SetIO() and com_SetIRQ(). When you use these functions, the I/O and IRQ settings for the port routines can be changed to the selected values. However, please notice that incorrect settings can have a wide range of consequences when they come in conflict with other hardware. These consequences include data loss or damage to hardware.

The correct settings for your hardware can be found at any given time in its accompanying documentation.

b>Possible Hardware Conflicts

CA-Clipper Tools recognizes the four addresses mentioned above for the ports COM1 to COM4. The com_Num() function uses these addresses to determine the number of available ports. For example, if the PC has a built-in ArcNet adapter, you can have a conflict between the I/O addresses. The CA-Clipper Tools routine addresses 02EAh, which is defined totally differently for the ArcNet adapter than for a serial interface. In this case an existing network connection would probably be disconnected. The com_SetIO() function can provide assistance by designating the second parameter as 0:

com_SetIO(port,0)

The corresponding standard address within the internal address table is deleted and access to other hardware is avoided. However, this is only possible if the com_Num() function has not previously been called within the program. (In this case the interface would have already been marked "in use.")

b>Important Notes

As the table of default settings indicates, it is possible for multiple ports to use the same IRQ — a procedure known as interrupt sharing.

While CA-Clipper Tools functions support these procedures, standard port hardware usually does not. Specialized multiple port cards are available from different manufacturers for this purpose.

Generally we cannot guarantee that interrupt sharing can be implemented.

CA-Clipper Tools supports up to four ports, each with sending and receiving buffers of up to 64kB and speed of up to 19200 baud. This is not to say that all this could be used at the same time to its highest limit. Eight buffers at 64kB are not possible. The buffers must be in conventional memory because the buffers are handled by interrupt routines. The number of ports and the speed with which they can function correctly is dependent upon the computer being used.

b>Differences from BASIC

In contrast to other programming languages (like BASIC), com_Open()/com_Init() do not influence control signals. If you want to address a modem over the serial port using CA-Clipper, you must set DTR and any other signals yourself, using the corresponding CA-Clipper Tools functions.

In this chapter, the group of functions determine the switch status and were implemented in the CA-Clipper Tools (CA-Clipper Summer 1987 release). CA-Clipper implemented the Set() function, so that these settings can be determined, set, and saved with this version. Therefore, some functions in this chapter only exist to enable compatibility with existing programs. All the affected functions are flagged with an "*".

If the functions relate to the CA-Clipper switches (SET's), the function name is represented as follows: CSET + the first four characters of the switch name. For example, if the switch is named CONFIRM, then the function that corresponds is CSETCONF(). If the parameter is optional and unspecified, the function returns the current setting for its switch, without a status change. When called with parameters, the function sets the switch to the passed value and returns the prior status as a value. In this way, a function call can both change a switch and save the old status. The logical value .T. corresponds to the ON setting of a switch; .F. corresponds to OFF.

b>Example

In the following example, the CONFIRM switch was set to .F.:

lOldValue:= CSETCONF(.T.)

After execution, the old variable lOldValue has a value of .F.; while the CONFIRM switch is ON (.T.).

In addition to their usefulness with CA-Clipper switches, these functions determine an assortment of other status information. For example, you can determine the current status of the debugger, set LASTKEY, and differentiate key traps. You can also determine the status of CAPS-LOCK, NUM-LOCK, INSERT, and SCROLL-LOCK.

There are an abundance of powerful string functions described in this chapter. A high degree of speed is assured because these functions and all of the CA-Clipper Tools are written exclusively in Assembler.

We have made an effort to find an appropriate example for as many unusual variations as possible. In view of this, we would like to take this opportunity to clarify a few ground rules regarding the use of these functions.

b>Passing Parameters by Reference

This chapter includes functions that pass parameters by reference. The following paragraphs contain clarification about these functions.

It has been possible to pass parameters of the character string type by reference to a UDF since the summer of 1987. This means that a reference to the original string is passed, thus avoiding the creation of an internal copy. When a function accepts this type of parameter and changes it, the original string is actually changed. This behavior does not normally apply to CA-Clipper functions. However, some CA-Clipper Tools functions behave differently and take parameters passed by reference. These functions and their corresponding parameters are described as reference sensitive in this section and are identified with [@] in the argument section of each function's description.

Passing parameters by reference has advantages and disadvantages. The most important advantage is that memory requirements are reduced. This allows you to avoid runtime errors that could result when there is insufficient memory available for string manipulation.

Whether or not the insufficient memory is a disadvantage depends on the function being used. Often you will want to change the original string. In a call that does not pass parameters by reference, the copy changed by the function must then be passed back to the "original" string again:

VAR := "Hello" VAR := FUNCTION(VAR)

When you work with very long strings, this method takes memory and time!

Here is an example of the reference method:

VAR := "Hello" FUNCTION(@VAR)

With most CA-Clipper Tools functions, it doesn't make any sense to pass parameters by reference. In some cases, a result is different when a parameter is passed in this way. However, when you do pass by reference, the functions change the parameters passed by the string directly. Memory is saved, and the functions work more quickly because you no longer need to make an internal copy. Watch for the [@] marker, indicating that a parameter is reference sensitive.

Functions which change the length of a string cannot, in principle pass by reference. Here is an overview of the functions that change length, or depending upon usage, could change if you attempt to pass by reference.

AtRepl() PosDel()

CharEven() PosIns()

CharOdd() PosRepl()

CharOne() WordOne()

CharOnly() WordOnly()

CharRem() WordToChar()

b>CSetRef()

This function additionally allows you to significantly optimize reference sensitive functions with regard to execution speed and memory use. Full details can be found in the corresponding function description later in this chapter.

Novell Transaction Tracking System (TTS)

This chapter provides functions for the use of the TTS within a CA-Clipper application. The use of the TTS within a CA-Clipper application requires more than start and termination or cancellation of a transaction with the related CA-Clipper Tools functions. With regard to the architecture, the application must be oriented to the specifics of TTS. The TTS takes into consideration only files managed on a server volume.

Transaction tracking occurs only on the files that have been marked as transactional. The transactional bit is an extended file attribute that can be set with the Novell utility FLAG.EXE or with the related CA-Clipper Tools function NNETEXTATT(). All files related to a .DBF file, (.NTX, .DBT) must also be marked as transactional.

The time between the start and the termination or cancellation of a transaction should be as short as possible. Avoid direct entries into database fields. Use memory variables for data input and then update the database within a transaction.

The reason for minimizing the transaction time is a characteristic of the Netware operating system that cannot be influenced by the application. When data in a file is modified, Netware physically locks the affected file area. In contrast to a logical locking with RLock(), the affected data cannot be read as long as the transaction is incomplete. If the transaction has been terminated successfully, the database record is updated. If the transaction has been interrupted, the record is reset to the previous value. A successful read access by another workstation could lead to fatal logical errors. The physical lock is removed automatically after the transaction has been completed or canceled. If a workstation tries to access a physically locked area, CA-Clipper causes an ACCESS DENIED error message and evaluates the error block. Normally, this results in a branch into the error recovery routine. An error message box is displayed, and the user can cause a repetition of the operation that failed. The error message text can be adapted to the running transaction. However, the problem is that from the beginning the application is not able to determine whether the ACCESS DENIED error results from a running transaction or another error source. Therefore, an application using the TTS should have a mechanism available that allows it to determine if a transaction is active for a specified group of files or not. Using Netware semaphores, for example, allows you to check to see if a transaction is active, either during the error recovery or before a file is accessed.

The functions of the User and Group Management chapter are based exclusively upon low level bindery accesses and could be accomplished completely with the low level bindery functions. However, working with low level bindery functions can be dangerous (see the Introduction to the Low Level Bindery Access chapter). Therefore, CA-Clipper Tools provide a number of high level functions for the most common requirements of user and group management. The functions in this chapter allow you to add or remove users, or groups of users, to or from groups. Various lists can be created: established users or groups, currently logged in users, members of a group, or groups of which a user is a member. You can determine if a user is a member of a specified group. For example, this allows you to combine the availibility of menu options with Netware settings.

A number of functions in this chapter have been developed in CA-Clipper with the use of low level bindery functions. The source code for these functions can be found on the product disks and can be used as an example for the use of the low level bindery functions.

Programming

To use the CA-Clipper Tools functions in your programs, specify the CT.LIB library during the LINK procedure. If required, also specify the CTUS.OBJ Extended Driver file. (See the section called "Extended Driver" below.)

All CA-Clipper rules apply when calling functions. For example, a function's return must not be assigned to a variable.

Both types of calls are possible:

FUNCTION(par1, par2) Var=FUNCTION(par1, par2)

Linking

CA-Clipper Tools functions can be linked with MS-LINK (often referred to as the DOS linker) as well as with RTLink.

Here is an example using MS-LINK:

LINK Prog1+Prog2+CTUS,,,CT/SE:nnn /NOE

With the exception of small test programs, MS-LINK requires that a value be assigned to the /SE: switch. We cannot recommend an adequate value for nnn.

Here is an example using RTLink in FreeFormat mode:

RTLINK FIProg1,Prog2,CTUS LIB CT

RTLink also contains a positional mode. When using this mode, the link command has to be identical to that in MS-LINK. Further information regarding RTLink can be found in the CA-Clipper Programming and Utilities Guide.

PLL Files

CA-Clipper Tools cannot be implemented in conjunction with the BASE50.PLL file created at CA-Clipper installation. You can, however, create a new corresponding .PLL file with the linker script file CT.LNK included in CA-Clipper Tools. Use the following command:

RTLINK @CT

This will exchange a particular module from the CA-Clipper library as well as several I/O routines out of TERMINAL.LIB for others in CTUS.OBJ or CT.LIB. The new .PLL file is called CT.PLL. If a new .PLL file is not created, then the alternative I/O routines and therefore many of the CA-Clipper Tools functions will not work for all the programs generated via prelinking.

If the CT.PLL file has been created once, the link procedure can be called as follows:

RTLINK FI prog LIB CT PLL CT

The CTUS.OBJ Extended Driver must not be specified, since it is already in the .PLL file.

Further CA-Clipper Tools modules have not been included in this or other .LNK files, since prelinked modules are always loaded at program start and increase memory usage accordingly. Creation of a .PLL file in conjunction with other external libraries becomes an individual procedure. However, all CT.LIB modules can be prelinked. You simply need to include a public for the desired module by inserting the REFER command.

Here is an example. By inserting:

REFER COM_BREAK, ACOS

the _COM and _TRI3 modules (serial interfaces and trigonometric functions) will be prelinked. The names of the module and the publics can be determined with a library manager like MS-LIB.

CA-Clipper Libraries

None of the preceding examples mentions any of the files belonging to CA-Clipper itself. This is because, during compiling, CA-Clipper's default setting enters the names of its four libraries in the resulting .OBJ file. When you influence this procedure, for example by using the /r compiler switch, all the required libraries must be called explicitly at linking.

Static Overlays

Most functions or CA-Clipper Tools modules cannot be stored to a static overlay, as they contain interrupt service routines. They may not reside in an overlay. The functions affected are KeySec(), KeyTime(), ShowTime(), SHOWKEY(), PRINTSCR(), PRINTSCRX(), and SETTIC(), as well as serial interface functions that also work interrupt controlled.

The Extended Driver CTUS.OBJ may never be placed in an overlay, since it is needed by CA-Clipper for every input and output. Linking CTUS.OBJ in an overlay will result in a system crash immediately after the start of your application. Therefore, be aware that the overlay will always have to be loaded in order for the function to be available.

All CA-Clipper Tools functions can be called from an overlay. The program code for some functions, however, cannot be placed within an overlay.

Possible Linking Problems

When implementing CA-Clipper Tools in an existing application for the first time, the linker warning message "Duplicate Definitions" may occur. In this case, probably one of your own procedures or functions or a function from another library has a name that was also used by one of the CA-Clipper Tools functions. If the name of this other function or procedure cannot be changed, it must be specified as a separate .OBJ file. Otherwise CT.LIB must be designated as the last library.

Note, also, that an .OBJ file will always overwrite a library module with the same name, independent of its position in the LINK command line. Therefore, the CA-Clipper Tools Extended Driver is delivered as an .OBJ file.

Extended Driver

In addition to the CT.LIB library, you will find a separate .OBJ module on your disk called CTUS.OBJ. This is the CA-Clipper Tools Extended Driver. If this is linked in, it replaces the CA-Clipper library driver. Above all, the Extended Driver is important for the implementation of window functions, but it also offers other interesting possibilities. For this reason all the functions in the chapter on the Extended Driver in this Reference Guide form a part of this module.

The CTUS.OBJ must only be added to the .OBJ file list to be linked. The sequence is not important. The Extended Driver replaces the CA-Clipper library driver module, so storing out to an overlay is not possible. You will find further information in the Extended Driver chapter.

Debugging

Working with CA-Clipper Tools makes additional debugger features available. These features are also controlled via the CLIPPER environmental variable, by setting a switch DEBUG:n.

How Problems Arise

There are many possible screen modes, fonts, windows, and virtual screens, so various problems can arise. The debugger also uses windows, as you can see on the debugger Windows menu. To avoid a collision with the windows of your application, the debugger has an additional windowing system.

Working with One Screen

When working with one screen, the debugger must be able to switch between the application screen and its own screen. The contents of the application screen must be saved. This can happen in an area of the available memory or in a free screen page.

Using a screen page saves memory and offers better performance, but it takes a screen page of the application. This is, however, taken into account by CA-Clipper Tools. The MAXPAGE() function, for example, returns a reduced value. The default value for the application is screen page, which can be changed with the environmental variable.

Working with Two Screens

Working intensively with CA-Clipper Tools video functions and the debugger on one screen is difficult. For this situation, the debugger supports two screens. This is possible because the PC can operate two cards simultaneously, for example, a Hercules card and a VGA card. The application output always occurs on the screen from which it was started, while the debugger output is displayed on the other screen. This capability is set via the CLIPPER environmental variable, by specifying DEBUG:2.

DEBUG Values

The DEBUG: n switch can be set with a numeric value. Each individual bit has a certain meaning. At this time, only two bits are used:

Note: Particular switch combinations in the CLIPPER environmental variable can lead to problems. Please construct your environmental variable as follows:

SET CLIPPER=/Fnnn /Ennnn /DEBUG:2 /SWAPPATH:"path"

Reference Sensitive[@]

CA-Clipper can pass parameters of the character string type to a UDF by reference. This means that what is actually passed is a pointer to the original, thus avoiding the creation of an internal copy. When a function takes on this type of parameter and changes it, it is the original that is actually changed. Here is an example:

VAR := "Hello" MYFUNC(@VAR)

Passing of parameters by reference has advantages and disadvantages. An important advantage is that memory usage is reduced. This avoids runtime errors that result from not having enough memory for string manipulation. If, on the other hand, you do not want the original string to be changed, passing of parameters by reference is a disadvantage.

With a normal call (that is, not by reference), it is the copy that is changed by the function. The change must then be passed back to the original:

VAR := "Hello" VAR :+ MYFUNC(VAR)

Particularly in the case of long strings, this method takes up memory and time.

It is not a good idea to pass parameters by reference for most of the CA-Clipper Tools functions. (In some cases there will even be a difference in the result when a parameter is passed this way.) The functions then change the string passed as a parameter directly. This saves memory space and the functions work more quickly, since there are no internal copy procedures taking place. Watch for the [@] identifier meaning reference sensitive.

CSetRef()

This function allows you to further optimize memory requirements and speed for different string functions. This assumes that a function is only working with data passed as a parameter and avoids internal copies of returned values as well. When CSetRef() is set, the affected function no longer returns a value.

You will find more information on this function in the chapter on string functions.

Working With Video Functions

This module discusses video functions that are either directly or indirectly concerned with the screen. Included are all functions that deal with such screen adapters as CGA, EGA and Hercules. Different modes on various adapters are supported, such as a 40-column CGA, a 43- line EGA, or a 50-line VGA.

DSETWINDOW()

Many of the functions in this chapter depend on setting the DSETWINDOW() switch. This switch determines if the screen output of external programs, as well as DOS, are redirected to a window. CA-Clipper Tools output functions are also valid as external. If the default setting in DSETWINDOW() is .T. or on, this rerouting is carried out. Some functions will then return inaccurate, or at the very least, different results. Examples of this are ISANSI() or NUMCOL()

Attribute

Many of the functions in this module work with color attributes designated as parameters. These arguments are carried out in three different ways:

A numeric value, which corresponds to a combined color attribute (e.g., 7).

A string in the "NN/NN" form, with two specified numeric values (e.g., "7/0").

A string in the "CC/CC" form, with two specified attributes are designated in the form CA-Clipper requires (e.g., "W/N").

With many functions, the attribute returns a combined numeric value. Attributes for the foreground and background are tied together this way.

Color attributes are constructed as follows:

Bit 8 7 6 5 4 3 2 1 Attribute * R G B + R G B

_ _ _ _ _ _ / _ _ _ _ _ _

Background / Foreground

Each attribute consists of four bits, which represent a value in the range of 0 to 15. Therefore, there are a total of 16*16, or 256, different values from 0 to 255. These numeric values can be changed into the "nn/nn" format, that can be used under CA-Clipper with the NTOCOLOR function. However, it is possible to directly influence this combined attribute value. The following examples show this and relate back to the chapter on number and bit manipulation:

NumOr( nattr, 128) // Flashing on NumAnd(nattr, 127) // Flashing off NumXor(nattr, 128) // Change flashing NumOr(nattr, 8) // High intensity on NumAnd(nattr, 247) // High intensity off NumXor(nattr, 8) // Switch high intensity

Special Parameter Type

With many functions, a parameter may be of the mIcCharacter|nCharacter type (e.g., an individual character). This can occur in two different ways:

Numerically, as the ASCII code of the desired character (e.g., 7).

Alphanumeric as the character (e.g., ":").

Because of this, you must not use the Chr() function to change special characters.

CLEARA and CLEARB

Some of the CA-Clipper Tools functions use a standard attribute and character to delete lines or screen areas. This attribute is described as CLEARA; the character as CLEARB. You can query both CLEARA and CLEARB with the corresponding functions. At the same time, certain preset values are in effect for CLEARA and CLEARB. The attribute "W/N" is the standard preset for CLEARA, while Chr(255) is the character used for CLEARB. If you use this character for CLEARB, it fills the background with the corresponding color for every deletion on every screen adapter.

Use the following functions to set standard values for CLEARA and CLEARB:

GetClearA() SetClearA() GetClearB() SetClearB()

If you use the SETCLEARx() functions in conjunction with the corresponding parameters (Attribute or Character), the currently existing default value is replaced by a parameter.

Clipper Functions and Commands Which Delete

If you use the CA-Clipper Extended Drivers, Chr(255) is used instead of a space for all CA-Clipper functions and commands that delete the screen in one way or another (see CLEARB). A Chr(255) is helpful on many screen adapters, since in contrast to a space, you can assign it a color. Then, the screen will not appear so fuzzy.

More precisely, the functions and commands concerned always use the delete character set by SetClearB(), which uses Chr(255) as the default setting. If you want to use a space to clear in CA-Clipper or CA-Clipper Tools, insert a SetClearB(32) into the program.

Re-implement a space for clear:

SetClearB(32) CLEAR // The affected Clipper command

Video Modes

Occasionally, there is some confusion about video modes. You will not be able to work in EGA mode just because your computer has an EGA adapter built into it. By the same token, you will not get either EGA or VGA modes, if you do not work with graphics.

EGA43 / VGA50 / VGA28, etc.

In this section, the concern is not to just get a mode "hardwired"' into a card, but for CA-Clipper Tools it is to generate corresponding fonts and other settings. For these reasons, the GETMODE() and GETSCRMODE() functions generate their own values that are greater than 255.

For example, changes to the screen mode concerned with line count can be combined with a 40-column mode:

CGA40() EGA43() // 43 lines and 40 columns

Video Functions and Windows

You cannot implement functions that change the base address for screen memory while windows are open. This includes all mode changes, as well as SETPAGE and SETSCRSTR.

It is hard to imagine using CA-Clipper without using windows. Windows are the best way to show multiple tasks so you can get a genuine overview of the system operation. The functions in this chapter offer a particularly valuable extension to CA-Clipper in this area.

b>The Window System

If you are only working with one screen, the CA-Clipper Tools functions permit up to 255 windows, depending on available memory. In conjunction with the MONISWITCH() function from the Video Function chapter, CA-Clipper Tools can even support two screens linked to a single CPU, with one monochrome screen and one color screen. In this way two entirely independent window systems, each with 255 windows, are available.

The window functions take into account the fact that CA-Clipper Tools supports larger screens than the common 25 rows x 80 columns. A screen, and therefore also a window, can be up to 255 rows or 255 columns in size. However, the complete contents of a screen can never require more than 32 KB of memory. So with 255 rows, no more than 128 columns are possible.

b>Moving Interactively

As soon as SCROLL LOCK is activated, the active window can be moved with different cursor keys. Depending on how you open them, windows can even overlap. The gray Plus key in the numeric key pad works like the function WCenter(). You use the Plus key to move a partially visible window back into a completely visible area. All window movements done after you activate SCROLL LOCK can be undone using the ESC key.

b>Programming with Window Functions

■ Each window is assigned a number between 1 and 255 when it is

opened. This number is known as the window handle. Handle 0 is the original screen, with no open windows. The window handle returned will be used to refer to that window during programming. (For example, you need the window handle when you select a background window.)

WMode(.T., .T., .T., .T.) // Overlap permitted

nWindow1 := WOpen(....) nWindow2 := WOpen(....) // This is the active window

WSelect(nWindow1) // Activate first window

■ The coordinates used for screen output are relative only to

the selected window, and not the entire screen.

nWindow1 := WOpen(....) // Selected window

@ 02, 02 SAY "CA-Clipper Tools"

■ Since a window behaves exactly as the normal screen would,

QOut() style output (?, ??, etc.) will be scrolled up as soon as it reaches the bottom row.

■ The window in the following example, which extends to row 24,

will not overwrite the help message on row 25:

@ 24, 00 SAY "........ HELP-ROW........" nWindow1 := WOpen(0, 0, 23, 79) // Protects the last row FOR nI = 1 TO 100

? "CA-Clipper Tools ...."

NEXT nI

■ A window displays as a full value, but is a virtual screen,

which differs from the original physical screen only in size. Extended drivers make the MaxRow() and MaxCol() functions available in a version enhanced over and above CA-Clipper to accommodate the changed size. Now the coordinates of virtual screens can also be determined; these functions return the last row or column concerned with the currently selected window:

nWindow1 := WOpen(10, 10, 20, 60)

? MaxRow() // Row: 10 ? MaxCol() // Column: 50

■ The underlying screen area is saved automatically when a new

window is opened. This applies equally to any area of the screen that becomes overlapped by the movement of a window. At the same time, all settings in the areas that have been overwritten are saved. These settings include cursor shape and position, as well as color attributes. So you do not have to save anything out of the affected screen area; CA-Clipper Tools takes over this task automatically.

■ The following example shows you how the window functions save

both the color and cursor setting:

SET COLOR TO R // Set color RED ? "Test-Text 1 ..." // Output in RED nWindow1 := WOpen(10, 10, 20, 55) WBox() // RED window border

SET COLOR TO BG // Set color CYAN ? "Test-Text 2 ..." // Output in CYAN Inkey(0) // Wait for keystroke

WFCLOSE() // Close window again

? "Test-Text 3 ..." // Output again in RED

// and directly below "Text 1"

b>Active Windows

After you close a window, the active window with the highest handle is the one selected, not the window that was previously active. If, for example, the highest window handle is 9 and window 5 was just selected, a newly opened window is assigned handle 10. However, after you close this window number 10, window 9 is selected. It is therefore important to save the window's handle to a variable when you open it, so that you can select the required window later.

You can save the active window handle by calling WSelect() with no parameters.

■ The external output of programs called with RUN within a

CA-Clipper program can be tied to windows:

DSETWINDOW(.T.) nWindow1 := WOpen(10, 10, 22, 70) RUN DIR // Display results in window

The only prerequisite is that such output is through DOS or BIOS. The DSETWINDOW() function controls whether or not this output is subsequently redirected. The Extended Driver chapter has more details.

In addition to the examples shown here there are many more window functions available for use that contribute to a comprehensive windows system.

■ The precision of the result can be influenced by the SetPrec()

function.

This function is very useful when you call procedures using macros. When you use AddAscii(), the string representing the macro can be changed without needing to include functions like Left(), Right(), Asc(), or SubStr() (see example).

This function also allows you to subtract a value. However, a conversion is necessary. If a lower case letter is converted into an upper case letter, a value of 32 must be subtracted. This occurs according to the following formula:

Chr((Asc(Character) + 256 - Difference) % 256)

■ If the nPosition is greater than the length of cString or

less than 0, the string remains unchanged.

■ Zero changes the value of the last character.

■ CSetRef() can be used to suppress the returned value for this

function in order to save space in working memory.

Security

If CA-Clipper Tools functions that change interrupts are not properly uninstalled or if the Extended Driver is not implemented, you could use the INTSAVE.EXE and INTOFF.EXE programs as additional security.

INTSAVE

Drive:INTSAVE[/S|/R[FileName]]RETURN

INTSAVE saves all 256 interrupt vectors to a file called INSAVE.TAB. Alternatively, a different filename can be selected, if multiple applications need to access the same path in a network. A call with the /S switch saves the interrupt vectors,while a call with /R restores them.

If the program is called without parameters, it explains its operation on the screen and, if required, displays a list of interrupt vectors that have been changed.

INTOFF

Drive:INTOFF RETURN

This program represents an "emergency brake". It sets the vectors described below to an IRET in the system ROM, so that there is no danger of a system crash as a result of erroneous interrupt vectors. The mouse interrupt (033h) is also newly initialized and the timer tic rate is reset. Memory resident programs are uncoupled from their interrupt vectors as well and are thereby rendered unusable. The program sets the following interrupt vectors to harmless IRETs:

Both programs could be linked into a batch job which starts your CA-Clipper application. This would look as follows:

ECHO OFF INTSAVE /S INTSAVE1.TAB

CLIPPROG

INTSAVE /R INTSAVE1.TAB ECHO ON

With INTOFF, it would look like this:

ECHO OFF

CLIPPROG INTOFF

ECHO ON

This will avoid later system crashes.

This function finds the nth (nCounter) occurrence of cSearchFor within cString and returns the remainder of the string from the first position behind the located sequence.

In order to determine the nth (nCounter) occurrence of cSearchFor, AfterAtNum() searches from the left for each instance of this sequence. If CSetAtMupa() is off, then the search is continued after the last character of the sequence most recently found. Otherwise the search is continued after the first character of the sequence most recently found.

■ Implementing SetAtLike() allows you to use wild card

characters within cSearchFor.

■ If there is not enough room on the stack, AlloFree(.T.)

returns a value of -1.

■ This function does not take character position into account,

so it cannot determine a character transposition. The Checksum() function should be used to determine character transposition.

■ The returned value can be between 0 and 255.

■ If cString is a null string, or nPosition is larger than

the length of the string, AscPos() returns 0.

■ If nPosition is 0, the ASCII value for the last character is

returned.

■ The SetPrec() function can influence the precision of the

result.

The function first looks for the cSearchFor parameter within the character string. From this point, the rest of the cString is moved (adjusted) by either inserting or removing blanks until the nTargetPosition is reached. In lieu of blanks, nCharacter| cCharacter can be used as a fill character.

Additionally you can specify that the nth occurrence of cSearchFor be used and whether or not a specific number of characters at the beginning of the search string is eliminated.

■ Using CSetAtMupa() can influence how the search is performed.

Using SetAtLike() permits the use of wild cards within the search sequence.

■ The SetPrec() function can influence the precision of the

result.

AtNum() determines the initial position of the nth (nCounter) occurrence of cSearchFor within the cString. Additionally, the function takes into account the CSetAtMupa() setting, which causes differing results.

AtNum() searches from the left in order to determine the nth (nCounter) occurrence of the cSearchFor. If CSetAtMupa() is off, the search continues after the last character of the sequence most recently located. However, if the CSetAtMupa() is on, the search always continues after the first character in the most recently located sequence.

If the nIgnore parameter is not specified, the function initiates the search with the first character of cString. If the nIgnore parameter is specified, nIgnore characters are ignored from the start of the string and are excluded from the search.

■ If no value is specified for nCounter, the function

determines the last occurrence of the cSearchFor sequence.

■ When you implement SetAtLike(), wildcard characters can be

used within the search expression.

AtRepl() allows you to replace one or more sequences within cString. cReplace can be shorter or longer than cSearchFor.

nCounter specifies that the function searches for the nth occurrence of the sequence. If no value is specified, then the last occurrence is used. All occurrences of cSearchFor, up to and including the one sought, are replaced unless nCounter is assigned a value greater than 0 and lMode is designated .T..

The CSetAtMupa() setting is only checked when the length of cReplace is shorter than or equal to that of cSearchFor, yielding different results. Beginning on the left, the character string is searched for each occurrence of the cSearchFor sequence. If CSetAtMupa() is off (.F.), then the search continues after the last character of the replaced sequence. However, if CSetAtMupa() is on, the search always continues from the first character of the replaced sequence.

■ By implementing SetAtLike() you can use wildcard characters

within the search sequence.

■ cString can be passed by reference. If this is the case,

then both cSearchFor and cReplace must be the same length.

■ If cSearchFor and cReplace are identical, the function

terminates immediately. Such an exchange makes no sense, and if CSetAtMupa() is (.T.), the exchange results in an endless loop.

AtToken() allows you to determine the beginning position of a token in cString. This value can be extremely helpful when you work with other string functions. The function uses the following list of delimiters as a standard:

CHR 32, 0, 9, 10, 13, 26, 32, 138, 141

and the characters ,.;:!?/<<>>()^#&%+-*

This list can also be replaced with your own list of separators, cDelimiter. Here are some examples of useful delimiters:

Table 4-1: Recommended Delimiter Sequences

This function determines the beginning position of the nth (nCounter) occurrence of cSearchFor within cString and returns the string segment before this sequence. Additionally, the function takes into account the CSetAtMupa() setting, which can cause differing results.

In order to determine the nth (nCounter) occurrence of the cSearchFor, BeforAtNum() searches from the left for each instance of this sequence. If CSetAtMupa() is off, then the search continues after the last character of the sequence most recently found. If CSetAtMupa() is on, the search continues after the first character of the sequence most recently found.

■ Implementing SetAtLike() allows you to use wildcard characters

within the search sequence.

■ If lMode is designated as .T., the string length that

results always corresponds to cBitpattern.

■ Although unlikely, you may not find a date at this BIOS

position. Therefore, you should test to see if a date is returned.

Blank() clears desired data fields with the variables. Blank() returns the following results:

Table 13-1: Data Type Blank Values

The default for lMode is .F. and produces a null string when a character string is input. However, if this parameter is designated as .T.., the string length is not changed.

■ SET DATE has no affect on how Blank() handles a date. The

blank date display is created in the format you select.

■ You can suppress the value this function returns by

manipulating strings through CSetRef() implementation. To save room in the working memory, designate lMode as .T..

■ If no date is passed, then the function automatically uses the

system date. An empty date parameter always returns an empty date.

■ If you do not specify a date, the function automatically uses

the system date. An empty date parameter always returns an empty date.

■ If no date is specified, the function automatically uses the

system date. An empty date parameter always returns an empty date.

■ Close all files prior to a boot. You can use CLOSE DATABASES.

■ If there is a large system memory, a RAM check takes a long

time. To avoid this lengthy procedure, you might consider using the BOOTWARM() function for a restart after changing CONFIG.SYS.

■ Close all files before you boot. You can use CLOSE DATABASES

to do this.

■ BOOTWARM() is the same as pressing the Ctrl-Alt-Del keys.

The output of a break means that the transmission line of an interface is held at a specific level for a fixed period of time. This time can be selected as a numeric parameter between 1 and 65535 milliseconds.

As a rule, a break is usually between 100 and 350 milliseconds long.

■ If an attempt is made to read the number of characters

available in a closed port, the function returns a value of -1.

CYCLIC REDUNDANCY CHECK Many file transfer protocols use CRC for accurate error recognition. This CRC function offers you decisive help when programming your own protocols, like XMODEM or KERMIT.

The specific CRC value always depends on the polynomial that you use. This information can be passed as an optional parameter in the form of an integer so that the function has almost universal utility. The CRC 16 X.25 polynomial used in X.25 systems,. XMODEM is the default value used in the examples below.

A few examples of polynomials:

Table 3-1: The Different Polynomials

■ If nStart is not passed, then the loss of the previous

Chr(0) out of cString is not detected by a later CRC review. This can be avoided if nStart is given a starting value that is not equal to 0.

■ A function called XMoBlock() is available for building XMODEM

blocks.

com_DosCon() allows you to output a string through DOS. This function can be used to provide an interpretation of ANSI control sequences through ANSI.SYS. The installed status of the ANSI driver can be determined using the ISANSI() function.

In this way you can easily create a communications program with ANSI terminal emulation.

■ Notice that DSETWINDOW() should be switched off when using

this function. Otherwise the output is routed through the CA-Clipper driver module, and operates like a print (?) with a position instruction.

■ The com_Close() function resets DTR (to inactive). By

contrast, COM_OPEN does not automatically make DTR active!

■ The Line Status Register (LSR) setting is used to determine

whether or not characters were inaccurately received.

As a rule, it is necessary to determine the cause of a trap if a character is placed in the keyboard buffer and the procedure specified with SET KEY TO is called. The numeric parameter determines what information is accessed. The information returned for modes 1 to 5 are defined as follows:

Table 3-2: Query Codes for Event Information

■ With the exception of the error counter, all status

information is reset when you open the port or when you call com_Key() again.

■ The conditions of MSR and LSR are considered at each interrupt

and are linked to the respective status byte in the internal environment through a logical OR operation. It is therefore possible to place multiple bits in one of the registers.

■ Overrun errors, parity errors, and frame errors (bits 1 to 3)

are counted as errors exclusively.

Important! The input lines on conventional PC interface cards are normally not terminated. This can lead to inexplicable results when you query the MSR.

This function allows you to flush all the characters in a receiving buffer. This makes it unnecessary to tediously determine how many characters are currently in the buffer in order to remove them with a read procedure.

com_Flush() guarantees a truly empty buffer. However, a new character can be received between the time that you call a com_Count() and a com_Read().

■ The hardware handshake only supports background transmission

(when com_Open() is implemented with the third parameter nBufferOut).

■ This function works for data input as well as output.

■ If you use a hardware handshake, then the RTS signal should no

longer be affected by com_RTS() or com_MCR().

■ The port must have been opened previously. It is impossible

to initialize a port prior to opening it.

■ If any or all of the four operating parameters are not

designated, or are designated incorrectly, the standard arguments of 300 baud, no parity, eight data bits, and one stop bit is used.

com_Key() allows you to monitor a port while the program is in a READ. In this way, various events at the port can cause a particular key code, selected by the programmer, to be placed in the keyboard buffer. This happens when:

■ Data arrives at the port.

■ A transmission error or a BREAK is recognized in the LSR.

■ One of the signals in the MSR changes.

■ The receiving buffer becomes 75% or more full.

The MSR and LSR status, the number of errors that have already occurred, and the receipt of individual characters can be monitored through the nKeyValue1 key code. All information is saved in an internal memory area and can be queried from there using the com_Event() function. This procedure is important because the register or the flags that release the interrupt, are automatically reset during read access. Otherwise, the information is lost.

If the nKeyValue2 parameter is specified, then one more procedure can be specified using the SET KEY TO command when the receiving buffer is 75% or more full. If the nKeyValue2 parameter is specified, the nKeyValue1 key code is no longer placed in the keyboard buffer when characters are received. However, you can still monitor the MSR and LSR.

■ The status of the various interface registers are connected to

the internal memory for as long as the event is "serviced" by a new com_Key() function call. This means that the modifications made during this period cannot be lost.

■ COM_KEY must be newly activated after every executed trap.

This deletes information concerning the internal environment.

■ When com_Key() places a character into the buffer because the

buffer is close to full, it does so independently of the com_Soft() or com_Hard() functions.

The Line Status Register makes the following information available:

Table 3-3: LS Register Coding

■ The Line Status Register can only be examined using this

function.

■ Some bits in this register are reset by a read.

The Modem Control Register can be read only and/or read and set. The second optional parameter determines if a new value is set. The bits have the following meaning:

Table 3-4: MC Register Coding

■ The OUT1, OUT2, and LOOP control bits can only be changed

using this function. Additional functions are available for DTR and RTS.

Not all the values for this status register can be determined from separate functions. For example, if you need Delta status information, you can use this function and test the corresponding bit. The individual bits are defined as follows:

Table 3-5: MC-Register Coding

■ The simultaneous testing of multiple bits in the MSR is fairly

simple when using a logical AND operation.

■ All delta bits in this register are reset using a read

procedure.

This function returns the number of the serial interface port available. This is not to say that a return value of 3 necessarily means that ports 1 through 3 are available; for example, COM2 could be missing. Whether or not a serial port can actually be used can be tested using the com_Open() or com_Init() functions.

Normally the addresses described in the Introduction to this chapter are scanned for available ports. Scanning can happen over alternate addresses selected through com_SetIO().

Important! Four I/O addresses are assigned to ports COM1 - COM4, internal to the port functions. The com_Num() function goes through these four addresses and tests to see if a port is available there. This can lead to problems if some other hardware is installed in one of the address areas. For example, problems like this have been noted in conjunction with ArcNet network cards, which conflict in the address area with COM4. The critical address areas are listed in the table below.

Table 3-6: I/O Addresses for COM1-COM4

If any kind of hardware is found within this I/O address area, then the conflicting COM port can be masked. Additionally, using com_SetIO() (nComPort, 0) the accompanying base address within the internal table is deleted. You can only mask the conflicting port when com_Num() has not previously been called in the program. If com_Num() has been called in the program, the interface is marked "in use".

This function allows you to open a serial interface port from COM1 to COM4. These ports have particular I/O addresses. For example, CA-Clipper Tools uses 3F8H as a base address for COM1. DOS or BIOS routines are not even involved; I/O addresses are not read from the BIOS data area. The default values described in the Introduction to this chapter are applied, or the values are set using com_SetIO(). The availability of a port is tested for these addresses before the port is opened.

Receiving Data A buffer of up to 64 kByte can be reserved for each com port. All arriving characters are saved here, even when the CA-Clipper program is active elsewhere with another process. The number of characters in the buffer can be checked and partially read.

Sending Data You can also reserve a sending buffer. If you reserve a sending buffer, com_Send() controls the interrupt function for data transmission, which means that the interrupt occurs in the background. Several functions are available to control the send buffer.

Interrupts during Transmission Errors If lTrapMode is specified as .T., the UART port only triggers an interrupt when there is data incoming or interrupt driven data being sent. Events connected with the MSR or the LSR are no longer taken into account. This affects the status signal and particularly affects transmission errors.

This capability was added as the result of research that indicated that some adapter ports seemed to trigger interrupts for no reason. These interrupts are caused by "trash" on the lines; as a rule, serial port incoming lines were not terminated (electronically closed). Overflowing interrupts can disturb program execution and lead to significant loss of performance.

Important! In contrast to other programming languages, like Basic, com_Open() and com_Init() do not affect any control signals. If you want to address a modem at the serial interface through CA-Clipper, you must set the DTR and every other signal using the correct CA-Clipper Tools functions.

■ Buffer size can be between 100 bytes and 64 kByte. Settings

too large or too small are corrected, increased or decreased, accordingly.

■ To ensure compatibility with earlier versions of CA-Clipper

Tools, the nComPort, nBufferIn, and lTrapMode parameters can be used without nBufferOut (see the example).

■ Remember that you can receive additional characters between

calling com_Count() and com_Read().

When longer text is sent, the receiver should be able to break off the transmission session or to delete the sending buffer. To do this, a character can be defined as an external line termination character. If this character is received, it deletes the background buffer of the sending station, as if you had called com_SFlush(). The sending CA-Clipper program no longer concerns itself with this session.

com_SMode() can help you determine if the buffer of the remote station has been deleted.

■ Before a binary file transfer, an existing line termination

character should be canceled because the transmission could be terminated accidentally.

■ When TERI (Trailing edge ring) is required, use the com_MSR()

function.

■ The com_Close() function resets (deactivates) the RTS signal.

The com_Open() function does not automatically activate it!

■ If you attempt to determine the character count in a port that

is not open, the function returns a value of -1.

com_Send() transmits one or more characters from one of four ports. This transmission can be interrupt driven (i.e. occurs in the background). The third parameter of com_Open() determines whether or not the transmission is direct or occurs in the background.

"Normal" Transmission During "normal" transmission, program execution can continue only when all of the characters have been sent to the port. A unique situation presents itself when the hardware handshake is activated. As soon as the receiving station deactivates the CTS signal from the sending station, any transmission is immediately stopped. To prevent the CA-Clipper program from hanging, com_Send() is terminated and a numeric value representing the number of characters not yet sent is returned. com_CTS() can determine if CTS input has been deactivated by the remote station. The software handshake is not supported in this mode!

Background Transmission The background mode supports software and hardware handshakes. The handshake automatically occurs in the background. Several new functions are available to help you maintain control of the transmission buffer in this situation. For example, com_SMode() allows you to determine if the buffer is waiting for an XON character to release the software handshake. Since this kind of wait can prove futile, you can use com_Flush() from within the program to empty the transmission buffer.

■ The handshake is only supported when the transmission buffer

is sending in the background. Use small packets during direct transmissions, and regularly query com_Soft_R().

■ Software and hardware handshakes are switched on using the

com_Soft() and com_Hard() functions.

■ The function tests to see if there is a port available at the

selected I/O address. com_SetIO() returns .T. or .F. accordingly.

Unfortunately, there is not a binding standard for serial ports, particularly for COM3 and COM4.

Each interface card uses an interrupt request line to advise the interrupt controller that a character has been received. The controller then passes this information on to the CPU, which calls a service routine through the corresponding interrupt vector. XT systems have eight such interrupt lines available. AT systems have more than 16 available interrupt lines, some of which are usually occupied with other peripherals. The allocation of a new IRQ is no small matter and requires considerable technical expertise. Determining which IRQ is available and is not currently in use can usually be done by studying the configuration of all external devices and the technical documentation that accompanies your computer system. Typically IRQ's 0 and 1 are used for internal purposes (timer), 2 and 9 for network adapters, 5 and 7 for the printer, and 6 and 14 for floppies or hard disks.

Tip: As you will notice from the default setting in the Introduction to this chapter, it is possible for multiple ports to use the same IRQ (interrupt sharing). While CA-Clipper Tools functions do support this process, standard port hardware usually does not. However, special multiple port cards for this purpose are offered by a variety of manufacturers.

■ Please notice that the base settings that CA-Clipper Tools

uses for COM1 to COM4 are described in the Introduction to this chapter.

■ com_SetIRQ() does not test to see if a port is actually

serving the selected IRQ.

■ A com_SFlush() to a closed port does not work.

■ It is not necessary to test for characters in the sending

buffer to carry out a com_SFlush().

This function allows you to monitor a transmission in the background with regard to the hardware or software handshake and the contents of the buffers. If you have designated nKeyValue1, it is deposited in the keyboard buffer as soon as the sending buffer is empty.

If the software or hardware handshake has been implemented by com_Soft() or com_Hard(), then the COM interface program places nKeyValue2 in the keyboard buffer when an XOFF is encountered or the CTS input is deactivated. If you have passed nKeyValue1, it is deposited in the keyboard buffer as soon as the sending buffer is empty.

Both events can prove very effective when combined with a CA-Clipper key trap. In this way the program does not constantly have to review the status of the sending buffer; it simply "takes note" when something happens. The specific event is then determined with com_SMode() within the called procedure.

The ability to transmit in the background demands the ability to control the sending buffer. For example, com_SMode() allows you to check to see if the sending buffer is waiting for an XON character when the software handshake is enabled. The bits in the returned value represent the different modes:

Table 3-7: Coding the Sending Mode

■ If no sending buffer has been set up for the designated port

using com_Open(), the function returns a value of 0.

■ If incoming XOFF characters are monitored, then it is best to

transmit relatively small strings through com_Send(). You can use com_Soft_R() to monitor between incoming XOFF characters.

■ When selecting the size of the buffer, decide whether the

remaining 25% will be sufficient at high baud rates.

■ The software handshake only supports background transmission

(when com_Open() has been implemented with the third parameter nBufferOut).

■ When you want to transmit binary data, the software handshake

must always be turned off.

The Center() function provides a simple way to center text in any line. Center() is able to pad only on the left or on the left and right using any selected character. Leading and trailing blanks (if any) are replaced with the new character.

When nLength is not specified, Center() assumes the maximum available line width to be MaxCol() + 1, so that the correct output appears in the windows. Additionally, the current cursor position or the column position selected through a SAY command is also noted. So, if there is an output on an 80-column line that begins at column 20, a section of 40 characters from column 20 is used to center the output.

■ If the sum of the pad characters is odd, then one more

character is inserted at the beginning of the character string.

Important! This function cannot be implemented when windows are open.

■ Modes set through this function can also be combined with

other line counts, i.e. EGA43().

■ A call with .T. corresponds to BIOS mode 0. A call with .F.

corresponds to BIOS mode 1.

Important! This function cannot be implemented when windows are open.

■ A call with .T. corresponds to BIOS mode 2. A call with .F.

corresponds to BIOS mode 3.

■ When both character strings are the same length, then the

first byte of cString1 can be linked with the first byte of cString2, and the second byte of cString1 can be linked with the second byte of cString2, and so on. If cString2 is shorter than cString1, then as soon as the last byte of cString2 is reached, the process continues and starts again with the first byte of cString2. However, if cString1 is shorter than cString2, the process terminates with the end of cString1.

■ Values greater than 256 can result when adding values. The

new value is then formed based on the following formula:

(Asc(Character1) + Asc(Character2))% 256.

■ Implementing CSetRef() can suppress the return value for this

function to save room in working memory.

■ When both character strings are the same length, then the

first byte of cString1 can be linked with the first byte of cString2, and the second byte of cString1 can be linked with the second byte of cString2, and so on. If cString2 is shorter than cString1, then as soon as the last byte of cString2 is reached, the process continues and starts again with the first byte of cString2. However, if cString1 is shorter than cString2, the process terminates with the end of cString1.

■ Implementing CSetRef() can suppress the return value for this

function to save room in working memory.

■ The first position in a string is 1, and therefore is not

even.

■ The CharList() function's return value is never longer than

256 characters.

■ If you sort this result with CharSort(), you have an ascending

list of characters.

CharMirr() reverses a string. The function returns a palindrome of cString.

The optional logical parameter allows you to mirror a string and ignore the blanks. This permits you to build index entries that end with a particular sequence.

■ The returned value of this function can be suppressed by

implementing CSetRef() to save room in working memory.

■ This function can be used to recombine strings extracted by

CharEven() or CharOdd().

■ The returned value of this function can be suppressed by

implementing CSetRef() to save room in working memory.

■ Without the cDeleteCharacter parameter, all the repeating

characters are removed. If the parameter is specified, only those characters in cDeleteCharacter are removed.

■ If both character strings are the same length, then the first

byte of cString1 is linked with the first byte of cString2, and the second byte of cString1 is linked with the second byte of cString2, etc.. If cString2 is shorter than cString1, then when the last byte of cString2 is reached, it continues with the first byte of cString2. However, if cString1 is shorter than cString2, the process terminates at the end of cString1.

■ The return value of this function can be suppressed by

implementing CSetRef() to save room in working memory.

This function allows you to compress (pack) the contents of strings. The function supports two different pack methods:

Table 4-2: Pack Methods Supported

Different screen adapters build characters from a different numbers of pixel lines. Based on the installed mode, the number of pixel lines for a particular type of screen adapter may also vary.

Use CharPix() to determine the number of pixel lines available in the currently installed mode. This information is useful when used in conjunction with SetCursor().

This function is easier to use than it seems. If we proceed on the assumption that both search expressions and the replacement expression are only one character long, then the following steps occur:

■ All positions are determined where cSearchFor1 is found

within cString1.

■ All positions are found where cSearchFor2 is found within

cString2.

■ The character in the cString2 string is replaced by the

character in the cReplaceExpression.

This function can be used to simplify work with variables that contain screen memory. If cPict1 contains the character "|"at position 34 and cPict2 contains the character "-" at the same position, then this position within cPict2 can be replaced with a new character, "+"', which represents the combination of the two.

Multiple Exchanges Both search expressions and the replacement expression can be longer than one character. The previously described exchange procedure occurs repeatedly — initially with the first character in the three character strings, then with the second, and so on. The number of iterations is regulated by the length of cSearchFor1. If cSearchFor2 or the cReplaceExpression are shorter, then the last byte is used again.

■ The length of cString2 determines the number of search

procedures at any one time. The length of cSearchFor1 determines the number of possible exchanges.

■ The return value of this function can be suppressed by

implementing CSetRef() to save space in working memory.

■ A use for multiple replacement using CharRelRep() can be found

in the accompanying sample programs.

This function allows you to carry out very complex replacement procedures. Every character in the cSearchFor is searched for within the cString. If found, the character is replaced by the corresponding character in the cReplaceExpression.

If lMode is not passed, characters are exchanged repeatedly as required. This means that the function goes through each individual character in the found characters in sequence, and then searches the entire cString, exchanging cSearchFor for corresponding characters in cReplaceExpression. When you use this technique, characters that have already been replaced are exchanged again if the replacement character also appears in the search list.

However, if the optional lMode parameter is specified, the function proceeds differently. It goes through each character in cString in sequence, determining whether or not it should be replaced. Characters that have been replaced are not replaced again.

As a rule, if the same characters appear within cReplaceExpression and cSearchFor, you must check very closely to determine which lMode parameter should be used (see example).

■ If the cReplaceExpression sequence is shorter than

cSearchFor, the characters that do not have a corresponding replacement in cReplaceExpression are replaced with the last character of cReplaceExpression (see example).

■ The return value of this function can be suppressed by

implementing CSetRef() to save space in working memory.

■ Invalid parameters return a null string.

■ The function uses a fast sort algorithm.

■ The return value of this function can be suppressed by

implementing CSetRef() to save space in working memory.

CharSpread() expands a string to a preset length. However, it behaves differently than the Expand() function.

CharSpread() uses cCharacter|nCharacter as the character to insert during the expansion. The string is expanded between tokens delimited by this character up to the length specified by nLength. This is similar to full justification in a text editor.

■ Previously existing fill characters cCharacter|nCharacter

are not taken into account in the redistribution (see examples). If this procedure is not satisfactory to you, then you can call the CharOne() for the string before you call CharSpread().

CharSwap() takes all neighboring characters in cString and exchanges them. As a result, bytes in even positions are exchanged for those in odd positions.

CharSwap() is very important when you use string integers generated by the CA-Clipper I2Bin() function that must be saved or sorted. The CharSwap() exchange must be carried out prior to calling CharSort() (low/high ordering of 16-bit integers) to achieve an accurate result.

■ Since the length of the character string is not changed, a

call by reference is recommended. This increases the speed of the function.

■ The value this function returns can be suppressed by setting

CSetRef() to save working memory space.

The function performs an exclusive OR operation on each character in cString1 with the corresponding characters in cString2.

You can use CharXor() to code passwords and text. The advantage of this function is that it can be used for both encryption and decryption.

■ If both character strings are the same length, then the first

byte of cString1 is linked with the first byte of cString2, and the second byte of cString1 is linked with the second byte of cString2, etc.. If cString2 is shorter than cString1, then when the last byte of cString2 is reached, it continues with the first byte of cString2. However, if cString1 is shorter than cString2, the process terminates at the end of cString1.

■ The return value of this function can be suppressed by

implementing CSetRef() to save room in working memory.

■ The return value is a 32-bit whole number.

■ The checksum cannot be used for definitive coding of data

because the calculated sum for two different character strings could be the same. For example, the checksum for "PASTETEN" and "PERSONAL" are identical.

■ If character strings have different lengths, the strings

cannot have identical values.

Use ClearEol() to clear a specific line from a given position to the end of that line. If arguments are not specified, then the current nRow cursor line and nColumn cursor column are used as the starting location. The clear always goes to the end of the line specified with the CLEARA attribute and CLEARB character, or with the Attr|nAttr attribute and cCharacter|nCharacter character.

ClearEol() has some advantages over the CA-Clipper @ Row, Column commands:

1. It lets you take the returned value of the character string type and

combine it with string outputs (e.g., LIST...ClearEol()).

2. The cursor position is not affected.

3. The arguments are optional. If they are not specified, the function

clears from the current cursor position with the CLEARA attribute and CLEARB character.

■ You can specify the cAttr|nAttr attribute and the

cCharacter|nCharacter character in a number of ways. Please refer to the chapter introduction.

■ Default attribute and character can be set with SetClearA()

and SetClearB().

■ If no arguments are specified for line or column, then the

function will automatically orients itself to the current cursor position.

■ If no screen coordinates are designated, the entire screen is

cleared.

ClearWin() clears a specified screen area. This area extends from

< nTopLine> to nBottomLine and from nLeftCol to nRightCol.

Without these parameters, the line and column that correspond to the current cursor position for nTopLine and nLeftCol, and the bottommost line and rightmost column are used for nBottomLine and nRightCol.

You can clear with the standard attribute and character (CLEARA and CLEARB), or with the cAttr|nAttr attribute and the cCharacter|nCharacter character.

■ The cAttr|nAttr attribute and cCharacter|nCharacter

character are specified in different ways. Please refer to the Introduction of this chapter for more details

■ The standard attribute and character are set with SetClearA()

and SetClearB().

■ If no parameters are specified for the line or column, the

function automatically orients itself to the current cursor position.

Implement the ClEol() function when you need to clear to black and cannot use the standard attribute and character. This function is especially useful with a monochrome video card. A significant advantage of ClEol() over ClearEol(), is the omission of the cAttr|nAttr and cCharacter|nCharacter parameters, which increase the speed of ClEol(). The function is faster because it does not note the CLEARA and CLEARB settings.

ClEol() has some advantages over the CA-Clipper @ Row, Column commands:

1. The function allows you to take the returned value of the character

string type and combine it with string outputs (e.g., LIST...ClEol()).

2. The cursor position is not affected.

3. The parameters are optional. If they are not specified, the function

clears from the current cursor position with the CLEARA attribute and the CLEARB character.

■ If no parameters are specified for line or column, the

function automatically orients itself to the current cursor position.

Implement ClWin() when you need to clear to black without the use of the standard attribute and character. This function is helpful when you use a monochrome video card. A significant advantage of ClWin() over ClearWin(), is the omission of the cAttr|nAtt and cCharacter|nCharacter parameters, because it increases the speed of ClWin(). The function is faster because it does not note the CLEARA and CLEARB settings.

ClWin() has some advantages over the Clipper @ Row, Column commands:

1. This function takes the returned value of the character string type

and combines it with string outputs (e.g., LIST...ClWin()).

2. The cursor position is not affected.

3. The parameters are optional. If they are not specified, the function

clears from the current cursor position.

■ If no parameters are specified for the line or column, the

function automatically orients itself to the current cursor position.

ColorRepl() simplifies screen handling. This function exchanges all occurrences of the cOldAttr|nOldAttr attribute for the cNewAttr|nNewAttr attribute.

For example, after a READ, you could take the colors in all input fields, (assuming they have a common attribute), and change them. This designates these fields as no longer active.

■ If the cOldAttr|nOldAttrparameter is not specified, then all

screen attributes (without exception) are exchanged for cNewAttr|nNewAttr. If cNewAttr|nNewAttr is also missing, then cOldAttr|nOldAttr is exchanged for the CLEARA standard attribute.

COLOR TO (N)umeric The function changes an alphanumeric color attribute from NN/NN or CC/CC into a combined numeric attribute. These combined attribute values are useful with the CA-Clipper Tools functions StrScreen(), ScreenMix(), ScreenAttr(), and the CA-Clipper commands SAVE/RESTORE SCREEN.

ColorToN() makes it easy to create numeric attributes for the CA-Clipper Tools functions.

■ If you specify an invalid attribute string, ColorToN() returns

the numeric attribute 0, meaning black on black (invisible).

ColorWin() exchanges all occurrences of cOldAttr|nOldAttrfor the cNewAttr|nNewAttr attribute, within a particular screen or window area. The function operates in a similar way to ColorRepl(), except with ColorWin() you can define the screen area to work on.

The parameters nTopLine and nLeftCol define the row and column for the top-left corner; nBottomLine and nRightCol define the row and column for the bottom-right column.

■ If cOldAttr|nOldAttr is not specified, all attributes are

exchanged for cNewAttr|nNewAttr; if cNewAttr|nNewAttr is not specified, the attributes are exchanged for CLEARA.

■ Complement(Complement(expValue)) always returns expValue

as output.

■ If you want the values specified in degrees, you can convert

them with the DToR() function.

■ If the values are specified in degrees, use the DToR()

function to convert them.

This function determines which microprocessor is in use. For instance, a PC may use a Vnn microprocessor or an AT may use a 386 microprocessor. The microprocessors have the following codes:

Table 12-1: Microprocessor Coding

In contrast to a simple lock using CharXor(), this function has a random number generator that uses a "random seed" algorithm. This makes the lock even more secure, at least as long as this additional algorithm is not known. Of course, this additional security costs some computer time.

Encrypted character strings can be decrypted with the same password. With multiple encryptions, the decryption must occur in reverse order.

■ Passwords should be as long as possible — a minimum of six

characters, preferably more.

■ The return value of this function can be suppressed by

implementing CSetRef() to save space in working memory.

CSetAtMupa() sets a switch, internal to CA-Clipper Tools, that affects the operation of several other CA-Clipper Tools functions. These functions permit targeted, extremely flexible substring manipulation. The affected functions are:

AtNum() AfterAtNum() BeforAtNum()

AtRepl() NumAt() AtAdjust()

WordToChar() WordRepl()

The CSetAtMupa() function sets the multi-pass mode on or off for these functions.

■ The default setting for CSetAtMupa() is .F., indicating that

the multi-pass mode is off.

■ To use this function, you must include the ct.ch file at the

beginning of your program with the command:

#include "CT.CH"

Find more information on this function in CH.CH.

A series of CA-Clipper Tools functions enable you to pass parameters by reference. After executing the function, the passed parameter already contains the result. However, each of these functions also returns this result as a value. A copy of the passed string exists for a short time in working memory, but it is invisible to you. In the worst possible case, two adjoining memory blocks would require up to 64 kB.

This behavior can be influenced by implementing CSetRef(.T.). Then the group of affected string functions no longer return a value, which can save you up to 64k of memory with large strings.

Functions affected by CSetRef():

AddAscii() Blank() CharAdd()

CharAnd() CharMirr() CharNot()

CharOr() CharRelRep() CharRepl()

CharSort() CharSwap() CharXor()

Crypt() JustLeft() JustRight()

PosChar() PosRepl() RangeRepl()

ReplAll() ReplLeft() ReplRight()

TokenLower() TokenUpper() WordRepl()

WordSwap()

■ If, in spite of having CSetRef(.T.), you need one of the

previously listed functions to return a value, then the target variable contains .F. instead of the anticipated string.

This function allows you to query the current setting for all CA-Clipper ON/OFF switches and change them. Since you can save 21 different switches, the function returns a 21-character string made with 0's and 1's, rather than logical values. This function makes it easy to save all the ON/OFF switches in a CA-Clipper error trap, and reset them when you exit. The following switches are contained in the character string (in the order they occur in the returned string):

Table 11-1: Clipper Switch Status

Table 11-2: Clipper Switch Status

■ If you specify an invalid parameter, the function returns a

null string and does not reset any switch.

■ Uppercase or lowercase letters have no impact on the

parameter.

This function allows you to query the current setting for SET DATE. The table below describes the numeric codes that are returned:

Table 11-3: Coding for country specific date formats