Machine Problem 1

Introduction

For this machine problem, you will write the algorithm to automate the game of 'Word Find'. This type of game, which is often found in newspapers or airline magazines, requires locating words in a matrix of letters. Words may appear in any direction, and (for this game) may even wrap around the edges.

Your code, if written properly, should be able to locate a word in such a game in a sub-millisecond, and thus easily beat any human player. As an optimized assembly-language program, the fastests program written for this class will become known as Deep 306.

Algorithm Description

Program Operation

The word to search for is entered on the command line.
If you are using a CMD shell and want to search for CSE306, type
MP1 CSE306.
If you are using a Cygwin bash shell and want to search for CSE306, type
./MP1 CSE306.
A sample run from the program is shown below:

H:\cse306\mp1>MP1 CSE306

------------- Original matrix ------------
EHUBBCLQMI
TI9ABSPUSS
ADUSLEAAAT
LDPSE3TKME
LCSE306EER
LNHMK6UKTA
ADDBINARYM
CAILLIX3BU
COLYLDOOWK
OOEDIVHEXR
MOODNIBBLE
MENTIMESEG

-------------- Final matrix --------------
.....C....
.....S....
.....E....
.....3....
.CSE306...
.....6....
..........
..........
..........
..........
..........
..........


LIBMP1 Ver 1.0 Calls: 
 -PrintMatrix 
 -CheckLetter 
 -CheckUp 
 -CheckDown 
 -ReplaceDown 
 -CheckLeft 
 -CheckRight 
 -ReplaceRight 

Run the program a few times to learn how it operates. Try searching for other words like: 'BINARY', 'NIBBLE', 'SEGMENT', 'VIDEO', 'REGISTER', and the number '3' (case matters). Note that words my wrap around the matrix. Also note that multiple words are found if they appear more than once.

Next, look through the given source code and rebuild the executable from source code by typing NMAKE CLEAN then NMAKE. Now run the program under CodeView. Choose your search word by a click to open the (R)un menu then (S)et Runtime Arguments. Step through the code as you did in MP1. Use the function keys to trace (F8) through your code, step (F10) over library calls, and go (F5) between breakpoints. Review MP0 if you need help with CodeView.

Variables

• OrigMatrix
  The matrix to search through. This array of bytes is defined in the WORDFILE.ASM file. Note that the data is stored sequentially in memory, starting with the first row of bytes.

• NumRows
  A constant defined in the WORDFILE.ASM file that specifies the number of rows in the matrices.

• NumCols
  A constant defined in the WORDFILE.ASM file that specifies the number of columns in the matrices.

• EndMatrix
  The final result of the program. This is another array of bytes equal in size to OrigMatrix. EndMatrix is initialized to dots ('.') and is overwritten with letters when words are found.

• offsetPos
  The current offset of the letter we are checking in the matrix. This variable is used by CheckLetter each time it compares the first letter of the word to a letter in OrigMatrix. Note that the initial value of offsetPos is zero, which is not necessarily the memory location of the variable itself.

• RowPos
  The current row of the letter we are checking in the matrix. Use this variable for bounds checking.

• ColPos
  The current column of the letter we are checking in the matrix. Use this variable for bounds checking.

Procedures

This assignment has ten procedures. You will receive credit by replacing each of these ten procedures listed below with your own code.

• CheckLetter
  • Purpose: Compare the current letter against the first letter in the word to search for.
  • Inputs:
    • origMatrix = Variable holding all letters
    • offsetPos = current position to be checked within origMatrix (an offset from the beginning)
    • The first letter of the command line argument (which is located at ES:[82h])
  • Output: Set the zero flag if letter matches, clear the zero flag otherwise.
  • Hints: :
    • Use offsetPos to calculate an address relative to origMatrix.
    • This should be a very short routine
  • Points: 8
