                                   WexT
                            Dos-Extender package
                                    by
                           Jonas Lund aka Whizzter
******************************************************************************
 Copyright (C) 1998 Jonas Lund, All Rights Reserved.
******************************************************************************

1.0-Table of Contents:
----------------------
1.0-Table of Contents
2.0-Information
3.0-Using with WatcomC
 3.1-Compiling and linking
 3.2-Coding style
 3.3-Recompiling the libs
 3.4-Memory system
 3.5-Supported functions
 3.6-Doing this with dos32?

2.0-Information
----------------------
 Look in wext.txt for legal information and some general info
 Beware, if you are going to use WexT with packages such as USMP or other
 packages using the dos32 allocation functions then read chapter 3.3 in here.

3.0-Using with WatcomC
----------------------

3.1-Compiling and linking

 in this release (1.10b) i remade the libs alot, the main thing is that
 i removed the stack calling conversion, so now the code will hopefully
 get some extra speed and at the same time reduce switches to the compiler

 Required switch:
 -I=includepath\
     : point this to the WexT include headers

 You can OFCOURSE try without it... but this is at your own risk! :)

 Good switches:
 -s  : Remove stack checking, it will make the code faster/more stable
       (this stuff helps watcom warn if there will be a stack overrun
        but i think the coder should try to keep the stack in control anyway
        , the reason i think it is more stable is that the wextlibs doesn't
        check if there is a overrun.. it just returns)

 -nt=code32
     : This names the codesegment to code32, not needed tho.

 in earlier versions i used tlink for all linking but borland and watcom
 has some serious incompability problems so i have decided to use wlink
 for all watcom linking, when making "normal" programs you can just
 use wlink but if you want to do intros this will introduce an extra linking
 step(even with the extra step it WILL work better)

----cut-test.c----
 #include <stdio.h>
 void main (void) {
  printf("hello\n");
 }
----cut-test.c----


 Example for "normal" overlayed execs:
   wcc386 -I=c:\extenders\wext\include\ test.c
   wlink @c:\extenders\include\wext.lnk system wextovr file test.obj

 Example for non-overlayed intro execs:
   wcc386 -I=c:\extenders\wext\include\ test.c
   wlink @c:\extenders\include\wext.lnk system wextint file test.obj
   bin2obj test.rex exec.obj exec
   tlink /3 /x c:\extenders\lib\intload.lib exec.obj,myexec.exe
   wextfix myexec.exe

 (notice that the compiling is the same but the linking is different)
 (also notice that c:\extenders have to be replaced with your path)

 and you will have a working exefile.

 look in the \example\wc_exam\ and \examples\wc_intro\
 directories for a examples

 Note: wpp386 (the C++ compiler) will now also work

 another thing that i should point out is that you ALWAYS should pass
 the watcom lib or the extender objfile FIRST.. this is because it must be
 within the first 64k.

3.2-Coding style

 normal C code should be no problem using, and the functions defined in this
 document will also work, for using external libs you might want to recompile
 the standard lib.
 for C++ code there shouldn't be any problems any more at all thanks to
 brainpow who helped me finding lots of dummies and so on, altho i figured
 out how to add new[] and delete[] myself.

3.3-Recompiling the libs
 as with the kernel in linux you might like to recompile the standard libs
 for wext before using them.

  the file \src\lib\stdc\defines.inc will have the value of how much 
  memory to exclude for dos32 style code.

  the file \src\lib\stdc\startup.asm has the stack size defined.

3.4-Memory system
 The dos32 memory system (applies to WexT also) is not fitted for C programming
 (no programming at all actually) and therefore i wrote a special memory subsystem
 for C programs using Malloc/Calloc etc.. BUT there is a problem.
 any lib using the dos32 memory system will die if we allocate ALL available
 memory at startup. so i defined 1 meg to be left for dos32 style programs.
 this can be changed by modifying the defines.inc file in the \src\lib\stdc\
 directory and remaking the standard libs.


3.5-Supported functions

 These functions are showed depending on the header file they are in:

***************************************************************************
 <stdio.h>
---------------------------------------------------------------------------
  Function:
   void printf(string);

  Description:
   The old printf function is here also, i didn't feel like doing it like the
   original so don't plan on showing numbers with this one.. it can just handle
   the "main" string. just simple support.

  Example:
   printf("hello\n");
   Works fine..

   printf(hello%i\n",integerval)
   this won't work! (yet?)
---------------------------------------------------------------------------
***************************************************************************
 <conio.h>
---------------------------------------------------------------------------
  Function:
   int getch(void);

  Description:
   Reads the keyboard into INT, if no keypress available then it will wait
    for it.
    The Ascii code will be stored into INT

  Example:
   variable=getch();
---------------------------------------------------------------------------
  Function:
   int kbhit(void);

  Description:
   Checks the keyboard, if there is no key in the buffer at the moment
    then it will return null, but if there is a key then the ascii code
    will be read into INT

  Example:
   variable=kbhit();
---------------------------------------------------------------------------
***************************************************************************
 <system.h>
---------------------------------------------------------------------------
 Function:
  int system_getbaseselector(void);

 Description:
  If you for some wacky reason would like to have a selector with
  base=0 then you will get the number of it with this function.

 Example:
  basedesc=system_getbaseselector();
---------------------------------------------------------------------------
 Function:
  int *system_getzerooffset(void);

 Description:
  this pointer points to the absolute 0 offset in memory, so if you want to
  write or read to segment 0x40 then just use the pointer of the zerooffset
  and add 0x400 to it.

 Example:
  *zeropointer=system_getzerooffset();
---------------------------------------------------------------------------
 Function:
  int *system_getpspoffset(void);

 Description:
  get a pointer to the psp for programs that needs it, for example usmplay

 Example:
  *psppointer=system_getpspoffset();
---------------------------------------------------------------------------
 Function:
  int *system_getenvoffset(void);

 Description:
  get pointer to the environment.

 Example:
  *envpointer=system_getenvoffset();
---------------------------------------------------------------------------
***************************************************************************
 <i86.h>
---------------------------------------------------------------------------
 < - scrapped - >
 Function:
  int int386(int Intnum,REGS *inregs,REGS *outregs);

 Description:
 < - scrapped - >

 Example:
  inregs.x.eax=0x4c00;
  int386(0x21,&inregs,&outregs);
---------------------------------------------------------------------------
***************************************************************************
 <stdlib.h>
---------------------------------------------------------------------------
 Function:
  void *malloc(int size);

 Description:
  allocates the defined amount of memory, i think it complies with the
  standard ansi-c malloc even :). ohwell it SHOULD work.
  NOTE: if you have overwritten "secure" memory and you call this then your
        program will terminate directly. just for security reasons.

 Example:
  *memoryptr=malloc(1000);
---------------------------------------------------------------------------
 Function:
  void *calloc(int size);

 Description:
  works as malloc described above, but also clears the allocated memory

 Example:
  *memoryptr=calloc(1000);
---------------------------------------------------------------------------
 Function:
  void exit(errcode);

 Description:
  exits with the exitcode errcode, this code is the same as in ah=4ch int 21h
  and the visible to dos. as you can guess it will not return.

 Example:
  exit(1);
---------------------------------------------------------------------------

3.6-Doing this with dos32?
  it did work but now i scrapped dos32 support due to the fact that the dos32
  linker is _R E A L L Y_ dumb.

Did i mention my english sucks?
                                  / Jonas Lund aka Whizzter of woorlic
