                         === DISCLAIMER ===


I allow you to use and distribute CHECKINI freely under the
condition that I am in no way responsible for any damage or
loss you may suffer. 


Henk Kelder, 2:280/801.339@fidonet.org


           === IMPORTANT - READ THIS FIRST !===

You should take care when using this program on new versions of
OS/2 since this program interprets data from the ini-files. 
The internal structure of this data can change, and the
program might fail or even corrupt information
This was the case with the new OS/2 2.00.1 (or 2.01) version as well
as the Service Pack release in october 1992.

The best way to test this is run checkini WITHOUT the /C option! 
(Optionally use the /W option to write out all checkini's findings and 
inspect the logfile)
If Checkini reports un unusual amount of errors, the internal structure of
the workplace shells data inside the ini-files might have changed. 
Look in CHECKINI's logfile at the  
"PM_Abstract:Objects & PM_Abstract:FldrContents" section with special care.
If this section contains a lot of errors while your workplace shell seems to
function properly there might have been a change, so:


         DO NOT USE CHECKINI.EXE or WPSBKP.EXE then!
         ===========================================

(see DANGER.TXT about this)
Note: The warning above does not apply to WPSREST.EXE and COPYINI.EXE!



CHECKINI checks for, and optionally corrects, some problems in
OS2.INI and OS2SYS.INI. CHECKINI only looks at information
regarding the workplace shell. 
The make full use of CHECKINI read this document to require
information about what CHECKINI does.

CHECKINI does not work when Presentation manager has not been started.

                    ==== DESCRIPTION ===


The main reason for CHECKINI is the growth that the both .INI
files tend to have if one uses the Workplace shell heavelly.
Using CHECKINI in conjunction with COPYINI helps to reduce the
INI files sizes, which in turn should increase the workplace
shells performance.

Since OS/2 2.1 the total INI-file handling has been changed and
the ini-files no longer show the big growth. Inconsistencies in the
ini-files can however still occur. Also, all redundant information, as
described in this document can still be present.

Also CHECKINI helps to determine some possible cause's for
workplace shell failures like loosing workplace shell objects,
or situations in which a program object looses the proper
executable name or current directory. Obviously, the real
cause for these problems must be in the workplace shell
itself, CHECKINI however could help you to determine the
degree of damage that has been done.


PM_Workplace:Handles

A special note is in place about a specific piece of
information in the INI-files called 'PM_Workplace:Handles'.
The workplace shell uses some obscure entity called
object-handles to refer to objects. Object handles are infact
numbers. A object-handle can refer to a abstract object (a
object NOT on your harddisk e.g. the color palette) and 
file-system objects (files & directories). 

Abstract objects reside in the ini-files. 
File-system objects reside on your harddisk. 

Whenever you add a program object to your desktop and specify
a programfile the workplace shell determines if a handle was
already assigned to the programfile and if so, it uses this
handle. If no handle was assigned, the shell creates a handle
and assignes it to the programfile. In the definition of the
program object (self an abstract object) the handle for the
programfile is stored.
 
When you start the program by clicking on the object the wps
must have a way to refer the stored handle back to the
programfile. This is done by using the 'PM_Workplace:Handles'
information. Unfortunately only handles are added to this
information and they are not removed when a (program)file is
removed from your harddisk.

In theory the total amount of handle-to-file information could
grow to big and than without any warning you will loose
information. The workplace shell than shows nonsence or
nothing at all in some of your program objects.

CHECKINI allows you to remove handles for files or directories
that are no longer present or inaccessable.


If you have installed the october service pack (CSD Level
XR06055) there has been a minor change in mechanisme described
above. The workplace shell now keeps multiple versions of
'PM_Workplace:Handles' in the ini-files. Appearantly this is
intended as a error-recovery mechanism. However, I've been
unable to determine of the backup mechanism itself is
implemented. As a result of this your OS2SYS.INI even grows more
rapidly!


ORPHAN OBJECTS

An wide spread way to remove undeleteable objects is to move
them to a directory, and then, in a OS/2 or DOS session remove
the directory. The Workplace shell than no longer shows the
objects. They are infact NOT removed but they simply have no
parent directory they will show in (no stool to sit on).
Also, sometimes it is possible that suddenly several objects
are lost. A reason for this could be a unintentional removal
of a desktop directory.

CHECKINI detect these 'orphan objects' and queries to user
(when /C specified) to move these objects to another (new)
location. The moved objects will appear after the workplace
shell has been restarted. (after a reboot!)
If this question is answered with NO, another question is
asked whether the objects should be removed from the
ini-files.


WARNING 1

if you are normally connected to a network and run CHECKINI
when you are NOT connected to this network, or when you are
not logged in, CHECKINI will report errors for references to
network objects.
In the situation mentioned above and with the /C switch given,
take care when confirming deleting or correcting problems.

