WelcomeLib Page | of 14 On-Line Documentation for the Invine Library ASSEMBLY | LANGUAGE FOR INTEL-BASED. COMPUTERS Summaries of the procedures in the Irvine libraries. About. Clrscr PROC Clears the screen by writing blanks to all positions. call args: None Return arg: None Example: call Clrser crlf PROC Writes a carriage return/linefeed sequence (0Dh,0Ah) to standard output, call args: None Return arg: None Example: call crit Delay PROC Delays (pauses) the current process for a given number of milliseconds. call args: AX = number of milliseconds Return arg: None Example: mov eax, 10 call Delay lelay 1 sec file:///C:/Users/Carlos%20Vasquez/AppData/Local/Temp/~hh3653.htm 25/5/2019WelcomeLib Page 2 of 14 Notes: The 16-bit library version runs only on Windows 95, 98, and MB. Because the 16-bit version directly accesses hardware ports, it will not run under Windows NT, ox XP DumpMem PROC Writes a range of memory to standard output in hexadecimal. call args: SI = starting offset ECX = number of units EBX - bytes/unit (1,2,or 4) Return arg: None Example: Dum a word array data array WORD 8,9,10,11,0FFFEn code mov esi,OPFS8T array mov cx, LENGTHOF array ;5 mov bx, TYPE array 32 call Dumpéem output; Dump of offset oado4aoa 0008 0009 G00A OG0B FEFF Note: The mDumpMem macro causes a call to this procedure. DumpRegs PROC Displays the EAX, EBD ECX, EDX, ESI, EDL, EBP, ESP, EIP, and EFL registers in hexadecimal. Also displays the Carry, Sign, Zero, and Overflow flags. EIP displays the offset of the instruction which follows the call to DumpRegs. cali args: None Return arg: None Example: call DumpRegs Sample output: EAX=0000 ESI-9184C544 EL EDX=BEEC94CO ESP-D063FE3C 2E=0 OF=0 GetCommandtail PROC Copies the tail of the program command line into a 129-byte buffer (after stripping off the first argument - the program's name). Each command line argument is followed by a space and the last argument is followed by both a space and a null. file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 3 of 14 call args: EDX points to receiving buffer Return arg: CF=1 if no command tail cP=0 if tail not null Example: data tailBuf BYTE 129 DUP code mov eds, OFFSET talleur call GetCommandtail je nofail iprocess tail noTail: GetDateTime PROC (Not available in 16-bit library) Gets and saves the current local date/time as a 64-bit integer (in the Win32 FILETIME format). The date/time is measured in 100ns intervals since January 1, 1601. call args: Dx points to 1 ving buffer (FILETIME STRUCT format) Return arg: The current date/time is stored in the structure pointed to by EDX. Example: FILETIME STRUCT (in Smallwin.ine) lopateT Line DWORD hibateTime DWORD FILETIME ENDS data dateTime PILBTIME <> code. Im KE GetDateTime, ADDR dateTime GetMaxxY PROC Returns the current number of columns X and rows Y in the sereen’s console window buffer. ‘The range of each is 0-255. For the default screen 80x25, X=80, and Y=25. ‘These values can change while a program is executing if the user modifies the properties of the application window. Use in conjunction with the coo. procedure (the maximum argument values when calling Gotoxy are DL=(X-1) and DH=(Y-1). call args: None Return args: DL = Current number of columns DH = Current number of rons Example: Locate the cursor in the lower right corner of the screent call GetMaxxy dec al jhighest column number dec dh jhighest row number = Y-1 file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 4 of 14 jto position the cursor GetMseconds PROC Returns the number of milliseconds that have elapsed since midnight. Resolution is 10ms under Windows NT/ 2000/ XP; and is 55ms (average) under Windows 98/ ME. call args: None Return arg: EAK = ((hours*3600) + (minutea* 60) + (seconds) }*1000 + milliseconds Example data msec DWORD ? code call GetMseconds Gotoxy PROC Locates the cursor at a given row and column in the screen's console buffer. ‘The values passed in DH and DL can range from 0 to X-1 and from 0 to Y- number of columns and Y is the number of rows in the console buffer. ‘The default window size is 80 x 25 but it can be set to a different size. Use the = 10-307 procedure to obtain the size of the screen's console buffer. If the console buffer is set larger than the display window, the window repositions itself automatically to display the cursor position. . Where X is the call args: 01 DH column row Return arg: None Example: Locate the cursor in the lower right corner of an 80 x 25 screen mov dl, 79 Lum mov dh,24 j;row call Gotoxy Note: The mGotoxy macro causes a call to this procedure IsDigit PROC Determines whether the character in AL is a valid decimal digit. call args: AL = character Return arg: 2F=1 valid digit 0 not a valid digit Example data achar BYTE 7 scode file:///C:/Users/Carlos%20Vasquez/AppData/Local/Temp/~hh3653.htm 25/5/2019WelcomeLib Page 5 of 14 moy al, achar call IsDigit jnz notDigit a pprocess digit notDigit: Random32 PROC Generates an unsigned pseudo-random 32-bit integer in the range of 0 through FFFFFFFFh. call args: None Return arg: EAK = random (0 to FFFFFFEFh) Example: data ranNum DWORD ? code call Random3 moy ranNum,eax ;save Notes: To re-seed the random mmber generator, use the Randomize procedure. To specify a range for the random number, use the BandowRange procedure. Randomize PROC Re-seeds the random number generator with the current time in hundredths of seconds. call args: None Return arg: None Example: call Randomize ;re-seed generator Note: The value of the new seed is used by the Randow32 and RandomRange procedures. RandomRange PROC Generates an unsigned pseudo-random 32-bit integer in the range of 0 through (n-1). call args: FAX n, the range Return arg: 5A) random (0 to n-=1) Example: Get a random number from 1 to 1¢ sdata ranNum DWORD ? code mov eax, 100 jget random 0 to 99 call RandomRange ; inc eax imake range 1 to 100 mov ranNum,eax save random number file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 6 of 14 Notes: To re-seed the random number generator, use the Random: To generate a 32-bit random number, use the Randoms procedure. dure. ReadChar PROC Reads a single character from standard input and returns the character in the AL register. ‘The character is not echoed on the screen. Waits for the character if none is currently in the input buffer. call args: one Return arg: AL = ACSII code Example: data arin BYTE ? wcode call ReadChar mov charIn,al ReadDec PROC Reads a 32-bit unsigned decimal integer from standard input, stopping when the Enter key is pressed. All valid digits occurring before a non-numeric character are converted to the integer value. Leading spaces are ignored. call args: None Return args: If CF-0, EAX = valid binary value, and SF=sign. If CF+1, BAX - 0 input is invalid (blank or larger than 2°32-1) Example: sdata decNum Di ? promptBad BYTE "Invalid input, please enter again",0 code read: call ReadDec ine goodInput mov eds, OFFSET promptBad call writestring imp read go input again gooaznput mov decNum,eax j store good value Notes: To read a signed integer, use the Readint procedure To read in hexadecimal, use the Readlex procedure. ReadHex PROC Reads a 32-bit hexadecimal integer from standard input, stopping when the Enter key is pressed. No error checking performed for bad digits or excess digits. You can use both uppercase and lowercase letters for the digits A through F. A maximum of eight digits may be entered. file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 7 of 14 Leading spaces are not permitted. call args: None Return arg: FAX — binary integer value Example: data hexNum DWORD ? code call Readtex mov hexNum, eat Notes: To read an unsigned integer, use the ReadDec procedure. To read a signed integer, use the ReadInt procedure. ReadInt PROC Reads a 32-bit signed decimal integer from standard input, stopping when the Enter key is pressed. All valid digits occurring before a non-numeric character are converted to the integer value. Leading spaces are ignored, and an optional leading + or - sign is permitted. ReadInt will display an error message, set the Overflow flag, and reset EAX to zero if the value entered cannot be represented as a 32-bit signed integer. call args: None Return args: If OF=0, valid binary value, and SF=sign Tf OF-1, 0 (invalid input) Example: wdata intNum — DWORD 2 promptBad BYTE "Invalid input, please enter again",0 scode read: call ReadInt Jno goodInput mov eds, OFFSET promptBad call writestring jmp read igo input again goodinput: mov intNum,eax jstore good value Notes: To read an unsigned integer, use the ReadDec procedure. To read in hexadecimal, use the Readticx procedure: ReadKey PROC (Not covered in the 4th edition) Performs a no-wait keyboard check and reads a single character if available. If the returned ASCII code is zero, special keys can be processed by checking the virtual sean code (ah) and virtual key code (dx). call args: None. file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 8 of 14 Return arg: ZF-1 if no key is available, 2P=0 if a key is read into the following registers: key's Ascii code (is set to zero for special extended codes) = Virtual scan code Virtual key code EEX = Keyboard flags (Alt,Ctr1,Caps, ete.) Upper halves of FAX and EDX are overwritten. Example: INCLUDE Irvine32. ine INCLUDE Macros. ine main PROC ; Read and display each key until is input. niveiteLn ™ call crlf II Virtual-scan Virtual key Keyboard flaga” LookForkey: mov eax, 50 : sleep, to allow OS to time slice call Delay i (otherwise, some key presses are lost) call Readkey } look for keyboard input jz LookForkey } no key pressed yet mshow al,h ah,h dx, h mshow ebx,hnn cmp dx, VK_ESCAPE ; time to quit? jne LookFork ono, go get next ke exit main ENDP END main Output when Fl, Shift-Pl, Ctrl-Pl, Alt-F1, and keys are input: CIL Virtual-scan Virtual-key Keyboard flags al = 00h ab = 28h dx ebx 00008 al = 00h ah = 54h bx 0010h al - ah = 58h eb = D0dk al = 00h ah = 68h ebx = po000003n al =1Bh ah = 01h ebx = 000000008 Notes: To walt for and read a single character from standard input, use the ReadChar procedure ReadString PROC Reads a string of up to ECX non-null characters from standard input, stopping when the user presses the Enter key. A null byte is stored following the characters input, but the trailing carriage return and line feed characters are not placed into the buffer. ECX should always be smaller than the buffer size (never equal to the buffer size) because the null file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 9 of 14 byte could be the (ECX+1)th character stored. call args: EDX pointe to the input buffer ECX max number of non-null chars to read Return arg: FAX = size of input string. Example data MAK = 60 imax chars to read stringIn BYTE MAX+1 DUP ixoom for null code. mov ex, OFFSET stringIn mov ecx,MAL jbuffer size - 1 call Readstring dure. Note: The mkeadstr macro causes a call to this pr SetTextColor PROC (Not available in the 16-bit library) Changes the color of all subsequent text output. call args: =AX = Bits 0: Bits 4-7 foreground color background color Return arg: None Example: Set for yellow text on blue background INCLUDE Irvine32.inc ;for color definitions mov eax, yellowt(blue*16) call SetTextColor Note: The colors defined in Irvine32.inc are: black, white, brown, yellow, blue, green, cyan, red, magenta, gray, lightBlue, LightGreen, lightCyan, lightRed, lightMagenta, and lightGray, Str_compare PROC Compares two null-terminated strings. ‘The Zero and Carry flags are affected exactly as they would be by the CMP instruction, call args: ADDR stringl, ADDR string2 Return arg: if stringl = string2 if stringl > string2 if etringl < string2 Example: wdata string] BYTE "hello",0 string? BYTE "hellx",0 scode INVOKE Str_compare, ADDR string1, ADDR string2 file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 10 of 14 je equal vjump if string] = string2 ja st_larger jjump if stringl > string2 jb sl_smaller ;jump if stringl < string2 Str_copy PROC Copies a null-terminated string from a source location to a target location. ‘The target operand must be large enough to hold the copied string. call args: ADDR source, ADDR target Return arg: None Example: data source BYTE "hello",0 target BYTE SIZEOF source DUP (2) code INVOKE Str_copy, ADDR source, ADDR target Str_length PRoc Returns the length of a null-terminated string in EAX. call arg: ADDR string Return arg: EAX — number of non-null bytes Example data string BYTE "hello", length DWORD ? code INVOKE Str_length, ADDR string mov length, eax Str_trim PROC Removes all occurrences of a given trailing character from the end of a null-terminated string. call args: ADDR string, character Return arg: onc Example wdata string BYTE “hellofworla#s##", 0 ar BYTE '#* INVOKE Str_trim, ADDR string, char file:///C:/Users/Carlos%20Vasquez/AppData/Local/Temp/~hh3653.htm 25/5/2019WelcomeLib Page 11 of 14 ;string now contains: "hello#world",0 Str_ucase PROC Converts a null-terminated string to all upper case characters. call args: ADDR string Return arg: None Example: sdata string BYTE "Hello",0 code INVOKE Str_ucase, ADDR string string now contains: "HELLO", 0 WaitMsg PROC Displays the prompt "Press [Enter] to continue..." and waits for the user to press the Enter key’ Use to pause the current program. call args: None Return arg: None Example: call Waitéeg WriteBin PROC Writes a 32-bit integer to standard output in ASCII binary format. ‘The binary bits are displayed in groups of 4 for easy reading. call args: EAX = the integer to write Return arg: None Example eax, 1234ARCDn output: 1010 1011 111 Note: To write a WORD or BYTE in binary, use the WiteBine pro edure or the mshov WriteBinB PROC (Not covered in the 4th edition) Writes an unsigned 8, 16, or 32-bit number to standard output in ASCII binary format. EBX must contain the TYPE of the number to write (1 for BYTE, 2 for WORD, or 4 for DWORD) ‘The binary bits are displayed in groups of 4 for easy reading. file:///C:/Users/Carlos%20Vasquez/AppData/Local/Temp/~hh3653.htm 25/5/2019WelcomeLib Page 12 of 14 call args % - the number to write. ite AL as 8 binary digits, to write AX as 16 binary digits, to write BAX ae 32 binary digits Return arg: None Example: «data bvalue BYTE ‘At code moy eax,bValue mov ebx, TYPE bValue call WriteBing Output: Notes: To write a DNORD, the Writebin procedure may also be used To write in hexadecimal, use the WriteHex® procedure. The mShow macro causes a call to this procedure. WriteChar PROC Writes a single character to standard output. Gall args: AL = the character to write Return arg: None Example: mov al, "$* call Writechar WriteDec PROC Writes an unsigned 32-bit decimal number to standard output in decimal format with no leading zeros. call arg: FAX = unsigned number to write Return arg: None Example: mov eax, 12345 call WriteDe output: 123456 Notes: To write a signed integer, use the jiriteInt procedure. To write in hexadecimal, use the Writelicx procedure. To write in binary, use the WriteBin procedure Use the mShow macro to display the contents of an 8-, 16-, or 32-bit variable or register in any combination of hexadscimal, signed decimal, unsigned decimal, or binary formats WriteHex PROC file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 13 of 14 Writes an unsigned 32-bit hexadecimal number to standard output in 8-digit hexadecimal format, Leading zeros are inserted if necessary. This procedure is useful for printing the result of a multi-double-word precision arithmetic operation. call args: BAX = unsigned number to write Return arg: None Example: mov eax, 7EFFEh call WriteHex Output: O007FEEF Notes: To write a WORD or BYTE in hex, use the Wri macro. To write in binary, use the WriteBin procedure To write an unsigned integer, use the WriteDec procedure To write a signed integer, use the jiriteInt procedure. lexB procedure or the mShow WriteHexB PROC = (Not covered in the 4th edition) Writes an unsigned &, 16, or 32 bit mmber to standard output in hexadecimal format EBX must contain the TYPE the number to write (1 for BYTE, 2 for WORD, or 4 for DWORD). Leading zeros are inserted if necessary call args: or EAM = uneigned number to write. to write AL as 2 hex digits, to write AK as 4 hex digits, to write BAK as @ hex digits. Return arg: None Example: data bvalue BYTE ‘At code mov eax,bValue mov ebx, TYPE bValue call WriteHexs output: 41 Notes: To write a DWORD, the WriteHex procedure may also be used To write in binary, the WEiteBinB procedure. The mShow macro calises a call to this procedure. WriteInt PROC Writes a signed 32-bit decimal number to standard output in decimal format with a leading sign and no leading zeros igned number to write file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019WelcomeLib Page 14 of 14 Example: mov eax, 216543 call WeiteInt output: 4216543 NOTES: To write an unsigned integer, use the WriteDec procedure. To write in hexadecimal, use the writeHiex procedure. To write in binary, the WiteBin procedure. Use the mShow macro to display the contents of an 8-, 16-, or 32-bit wiable or register in any Combination of hexadecimal, signed decimal, unsigned decimal, or binary formats. WriteString PROC Writes a null-terminated ring to standard output. ED! points te string Return arg: None Example: data prompt BYTE "Enter your name: 7,0 code moy edx, OFFSET prompt call Writestring Note: The mijritestr macra causes a call to this procedure file:///C:/Users/Carlos?20Vasquez/AppData/Local/Temp/~hh3653.htm_ 25/3/2019