Link Library Documentation

In printings 1-6, the documentation for the book's link library (IRVINE.LIB) in Appendix E is not as complete as it should be. The following documentation was taken directly from the library source code, and explains how to call each of the procedures.

Recent Additions: WritelongHex, DumpMem, DumpRegs, DumpStack, ReadHex
Recent Revisions: Get_Commandtail, ReadInt, ReadLong, Seconds_today

Last update: 03/27/02

Note: Before calling the functions in this library, initialize the DS register to the start of the data segment:

  mov ax,@data
  mov ds,ax

Close_file
Close a file handle. Input: BX = file handle.

Clrscr
Clears the entire screen and locates the cursor at row 0, column 0. No parameters. Works only on video page 0, in text mode.

Create_file
Create a new file using a given filename. Input parameter: DX = offset of filename. Output: AX = file handle

Crlf
Writes a carriage return / linefeed sequence (0Dh,0Ah) to standard output.

Delay_seconds
Causes the program to pause for n seconds. Input parameter: EAX contains the number of seconds.

DOS_error
Writes an error message to the standard error output device (the console). Input parameter: AX contains an MS-DOS error code.

DumpMem
Displays a range of memory. Input parameters: SI = starting offset, BX = unit size, CX = number of units to display. Great for debugging! For example, the following displays var1 as 5 bytes:

var1 DB 1,2,3,4,5
.code
mov si,offset var1
mov bx,1                  ; byte format
mov cx,5                  ; display 5 units
call DumpMem

Sample output:

Dump of offset 00000000 
01 02 03 04 05

DumpRegs
Displays the 32-bit registers and flags. No input parameters. Great for debugging! Sample:

  EAX=00000619  EBX=00000001  ECX=00000005  EDX=00000598
  ESI=0000000C  EDI=00000100  EBP=0000091E  ESP=00000100
  EIP=00000014  EFL=00003212  CF=0  SF=0  ZF=0  OF=0

DumpStack
Displays n 16-bit stack entries in hexadecimal, starting from the stack pointer's current location. Input parameter: CX contains n.

Get_Commandtail
Gets a copy of the DOS Command Tail at PSP:80h. Input parameter: DS:DX points to a buffer that will receive a copy of the Command Tail as a null-terminated string.

Get_Deviceparms
Get the Device BPB table for a disk drive, found in its device driver. Input parmeters: BL = drive number (0 = default drive, 1 = A, 2 = B, etc.). Output: AX points to a ParameterStruc (structure) where DOS stores the device information.

Get_Diskfreespace
Returns the amount of free space on a selected drive. Input: AL = drive (0=A, 1=B, 2=C). Output: DX:AX = free space.

Get_Disksize
Returns the size (in bytes) of a specified disk drive. Input parameters: AL = drive number (0=A, 1=B, 2=C, etc.). Output: DX:AX = disk space.

Get_time
Get the current system time.Input parameter: DS:SI points to a TimeRecord structure.

Gotoxy
Locates the cursor at row, col on video page zero. Input parameters: DH = row, DL = column.

Open_infile
Open a file for input. Input parameter: DX = offset of ASCIIZ file name. Output: AX = file handle.

Open_outfile
Open a file for output. Input parameter: DX = offset of ASCIIZ file name. Output: AX = file handle.

PackedToBin
Convert the BCD value in AL to a binary byte, which is returned in AL.

Randomize
Reseeds the random number generator. No input or output required.

Random_range
Return an unsigned pseudorandom 32-bit integer in EAX, between 0 and n1. Input parameter: EAX = n.

Random32
Return an unsigned pseudorandom 32-bit integer in EAX,in the range 0 to FFFFFFFFh.

Readchar
Reads a single character from standard input without echoing the character or waiting for input. Output: If a character was found, ZF = 0 and AL contains the character. If no character was found, ZF = 1.

ReadHex
Reads a 32-bit hexadecimal integer from standard input. Output: returns the binary value in EAX.

Readint
Reads a 16-bit signed decimal integer from standard input, in the range 32768 to +32767. Skip leading spaces. Returns the binary value of the number in AX. The Overflow flag is set if the signed integer is out of range; otherwise, the Overflow flag is clear.

Readkey
Waits for a key until one is pressed. Returns the scan code in AH and the ASCII code in AL. Cannot be redirected.

Readlong
Reads a 32-bit signed decimal integer from standard input, stopping when the Enter key (0dh) is read. Converts the value to signed binary. Leading spaces are ignored. Returns: EAX contains a binary integer. The Overflow flag is set if the signed integer is out of range; otherwise, the Overflow flag is clear.

