Using XMS in QB

This article was written by Fling-master

This tutorial will give you a start to programming routines for the Extended Memory Specification, or XMS. Please note that this is for advanced QB programmers only! I also expect you know some basic assembly. If not than I would suggest not reading this. Don't say I didn't warn you! =) Now that that's out of the way, I can begin.

Is your game, utility, or whatever running out of memory? Do you get all red in the face when QuickBASIC stops your program and displays the "Out of memory" error? If so then XMS is for you. XMS gives you huge amounts of memory which is limited by your computers RAM. This will usually be enough for most QB programs. "Great," you say "So how do I use it then?" Well first you need to find out if your computer has XMS. (I feel sorry for you if it doesn't.) This is determined via interrupt 2Fh. The following example routine will check if it exists, initialize it for use, AND return the version installed:

XMSInit PROC
 mov ax,4300h                        ;This function lets us detect XMS
 int 2Fh                             ;Use interrupt 2Fh.
 cmp al,80h                          ;If AL isn't 80h then XMS is not present!
 jne NoXMS
 mov ax,4310h                        ;Since XMS is present lets get the version number
 int 2Fh                             ;and the address of the control function.
 mov word ptr [XMSControl],bx        ;XMSControl must be a DWORD.
 mov word ptr [XMSControl+2],es
 xor ax,ax                           ;Now run function 00h which returns the version.
 call [XMSControl]                   ;Call the XMS Control function.
 ret
NoXMS:
 mov ax,-1                           ;If there's no XMS driver we return a -1 to QB.
 ret
ENDP XMSInit

If you found that confusing the read the comments carefully. There's a funny thing about the version number returned. If you try to print it, it won't be the right number. Use this code to fix that:

XMSversion$ = str$(version% / &H100)+"."+str$(version% AND &HFF)

That will return the version as a string. version% would be the number returned by the above function. If you don't have version 3.0 or later than these functions I'm showing you might not work.

Now wouldn't you like to know how much memory is available to you? Well there's a function for that. Function 08h. It returns the largest free block in kb into AX, and the total free memory in kb into DX. Here's an example routine:

XMSInfo PROC freemem:WORD, totalmem:WORD
 mov ah,08h                          ;Use function 08h
 call [XMSControl]                   ;Call the API
 mov bx,totalmem                     ;Put the value in DX in totalmem.
 mov [bx],dx 
 mov bx,freemem                      ;Put the value of AX in freemem
 mov [bx],ax
 ret
ENDP XMSInfo

That will return the available memory in freemem and the total memory in totalmem. One thing about the above routine, it won't show an amount greater than 64MB. There is a function which will but I'm not showing you it now. I want you first to understand how it all works. Next issue you'll see. =P

Ok now, to actually use XMS you have to allocate a block of it. That is, you have to tell the computer that you want x amount of XMS for use in your program. We can do that via function 09h. With this routine it is not possible to allocate over 64MB or memory. There is a routine for it but I'll show you it next issue. Before you call the routine you have to have the amount of kb you want to allocate in DX. After you call it AX will be 0001h if it was successful. If not 0000h is returned. DX will also return the 16-bit handle of the allocated block. "Handle? What the heck!?" The handle you get is your "password" to accessing the block of memory. So when you allocate memory make sure that you keep the handle! There is no way to get it back and worse, you can't deallocate the block without it! Then other programs won't be able to use that block until you restart your computer! So before I get ahead of myself, here's an example routine to allocate a block:

XMSAlloc PROC kb:WORD
 mov ah,09h                         ;Use function 09h
 mov dx,kb                          ;Move kb into DX.
 call [XMSControl]                  ;Call the API
 cmp ax,0001h                       ;Is AX = 0001h? If it is then it worked!
 jne AllocErr                       ;If it isn't then . . . too bad! =P
 mov ax,dx                          ;Move the handle into AX so its returned.
 ret
AllocErr:                           ;Since we can't get a handle if it didn't work we don't
 ret                                ;want DX to get into AX.
ENDP XMSAlloc

There ya go! That will allocate up to 64MB. So lets find out how to deallocate a block of memory.

Deallocating isn't that hard. It basically works the same way. We need to make use of function 0Ah for it. DX must hold the handle of the allocated block to be freed up. After called AX will have 0001h in it if successful. If not the its 0000h. Here's the code:

XMSDeAlloc PROC handle:WORD
 mov ah,0Ah                         ;Use function 0Ah
 mov bx,handle                      ;Put the handle into DX
 mov dx,[bx]
 call [XMSControl]                  ;Call the API
 ret
ENDP XMSDeAlloc

Pretty simple ain't it? Now if used as a function it'll return 0001h if successful.

Now you've probably asked yourself: "How do I know what error occurs?" Well every XMS function will return an error code into BL if an error happened. There's quite a few error codes so I'll put 'em in a nice table for you all to see!

Some of those errors won't apply here so you can ignore them. (Like the ones dealing with the A20 line.) What you could do is make the routine check if an error occured and then it could return that to QB. Although you don't have to.

Alright, now comes moving between XMS and QB. To do this you have to define a data structure at the beginning of your assembly source file like the one below:

MoveXMS struc		            ;Our main XMS data structure
  Len		dd ?		    ;number of bytes to transfer
  SHandle	dw ?		    ;handle of the source block
  SOffset	dd ?		    ;offset into the source block
  DHandle	dw ?		    ;handle of the destination block
  DOffset	dd ?		    ;offset into the destination block
MoveXMS ends

XMSmove MoveXMS ?                   ;This makes it so we can use it =)