• PrintMatrix
  • Purpose: Prints the matrix onto the screen.
  • Inputs:
    • NumRows, NumCols = width and height
    • SI = offset in memory of beginning of array
      (SI will set to either offset origMatrix or to offset EndMatrix before the routine is called).
  • Output: Screen
  • Hints:
    • Avoid repetitive code by using loops to iterate through the rows.
    • There are free library functions you can use... such as DSPMSG, DSPOUT (see lab manual).
    • Every screen line MUST end with a carriage return and line feed.
  • Points: 10
• Check{Right,Down,Left,Up}
  • Purpose: Once a match is found for the first letter, this function scans origMatrix from that position to see if the entire word is a match in the direction given.
  • Inputs:
    • WordLength = number of characters in the command line (including space at beginning)
    • offsetPos = position of the letter that was matched up
    • RowPos = row position of the letter that was matched up
    • ColPos = column position of the letter that was matched up
  • Output: Set the zero flag if word matches, clear the zero flag otherwise.
  • Hints:
    • Don't forget to account for 1 letter words and wraparound!
    • Write your code in a modular manner to avoid repetition
  • Points: 4 points for each of the four functions (16 points total)
• Replace{Up,Down,Left,Right}
  • Purpose: Once a match is found for word, this function moves the word into the EndMatrix in the direction given.
  • Inputs:
    • WordLength = number of characters in the command line (including space at beginning)
    • offsetPos = position of the letter that was matched up
    • RowPos = row position of the letter that was matched up
    • ColPos = column position of the letter that was matched up
  • Output: Moves data into EndMatrix.
  • Hints:
    • Don't forget to account for 1 letter words and wraparound!
    • Write your code in a modular manner to avoid repetition
  • Points: 4 points for each of the four functions (16 points total)

Preliminary Procedure

• Create a directory under your home (H:) drive called CSE306\MP1
• Download mp1.zip and extract the partial MP1 program (MP1.ASM), the data file (WORDFILE.ASM), libraries (libmp1.lib and lib306.lib), and the Makefile to your MP1 directory.
• Open Windows/DOS Command shell (Start > Run > CMD) or
  open a Cygwin Bash Shell (Click on Desktop Icon)
  • It is helpful to resize the height of the window so that it is taller than 25 lines.
• Change to the directory where you download the files
  • From DOS/Windows, type
    H:
    cd \cs306\mp:
    
  • From Cygwin, type
    cd H:
    cd cs306/mp:
    
• As with MP0, run NMake to build an executable program using the given ECE306 library functions.
• As with MP0, run the program to see how it works. This program uses a command-line argument to specify the string which is searched.
  • From a DOS Command window, type
    MP1 CSE306
    to search for the string 'CSE306'
  • Or, from a Cygwin window, type
    ./MP1 CSE306
    to search for the string 'CSE306'
• Look for other words, like 'BINARY', 'NIBBLE', 'SEGMENT', 'VIDEO', and 'REGISTER' as described above.
• As with MP0, use a text editor to modify the program. As given, the program uses LIBMP1 routines to implement all functionality. To receive credit for the assignment, you must replace all of the subroutines described above with your own code.
• All coding should be your own work. You will be required to sign a statement on the submission page that your work on this assignement is original.

Hints

• The LIBMP1 file contains executable library functions for each of the routines that you need to implement. This allows you to run the program and understand how it works before you implment it. You can test your program with any combinations of your own code and library functions. You will only receive credit, however, for the routines that you implement yourself.
• As with MP0, use CodeView (CV /50) to debug and test your program. Because you only receive credit for procedures that functions entirely as specified (and with all possible types of input), it is best to debug each routine individually. You not earn any points by coding only part of a subroutine.
  • In order to process a string, you will need to enter a command line argument. This can be done from the (R)un menu, using the (S)et RunTime arguments. Try typing the string 'CSE306'
