The dBASE INI File Explained Last Modified: January 23, 2004 This article is an attempt at de-mystifying the entries in a standard dBASE .INI file. Some of the entries are only going to be seen in newer versions of dBASE (dB2K and dBASE Plus), and many of them have been around for awhile. Some of this information is based on the Visual dBASE 5.x documentation (specifically the User's Guide), and the rest from examining a current .INI file and attempting to explain what it's all about. What is an INI file, anyway?The letters "INI" are short for "Initialization". An initialization file is used to contain information for an application, and is often (but not always) read at startup of the application. When starting dBASE, a specific .INI file is used, and if it doesn't exist, it is re-created with a bunch of default settings. If the .INI file exists, but specific settings are not there, dBASE will re-create those settings. The same thing happens for an application created by dBASE -- if a .INI file does not exist, it is created (or re-created), and even if it does exist if some settings are not there, they are created with default values. What are the names of the .INI file? For the most part, these are the names of the .EXE file. So, for dB2K, the .exe is named "dB2K.exe", and therefore the .ini file is named "dB2K.ini". For dBASE Plus, the .exe is named "Plus.exe", and so the .ini file is named "Plus.ini". For an application you created (a .exe used with the dBASE runtime), the name of the .ini should be the name of the executable (i.e., "MyApp.exe" would have "MyApp.ini"). Finally, a .INI file is simply a DOS Text file -- it can be opened in the Source Editor of dBASE, it can be opened with WordPad, Notepad, and any other application that can read text files. It can be manipulated in dBL either by using a file object, or by using a special custom class called INI.CC to manipulate it (found in the dBASE Users' Function Library - dUFLP for short). Be careful when modifying the .INI file for dBASE Plus or dB2K -- if you change something you didn't mean to, you may get some odd results. Note that as you make changes in the properties dialog, or in other parts of the IDE, that dBASE will be updating the .INI file -- this is so that it can remember the last place the inspector was in the designers, for example. How Do I Find Things in My .INI File?A .ini file is broken into two parts -- section headings, and name/value pairs. A section heading is a title with square brackets around it. It might look like: [CommandSettings] The name/value pairs are specific things that the application looks for under a section heading by name, followed by an equal sign (=) and then by the value. Note that since this is a text file, all values appear as character strings, and if you use code to read these values, they will be returned as character strings (more on that later). A typical name/value pair might look like: SEPARATOR=, Note that the string is not in quotes -- this is not necessary, and can actually cause some difficulties. Examining PLUS.INIA good portion of the rest of this document will be exploring the various parts of the standard dBASE Plus .INI file ("Plus.ini"), and explaining the various sections. As we examine these -- section-by-section -- a brief mention of items you may wish to include in your own application's .INI will be made ... InstallThe Install section is created when you install dBASE. It contains just some basic information that you fill in when you run the installer. Some of this information appears in the "Help | About dBASE" dialog ... A typical "install" section looks like: [Install] For your own applications, you probably do not need this section, unless you intend to do something similar to what dBASE does (read this and use it for the Help | About dialog ...). SourcePathThe SourcePath section is used by dBASE to define source aliases -- you can see these in the Properties dialog. If you want to you can change these, but it's not really a good idea to change the ones used specifically by dBASE itself -- you can modify your own, if you wish (see the dUFLP entry below, for example). [SourcePath] For your own applications, you do not need this section, as Source Aliases are not used in the Runtime environment, and this section will be ignored by your application. DirectoriesThe following is typical after you have used dBASE for awhile -- the directories section displays the most recently used directories, and has a specific name/value for the most recent or current directory. This is updated as you change the current folder in the Navigator window. [Directories] If you are deploying your own application, you should consider just removing this section. It will be re-created the first time the application is started. If you include this section with a path that doesn't exist on the users' machine, it can confuse the runtime engine and may cause problems. CustomClassesThis section is used to load specific custom classes into memory with dBASE Plus loads. Note that as shown below this uses Source Aliases as defined in the earlier [SourcePath] section. If you find that when you load dBASE it gives an error about a custom class that it cannot find, then this is where you can fix this problem. Simply find the entry for that file and delete it. How do custom controls get added to this list? There are a couple of ways -- the first is to double-click on one in the dBASE Navigator. This automatically places it in the .ini file. The other is to use the File menu when in the form or report designer and select to save a custom control when done designing it, there is a checkbox in the save dialog to place it on the Component Palette. If you check this it will be placed in the .INI file in the list below. [CustomClasses] For your own application -- this is used for the design surfaces, and will not be useful for your .EXE -- it will be ignored as the design surfaces are not accessible from a dBASE runtime application. ToolbarsThe toolbars section is used to define information about specific toolbars used in the IDE (Integrated Development Environment), including whether they are available (turned on), 'float', etc. In the case of many of these options, the choice is simply 1 or 0 -- 1 means "on", zero or 0 means "off". In some cases zero (0) means "use the default" and one (1) means do something other than the default. Position entries: The entries that have four numbers with spaces between them are used to define the following -- position of the left side of the toolbar from the left of the screen, position of the top side of the toolbar from the top of the screen, position of the right side of the toolbar from the left side of the screen, and position of the bottom of the toolbar from the top of the screen. What this means is if you see the following: StandardPosition=0 38 222 69 It means that the toolbar has the following coordinates: Note that if a position given is REALLY large (or has a negative value), you may find that this is the reason you cannot see something -- one way to reset this is to delete the entry from outside of dBASE (with dBASE not running), and then run dBASE again -- the entry will be re-created with a more rational setting. The question than becomes what do each of these entries stand for? In many cases this is pretty straightforward, but I will attempt to explain in greater detail: [Toolbars] The standard toolbar is the one that is normally docked at the top of the screen in the IDE. The first entry means that it is on -- in other words, when you start dBASE it appears. StandardFloat references whether or not it is a floating toolbar -- in other words, is it docked or not? If it is floating it appears as a palette or window. This defaults to zero (0) or "off", meaning it is NOT a floating toolbar. StandardStyle ...? StandardPosition -- see the discussion on "Position entries" above. The rest of these entries should start to make sense if you examine them. FormatPosition=864 408 1007 575 InspectorThe inspector section includes items specific to the Inspector window. Again, most of these should make sense if you examine them. [Inspector] Most of these make sense if you look at them, the following have a bit more explanation: Centerline is the line that separates the names of the properties, events and methods, and the right side of the inspector where you can modify these values. This is the position from the left of the inspector in pixels. ExpandedCategories ??? Visible - is pretty understandable ... if it's '1' it is on screen, if it's '0' it is not. CurrentTab - this is the current tab in the Inspector - 0, 1 or 2 (Properties, Events or Methods). CategoryView - is either '1' or '0' - on or off -- category view shows the properties in category listings, if it is off, it just shows all properties alphabetically. AlwaysOnTopAdjust ??? FormDesignerThe form designer section gives some specific details on how the form designer opens, and so on. [FormDesigner] MethodEditor is either 1 or 0, if it is 1 it means that when the form designer opens, the MethodEditor window opens with it. If it is 0 the form designer does not open the MethodEditor window. BaseFormClassFileName is used to specify the name of the current (if any) custom form class file -- the file that contains the definition of the custom form. This is set when the designer is open, using the File menu, and "Set Custom Form Class ...". The dialog that appears allows you to set a class that will be used until you clear it (and you can clear it from the same dialog). BaseFormClassName is the name of the actual custom form -- a custom form file can contain more than one form ... SnapTo is either 1 or 0, it refers to the "Snap To Grid" setting, which can be changed by right clicking on the form designer and selecting the "Form Designer Properties" menu option. GridOneCharacter ??? ShowGrid is either 1 or 0, and it tells the designer whether to show the grid (as dots) on the form designer surface. GridPixelUnits these two numbers are the values shown in the Form Designer Properties dialog for the X and Y settings. LastCC is the last Custom Control loaded when using the form designer. DesktopThe desktop settings are modified from the Desktop Properties dialog box accessed from most of the menus in dBASE. A few settings below are not changed in that dialog, but most are. The ones that are modified in the Properties dialog have names that should make sense, and most of the values are 1 or 0 (on or off). [Desktop] Maximized is whether or not the IDE itself is maximized. StatusBar is whether not the status bar appears at the bottom of the screen. CurrentTab is the current tab of the Desktop Properties dialog ... CommandWindowThis specifies whether the Command Window itself is open when you start dBASE, maximized, minimized, and so on. [CommandWindow] PaneRatio -- the splitter between the Command Window and the Output Pane, this is the distance from the top (or left) of the Command Window. PanePosition is either 0 (horizontal) or 1 (vertical) -- meaning that the if it is zero, the Command Window is on top, and the Output Pane is on the bottom; if it is 1, the Command Window is on the left, and the Output Pane is on the right ... NavigatorThis is pretty straightforward based on previous entries. [Navigator] DatabaseThis is the last database alias that was open the last time you close dBASE, and a couple of other entries that can be modified from the Desktop Properties dialog. [Database] RecentFilesThis is the "Most Recently Used" (MRU) list. You can change the list size if you wish, and these are the files most recently examined, worked with, etc. The number following the files ... (?) [RecentFiles] RecentProjectsJust like it sounds, if there were any projects in this list below it would look very similar to the above list for RecentFiles ... [RecentProjects] CommandSettingsMany or most of these can be gotten to and changed or modified from either the Desktop Properties dialog, or from commands in dBASE (SET or SET TO commands -- check online help). [CommandSettings] When preparing an application for deployment, you should check to see if these commands are ones you need to have in the .INI file for your application. If these are not in the .INI file the user may get defaults that don't match, many of these mismatches are the cause of differences that developers experience between their application running in the IDE and a separate executable on a user's machine. ImageViewerThese are settings for the image viewer. These can be changed in the Desktop Properties dialog, on the Application tab ("Viewers" section). [ImageViewer] PlayForever is an on/off setting (1/0) and has to do with animated images -- if it is set to 1, it will loop back to the beginning of the animated image. SizeToFit is the "Size window to content" option, this defaults to 1, and isn't in the .ini file by default -- it should only be here if you change the default. OleViewer [OLEViewer] StoreAsOLE2 -- If checked the value is 1 (checked in the Desktop Properties dialog) OLE 1.0 objects in legacy code will not work. Check this option only if you do not have to support the older version of OLE. OnOffCommandSettingsNearly all of these, if not all, can be modified through SET commands (i.e., "set century on" and/or they can be modified through the Desktop Properties dialog. Check the online help for details about these specific entries (SET CURRENCY, for example). [OnOffCommandSettings] When preparing an application for deployment, you should check to see if these commands are ones you need to have in the .INI file for your application. If these are not in the .INI file the user may get defaults that don't match, many of these mismatches are the cause of differences that developers experience between their application running in the IDE and a separate executable on a user's machine. ErrorHandlingNew to dB2K release 0.4, the errorHandling options given match up with the options in the Desktop Properties dialog, and with the _app properties of the same name. Check online help for details on how these work. [ErrorHandling] You may want to use these for your own applications -- particularly the options for Web Applications (check the OLH -- the ability to create your own error page is really pretty amazing). BriefEditorThese options all affect the Source Editor (Method Editor) and in some cases affect the Command Window as well. [BriefEditor] None of these options are useful for a deployed application, as your user will not have access to the Source Editor. EditorI believe this is the position of the editor used when modifying a memo in the IDE -- if you double-click on a table and work from the grid view, and double-click on the memo field, this editor is what appears. [Editor] Not very useful for a deployed application, if you allow your user to use this, they can move it where they will, so setting a specific position is not something that makes much sense. MethodEditorThis is the editor used in the form designer, report designer, etc. to modify/edit your source code. [MethodEditor] Not very useful for a deployed application. TextEditorThis is the location of the Source Editor when it is invoked by typing MODIFY COMMAND <filename> in the Command Window, or opening an existing text file. [TextEditor] ReportDesignerMost of these are options that can be modified by right-clicking on the design surface in the report designer and selecting "Report Designer Properties ...". [ReportDesigner] BaseReportClassFileName and BaseReportClassName are similar to the similar name/value pairs for the ReportDesigner section, as is the LastCC option. As with the form designer, these options are not needed for a deployed application as your user will never see the report designer. ProjectUsed by the Project Manager, this only shows on option at the moment, perhaps others when a real project is created. [Project] Again, your user is never going to see the Project Manager, so this is not useful in your own application's .INI. ProjectExtensionsI have NO idea what the numbers mean here. [ProjectExtensions] ProjectExplorerItems relating to position and such for the Project Explorer. (Note: this is the older Project Manager or Project Explorer used in versions of dBASE prior to dBASE Plus release 2.2. The new Project Explorer that is pure dBL code uses its own .ini file ...) [ProjectExplorer] The Project Explorer is really a design surface for projects, and again the properties of this are not going to be useful in a deployed application as the user won't have access to it. ReportViewerThis is the internal report viewer that is displayed when you run a report in the IDE, or in the runtime environment. Since this can be moved by the user, it's only purpose is to show the last position it was at when a report was viewed using it. [ReportViewer] DialogsThese are all positions from the last time these dialogs were used. These dialogs are only useful in the IDE ... [Dialogs] ComponentsActiveX file registration values, these are used to make these available in the form and/or report designer. [Components] You may need to leave these out, as registering ActiveX controls may provide a different value for a different computer (?). CustomColorsThese are custom colors as defined by the getColor() dialog. [CustomColors] I'm not real sure how useful these might be in a deployed application. ProjectCustomFoldersThis is filled in when you add a custom folder to a project. (Right click on the treeview side of the Project Manager, choose "New Folder"). Custom folders are not stored in the project itself, just in the application's .INI file. These entries are not used by any part of the software other than the Project Manager, and are not necessary to worry about for deployment. The default entry is: [ProjectCustomFolders] If you have added any custom folders then you might see: [ProjectCustomFolders] MenuDesignerThe position of the menu design surface, not sure what else might appear here. [MenuDesigner] As with other designer entries, this is not too likely to be useful in a deployed application. ComponentTypesThese options can be gotten to in several places when working in the IDE, including from the Desktop Properties dialog (Table tab, "Associate Component Types" button), to specify what the default component types are for specific field types. [ComponentTypes] For a deployed object it may be useful to include this section from your own application -- in some cases, specifically grids, if you have modified these settings, you may see incorrect settings on your forms. In addition to those above, with some changes in dBASE Plus release 2.2 in the grid, when 2.21 came out a new option was added that can be manually placed in the .ini file. By default the grid now uses a special columnEditor control for memo fields. If you would prefer older behavior (the entryfield with an icon) for memo fields in a grid, then add the following to your Plus.ini (and/or your application's .ini file). Note that this also affects the grid as used with the BROWSE command from the Command Window, or double-clicking on a table in the Navigator.: [Grid] The value zero (0) in place of the '1' in the above line will tell dBASE to use the default behavior (use a columnEditor for memo fields). Custom BDE .CFG File?When deploying an application that uses a custom .CFG file, you need a special set of entries: [IDAPI] The name of the .cfg file, as well as the path, if it is not in the folder of the application should be included. Encrypted TablesIf you are working with encrypted tables (using the dBASE PROTECT command to do so), you will need to deploy the DBSYSTEM.DB file, but you also need to have an entry in your .INI that looks like: [CommandSettings] Where "D:\PATH" is the path to the directory where you are deploying this file to. If you already have a "[CommandSettings]" section (see above), just add the "DBSYSTEM" entry. If you are deploying the DBSYSTEM file to the same as your application you can set this to "." (i.e., DBSYSTEM=. ) -- the "." stands for "current directory" ... Items You Can AddYou can add some settings to the .ini file that may not be there to start with. These include things like a "Default Fonts" group: [Default Fonts] Note that you need to do this with the name of a font and with the fontsize, so you could do something like: [Default Fonts] Reading/Modifying a .INI File In An ApplicationIf you do not create a .INI file for your application, the first time you start a .exe, it will create a .INI file with the following information (note, the .INI will have the same name as the .EXE, so if your executable's name was MYAPP.EXE, the .INI would be named MYAPP.INI): [Toolbars] If you wish to, you can use the .INI file for your own purposes. You can use code calling the Windows API if you wish (that's a bit tricky for a lot of programmers), you can use the File class in dBASE, or you can use an existing custom class that is in the freeware library of code called the dUFLP (dBASE Users' Function Library Project) called INI.CC. This class allows you to read entries, modify them, delete them, and a lot more. It's worth checking out, rather than writing your own code to do what is already written. What kinds of things would you want to code into a .INI file?
Dynamic External Objects (DEO)If you are using DEO for your application, you may wish to place your object files (.PRO, .WFO, etc.) into specific folders. This is discussed elsewhere, but for a deployed application you need special entries in the application's .INI file. You need an entry for each folder you are using, but note that there is an upper limit to the number of folders that can be recognized by DEO. [ObjectPath] This would be the first folder that your application looks in to find an external object, and so on. You can have a total of 10 folders, and the name on the left of the equal sign must always be "objPath" followed by a number from 0 to 9, the value on the right of the equal sign must always be a valid path (although dBASE won't return an error if it is not valid).
EoHT: dBASEIniFile.htm -- January 23, 2004 -- KJM |