WARNING 2

Whenever you run CHECKINI with the /C switch you must be
prepared to shutdown immediatly after you have run the
program. This because the workplace shell has a lot of info in
memory and it you keep on working some of the changes checkini
has made will be overwritten by the desktop. 




USING CHECKINI

From an OS/2 command prompt enter the command CHECKINI.
Without any command line options CHECKINI doesn't change
anything to your ini-files.

COMMAND LINE OPTIONS

/C             -    Write corrections to ini-files. The
                    default is to diagnose only. If this
                    option is specified the program will ask
                    confirmations for all changes it may want
                    to do in your ini-files.

/APath         -    Specify different location for ini-files
                    to be checked. This option is usefull if
                    you have a copy of you ini files and you
                    would like these copies to be checked. 
                    NOTE: Do NOT use this option to check ini-
                    files not belonging to the PC you run
                    CHECKINI on.

/Llogfilename  -    Specify name of logfile. The default is
                    CHECKINI.LOG in the directory you start
                    the program in.

/W             -    Write all output to logfile. Normally only
                    problems are written to the logfile. This
                    option could help you to inspect a lot
                    about your workplace shell objects
                    (actually workplace shell objects
                    instances).

/S             -    'Silent run', only write logfile. Normally
                    found errors are reported directly.

/?             -    Show info.



HOW THE PROGRAM WORKS

While running CHECKINI displays all found information on the
screen. Whenever a problem is found, and the /S switch is not
used the program reports the problem. The problem itself is
visible in the bottom lines of the screen. Problems are always
reported in CAPITALS.


EXAMPLES of OUTPUT:

=================================================
 PM_Workplace:Handles:BLOCK1                   
=================================================
3E2DA:CHECKINI.EXE   =>E:\ICON\CHECKINI.EXE<-UNABLE TO ACCESS
395F8:COPYINI.EXE    =>E:\ICON\COPYINI.EXE<-UNABLE TO ACCESS
39400:GETPROG.EXE    =>E:\ICON\GETPROG.EXE<-UNABLE TO ACCESS
=================================================
 PM_Abstract:Objects & PM_Abstract:FldrContents
=================================================
  Object 13087, Class WPNetLink : A network folder
   Linked to: \\SERVER09\SYS3\DIRECTORY1<-UNABLE TO ACCESS!
  Object 140AD, Class WPNetLink : SYS3
   Linked to: \\SERVER09\SYS3<-UNABLE TO ACCESS!
  Object 15185, Class WPNetLink : SYS1
   Linked to: \\SERVER09\SYS1<-UNABLE TO ACCESS!
  Object 15956, Class WPNetLink : A network folder
   Linked to: \\SERVER09\SYS3\DIRECTORY1<-UNABLE TO ACCESS!
=================================================
 Checking AssocCheckSum                          
=================================================
PMWP_ASSOC_CHECKSUM:252153
  points to 3D8F9 - E:\ICON\GETBLOCK.EXE<-UNABLE TO ACCESS
=================================================
 Checking FolderPos                              
=================================================
PM_Workplace:FolderPos:252223@10
  points to 3D93F - OBJECT DOES NOT EXIST



WHAT THE PROGRAM CHECKS

The following ini-records (Application - Key) are checked:

PM_Abstract:Objects     - (all keys)
(Mainly checks WPProgram objects for consistency, but also
checks for 'lost-objects' - objects moved to non-existing
locations. Also checks WPNetLink and WPShadow links.)


PM_Abstract:FldrContent - (all keys)
(Used for the check mentioned above for 'lost-objects')    


PM_Workplace:Handles[0/1] - BLOCK1 
(Checks consistency and existence of filesystem object-handles)

PM_Workplace:Location   - (all keys)
(Checks existence of object where id-strings like <WP_DESKTOP> point to)


PM_Workplace:Folderpos  - (all keys)
(Checks for obsolete saved object positions, fonts, etc)

PM_PrintObject:JobCnrPos - (all keys)
(Checks for obsolete saved print job container positions)

PM_Workplace:PalettePos - (all keys)
(Checks for obsolete saved palette positions, fonts, etc)

PM_Workplace:Templates  - (all keys)
(Checks for template-records that refer to non-existing objects)


PM_Abstract:Icons       - (all keys)
(Checks for obsolete icons, icons for abstract objects that do
not exist)

PMWP_ASSOC_FILTER       - (all keys)
(Checks for associations with non-existing objects)

PMWP_ASSOC_TYPE         - (all keys)
(Checks for associations with non-existing objects)

PMWP_ASSOC_CHECKSUM     - (all keys)
(Checks for obsolete checksum record that point to
non-existing objects)

PM_Workplace:Location   - (all keys)
(Checks consistency of logical location names e.g.
<WP_DESKTOP>)