• When referring to memory locations, use symbolic names rather than a numeric address values.
• If you feel that you are repeating code, then STOP. Using modular procedures, you should be able to elimate most of the redundant code in your program. This is most important for the routines Check{Right,Down,Left,Up} and Replace{Right,Down,Left,Up}. The shorter your code, the better!
• START EARLY! This is the first MP that requires you to write your own program. Composition is much mork difficult than comprehension.
• Monitor the Message Board for clarifications and help.

Final Steps

1. Print a copy of the MP1 grading report (MP1GR). Double-check that your program is ready for demonstration before you ask a TA to grade it.
2. Demonstrate your MP1.EXE to a TA or to the instructor. You will then be asked to recompile and demonstrate MP1 with different word files and search terms. Your program must work with all given input.
3. Be prepared to answer questions about any aspect of the operation of your program. The TAs will not accept an MP if you cannot fully explain the operation of your code and details of your implementation. Delayed MPs will be subject to late penalties.
4. Upload MP1 to the GradeBot.

Wordfile.ASM (program framework)

        PAGE 75, 132
        TITLE Deep306 - Your Name - Current Date

COMMENT %
        WordFind
        --------------------
        CSE306: MP1 - WordFinder
        Prof. John W. Lockwood
        Washington University in St. Louis
        Assistant Guest Authors: Pat Spizzo, Neil Kumar
        Spring 2004
        Revision 2.0
        %

;====== Constants =========================================================

CR      EQU 13
LF      EQU 10

;====== Externals =========================================================

; -- LIB306 Routines (free) --

  extrn dspout:near  ; See webpage for a full description
  extrn dspmsg:near  ;    of the lib306 functions
  extrn dosxit:near  ; Exit Program

; -- LIB306 Routines (free) --
  extrn mp1xit:near  ; Terminate MP1

;====== Stack Segment =====================================================
stkseg  segment stack
        db 64 dup ('STACK   ')
stkseg  ends

;====== Code/Data segment =================================================
cseg    segment public 'CODE' 
        assume  cs:cseg, ds:cseg, ss:stkseg, es:nothing

;====== Variables =========================================================

INCLUDE wordfile.asm   ; Define NumRows & NumCols; Create OrigMatrix

EndMatrix db NumRows*NumCols dup ('.')
RowSize   dw NumRows
ColSize   dw NumCols

CommandErrorMessage db 'Usage: mp1 WordToFind',CR,LF,'$' 
StartMessage db '------------- Original matrix ------------',CR,LF,'$'
EndMessage   db '-------------- Final matrix --------------',CR,LF,'$'
crlf db CR,LF,'$'  ; Carriage Return / Line Feed String

WordLength dw ?        ; Length of search word
RowPos dw ?
ColPos dw ?
offsetPos dw ?

PUBLIC OrigMatrix,RowSize,ColSize,EndMatrix ; Variables visible to LIBMP1
PUBLIC WordLength,RowPos,ColPos,offsetPos   ;

; ======== Your Code ======================================================

; -- Write the code for your subroutines below --
; To use your own code,
; comment out the 'extrn' routine from above and
; uncomment your procedure declaration

extrn PrintMatrix:near
; Inputs:
;    si = index to matrix to print

; PrintMatrix proc NEAR
;  For all letters in origMatrix {
;      ..
;    MOV DL,[si]
;      ..
;    Print character to screen 
;      ..
;  }
; PrintMatrix ENDP

extrn CheckLetter:near
; Inputs:
;    offsetPos = position of letter in OrigMatrix to check
; Outputs:
;    zf = zero if letter matches
;    zf = one  if letter does not match 

extrn CheckRight:near
; Inputs:
;    offsetPos = RowPos*NumCols + ColPos
;    RowPos = current row position
;    ColPos = current column position
;    WordLength = length of word to find
; Outputs
;    zf = zero if word matches
;    zf = one  if any letter mismatches 

extrn ReplaceRight:near
; Inputs:
;    offsetPos = RowPos*NumCols + ColPos
;    RowPos = current row position
;    ColPos = current column position
;    WordLength = length of word to find
; Output
;    EndMatrix 

