Introducing CometLib

1. Introducing CometLib • What is CometLib? • What capabilities does CometLib provide? • What can CometLib be used for? • What languages can use CometLib?

2. What is CometLib? CometLib is a “COM” server, that is a server that conforms to the Microsoft “Component Object Model”. The COM model outlines a mechanism for programs to interact with one another using a standardized set of rules. Any language that provides support for the COM object model is capable of working with CometLib.

3. What capabilities does CometLib provide? CometLib extends to a client program all of the Comet file system features available to a Internet Basic program. Files can be opened, read from, or written to (and all the variations). IB features like FStat and DStat and other supporting functions are also supported by CometLib.

4. What can CometLib be used for? Often a customer will request a program that must perform a function that cannot easily (if at all) be coded using Internet Basic. An example might be a program to interface to a external piece of equipment or maybe a program that must communicate with another application. CometLib can be used to solve these problems by allowing a programmer to write special programs in other languages while still having full access to the Comet file system.

5. What languages can use CometLib? Any modern COM compliant language can use CometLib. At Signature Systems we have tested CometLib with Visual C++, Visual Basic, and VB Script and Java (thanks Willie Klein). Some of these languages can also be embedded inside of HTML web pages providing them full access to the Comet file system.

6. Using CometLib • Issues for IB programmers • Numeric Data Representation • Formatting Data • Exception Handling • True/False Values • File System Function Differences

7. Numeric Data Representation Internet Basic supports fixed-point numeric values with a maximum length of 16 and a maximum precision of 15. VB Is limited to at most 15 digits of significance and precision digits. Place close attention to the “Numeric Data Limits” section of the CometLib Library Reference.

8. Formatting Data Internet Basic provides the ability to layout data records using the FORMAT statement. This is NOT the case with CometLib. Instead, you place data into a record at a specified position on a field-by-field basis. Field data is retrieved from a record in a similar manner. Methods have been provided to help ensure data is properly fielded.

9. Exception Handling Comet file system functions use an exception (EXCP=) mechanism to specify the label of an error handling routine. Not all COM compatible languages have such a mechanism so CometLib handles errors in a more generalized manner as outlined in the COM specification.

10. True/False Values Internet Basic pre-defines the constants TRUE (1) and FALSE (0) for use by a IB program. In VB the constant True is actually equal to –1 and False is equal to 0. It is very important that you understand that any reference to a Boolean value of True or False must not be mistaken for 1 or 0. To avoid possible programming errors it is recommended that you always use the appropriate symbolic constant in your code.

11. File System Function Differences For the most part, the Comet file system functions you already use on a day-to-day basis are provided by CometLib. In some cases minor name changes have been made to account for the varying nature of certain file system functions. For Example: In IB when you want to create a file you simply specify a K, S, or T to indicate the file type. In CometLib you must use the method that corresponds to the file type you want to create. Internet Basic: CREATE <FileName>, <RecSize>, K, <KeySize>, Dir=<Directory> CometLib: CreateKeyedFile(<FileName>, <Directory>, <RecSize>, <KeySize>)

12. Changed FS Function Names • CREATE • CreateKeyedFile • CreateSequentialFile • CreateTextFile • READ/WRITE/EXTRACT/INQUIRE – for moving sequentially through a file. • ReadNext • WriteNext • ExtractNext • InquireNext • KEY - NextKey • LOCK/UNLOCK • LockFile • UnLockFile • GETHANDLES – GetDosHandles • FSTAT – FileStatus • DSTAT – DabStat • FILE – FORWARD/REVERSE/EOF/BOF • Forward • Reverse • EndFile • BeginFile

13. Code Excerpts Here’s a code excerpt that demonstrates sequential reading from a file. This program opens the file “Contacts” from the “Bas” directory. It reads a record and prints the first 80 bytes to the main program form, and repeats this process until all of the records have been read/printed. DB.Open (1, "Contacts", "Bas") While (DB.ReadNext(Lun)) RecData = DB.GetRecField(1, 0, 80) Print RecData Wend DB.Close(1) Here’s a code excerpt that demonstrates reading a record from a file using keyed access. This program opens the file “Contacts” from the “Bas” directory. It reads a record and prints the first 80 bytes to the main program form. DB.Open (Lun, "Contacts", "Bas") DB.Read (Lun, “john”)) RecData = DB.GetRecField(Lun, 0, 80) Print RecData DB.Close(Lun)

14. Want More? A sample VB program called “ContactMgr” is available in source form. This program maintains a database of contact information to demonstrate many CometLib features. Please refer to the “CometLib Library Reference” for additional information on CometLib and Comet file system features.