═══ 1. SOMXBASE - Object-Oriented Access to dBase Databases. ═══ Version 1.00 SOMXBase is a dBase database engine for programmers interested in using SOM. SOM - System Object Module is a object-oriented programming interface that remains language neutral. For more information on SOM please review IBM documentation and other user guides. By providing a language neutral interface, SOMXBase allows any language that is SOM aware to access dBase files. ═══ 1.1. American Coders Ltd. ═══ American Coders, LTD. Post Office Box 97462 Raleigh, NC 27624 (919); 846-2014 Compuserve ID: 74150,2370 Internet ID: joe@usacoder.rtp.nc.us. Copyright 1995 American Coders LTD Raleigh NC USA Programming Solutions For Your Business ═══ 1.2. How To Register Your Copy ═══ We have several methods for you to register your copy of SOMXBase. o Registration Form. The cost for registering SOMXBase is $95.00.At this time, the program is limited in functionality so the price may seem high. But we will grant early registers of the product an extension on the number of updates and not just fixes. If registed before Jan.31, 1996 a registered user will receive updates throughout 1996. There is also a shipping and handling charge. For U.S.and Canada registrations it is $10.00, all other international orders $15.00. If you are planning to order ten (10); or more copies use the SITELICE.DOC in your package. ═══ 1.2.1. Registration Form. ═══ Print out the file REGISTER.FRM. Attach a check and mail to us using the address on the form (or see above);. ═══ 1.3. Version Changes. ═══ Version 1.00 Sept 30,1995. Initial release. ═══ 2. What Is SOMXBase & What It Isn't ═══ SOMXBase is a programmer's tool to access dBase III and IV files. It provides a object-oriented interface to DBF, MDX and DBT files. By providing a class object, known as xdbf, a program is provided a simple API to read, write, and update the database. Using an object-oriented tool, we will be able to enhance and extend the functionality of SOMXBase through the use of such features as Inheritance and Polymorhphism. And by encapsulating the data and methods of SOMXBase we can provide an upwardly compatible interface without comprimising future development. There is one exception to the above statement. In the future we may introduce a new class for database fields. With this in mind, it may be necessary to alter some of these datatypes. Though SOMXBase is an object-oriented programming tool, the database is not and should not be considered object-oriented. Though, hopefully, over the life of this project we will be able to allow these types of database to become object-oriented-like. ═══ 2.1. Requirements. ═══ The following is a brief discussion of what is needed to develop with SOMXBase. An operating system environment. OS/2 Version 2.x and Warp. A SOM Enabled Compiler At this time, SOMXBase has been tested with IBM C/Set++. A Requirement To Develop An Object-Oriented Application. Sorry, we can't help you there. ═══ 3. Included Code. ═══ Along with the SOMXBASE.DLL there are several other files that you will need to compile a client program. At this time only c-language based files are included. ═══ 3.1. Public INCLUDE File To Access xdbf Class. ═══ The following is a copy of the somxbase.h file. /* * This file was generated by the SOM Compiler. * FileName: somxbase.h. * Generated using: * SOM Precompiler spc: 1.22 * SOM Emitter emith: 1.11 */ /* * somxbase.csc * * a class defining a set of objects (somxbases) */ #ifndef somxbase_h #define somxbase_h #include /* * Define the class name as an object type */ #ifndef xdbf #define xdbf SOMAny #endif #include #define xdbf_MajorVersion 0 #define xdbf_MinorVersion 0 /* * External name shortening if required */ #ifdef SOM_USE_SHORT_EXTERNAL_NAMES #define xdbfNewClass c #pragma linkage(c, system) #define xdbfClassData d #define xdbfCClassData x #endif /* SOM_USE_SHORT_EXTERNAL_NAMES */ /*--------------Migration------------*/ #define xdbf_classObj xdbfClassData.classObject #define _xdbf xdbf_classObj /* * New and Renew macros for xdbf */ #define _xdbfNew() (_somNew(xdbfClassData.classObject)) #define xdbfNew() \ ( xdbfClassData.classObject \ ? _xdbfNew() \ : ( xdbfNewClass(xdbf_MajorVersion, xdbf_MinorVersion), _xdbfNew() ) ) #define xdbfRenew(buf) \ ( _somRenew(xdbfClassData.classObject, buf) ) /* * New Method: open */ typedef short SOMLINK somTP_xdbf_open(xdbf *somSelf, char *dbfname); #pragma linkage(somTP_xdbf_open, system) typedef somTP_xdbf_open *somTD_xdbf_open; #define somMD_xdbf_open "----" #define xdbf_open(somSelf,dbfname) \ (SOM_Resolve(somSelf, xdbf, open) \ (somSelf,dbfname)) #define _open xdbf_open /* * New Method: read */ typedef short SOMLINK somTP_xdbf_read(xdbf *somSelf); #pragma linkage(somTP_xdbf_read, system) typedef somTP_xdbf_read *somTD_xdbf_read; #define somMD_xdbf_read "----" #define xdbf_read(somSelf) \ (SOM_Resolve(somSelf, xdbf, read) \ (somSelf)) #define _read xdbf_read /* * New Method: write */ typedef short SOMLINK somTP_xdbf_write(xdbf *somSelf); #pragma linkage(somTP_xdbf_write, system) typedef somTP_xdbf_write *somTD_xdbf_write; #define somMD_xdbf_write "----" #define xdbf_write(somSelf) \ (SOM_Resolve(somSelf, xdbf, write) \ (somSelf)) #define _write xdbf_write /* * New Method: go_to */ typedef short SOMLINK somTP_xdbf_go_to(xdbf *somSelf, int recno); #pragma linkage(somTP_xdbf_go_to, system) typedef somTP_xdbf_go_to *somTD_xdbf_go_to; #define somMD_xdbf_go_to "----" #define xdbf_go_to(somSelf,recno) \ (SOM_Resolve(somSelf, xdbf, go_to) \ (somSelf,recno)) #define _go_to xdbf_go_to /* * New Method: update */ typedef short SOMLINK somTP_xdbf_update(xdbf *somSelf); #pragma linkage(somTP_xdbf_update, system) typedef somTP_xdbf_update *somTD_xdbf_update; #define somMD_xdbf_update "----" #define xdbf_update(somSelf) \ (SOM_Resolve(somSelf, xdbf, update) \ (somSelf)) #define _update xdbf_update /* * New Method: close */ typedef short SOMLINK somTP_xdbf_close(xdbf *somSelf); #pragma linkage(somTP_xdbf_close, system) typedef somTP_xdbf_close *somTD_xdbf_close; #define somMD_xdbf_close "----" #define xdbf_close(somSelf) \ (SOM_Resolve(somSelf, xdbf, close) \ (somSelf)) #define _close xdbf_close /* * New Method: getfld */ typedef short SOMLINK somTP_xdbf_getfld(xdbf *somSelf, char *fldname, char *flddata); #pragma linkage(somTP_xdbf_getfld, system) typedef somTP_xdbf_getfld *somTD_xdbf_getfld; #define somMD_xdbf_getfld "----" #define xdbf_getfld(somSelf,fldname,flddata) \ (SOM_Resolve(somSelf, xdbf, getfld) \ (somSelf,fldname,flddata)) #define _getfld xdbf_getfld /* * New Method: setfld */ typedef short SOMLINK somTP_xdbf_setfld(xdbf *somSelf, char *fldname, char *flddata); #pragma linkage(somTP_xdbf_setfld, system) typedef somTP_xdbf_setfld *somTD_xdbf_setfld; #define somMD_xdbf_setfld "----" #define xdbf_setfld(somSelf,fldname,flddata) \ (SOM_Resolve(somSelf, xdbf, setfld) \ (somSelf,fldname,flddata)) #define _setfld xdbf_setfld /* * New Method: whaterror */ typedef char * SOMLINK somTP_xdbf_whaterror(xdbf *somSelf); #pragma linkage(somTP_xdbf_whaterror, system) typedef somTP_xdbf_whaterror *somTD_xdbf_whaterror; #define somMD_xdbf_whaterror "----" #define xdbf_whaterror(somSelf) \ (SOM_Resolve(somSelf, xdbf, whaterror) \ (somSelf)) #define _whaterror xdbf_whaterror /* * Declare the class creation procedure */ SOMEXTERN SOMAny * SOMLINK xdbfNewClass(integer4 scemajorVersion, integer4 sceminorVersion); #pragma linkage(xdbfNewClass, system) /* * Declare the class data structure */ SOMEXTERN struct xdbfClassDataStructure { SOMAny *classObject; somMToken open; somMToken read; somMToken write; somMToken go_to; somMToken update; somMToken close; somMToken getfld; somMToken setfld; somDToken file; somDToken error; somMToken whaterror; } xdbfClassData; /* * Declare the C specific class data structure */ SOMEXTERN struct xdbfCClassDataStructure { somMethodTab *parentMtab; somDToken instanceDataToken; } xdbfCClassData; #endif /* somxbase_h */ ═══ 3.2. Language-Neutral Form. ═══ IBM recommends that this file be published to users of the class. # This file was generated by the SOM Compiler. # FileName: somxbase.sc. # Generated using: # SOM Precompiler spc: 1.22 # SOM Emitter emitcsc: 1.10 -- somxbase.csc -- -- a class defining a set of objects (somxbases) #include class: xdbf, file stem = somxbase; parent class: SOMObject; release order: open, read, write, go_to, update, close, getfld, setfld, file, error, whaterror; methods: -- group: access_methods short open(char *dbfname); short read(); short write(); short go_to(int recno); short update(); short close(); short getfld(char *fldname, char *flddata); short setfld(char *fldname, char *flddata); char * whaterror(); ═══ 3.3. Sample Make File ═══ This is a sample make file that can be used with NMAKE. # Created by IBM WorkFrame/2 MakeMake at 05:01:26 on 09/21/95 # # This makefile should be run in the following directory: # d:\somxbase # # The actions included in this makefile are: # COMPILE::C Set ++ Compile # LINK::Link .all: \ .\sample.EXE .SUFFIXES: .c .c.obj: icc.exe /Ss /Q /Ti /G4 /C %s .\sample.EXE: \ .\sample.obj \ {$(LIB)}somxbase.lib \ {$(LIB)}som.lib \ sample.mak link386.exe @<< /PM:VIO /DE /NOI /NOLOGO + .\sample.obj sample.EXE somxbase + som ; << .\sample.obj: \ d:\somxbase\sample.c \ {d:\somxbase;$(INCLUDE);}somxbase.h \ sample.mak ═══ 4. The Class Interface ═══ In SOM, an application program that defines and uses a SOM class is a Client program. Like all SOM enabled objects SOMXBase provides you with a class to build your objects on. The class, xdbf, is used to define your database object.This object is defined in the C include file "somxbase.h" which is included with your package. You define the database class as a pointer to the class xdbf. This pointer is known as an "Instance" of the class. Also SOMXBase provides the functions, or in SOM-speak, methods, to access a database. Methods are referenced in your program by prefixing the method name with the underscore '_' character. Most methods require one parameter, usually the defined class object. ═══ 4.1. Defining A Pointer To The Class Instance ═══ Description. Defines an addres placeholder for the class instance. Purpose. The program needs to be able to address the instance to be processed by the class methods. Format. using the C format It's rather simple: #include "somxbase.h" int main(); { xdbf *database; ... In the above example we have defined a class instance known as database. ═══ 4.2. Creating An Instance of a Database Object ═══ Description. Assigns an addres to the class instance. Purpose. The program completes the addressability to the instance . Format. name = _xdbfNew(); Parameters. N/A Return Value in name Description NULL SOM error some address normal An example: #include "somxbase.h" int main(); { xdbf *database; database = xdbfNew();... ═══ 4.3. _open ═══ Description. Prior to processing a database file, the file must be opened. When your procedure opens the database file several activities occur. o The database file is opened. o MDX files, if dBase IV format dbf, are opened. Purpose. To open the database for processing. Format. _open(instance, dbfname); Parameters. instance The pointer to the instance of the class object. dbfname The name of your database as it is known to the operating system. Return Value Description 0 Normal 1 Failure The following example opens the machines database. #include "somxbase.h" int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; }... ═══ 4.4. _read ═══ Description. To read data from the database. Purpose. This method will read a record from the database. Your program will need to use the _getfld method to processes the data. Format. _read(instance); Parameters. instance The pointer to the instance of the class object. Return Value Description 0 Normal 1 Failure int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _read(database); if (rc); { printf("Something not right\n"); exit; }... }... ═══ 4.5. _getfld ═══ Description. Load the contents of a database field into memory. Purpose. To make the data available to your program. Format. _getfld(instance, name, data); Parameters. instance The pointer to the instance of the class object. name The name of the field in the database. data Some character pointer. Return Value Description 0 Normal 1 Failure The following example shows how data is assign to a database. #include "somxbase.h" int main(); { xdbf *database; int rc; char *name, *location; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _read(database); if (rc); { printf("Something not right\n"); exit; }... rc = _getfld(database, "Name", name); if (rc); { printf("Something not right\n"); exit; } rc = _getfld(database, "Location", location); if (rc); {... ═══ 4.6. _setfld ═══ Description. Sets the contents of a database field. Purpose. To prepare data for the database. Format. _setfld(instance, name, data); Parameters. instance The pointer to the instance of the class object. name The name of the field in the database to receive the data. data Some character string. Return Value Description 0 Normal 1 Failure The following example shows how data is assign to a database. #include "somxbase."h int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _setfld(database, "Name", "Springer"); if (rc); { printf("Something not right\n"); exit; } rc = _setfld(database, "Location", "Building 6 Room A"); if (rc); {... ═══ 4.7. _write ═══ Description. To place data into the database. Purpose. The _write method physically commits the data to the database. The data is appended to the file. Format. _write(instance); Parameters. instance The pointer to the instance of the class object. Return Value Description 0 Normal 1 Failure int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _setfld(database, "Name", "Springer"); if (rc); { printf("Something not right\n"); exit; } rc = _setfld(database, "Location", "Building 6 Room A"); if (rc); { printf("Something not right\n"); exit; } rc = _write(database); if (rc); { printf("Something not right\n"); exit; }... ═══ 4.8. _update ═══ Description. To update existing data in the database. Purpose. The _update physically commits the data to the database. The data is replaced in the file. Format. _update(instance); Parameters. instance The pointer to the instance of the class object. Return Value Description 0 Normal 1 Failure int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _read(database); if (rc); { printf("Something not right\n"); exit; } rc = _setfld(database, "Location", "Building 7 Room D Aisle 14B"); if (rc); { printf("Something not right\n"); exit; } rc = _update(database); if (rc); { printf("Something not right\n"); exit; }... ═══ 4.9. _go_to ═══ Description. Allows to reposition the record pointers. Purpose. To read a particular record by its record number. Format. _go_to(instance, recno); Parameters. instance The pointer to the instance of the class object. recno signed long record number. Return Value Description 0 Normal 1 Failure int main(); { xdbf *database; int rc; char *name, willbe[] = "Springer - 100"; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("Something not right\n"); exit; } rc = _go_to(database,100); if (rc); { printf("Something not right\n"); exit; } rc = _getfld(database, "Name", name); if (rc); { printf("Something not right\n"); exit; } printf("Changing record 100 from %s to %s\n",name, willbe); rc = _setfld(database, "Name", willbe); if (rc); { printf("Something not right\n"); exit; } rc = _update(database); if (rc); { printf("Something not right\n"); exit; }... ═══ 4.10. _whaterror ═══ Description. To get a more specific error other than 1. Purpose. The error handling is weak at best (for the time being). To get specific error messages use this function. Format. _whaterror(instance) Parameters. instance The pointer to the instance of the class object. Return Value Description some character string. Normal int main(); { xdbf *database; int rc; char *name, willbe[] = "Springer - 100"; database = xdbfNew(); rc = _open(database, ".dbf"); if (rc); { printf("open failed with a reason of %s\n",_whaterror(database)); exit; } ═══ 4.11. _close ═══ Description. To close the database correctly. Purpose. To free the database for other applications to use and update all database information Format. _close(instance) Parameters. instance The pointer to the instance of the class object. Return Value Description 0 Normal 1 Failure int main(); { xdbf *database; int rc; database = xdbfNew(); rc = _open(database, "x:\machines.dbf"); if (rc); { printf("open failed with a reason of %s\n",_close(database)); exit; } rc = _close(database); if (rc); { printf("close failed with a reason of %s\n",_close(database)); exit; } ═══ 5. Error Messages. ═══ This is a list of possible error messages and the offending method ┌────────────────────┬──────────┬──────────────────────────────────────────────────┐ │Error Message │Method │Description │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Error will opening │_open │An operating system error occurred while trying to│ │file XX │ │open the file. XX represents the return code from│ │ │ │the operating system. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Error will opening │_open │An operating system error occurred while trying to│ │production mdx file │ │open the mdx file associated with the DBF file. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │end of file │_read │Normal end of file │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Invalid record │_go_to │Record number parameter is either less than 1 or │ │number │ │greater than the total number of records in the │ │ │ │database. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │invalid record │_update │The record pointer was not positioned on a valid │ │position │ │record. This usually occurs if no record has been│ │ │ │read or when an end of file occurred. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Unknown field │_getfld │The field identified by the second parameter is │ │ │ │not part of the database. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Unknown field │_setfld │The field identified by the second parameter is │ │ │ │not part of the database. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │logic fldptr value │_setfld │The field associated with a logic field is either │ │invalid, value set │ │not 0, 1, 'T', 'F', 'Y' or 'N'. │ │to 'F' │ │ │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Can't allocate memo │_setfld │Internal processing error. Please contact us if │ │space │ │this occurs. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Bad field type when │_setfld │Field type is not defined to SOMXBASE. At this │ │getting field value │ │time the only valid field types are C, D, L, M │ │ │ │and N. │ ├────────────────────┼──────────┼──────────────────────────────────────────────────┤ │Bad date found, │_setfld │The field is not in the format of CCYYMMDD. Where│ │changed to all │ │CC is century, YY is year, MM is month and DD is │ │spaces │ │day. │ └────────────────────┴──────────┴──────────────────────────────────────────────────┘ ═══ 6. Shareware ═══ DEFINITION OF SHAREWARE Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. ═══ 6.1. Copyright ═══ Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. ═══ 6.2. Distribution. ═══ Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. ═══ 7. Disclaimer ═══ DISCLAIMER - AGREEMENT Users of SOMXBase must accept this disclaimer of warranty: "SOMXBase is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of SOMXBase ." ═══ 8. Sharing SOMXBase ═══ SOMXBase is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using SOMXBase and continue to use SOMXBase after a reasonable trial period, you must make a registration payment of $95.00 to American Coders, Ltd. The $95.00 registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. ═══ 8.1. Commercial Users ═══ Commercial users of SOMXBase must register and pay for their copies of SOMXBase within 30 days of first use or their license is withdrawn. Site-License arrangements may be made by contacting American Coders, Ltd. ═══ 8.2. Distributing ═══ Anyone distributing SOMXBase for any kind of remuneration must first contact American Coders, Ltd. at our address. below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering SOMXBase immediately (However American Coders, Ltd. must still be advised so that the distributor can be kept up-to-date with the latest version of SOMXBase .). ═══ 8.3. Pass Along ═══ You are encouraged to pass a copy of SOMXBase along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of the SOMXBase system. ═══ 9. Ombudsman Statement ═══ This program is produced by American Coders, LTD, a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442-9427 USA, FAX 616-788-2765 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536.