Read_record
Read a block of data from an input file. Input parameters: DX points to input buffer, BX = file handle, CX = number of bytes to read.

Readstring
Uses INT 21h to read a string from standard input, stopping when 0Dh is found. Input parameters: DS:DX points to the input buffer, CX = maximum characters that may be typed. Output: The buffer is initialized to an ASCIIZ (null-terminated) string, and AX = size of the input string.

Scroll
Scrolls all lines in a prescribed window. No range checking is performed on the input parameters:
    CH    Row of the window's upper left corner
    CL    Column of the window's upper left corner
    DH    Row of the window's lower right corner
    DL    Column of the window's lower right corner
    BH    Attribute/color of the scrolled lines

Seconds_today
Returns a count of the number of seconds that have elapsed today. Output: EAX contains the return value.

Seek_eof
Move the DOS file pointer to the end of file. Input: BX = file handle of an open file Output: DX:AX = new file pointer offset.

Seek_record
Move the DOS file pointer to a specific record in a file. Input parameters: AX = record number, BX = file handle, CX = record length. Output: DX:AX = new file pointer offset.

Set_videoseg
Set the current video segment address (the default is B800h). Input parameter: AX contains the segment address value.

Show_time
Write a TimeRecord structure in 24-hour military format to standard output. Input: DS:SI points to the structure.

Str_compare
Compares a string pointed to by DS:SI (called 'first') to a string pointed to by ES:DI (called 'second'). The comparison is case-sensitive, and the Flags register is affected as follows:
    first < second     CF=1, ZF=0
    first = second     CF=0, ZF=1
    first > second     CF=0, ZF=0

Str_copy
Copies a null-terminated source string to a destination string. Input parameters: DS:SI points to the source and ES:DI points to the destination. No range checking is performed on the destination.

Str_length
Returns the length of a null-terminated string. Input parameter: ES:DI points to the string. Output: AX contains the string length.

Str_ucase
Converts a null-terminated string to upper case. Input parameter: DS:SI points to the string.

Waitchar
Reads a single character from standard input without echoing the character. Waits for input. Input parameters: none. Output: AL contains the character.

Writebcd
Writes the ASCII representation of a packed BCD byte to standard output. Input parameter: AL contains the BCD byte. Also works for binary hexadecimal bytes.

Writechar
Write a character to standard output, using INT 21h. Input parameter: AL = character.

Writechar_direct
Write a character directly to video RAM. Input parameters: AL = character, AH = attribute, DH/DL = row, column on screen (0-24, 0-79).

Write_errorstr
Write a string to the standard error output device (the console). Input parameter: DS:DX points to a null-terminated string.

Writeint
Writes a 16-bit unsigned binary integer to standard output. Input parameters: AX = integer value, BX = radix.

Writeint_signed
Writes a signed binary integer to standard output in ASCII decimal. Input parameter: AX = integer value.

Writelong
Writes an unsigned 32-bit integer to standard output. Input parameters: EAX = integer value, and EBX = radix.

WritelongHex
Writes an unsigned 32-bit integer to standard output in hexadecimal with leading zeros. Input parameter: EAX = the integer to write.

Writestring
Writes a null-terminated string to standard output. Input parameter: DS:DX points to the string.

Writestring_Direct
Write a string directly to video RAM. Input parameters: DS:SI points to a null-terminated string, AH = attribute, DH/DL = row/column on the screen (0-24, 0-79).

Data Structures

TimeRecord

TimeRecord struc
  hours db ?
  minutes db ?
  seconds db ?
  hhss db ?
TimeRecord ends

ParameterStruc

ParameterStruc struc 
  specialFunctions db ?
  deviceType db ?
  deviceAttributes dw ?
  numberCylinders dw ?
  mediaType db ?
  bytesPerSector dw ? 
  sectorsPerCluster db ?
  reservedSectors dw ?
  numberOfFATs db ?
  maxRootDirEntries dw ?
  numberOfSectors dw ?
  mediaDescriptor db ?
  sectorsPerFAT dw ?
  sectorsPerTrack dw ?
  numberOfHeads dw ?
  numHiddenSectors dd ?
  numberSectorsLong dd ?       ; used if numberOfSectors = 0
  reservedBytes db 6 dup(?)
  trackLayout dw 40 dup(0)     ; specific track data
ParameterStruc ends