Win32NASM Package / Gaz's NASM 32-bit DOS Protected Mode routines
Version: 0.2
Released: January 27th 2000

Contents:
0. Disclaimer / license
1. Respect / greets to / misc ...
2. Package contents
3. Introduction
4. Installation
5. Requirements
6. Protected mode routines for DOS
7. Win32asm package
8. Bugs / history / comments / suggestions / next version
9. Contacting me / latest version

------------------------------------------------------------------------------

Disclaimer / license:
    See License.txt for the complete details. Use of any part of this package
    signifies understanding and acceptance of the terms as described in
    License.txt.

------------------------------------------------------------------------------

Respect / greets to (in no particular order):
    Michael Tippach (aka Wuschel) for making the incredible WDOSX and
    for being such a generally nice guy

    The NASM authors for the _best_ x86 assembler around

    Rattman at the RATM Propaganda Network

    Watcher^TUHB, Techno Hazard^TUHB

    _mammon et al for the Assembly Language Journal

    Iczelion for the win32asm page and the forum

    Hutch and Mike Bibby for being such top Win32asm coders

    Everyone on comp.lang.asm.x86 (we've gotta get a homework
    question filterer though... <grin>)

    HNN (www.hackernews.com) for the excellent news and the L0pht
    (www.l0pht.com) for everything they do :)

    Bits on 4Later, what a top show, what top presenters! :)

    Dawson's Creek, which has the extra advantage of having Katie Holmes
    on it, who is a total babe :) Season two sucked pretty badly though :(

    Buffy, which I've just started watching and really like. Serious _and_
    fun, shows just how badly DC needs KW back. Now, if only the creator
    could see Ultraviolet and use his position to convince someone to
    get them to make another series, but keeping the stories and characters
    intact. I think Joss Wheldon would like the darkness and ambiguity of
    Ultraviolet, and it does have humour...

    Everyone I know (Crusty,Bani,Random Henders,all@KMP esp. code corner,Gina,
    Andy/Ju/Scone/Em/Tom et al, etc) and all those I used to know, especially
    ST (Hi! Huge apologies for my behaviour, hope you can forgive me and maybe
    not hate me too much) even though she'll almost certainly never read this.

Things that have made this production possible:
    Lots of Coke (mmm, caffeine :), usually 1 - 1.5 litres a night
    Learning to survive on 5-6 hours sleep a night
    Getting drunk at various pubs/clubs on fri/sat with lots of alcohol,
    especially Vodka and Red Bull, and dancing - kept me from going mad doing
    a full time job and this at nights...
    TV/vid: The Lakes (1 and 2), Ultraviolet, B5, lots of films

------------------------------------------------------------------------------

Package contents:
    Main directory:
      Readme.txt                                (this file)
      License.txt                               (license for this package)
      Gaz:
        Dos:
          Docs:
            Readme.txt                          (DOS programming doc)
          Examples:
            *.asm                               (example source files)
            speedtst.asm                        (code speed tester)
            *.exe                               (example executables)
          Includes:
            *.inc                               (include files)
          Macros:
            *.mac                               (macro files)
      Win32:
        Bin:
          Cvtres.exe                            (used by Link.exe to link
                                                 in resource files)
          Dbgview.*                             (used to capture debugging
                                                 messages to aid debugging)
          Lib.exe
          Link.exe                              (Win32 linker)
          Rc.exe                                (Win32 Resource Compiler)
          W95ws2setup.exe                       (Win95 WinSock 2 setup,
                                                 required for Dbgview)
          *.dll                                 (required DLLs)
        Docs:
          Readme.txt                            (Win32 programming doc)
          Making.txt                            (how to assemble/link Win32
                                                 applications)
          Win32Nasm quick reference.txt         (Win32Nasm quick reference)
        Examples:
          *.*                                   (various Win32 examples)
        Include:
          C:
            done:
              *.c                               (C header files that have
                                                 been converted to asm)
            notdone:
              *.c                               (Ones that haven't and
                                                 aren't going to be)
            *.c                                 (original C header files)
        Lib:
          *.lib                                 (Win32 library files used
                                                 during linking)

------------------------------------------------------------------------------

Introduction:
    I'm a big assembler fan, and a big fan of NASM and think you can use
    assembler to write pretty much any application you want to. The main
    problem is the lack of source code out there, particularly libraries for
    standard functions (like C has) and the reputation assembler has of being
    an out-dated and unnecessary language in today's world of extremely fast
    CPUs, many Mb of main memory and Gb of hard disk space.

    Well, I disagree - I'd like to know why all the NT boxes at work use tens
    of Mb just to get going, why every new application or upgrade eats hard
    disk space like there's no tomorrow and seems to require yet more CPU
    power and memory, but saddest of all why users simply accept this.

    I'm making my stand against this. It might be easier to use a RAD or
    'visual' tool to generate applications, and just about anyone can pick
    up Visual Basic in a short time, but I don't see why I should when I
    can write smaller and faster programs and I have full control over what
    my program does. It may be fashionable to use a HLL or a 'visual' tool
    but I'd like to see a return to making efficient programs with a focus
    on making it work well on the users machines and making it small.

    IE4 and 5 weigh in at around 10Mb for a browser-only install. Opera,
    with comparable features, is under 2Mb (and very fast).

    Age of Empires and Starcraft really require a P200 to be playable
    (especially multiplayer)...why?!

    Outlook Express starts marking messages as read _very_ slowly when dealing
    with high-traffic newsgroups (we're talking many _minutes_ here). (Yeah,
    this is more of an algorithmic issue but is still an extension of
    people's reliance on hardware and HLLs) and takes lots of space. Compare
    with Forte Agent which is much faster and takes up less space (though
    it doesn't have quite as nice a user interface).

    Windows is just _so_ slow. For example, KDE on Linux offers comparable
    features and runs faster whilst requiring less resources. You can use
    far inferior machines running *nix for certain applications and obtain
    the same performance as a better machine running Windows.

    There's no real point to listing more, you get the idea.

    Note that I'm _not_ advocating that everything be written in assembler.
    Scripting or other HLL languages (eg ASP, JavaScript, Perl) seem the
    perfect choice for interactive web sites, for example, but how about
    COM components for ASP in assembler or the web server itself in
    assembler? I'm fully aware of assembler's advantages and disadvantages,
    but it seems that the use of assembler is looked upon as an archaic
    hangover from days gone by and not to be encouraged.

    This package is aimed at making it easier to write large assembler
    applications and contains a variety of functions to help the
    programmer with many standard tasks. The original releases focused
    on DOS-based applications, but this version begins the move to Win32.
    Like it or not, this is because:

        o Except for specialised and legacy applications, DOS is fast
          disappearing

        o Win32 is one of the most dominant APIs in use, and looks likely
          to remain that way for the forseeable future (even if that does
          change, witness how long its taken to even _begin_ to eradicate
          DOS from mainstream systems)

        o Writing Win32 applications in assembler forces you to have a
          good understanding of the API, something that is essential to
          writing small and efficient Win32 programs, regardless of the
          language you actually use, and is a valuable skill. This sort
          of knowledge also distinguishes you from a large section of the
          'visual' crowd and note that you will easily be able to use such
          a tool and use your knowledge to write better applications

        o If you can write Win32 applications in assembler, you can
          easily use any other language to write Win32 programs as it is
          only the language syntax that differs

        o Being able to write Win32 applications is a saleable skill, and
          a good understanding of the API makes you stand out from the
          crowd (particularly in today's world of RAD and visual tools)

        o Many Win32 positions require x86 assembler experience
          (particularly the games industry) and having x86 skills as well
          as Win32 in x86 will give you an edge

    As this is the initial release, I have concentrated on ensuring that the
    package contains everything needed to make Win32 applications, but I
    have not yet converted (where necessary) and tested the original
    DOS-based functions under a Win32 environment. Hence, for this release,
    you're limited to the Win32 API and no nice string, memory, etc. functions
    are available under Win32. This will change in a later version.

------------------------------------------------------------------------------

Installation:
    To install, unzip the package into your NASM include directory, not
    forgetting to use the -d option (if you're using the command-line
    version of pkunzip) or Restore path (if you're using WinZip) to keep the
    directory structure intact. If you haven't set up a NASM include directory
    already or don't use one then you'll need to. All this does is tell NASM
    where it can find include files and you can either set an environment
    variable or pass it on the command line. Setting a variable is probably
    the preferred choice, and you can do this by adding the following line to
    your autoexec.bat file:

        SET NASM=-i<your include directory here>

    Note that your include directory _must_ be terminated with the trailing
    backslash. For example, my autoexec.bat has the line:

        SET NASM=-iC:\GAZ\NASM\

    NT users should use Control Panel->System->Environment to add the
    environment variable to the system instead.

    Once you've set up your include directory and unzipped the files into it,
    you're ready to start using the package. DOS programmers should see
    Gaz\Dos\Docs\Readme.txt whilst Win32 programmers should see
    Gaz\Win32\Docs\Readme.txt

------------------------------------------------------------------------------

Requirements:
    For DOS programming, NASM 0.98 is required. The code and macros have all
    been tested with 0.98 and will likely fail with earlier versions. If you're
    not using 0.98, now is the time to upgrade, particularly since the DOS
    macros now work under 0.98.

    Win32 programming is the same, requiring NASM 0.98.

------------------------------------------------------------------------------

Protected-mode routines for DOS:
    See Gaz\Dos\Docs\Readme.txt. The routines include:
        CD-Audio
        File
        Keyboard
        Memory management (malloc, free, etc)
        Mouse
        String
        VBE

------------------------------------------------------------------------------

Win32asm package:
    See Gaz\Win32\Docs\Readme.txt. Package includes:
        Docs
        Examples
        Help file (extra download)
        Libraries
        Linker

------------------------------------------------------------------------------

Bugs / history / comments / suggestions / next version:
    I've checked the code as much as I can and have tested it under Win95 (my
    development system) and had no problems. However, this is no guarantee so
    if you do think you've found a bug then _PLEASE_ contact me with details
    of how to reproduce it / what it is.

    Comments on the functions or the package in general are more than welcome,
    as are suggestions for new things or improvements.

    After a ridiculously long delay, this release has finally seen the light of
    day. Whilst for DOS users there's nothing new, I think the Win32 additions
    should prove popular and for us NASM users it's about time we caught up
    to our MASM/TASM cousins (particularly as NASM is so much better <grin>).
    I guess the question on someone's lips is what next though? I have several
    ideas for the next release:

        o Discontinue DOS support? This is highly likely (pretty certain in
          fact), I don't really see any reason to keep coding under DOS

        o Unicode support

        o Networking (ie Winsock so we can play with TCP/IP)

        o DirectX

        o COM components for ASP

        o I'm in two minds as to whether I go for DirectX or COM components
          first. On the one hand, DirectX is fun, allows us to play with
          nice things like graphics and sound and probably everyone has
          access to a system with it installed. On the other hand though,
          I'd like to try writing something fairly serious completely in
          assembler and DirectX is DirectX.

        o More Win32 examples, particularly complex stuff

        o Improve NASM's performance, I've got a few ideas in this vein

        o HTMLHelp documentation instead?

        o Thinking further ahead, or just various ideas I've had (these
          aren't things for the next release, just some thoughts):

          I'm quite interested in some kind of 'Visual' IDE for Win32asm.
          I've been thinking about this in the back of my mind for the
          last few days and it's beginning to take shape, though I've yet
          to give the design the serious thought it requires.

          Tying in with that, some kind of object or template framework
          for assembler (not necessarily just for Win32)? Maybe in the
          vein of the MFC or WFC. An article I saw recently got me
          thinking about this.

    Of all the things above, my primary concern is Unicode support so we can
    run natively under NT or Win2K, followed by TCP/IP as it's quite simple
    really and networking is a major part of applications now. After that,
    DirectX, COM and services are my priorities.

    However, the last item (the various thoughts) is intriguing me the most.
    C moved on (some might say moved backward!) to C++, introducing object-
    orientation, which hasn't proved to be the panacea many had hoped. Still,
    it's an improvement and improving assembler in the same way is something
    I'd very much like to try. A few years ago, Pascal was all but obsolete,
    save for legacy applications, until one man turned out Object Pascal,
    which begat Borland's Delphi - a RAD tool which found great favour with
    developers due to its Win32 API encapsulation and superb RAD. It can be
    argued that Borland had the advantage of having already tried to OO the
    Win32 API in their OWL but C++ was playing catch-up for a very long
    time - only recently has C++ Builder matched up to Delphi. I'm going off
    at a tangent here but let's consider if we had _proper_ OO available to
    us in assembler. We could have objects, inheritance, etc. which certainly
    make coding easier, _if used properly_. I'm not saying that we should OO
    everything as it's not a magic bullet, but the benefits of having the
    choice are enormous - some things simply map well to OO, like COM
    components and it would be nice to be able to code them as such. In that
    scenario, I _want_ to be able to say what things are properties, etc. as
    that's how they'll be used, but that doesn't mean I want to OO every
    program I write. What would be nice though is to be able to use OO where
    appropriate and switch out of it where not.

    That's got a little long-winded and some may say it's a pointless task,
    but I'd like to try - we have an assembler we can customise to our heart's
    content and we have vision. Some may say that it would remove the need
    for assembler, but let's assume that all code is still just as compact
    as if it had been hand-coded. In this case, why would the proficient
    assembler coder choose another language? Before anyone flames, remember
    that I don't advocate writing everything in assembler - but services,
    COM components, DLLs, etc. are all usually small and are required to be
    as fast as possible (in general) so why not? Write your large application
    in a HLL and DLL out the speed-critical parts to assembler. However, unless
    your application is very large even this may not be necessary. Besides,
    if you write your HLL code in a modular fashion you can easily convert
    parts to assembler later on if required, or for the sport of it :) In the
    end of course, it all boils down to choice - what do you want to write
    in. You may argue you can churn out GUI apps far quicker than an
    assembler version, but it's probably only because of your visual RAD tool.
    Switch down to C and you may be surprised at how little difference there
    really is from assembler. If assembler had these RAD tools available,
    yes you'd probably be faster, but not by much since we've got all the
    HLL constructs available too. I don't see a reason why assembler couldn't
    be a language of choice if it had these features. And I'm seriously thinking
    about how to add them to it.

    Rant over :)

    I've tried to include enough Win32 examples to get things going, and to
    provide a decent starting point for newcomers to Win32. However, I can't
    do everything and I have no doubt other people will have ideas for
    examples, etc. So, what do _you_ want to see next time?

        o More documentation on specific concepts, ideas, Win32 stuff?

        o Certain C header files converting?

        o More examples?

        o Tutorials? (I've tried to make the examples be tutorials where the
          explanations are in comments in the source code)

        o Different doc, example formats?

        o Something else?

    If you don't tell me what you'd like to see, then I've no way of knowing!
    So tell me! For the moment, I'd prefer to stick to the 'core' Win32
    stuff and not stray into COM, ADO, etc. This will allow us to have good
    support for the most commonly used Win32 stuff (the GUI, files, etc)
    before getting into the more difficult areas (and you usually need a good
    graps of the core before getting into the other things). Of course,
    persuasive argument(s) could sway me to concentrate in particular areas
    if there's good enough reason (eg lots of people want it :)...

    As a final note, I'm very interested to know what people think of the
    examples style, in particular whether they find it good, bad, annoying, etc.

    History:
        0.1 - Initial release
        0.1b- Switch to use val32 for return values.

          Additions:
            Realloc, HeapBlockSpace, HeapBlockSize, Free improved.
            Dynamic string functions
            StringList object
            File subsystem

          Bug fixes:
            IntToStr, IntToStrU, IntToBin (weren't saving esi)
            PosLetter (wrong stack offset after I changed the code)
            CompareText (was using wrong stack offset)

        0.2 - Win32

          Additions:
            SoundBlaster detection
            Malloc/Free improved
            Win32 added
            Package reorganised
            Made compatible with NASM 0.98

          Bug fixes:
            DetectOS (Win95 detection improved, wasn't detecting NT)
            Milli/MicrosecondDelay (delay wasn't being passed to call...)
            Free (wasn't updating pointer leading to unpredictable errors...)

------------------------------------------------------------------------------

Contacting me / latest version:

    Email: win32NASM@phoenix.gb.net
    Web:   http://www.phoenix.gb.net