PM_Workplace:Startup    - (all keys)
(Checks if the referenced folders are infact startup folders)

FolderWorkareaRunningObjects - (all keys)
(Checks for a list of open objects for a workarea)

               === Whats new in Checkini ? ===

Notes on version 1.1:

o  Some checks were added: 
    PM_Workplace:PalettePos
    PM_Workplace:Startup
    Some other checkings were extended.

Notes on version 1.2:

o    The check for PM_Workplace:Handles was moved so that it
     would be the last test done. 

o    The frase 'DOES NOT EXIST' for file objects (files &
     directories) has been changed to 'UNABLE TO ACCESS' since
     this is a beter description of what CHECKINI finds.

Notes on version 1.3:

o    The only extra in this version is that it support OS/2
     2.00.1 (beta version) since in this version the internal
     structure of various workplace shells object data has
     changed.

Notes on version 1.4:

o    Not all the data checkini appearantly needs to exist. If
     some data  checkini checks does not exist, the test is
     skipped.

Notes on version 1.5:

o    Checkini now works properly after installing the
     servicepack dated october 1992.

Notes on version 1.6:

o    Two additional tests were added. These test are for:
     - 'FolderWorkareaRunningObjects' and 
     - 'PM_PrintObject:JobCnrPos'

o    When a conflict in OBJECTID's is detected (two or more objects having
     the same OBJECTID, CHECKINI /c can assign a new OBJECTID to the objects
     that claim to have an OBJECTID that is already in use by another
     object.

o    Updated the documentation files (this file)

o    A simple test has been build in to see if OBJECTID's can be found
     in the ini-files, to determine if the internal data structure of the
     ini-files might have been changed and CHECKINI will fail completely.
     This is however no guarantee that CHECKINI will function properly on
     new versions of OS/2 2.0.

Notes on version 1.7:

o    The 'simple test' mentioned above might block someone using CheckIni
     if the ini-file itself is corrupt. Now the test is only performed when
     /C (correct) switch is specified.

Notes on version 1.8:

o     When checking 'PM_Workplace:Handles' a test has been put in that 
      checks the accessibility on a volume in one strike. 
      If the user okays the removal of a non-locateable volume, all
      handles on that volume are removed without further checking.

Notes on version 1.81:

o     Appearantly CheckIni went bananas whenever an alternate ini directory 
      was specified and no ini's were found. This has been corrected.

o     Some minor enhancements were made to the text that is being shown on
      the screen. These changes mainly have to do with signalling problems 
      with OBJECTID's.

o     CheckIni refused to Change/Correct anything if the Desktop's 
      Extended attributes have been damaged. 
      CheckIni now offers a try-to-repair option.

      This option comes down to CheckIni re-assigning objectid <WP_DESKTOP>
      to the desktop when CheckIni is unable to locate this ObjectId inside
      the Desktop Extended Attributes. If this corrective action has been
      taken CheckIni terminates and one should wait a view moments so 
      the WPS has time to update the fysical extended attribute on disk.

Notes on version 1.90:

o     This version now supports all known versions of OS/2 2.0 and 
      OS/2 2.1 Beta versions uptill release level 6.498 (March '93)


Notes on version 1.91:

o     The try-to-repair option will be called also now when the desktop 
      folder doesn't contain the .CLASSINFO extented attribute at all.

o     When /C was specified, and lost objects were found and the user
      chose for 'discard object', the OBJECTID was still checked and when
      an error was found the program asked if a new OBJECTID should be
      assigned. This has been corrected

Notes on version 1.92:

o     Several small (non-functional) errors were corrected.

o     Verified that CHECKINI works with OS/2 2.1 GA (rev. 6.514)

Notes on version 1.93:

o     Corrected a problem were CheckIni reported a problem with 
      'Not enough memory' in GetAllProfileNames.

o     When a directory containing objects is missing, CHECKINI now first
      tries to recreate this directory before trying to move the objects.
      (Only on local drives)

Notes on version 1.94:

o     Due to a bug in the Workplace shell, whenever Checkini (re)assigned
      an OBJECTID to a Scheme Palette, all scheme's went to 'New Scheme'.

      The same problem  could occur on OS/2 2.1 installations that were
      installed on top of OS/2 2.0. The problem would even then occur 
      when the /C option was not specified.

      These problems have been corrected.
        
Notes on version 1.95:

o     When the workplace shell had more then 64 Kb of object-handle-to-file
      data (PM_Workplace:HandlesX) CHECKINI would mess up. Now CHECKINI
      can handle multiple BLOCK records and will only write as much of these
      records as needed back to OS2SYS.INI (and discard any others)

o     Objects of class WPTransient were not recoqnized and therefore
      whenever and OBJECTID of such an object existed CHECKINI would give
      an error message. This has been corrected.