Using this structure we'll be able to specify what variable you want to move from QB to XMS and vice-versa. The best way to explain this I think is with an example. This sample routine will let you move data from QB to XMS:

XMSPut proc handle:WORD, segm:WORD, offs:WORD, bytes:DWORD, XMSoffs:DWORD
 mov eax,bytes			   ;Get the length of the data to move into Len
 mov XMSmove.Len,eax
 mov XMSmove.SHandle,0000h         ;SHandle must be set to 0000h to move TO XMS.
 mov bx,offs                       ;Now we move the offset of the variable to SOffset.
 mov word ptr [XMSmove.SOffset],bx
 mov bx,segm                       ;Then the segment goes to SOffset+2
 mov word ptr [XMSmove.SOffset+2],bx
 mov bx,handle                     ;Now we must move the destination handle. This is the
 mov XMSmove.DHandle,bx            ;handle which we're moving the data to.
 mov eax,XMSoffs                   ;This is the location in the specified handle to move
 mov XMSmove.DOffset,eax           ;the data to.
 mov si,Offset XMSmove             ;Now we get the offset address of the data structure into SI
 mov ah,0bh                        ;And make sure that we call function 0Bh
 call [XMSControl]                 ;Now call the XMS driver to move the data.
 ret
endp XMSPut

There. That will correctly move data from a variable, array, whatever in QB to the specified XMS handle. DON'T use this function unless you've allocated a block! If the move was successful AX will return 0001h or else it returns 0000h. I would make this routine a function so that you can tell from QB if it was successful or not. If that was too complicated for you than just go over it again slowly until you get it. Now, how do we move data from XMS to a variable in QB? Well we really only have to change a little bit of the above code:

XMSGet proc handle:WORD, segm:WORD, offs:WORD, bytes:DWORD, XMSoffs:DWORD
 mov eax,bytes                     ;Get the length to move into Len.
 mov XMSmove.Len,eax
 mov bx,handle                     ;Get the handle of the XMS block with the wanted data into
 mov XMSmove.SHandle,bx            ;SHandle as XMS is now the source.
 mov eax,XMSoffs                   ;Also get the offset into the handle into SOffset.
 mov XMSmove.SOffset,eax
 mov XMSmove.DHandle,0000h         ;DHandle must be 0000h so that we can pass the segment and
                                   ;offset of a QB variable to DOffset.
 mov bx,offs                       ;Get the offset of the QB variable.
 mov word ptr [XMSmove.DOffset],bx
 mov bx,segm                       ;And the segment.
 mov word ptr [XMSmove.DOffset+2],bx
 mov si, Offset XMSmove            ;Now get the offset of the data structure into SI.
 mov ah,0bh                        ;Use function 0Bh
 call [XMSControl]                 ;Call the API!
 ret
endp XMSGet

That will return the same as the other function into AX depending on what happened. As you probably saw we just used function 0Bh like before just we switched some things around. Not that hard, eh? Now all that's left for me to show you this issue is how to Reallocate a XMS block. This is handy if you need more memory for your game or something, I really don't know =). To reallocate a block you call subfunction 0Fh. Heres the commented code:

XMSReAlloc proc handle:WORD, kb:WORD
 mov ah,0Fh                        ;Use subfunction 0Fh
 mov bx,handle                     ;Get the handle to deallocate into DX.
 mov dx,[bx]
 mov bx,kb                         ;Get the new amount to resize the handle to into BX.
 call [XMSControl]                 ;Call the API.
 mov bx,handle                     ;Return the handle to QB.
 mov [bx],ax
endp XMSReAlloc

As you can see it's pretty similar to the allocation routine. This like the allocation routine will only allocate up to 64MB. There is a routine that'll allow more (up to 4GB) but I want you to understand these first before you dive in. And thats all I have to say for this issue. Next issue I'll show you the other allocation routines and we'll combine this into a lib you can use. If you still don't understand any of this than don't hesitate to e-mail me!