## Using Your DDK

[prev][next][parent][TOC]

### Module Level Version Control

The architecture of OS/2 mandates that certain device drivers supplied by our customers use the same names as those supplied with the OS/2 product. When IBM supplied a ServicePak to support our product, there was no way to detect the actual supplier of the device driver being serviced. In some cases, our service utility was replacing a vendor-supplied device driver with an IBM developed driver. To fix this problem, IBM is implementing Module Level Version Control in steps.

Step 1

The service utility will look for the "IBM" string in the Description field located in the LINKER definition file (see below). The utility will look for the "IBM" string only in the device drivers that had the support implemented when OS/2 Warp, Version 3 shipped. Consequently, version control will work only on DDK drivers whose makefiles have versioning already implemented in them.

Step 2

The second step of this architecture is being implemented by IBM OS/2 development. Development is adding support through the Description field of the LINKER definition file (DEF file). The current implementation uses the "IBM" string located in the built binary (in our case, a device driver) to allow our service utility to detect whether the module being serviced is actually an IBM module or one supplied by another party. The support is not complete, but there are examples in some MAKEFILEs of how we implemented this strategy. A specification is also provided below.

How to Insert the Information into the Executable

1.Modify MAKEFILE to create the LINKER definition file dynamically. This is implemented by utilizing the internal function of NMAKE, which allows for automatic creation of files from within the MAKEFILE. In addition, the description field of the LINKER definition file should be changed to reflect the following information. The "description" information will be taken by the LINKER and put in the load module header as the first entry in the Non-Resident Names Table. The loader will not load it, so there is no memory or performance impact.

The following is an example of how this is implemented in the IBMFLPY1.ADD device driver MAKEFILE which is located in the SRC\DEV\DASD\IBM\IBMFLPY1 directory of the DDK.

           !include $(H)\VERSION.MAK

              .

              .

              .

           ibm1flpy.add:  $(OBJS) $(LIBS) makefile

                   Rem Create DEF file <<$(DEF02)

           LIBRARY IBM1FLPY

           DESCRIPTION "$(FILEVER)  Adapter Driver for ISA Diskette Controllers"

           PROTMODE

           SEGMENTS

            DDHeader       CLASS 'DATA'

            LIBDATA        CLASS 'DATA'

            _DATA          CLASS 'DATA'

            CONST          CLASS 'CONST'

            _BSS           CLASS 'BSS'

            'Code'         CLASS 'CODE' IOPL

            LIBCODE        CLASS 'CODE' IOPL

            _TEXT          CLASS 'CODE' IOPL

            SwapCode       CLASS 'CODE' IOPL

           <<keep

2.Add the inclusion of the VERSION.MAK file located in the H directory of the current release to the MAKEFILE. The following is an example of one of the VERSION.MAK files located on the DDK.

    #

    #       VERSION.MAK

    #

    #       Current build level for File Versioning

    #

    #       This file should reside   in   the   same   place   as   COMMON . MAK

    #

    _ VENDOR    =   OEM

    _ VERSION   =   8 . 155

    FILEVER   =   @ ^ # $ ( _ VENDOR ) : $ ( _ VERSION ) ^ # @

Notes:

1.There are currently three VERSION.MAK files located on the DDK. These files represent the different "build" levels or releases that the source code supports. This "build" number is an IBM internal numbering scheme used to identify the release that the module supports by use of the _ VERSION macro.

2.The VERSION.MAK file has the string "OEM" placed in the _VENDOR macro when the DDK is created. This string can be replaced with anything other than the string "IBM", which is reserved.

The following is the format of the complete Description field:

The maximum length of the Description entry is 256 bytes. This field should be kept to a minimum to limit disk space impact. The Description field is broken up into the following parts:

The leading string of an "at sign" followed by the "pound sign" (@#).

Vendor name followed by a colon (:). This is implemented in the _VENDOR macro imbedded in the FILEVER macro "OEM" (without the quotes).

A version number of the form [A.B.C.D.], where A,B,C,D are alphanumeric fields that always increase in value in the ASCII table and never decrease for newer versions of the module. The version number is used to indicate function and cumulative fix levels. C and D (with the associated periods) are optional. A is the major version number. B is the minor version number. C (if present) is a revision level and D is a minor revision level . For example, 7.709 (a build number) would be a valid version indicator.

The trailing string of a "pound sign" followed by an "at sign" (#@)

Comment field (optional). If present, the comment should be kept as short as possible to limit disk footprint impact.