INI

Last update: Feb 19, 2021

PURPOSE OPERATION CONTENTS of INI INI KEYWORDS

PURPOSE

Some of the MAREWARE programs have been designed to make use of traditional type .ini files. The use of these files is intended to allow the user to set up a “standard” set of option defaults for each program which supports the ini file.

This capability allows for consistant operation from run to run and eliminates the possibility of forgetting key options. It also has the benefit of allowing inexperienced users the capability of having pre-set options which were designed by a more experienced user.

The .ini file capability is designed to make the users life easier. However we are not saying that the learning process of how the ini files work is going to be easy. Once mastered and understood, the ini file concept in Maresware will provide a useful tool.

Important item to remember when naming the ini files. Each program has an embedded internal filename built into the exe, and is associated with the exe. For instance the hash program has an internal name of hash.exe. When it searches for an ini file it ONLY searches for one named hash.ini (or for a line in the maresware.ini with the subsection [HASH]. If you rename the executable to hash_xyz.exe and can't figure out why some options are still being installed, it is because the program is still finding an ini file named hash.ini and processing its contents. If you wish for hash_xyz to NOT process any ini contents, then you MIUST rename the hash.ini to something incosequential, like: hashini. This way the program cannot match its internal name: HASH with any current ini file.

NOTE: System variables such as SET RESET=ON are also possible. Check the help files for more information on the system variables settings

top

OPERATION

The user sets up the ini file which contains option settings relative to the specific Maresware program. When any one of the ini capable programs runs, it checks the ini file for appropriate settings. If it finds settings compatable with its operation, options are initialized just as if the user had done so on the command line. Because some options may have simple, and complicated or verbose settings, the ini file will usually only handle the simple versions of the option. Meaning it may turn an option on or off, but not allow for robust modifications of the option setting. (see the -T options in diskcat and related programs).

The command line can still be used to add additional options or modify and negate the default settings found in the ini file. Example: suppose the ini file indicated it wanted to search for only files of a *.dll type. But at run time the user decided to include all files. A command line option of -f *.* would be used. Depending on the option, the command line will either enhance, or turn off the pre-set ini settings. Command line options always take precedence over ini settings. The specific action is obviously dictated by the designed operation of the option. And each may respond differently.

One drawback of setting default options, is that if they are in fact set, and the user is not getting the expected results, the user may forget to check the settings of the ini file for a setting that is causing the problem. In April 2008, if the logging option is chosen, there may be an indication in the logfile that the ini file options were instantiated.

There are two types of ini files. One ini file has the name MARSWARE.INI. This file can contain sections which pertain to all the ini capable programs. Similar to the way a config.sys file is set up with different boot options. If a section is set up for the particular program (for example: DISKCAT) it is executed, if the section within the MARSWARE.INI file doesn't reference the particular program being run, nothing is done from the MARSWARE.INI.

The second type of ini file is one which bears the name of the program. If the program being run was mdir.exe then the associated ini file shold be named mdir.ini. (we will use mdir.ini as the reference to a generic program ini file throughout this document). If the ini file is not named exactly the same, the program won’t find it, and thus won't process it.

There is also a heirarchy as to the order in which ini files are searched for and processed. There are 2 possible locations for ini files, and since there are 2 possible names for each program to associate with an ini file (marsware.ini, and program.ini) that makes a matrix of 4 possible scenarios. Once the program finds one ini file with settings applicable to itself, it doesn’t continue to search for the rest. So in any one run, only one ini file will be used. It just depends on its location. As the saying goes, whats important is location, location, location.

The two possible locations for the ini files are: the current working directory, and the directory from which the program is being run (assuming it is being run from somewhere in the path).

The search order (and thus priority) is this:

1. Look for the program.ini (mdir.ini) file in the current default directory.
2. Look for the program.ini (mdir.ini) file in the directory the program is being run from (the path).
3. Look for the marsware.ini file in the current default directory.
4. Look for the marsware.ini file in the directory the program is being run from.

Notice the program.ini files take precedence over the marsware.ini files regardless of location. The first occurance of any of these files is the one which sets the options.

top

CONTENTS of the INI FILE

The MARSWARE.INI file has a more complicated format than the program.ini (mdir.ini) file, so that will be the first one described.

Since the marsware.ini file is a generic file which will be used by any program with ini capability there has to be a way of separating the sections for each of the programs. These seperators or headers contain program names within square brackets. [programname], or [mdir]. The ini file is read one line at a time until it comes to a [program section header]. From that point on it reads one line at a time until it reaches the next [program section header] with the same program name. Thus you must include a start and end [program section header]. All the lines between the two program headers are read and interpreted as option settings for that program.

A sample marsware.ini file with two sections might have section headers like the following:


[MDIR]
; lines beginning with a semi-colon (;) are comments
; all the option settings are here one line at a time
; the following 3 lines are option settings using keywords
output=d:\work\output.fle
append=ON
time=a
; then you end the section with another header
[MDIR]

[DISKCAT]
; here is a section for the diskcat options
; there should be no blank lines
; end of the section
path=c:\work
files=*.dll
[DISKCAT]

You can add sections for any program that is ini capable.

Be certain that you have a section header to start and end a section. Actually once a section is entered, another square bracket will end the processing, regardless of what is inside the brackets. The ending section header just adds legibility.

Do not leave any blank lines within the program sections. You can have blank lines between the sections.

Comment lines begin with a semi-colon (;). These lines are passed over and ignored. Most users make use of these comments for later documentation.

top

PROGRAM.INI files

The only difference between marsware.ini and program ini (mdir.ini) files is that because the ini file deals with a specific program, there is no need for the section headers. This means that the entire file should contain comments or option lines and nothing embedded in [square brackets].


;search the c:\work path
path=c:\work
;for all *.dll files
files=*.dll
;append to an output file, provided on command line
append=ON
;find files newer than 5 days old
newer=5
;find files lessthan 10000 bytes in size
lessthan=10000

FORMAT of the lines:

Each line consists of three (3) parts.

Part 1: Is the keyword, It can be upper or lower case. (APPEND)
Part 2: Is the equal sign (=)
Part 3: Is the modifier for the keyword. It is usually just an ON or OFF. But may be a numeric value, path, file type or other literal such as those items for the TIME keyword. These are not case sensitive, as the program converts all to uppercase be default.

Note: If an option, such as APPEND, or any option which has an ON/OFF capability is not followed by the equal (=) sign and the word [ON or OFF], then the default is that the option is turned on. So an ini line like:
APPEND
would get the same results as:
APPEND=ON

If the option can be turned on without a modifier, and it is the only item on the line, then it is turned on. If the option can take a modifier, then the modifier will obviously enhance the option value.

If the option requires a modifier (such as WIDTH=xx, or DELIMETER=|) and there is no value installed (just: WIDTH, DELIMETER) , then an error message is briefly displayed, and the option is turned OFF.

top

KEYWORDS

Typical INI keywords and a sample setting are shown below. They may not all work in all programs. Some programs logically will not support all the keywords. This is just a summary for the most popular used. The same keyword may act differently in each program depending on the programs use. However, great pains were taken to make certain they all worked as consistantly as possible.

If a program is INI capable it will be noted in the options section and in the options help screen of the program itself. In the options section of the program the option explanation will end with the keyword in [BOLD BRACKETS]. Here are the currently acceptable keywords, and choices. The word ON can replaced by YES. However, the word OFF cannot be replaced by NO. (sorry).

When you see the format [ON|OFF] This means that only one of the items is used. DO NOT INCLUDE THE BRACKETS. This is typical programming instructional format for a choice of one OR (|) the other. Remember, if you fail to include the ON or OFF indicator, the options is usually turned ON.

Here are the current acceptable keywords in alphabetical order

;the next 6 deal with file attributes od the diskcat program

Here are the keywords grouped somewhat logically

File inclusion/exclusion/paths

PATH=path here. separate line for each path
FILE=file type here. separate line for each type
EXCLUDE=file type here. separate line for each type
RECURSE=[ON|OFF]

file ages and sizes for selection

GREATER=value here
LESSTHAN=value here
OLDER=value or date here
[YOUNGER|NEWER]=value or date here

file attribute selection criteria (MDIR only)

hashing

file processing start displacements

DISPLACE=value here
FDI=[ON|OFF

file and data output criteria

file times (also see RESET)

miscellaneous

[NO_COUNT|IMMEDIATE]=[ON|OFF] VARIABLE=[ON|OFF]

It is always advisable to check the operation of any of the INI options prior to putting them into "production". And above all, check the help screens for any last minute changes. DAH!

top