extrn CheckDown:near
; Inputs/Ouputs: Same as CheckRight

extrn ReplaceDown:near
; Inputs/Ouputs: Same as ReplaceRight

; Remaining Directions..
extrn CheckLeft:near
extrn ReplaceLeft:near
extrn CheckUp:near
extrn ReplaceUp:near


;====== Main procedure ====================================================

main    proc    far

        ; The Main body of the program parses the command
        ; line and invokes each subroutine.  You are given this code.

        ; Command line arguments can be set in Codeview
        ; by selecting the (R)un menu, then (S)et args.

        mov  ax, ds  ; Initially, DS holds segment w/command line arguments
        mov  es, ax 

        mov  ax, cseg ; Set DS=CS (Set Default Segment to segment with code)
        mov  ds, ax  

        mov  cl, byte ptr es:[80h]     ; Read Length of Command Line
        cmp  cl, 1                    
        jbe  CommandLineError          ; Terminate program for no input

        mov  ch,0
        dec  CX
        mov  SI,0

CheckNextArgumentLetter:
        CMP BYTE PTR ES:[82h+SI],' '
        JE  CommandLineDone            ; Determine length of first argument
        INC SI                         ; by scanning for a space
        LOOP CheckNextArgumentLetter

CommandLineDone:                       ; Start MP0
        mov  WordLength,SI

        mov  dx, offset StartMessage   
        call dspmsg        
        mov  si, offset OrigMatrix
        call PrintMatrix        
        
        mov  offsetPos, 0              ; Start scanning at top-left 
        mov  RowPos, 0                 ; corner of OrigMatrix.
        mov  ColPos, 0

LetterScanLoop:
        call CheckLetter               
        jne  ProcessNextLetter
        
; First Letter matches, now check for word match in all four directions

        call CheckRight   ; Scan for words going right
        jne  RightChecked    
        call ReplaceRight ; Copy word to EndMatrix if it matches
RightChecked:

        call CheckDown    ; Scan for words going down
        jne  DownChecked  
        call ReplaceDown  
DownChecked:

        call CheckLeft    ; Scan for words going right
        jne  LeftChecked     
        call ReplaceLeft  
LeftChecked:

        call CheckUp
        jne  UpChecked    ; Scan for words going up
        call ReplaceUp
UpChecked:

ProcessNextLetter:
        inc  offsetPos          ; advance to next position
        
        inc  ColPos             ; advance to next column
        cmp  ColPos, NumCols
        jb   LetterScanLoop

ProcessNextRow:
        mov  ColPos,0
        inc  RowPos             ; advance to next row 
        cmp  RowPos, NumRows   
        jb   LetterScanLoop 

; Search has completed
        mov  dx, offset CRLF
        call dspmsg
        mov  dx, offset EndMessage
        call dspmsg        

        mov  si, offset EndMatrix        
        call PrintMatrix
        
        call mp1xit

CommandLineError:
        mov   dx, offset CommandErrorMessage
        call  dspmsg                   
          ; Print Error message and quit if program isn't
          ; called with command line argument
        call dosxit

main    endp

cseg    ends
        end     main

Wordfile.ASM (program framework)

; Word Search Data File
;  (Feel free to invent your own test cases as well)

NumRows EQU 12
NumCols EQU 10

; Note that the Number of rows and columns CAN be changed!
; Your program should work for all sizes of matrices up to 255 x 255

OrigMatrix db 'EHUBBCLQMI',
              'TI9ABSPUSS',
              'ADUSLEAAAT',
              'LDPSE3TKME',
              'LCSE306EER',
              'LNHMK6UKTA',
              'ADDBINARYM',
              'CAILLIX3BU',
              'COLYLDOOWK',
              'OOEDIVHEXR',
              'MOODNIBBLE',
              'MENTIMESEG'