 |
 |
       |
|
|
|
||||
Technical Notes |
|||||
|
FILE STRUCTURE MEMORY USAGE SPECIAL DATA STORAGE USING RESOURCES SOURCE CODE BASICS Goldenseal keeps all of the information about your company in one file. It uses an object database to organize your company records. That means that each record is stored as a separate "object" on the disk. An object is a "chunk" of information that is organized in a specific way for that class of object. Each object contains data fields which make sense for that type of record. Every object has a class ID (the type of record it is) and an item ID (a unique record number). HINT-- To see the raw contents of your company file, choose Security from the View menu, and choose Database Report from the submenu. Goldenseal includes over 200 classes of objects which cover the many details of running a business. They belong to the following basic types:
HINT-- Goldenseal uses a hierarchy of object classes to make it easier to keep them organized. For example, all account classes "inherit" from a basic Account class which contains data and behavior that are common to all accounts. There are also intermediate account classes such as Job Accounts, Bank Accounts and Cost Accounts. Each object has a unique ID number. Goldenseal assigns the ID number when you first create a record. You never need to know the ID number, and you can't change it. ID numbers start at one, and increase by one, each time you add a record. Goldenseal can store more than 2 billion records in each class. Some accounts and transactions have a separate reference number or invoice number which you can change. You don't need to use these numbers,
but they are available if you prefer to use a numbering system for your accounts or transactions. When you view or change records, Goldenseal fetches the record data from your hard drive, and shows it on the screen. When you view reports, Goldenseal may need to fetch hundreds or thousands of records to fill in the report. The action commands (Billing, Deposit Funds, Job Costs, Pay Bills and Write Payroll) also need to fetch data from hundreds or thousands of records. To keep performance zippy, Goldenseal uses a "binary tree" to locate each object on the disk. In practical terms, that means that Goldenseal can find any record in about the same amount of time, even if you have many thousands of records. TECHNICAL NOTE-- You will generally retrieve records by their name, but Goldenseal always uses numbers to locate the record. Each record is identified with a class ID number and a unique object ID number. Many accounts and transactions also store links to the records that they are most likely to use, so it is extremely fast to find those items. The Goldenseal File Manager stores the location on disk for each record in your company file. It also keeps track of the empty spaces between records, so it knows where it can add new records most efficiently. HINT-- To view the complete contents of your company file, use the File Order Report. To export a list of file contents, use the File Contents Report. When you add a new record, the File Manager checks the empty space within the company file, and puts the record in the first space where it fits exactly. If there is no space that is exactly right, the File Manager finds a space as close to the beginning of the file as possible. If there are no internal spaces big enough for the record, the File Manager puts it at the end and increases the size of the file. When you delete a record, the File Manager keeps track of the empty space, so something else can go there later. When you change a record, the File Manager first deletes it, and then adds it back. That way if its length changes, it ends up in the best possible place. When you use the Verify File command, Goldenseal checks each record's actual location against the File Manager, to make sure they match. Each Goldenseal record includes data fields that store useful information about the record. Some of the fields are visible when you use a data entry window. Other fields are not visible there. To see all of the data in a record, follow these steps:
Each Goldenseal record contains several types of information:
HINT-- The Disk Contents column shows the actual raw data on the hard drive. Money, number, popup and clairvoyant fields are stored in a special format, so the disk contents will not look the same as what you see in the Value column. Goldenseal records are often linked to other records. For example, a new Labor Hours record is added to an array of all labor items in the Employee Account, and also to an array of unpaid items (until it is paid). It is also added to arrays in the job account and utility accounts that apply to labor. Goldenseal uses the record links to make common operations much faster. Most commands will not slow down even when you have many thousands of records, since they can locate the information they need via the efficient record links. Goldenseal updates record links as part of the posting process when you close a record. Goldenseal automatically saves all changed records whenever you close a record or perform an action through one of the action commands (Billing, Deposit Funds, Job Costs, Pay Bills and Write Payroll). Most records "post" to accounts and other records, so a single change may affect dozens or even hundreds of records. It only takes a small fraction of a second to complete the save, even if there are many changed records. If you leave Goldenseal unexpectedly due to a power failure, unexpected quit or other problem, you'll only lose the data in the records that were incomplete at the time. WARNING-- If Goldenseal is interrupted in the middle of a save, it could suffer serious damage to the file. Although this is an extremely rare occurrence, it's still a good idea to have a good backup system in place so you can revert to a recent version if that ever happens. Goldenseal data is corrupted when the contents of a record don't "make sense". Goldenseal checks records when they are used, and gives an error message if it seems to have problems. Records can be corrupted in any of the following rare cases:
To check for corrupted data, choose Security from the View menu, and choose Verify File from the submenu. Goldenseal will scan all records in the company file and report any problems. HINT-- Goldenseal will automatically verify the file any time the program is closed improperly. To fix a corrupted file, try any of the following:
NOTE-- You'll also need to separately export/import any layouts that you changed with the Custom Layouts command, and any estimate dimensions. To export recent data from your company file, and import it into a recent backup, follow these steps:
When Goldenseal finds an object, it keeps it in RAM until you leave Goldenseal, or until the program needs that memory space for something else. In practical terms, that makes Goldenseal much faster. HINT-- Sometimes you will notice that an operation goes faster the second time you use it. That's because Goldenseal doesn't need to fetch records from disk the second time. You can increase the speed for some operations by giving Goldenseal more RAM memory-- that way it won't have to fetch records from the disk as often (RAM access is thousands of times faster than disk access). Goldenseal is also more reliable if it has plenty of RAM to work in. It is much less likely to run out of memory, which is the most likely cause of unexpected quits and other problems. NOTE---- Modern computers have tons of RAM and large, fast hard drives. You will rarely see speed or memory problems in Goldenseal, in any computer less than 5 or 10 years old. To set the memory size in Mac OS 9 and earlier, follow these steps:
Mac OS X and Windows control memory allocations internally. They should automatically give more memory to Goldenseal when it needs it. Each line in a breakdown table is stored as a separate breakdown object. The parent transaction stores an array that lists each breakdown that it contains. Each breakdown also stores a reference to its parent. That way they can find each other quickly. When you export data for a company file, Goldenseal automatically exports all objects in the correct order, so they can link up correctly when you import the data into a new file. You can also export transactions and breakdowns separately-- but in that case you'll need to import transactions, and then breakdowns, so they can link up correctly. Goldenseal layouts control the way things look on the screen, and the way reports and printed forms look. Goldenseal stores starter layouts as resources. To change any layout, choose Custom Layouts from the Options menu, and choose one of the submenus. When you save changes in a layout, Goldenseal store a database object which contains the layout details. Layouts are not included when you make a Company File export. To export custom layouts, choose Export from the File menu, choose Other Items from the submenu, and choose one of the layout types from the second submenu. Data Storage-- Icons and Pictures Goldenseal lets you paste pictures into Cost Items and Assemblies. Each picture is stored as a separate database object which contains that graphic. You can also paste custom icons into Accounts. Each icon is stored as a separate database object which contains that graphic. Icons and pictures are not included when you make a Company File export. We currently have no automatic way to move pictures between files-- you'll need to use copy and paste. Goldenseal stores passwords in encrypted form. That way a snoop cannot see your user passwords, even if they use a file editing program to view the raw data in your file. HINT-- You can make Goldenseal more secure by avoiding obvious passwords. It also helps if you don't write your password on a post-it note attached to your computer! Many of the human interface elements in Goldenseal are set with resources. If you are an experienced "hacker", you can use ResEdit to change some parts of Goldenseal. ResEdit is available for free download from the apple web site-- www.apple.com. Resources make it possible to convert Goldenseal to other languages, and make certain other changes, without needing access to the source code. WARNING-- You can cause extremely serious damage with ResEdit! Always try changes on a copy of Goldenseal. If you have problems with a customized copy of Goldenseal, be sure to tell us what changes you've made, when you call us for tech support. Windows does not support user-editable resources. The Windows version of Goldenseal uses a specially converted form of the Macintosh resources which is imbedded in the Goldenseal application file. It is theoretically possible to use a file editor to change the imbedded resources, but you'd need to be a very experienced "hacker" to do it successfully. You can use Goldenseal itself to customize many parts of the program. Goldenseal lets you change the following items, without need for ResEdit:
WARNING-- Don't change any other resources! Doing so may cause crashes, strange results, plagues of frogs and/or increased hair loss. Or worse. To change Goldenseal resources with ResEdit, follow these steps:
The icons that are available for the Chart of Accounts are stored in the icl8 (large icon) and ics8 (small icon) resources. Changing Icons You can use the simple graphics editor in ResEdit to change any icons. To do so, follow these steps:
Adding Icons To add a new account icon, follow these steps:
HINT-- You can also double-click on any account icon and paste in a graphic. The MEMB resources in the Goldenseal application store information about the data fields in each object class. Each MEMB resource lists each of the fields in that class. You probably will never need to change anything in the MEMB resources. If you want to add custom fields, you can do that with the Custom Layouts command. You can also use that command to change fields so they are not editable, or so they require a value to be entered. You can change the name of any data member. You can also change the following buttons for any member field, and usually not have problems: Allow Negatives, Can Always Change, Can Replace All. WARNING-- Never change the Tag, Type or Param values for any field. Never change the button settings, except for the items mentioned above. Never delete a data field. You can cause extremely serious problems if you do the wrong thing to these resources! The REQO resources list the accounts and lists that are included in a new company file. You can type in new names for any of the start-up accounts or lists. WARNING-- Never change the Class ID value for any REQO item. Never delete any item from this resource. To change the text of any menu command, open the MENU resource, double-click on a menu, and type in new text. The MENU resources apply to the pull-down menus at the top of the screen and to popup buttons. WARNING-- Never delete menus or change their order. You can cause extremely serious problems if you do the wrong thing to these resources! The STR# resources include all text that is used in error messages, plus any other text that might need to be changed in a foreign language version. To change stock text, follow these steps:
WARNING-- Never delete any items, add any items, or change the order of items in a list. Programming DetailsGoldenseal was written in C++, using the CodeWarrior Pro development environment. We used the PowerPlant application framework (part of CodeWarrior). The layout for some windows was done using Constructor (also part of CodeWarrior). CodeWarrior is a great program. Thanks, Metrowerks!The basic database features in Goldenseal are based on NeoAccess, licensed from NeoLogic Systems. Unfortunately we ended up re-writing a large percentage of the code there, which explains 6 or 8 months of the delay in our shipping date. We have used OOP (object oriented programming) throughout Goldenseal. It's a very good programming model which makes it easy for us to add new features, without getting lost in the 5+ million lines of code that the program now contains. A lot of that is comments and spacer rows, but it still represents many programmer-years! We estimate that about 50% of the code is for the basic interface-- screen display, file management, mouse behavior. About 25% handles data storage for the many object classes, and 25% handles posting, action dialogs, basic accounting and estimating features. Goldenseal is not an Open Source program, but we will consider source code licenses to interested parties. Please contact us for details.
Main Page | Accounts | Lists | Transactions | Menus | Index | Website | User Page |
