*******************************************************************************

IBM Win32 DMI Service Layer Code and Utilities:


*******************************************************************************
Basic Installation instructions:
   1. Download SVAIMAGE.ZIP from ftp.software.ibm.com
   2. Use PKZIP to expand into SVAIMAGE.DSK
      (PKZIP is available on ftp.software.ibm.com, the path is as
       follows:  ps/tools)
   3. Use LOADDSKF to expand the SVAIMAGE.DSK file into the
      WIN32 SystemView Agent SDK.  LOADDSKF can expand the .dsk 
      file to either your harddrive or floppy. 
     (LOADSKF is available on ftp.software.ibm.com, the path is as
      follows:  ps/tools)
   4. To install:  RUN [diskdir]: setup

After Installation:


    - When it completes, you should now have a Folder on your machine
      for the (SVA) SystemView Agent Toolkit, and a directory structure as follows:

        (SVA)\
            dmi\
                bin\
                    mifs\
                    backup\
                examples\
                    ci\
                    mi\
                include\
                lib\


Included FIles:


 Service Layer code:

         DMISLAPP.EXE     - Service layer process Windows 95
         DMISLSRV.EXE     - Service layer process Windows NT

         - This file provides all of the function
           specified by DMI Version 1.0.



         DMIAPI32.DLL      - Service Layer API DLL

         - This should be used by any application or
           direct interface component that uses the
           service layer.  It provides the actual DMI
           APIs, and provides all of the required
           IPC with the service layer (DMISLSRV.EXE or DMISLAPP.EXE).


  Utilities:

         DMIWIN32.EXE   - 32bit Windows MIF browser

         - This is a Windows based graphical
      application that Dynamically links to the the running
      service layer using DMIAPI32.DLL, and allows you to
      browse the current MIF database.  This application
      uses the DMI Primitives and the MI interface to
      accomplish this.


 Development files:

    DMI.H         - Primitive structure definitions, and command values
    ERROR.H       - Service Layer error codes

    - These two files are common for ANY implementation of the
      DMI Service Layer.

         OS_DMI.H      - Win32 specifics include file.

    - Sets up any OS unique requirements, such as function call
      styles, and byte ordering,...

    DMI_API.H     - Application / Component include file.

    - When building an application or component to use or provide
      function(s) of/to the service layer include this file.  It
      sets up any Win32 specifics by including OS_DMI.H, and
      then includes the two common files (DMI.H and ERROR.H).

    DMIAPI32.LIB    - Service Layer Import Library

    - Link any new code you are building with this import library
      to resolve the Dynamic Links to DMIAPI.DLL.

    - NOTE: Under Win32 there are several ways to resolve Dynamic Links,
            Import libraries are only one of those mechanisms.

 Other:

         NAMES.C      - Sample Dynamic Component.

         - This is a file containing all of the source files required to build NAMES.DLL.
                It is intended for use as an example or template.

         DMI32.C      - Sample MI code.

         - This is intended as an example of how to use the MI interface.  It is not a
      complete package, as only the .c file is included.  Basically it is a VERY old
                version of DMIWIN32.

         NAMEDIR.C     - Source code for a sample direct interface component.

         - This is a file containing all of the source files required to build an example
                direct interface component.


*******************************************************************************

New/Fixed in the release:
    * On Windows NT the service layer runs as a service.  Under
      NT the service layer can be controlled from the services applet in the
      control panel.  Before you uninstall the service layer you should "STOP"
      the DMISL service if it is running.
      This also applies to a reinstallation of the SystemView Agent.
      When a process is running it should not be overwritten.

    *  On Windows 95 the service layer is a simple service.  The service layer
       was added as a service under the registry key:
 "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunServices\DMISL"
       In order to uninstall or reinstall the IBM SystemView Agent package,
       the DMISL value key should be DELETED and the machine rebooted. This can
       be accomplished using the registry editor that is supplied with
       Windows 95.

Previous Releases:

    * DateTime stamp was not being set properly as the result of an inconsistency
      in runtime library support between IBM CSet++ (OS/2) and Borland C++4.5.

    * OK, this is the big one...  Several of you asked for this:  Support of the
      Microsoft Visual C++ envronment.  I looked everywhere, and talked to MANY
      people on this topic, and came to the conclusion that Visual C++ does NOT
      support other vendor compilers very well.  In short the problem is that
      there is no way to build an IMPORT library from an existing DLL.  Fortunately,
      ALL of the other compiler vendors I tried do support this function.
      The Service Layer and tools in this release are all built with the
      Visual C++ tools (V2.0)
      If you build with another developement environment, you will need to build
      a new DMIAPI32.LIB import library that works with your compiler/linker.


*******************************************************************************

General Issues

 SERVICE LAYER RETURNS KEYS IN MIF ORDER


    For non-instrumented components, the service layer returns keyed
    attributes in the order that they appear in the MIF file.  For
    instrumented components, the service layer returns attributes in the
    order that they are returned by the instrumentation.




 BYTE ORDERING


    Because the service layer does not perform any byte swapping, it is
    important to use the same packing mechanism when packing a 64-bit value
    (counter64 or int64) for transmission to the service layer and when
    unpacking a 64-bit value returned from the service layer.

    To follow conventions on machine byte ordering, express 64-bit values in
    the following way:

      typedef struct {
           #ifdef LITTLE_ENDIAN
           unsigned long Low32;
           unsigned long High32;
           #else
           unsigned long High32;
           unsigned long Low32;
           #endif
           } int64;

    This structure assumes that an unsigned long is 32 bits.


Windows NT Unique Features:

1)    The service layer has a "helper" function for those building
      components on NT.  Since the "overlay" type of components (in the
      case of Win32 these are DLLs) are transient by nature, it is
      very difficult to set breakpoints in order to debug component
      code.  If you start the service layer like this:

            "d:\SVA\dmi\bin\dmislsrv DEBUG"

      then a debug address will be displayed once the SL is started.
      With a breakpoint at this address, execution will stop immediately
      prior to a component DmiCiInvoke() call.  At this time the
      component DLL will be loaded, and you can set any breakpoints in
      your new component code that you need.

      NOTE: Because the SL normally runs as a background process
            started by Windows NT you will normally NOT see this
            information.  In order to debug a component you must
            temporarily stop the DMISL service.
            The service layer service DMISL can be stopped under
            <control panel>\<services>.  Select DMISL and select
            Stop.  You can also remove the service if you prefer to
            run the service layer manually.

            Now you will be able to run the service layer under a
            debugger from any command window, once you've rebooted.

           The service layer, DMISLSRV.EXE can return its current version information
           by invoking it with the following command line:

                  "d:\sva\dmi\bin\dmislsrv VERSION"

           Note: This will return the SL banner, and will NOT start the Service
                 layer.  This will allow it to be issued even while the SL
                 is running.


*******************************************************************************
*******************************************************************************
