CS 330

Format for Assembly Language Program Submissions

Fall 2016

The last four lab assignments are assembly language programs. The programs must meet the specified conditions to be turned in and graded. It is the student’s responsibility to meet these conditions.

Program due dates	Fall 2016
By 5:00 PM	Nov 2	Program 3 ASCII code creator
	Nov 9	Program 4h and 4d, Hexadecimal and Decimal adders/subtractors NOTE: Hex version must be fully documented, the Decimal one needs only to document the changes from Hex.
	Nov 16	Program 5 Linked table sort
	Nov 30	Program 6 Final Project program

Formatting and Mechanical Considerations for CS 330 Programs

What you must be Documenting

What to avoid in Documenting

Examples of Documentation (Good and Bad)

Formatting and Mechanical Considerations for CS 330 Programs

Programs are due on the specified dates by 5:00 PM. Any programs not turned in by that time are late and subject to penalties for being late. 10% per day up to five days. After which the program will not be accepted. Computers being down, unavailable, etc. are not valid excuses unless in the extreme case that they have been unavailable, etc. for a substantial period of time. Do not put off doing these assignments until the night before. Note: Program 4 is fairly difficult. Do not wait on it.

The professor may alter the conditions of the program assignments at any time so long as he makes an announcement during any regularly scheduled meeting of the class (either lecture or lab) or he sends an email to the entire class’s NMU accounts.

Students must provide two identical copies of the program. These are a printed copy of the documented file and a computer file that will run on the professor’s computer with all documentation included in the file. Please note this is not negotiable, the programs must be identical in every way including spacing and punctuation. The most efficient means of providing the professor with an electronic copy is email. Due to issues with computer viruses the professor will not accept USB drives from students.

The name of the program must follow the convention xyzlabw.asm where xyz are your three initials w is the program number either 3, 4h, 4d, 5, and 6. This allows the professor to easily distinguish the authors of the programs. For example, if the professor were submitting the ascii code generator program he would name it dwdlab3.asm. Failure to name this way will result in a loss of points which will escalate each week. This condition will be altered if your initials happen to create a reserved word problem. You will be aware of this if you are unable to rebuild your program.

Certain mail programs place attachments into the body of the email. If your program does this, you may find that zipping the file before you make it an attachment will usually solve this problem. You are encouraged to email the professor a test program to ensure that your mail program and your word processing software does not create an unreadable file for the professor.

These two versions of the programs (printed paper and electronic) must be EXACTLY the SAME. This means you may not write your name on it and hand it in. Put your name into the program at the top as a comment. By the way, you must have your name at the top of your program. It is recommended that you print out the very document you send to the Professor. Note: The professor is aware that sometimes tabs and other formatting controls are almost impossible to match. In such cases, your electronic tabbing may appear slightly different.

Programs which are not IDENTICAL (both electronic and paper) do not qualify as a valid submission of a program. Programs which do not open in the Quick Assembler environment on the Professor’s computer do not qualify as a valid submission. Programs which do open but will not compile without error do not qualify as a valid submission. Programs which do not run correctly do not qualify as a valid submission. It will not matter if the student had the program working on a lab machine or on another machine, if it does not run on the professor’s machine. Programs must use a font size between 12 and 16.

Students who submit programs which are not valid submissions will be notified and provided approximately 48 hours to resubmit their programs. In a resubmission two new IDENTICAL copies (electronic and paper) must be resubmitted. Even if the error which prevented the valid submission is a single character added or removed, you must provide two new versions of the program.

Programs which are not valid submissions after two attempts receive a score of zero.

While the professor is willing to check that a program is working as required, he will not initial the program as final until the program is working with the full documentation included. He will not grade your comments prior to program submission. The professor will make brief remarks about the suitability of comments, but he will not give you assurances that your comments are sufficient ahead of time.

What you must be Documenting

All programs are to be fully documented as outlined below. The majority of the grade for each program is the quality of the documentation. While it is understood that lab partners may choose to write programs together; and therefore, would most likely have identical code, the documentation is not to be written together and must be obviously different. Simply changing a word here or there is not sufficient for this. Partners are warned that if the documentation is not sufficiently different, the programs may have major points removed including being awarded no credit.

Even if you write significantly different code than the professor provides to the class, documentation remains the primary component of the grade. If the professor cannot easily follow and see the student understands what the code is doing from the documentation, then the program will be graded accordingly (i.e. the grade would be low).

The professor would prefer that you not use assembly language commands not covered in class. If you choose to however, you must assume that your audience (another member of the cs 330 class) has never seen this command. Therefore, your documentation must account for that. You must first explain the command in detail and then explain what’s its role in the program is.

Keep in mind the point of documentation is to allow another person (or perhaps yourself after a long period of time) to understand why your code is doing what it is doing. All programmers find viewing another’s raw code confusing at first. Everyone has their unique way of approaching a program. Documentation allows another to quickly understand the purpose and the method by which a piece of code is functioning. This allows another person to modify or re-use elsewhere as needed someone else’s code. No one likes doing documentation, but it is necessary.

As you write documentation keep in mind WHY rather than WHAT. Anyone familiar with a language will quickly see what the action of the line is. The question is why do that line at all? Why do that line at this point in the code rather than earlier or later? Think about those questions as you write the documentation.

Documentation is achieved by writing comments after the code. First one places a ; (semicolon) to inform the compiler that what follows is documentation and not program. The best method of documentation would be to have a brief statement at the beginning of the program explaining the purpose of the program as a whole. Then, at the start of each section of the program a line or two outlining that section’s purpose and how it is done. Finally, individual lines should be as fully commented as possible.

Some procedures require several code lines to carry out and individual lines are not sensible to be commented on, in such cases you may comment on the lines as a whole, but be clear in your comments of how all lines are needed. This occurs when a single task or function requires two or three lines to carry out, such as the getting of input from the keyboard, or the printing of characters to screen. Jumps usually have at least two lines related. For example jc Label1 is of course jump if carry flag is set, but this usually follows a compare statement. So comment on the pair, for example:

cmp al, bl	;comparing the number of stars left (al) to the minimum number needed (bl).
jc label2	;When al is less then bl jump to label2 to start final analysis.

The professor is fully aware of how much code he is providing for each of these four programs. That is why documentation is so important. You are convincing him that YOU understand why the program works. Less explanation is not better!! If it is not clear to the professor that you have this understanding, points will be taken off. Consider that if you choose to do the least work you think is possible, the professor has the right to do the least work in determining whether you understand something or not and could choose that you do not understand and simply give you a low score. If you wish a high score, show off your knowledge. Do more work, not less.

While the professor in some class examples provides minimal documentation, you are not permitted this luxury. You must fully explain what you are doing. Just because the professor kept the documentation brief does not give you the right to copy his brief comments and indicate since he wrote this, it is sufficient. Remember part of the reason for brevity in the first place in his instructions is to not hand you the documentation in addition to the code.

Use proper writing and grammar styles in your documentation. Do not use IM-speak! Full sentences are preferred. The goal is to explain the code fully enough so that someone who has a basic knowledge of assembly language, but does not know what the program goals are ahead of time can read the documentation and understand what you are doing and how the program works. Again, you are demonstrating to the professor that you understand what is happening. Making inaccurate statements obviously hurts this and points will be lost. Use the proper terms and vocabulary. Bit means 1 binary digit. Byte means 8 bits not 4 bits! IF you say byte and you mean nibble, you are just wrong. If you say ch, but you really mean cl, again, you are wrong. So PROOFREAD!!!! And SPELLCHECK!!!

Once you have documented a procedure in a program within the same program you may briefly point out that the same thing is happening in subsequent uses of that procedure. In future programs you may be allowed to be relatively brief if the professor feels you have sufficiently explained this in early programs. Still in a later program the first instance of the procedure should entail some explanation. Unless comments receive an excellent grade, improve the comments each time a program is submitted.

What to avoid in documenting

First of all consider giving a driver directions when they have no idea where they are going. Is it useful to describe things that they are nowhere near? When you are driving across the UP, describing turns that you will eventually get to in New York City are not likely to be very useful. Similarly describing things that will happen later in the program is not so useful.

Never say “use later” or “for later use”.

Remember documentation is not about making your life easier, it is about making the reader’s life easier.

Watch the tone of your comments. Do not try to be funny. Do not be sarcastic or annoyed in your tone. Points will be deducted. This is not your blog, this is not for your enjoyment. This is an assignment.

Neatness counts. Do not turn in programs that look like crap! Warning: the assembler will create run over lines which do not look good. Be sure that you never go past the 80 column. The program will show what column you are on. Notice in the examples of good documentation below that spaces are used to break the program into logical sections related to function. Notice also the uniform spacing of where the comments started. If the professor cannot follow your comments because they are too intertwined with code, even if the comments are 100% right, you will be deducted points. You do not have to comment the pre and post code required to make your programs run in the assembler. But remember the programs will not run without this code.

Do not get hung up on Flags. They are useful, but remember the reader has had CS 330 and knows what they are and do. Instead of fixating on what the carry flag is, it is better to discuss what is happening, for example JC is jump if the carry flag is set, don’t tell me that. Tell me why you are jumping. For example, we jump here if the number is less than 30 because that means we have an ASCII code that is not in our valid range.

Do not tell what the action of a line is. For example, telling that “mov bx,ax” copies ax into bx will get the DUH comment written by it. Do not indicate that “add al,30h” is adding 30 hex to al. Again DUH. Explain WHY. Why is a line in the program? That is the key to writing comments. If the line has no purpose, take it out. (Put a “ ; ” in front of the line and try running the program.) If the program will not function correctly without the line, then there is a reason the line is needed. Figure it out.

Points will not usually be deducted for occasional bad programming. But if the program is horrendous enough (in the professor’s opinion) then points will be deducted. For example, points will not be deducted for an occasional line that serves no purpose, but if you have too many, then points may be lost. Do not ever jump to the very next line of a program. If you are jumping to the next line change your logic.

Do not try to sound impressive. We print on a screen not a console, we use a keyboard. Keep it simple and straightforward.

Do not write a section summary and then say the exact same things on each line.

Do not write to get points. Write to explain. Writing to just add length is not going to increase your score and likely will decrease your score. It is about getting the appropriate information conveyed, not getting some number of words or lines down.

Finally, have a friend read over your documentation and see if they understand what you are doing. If they ask you questions, then you know what you need to explain more.

From Recent Semesters: These are things you should not do.

Do not tell the professor to go to another section for more information.

Don’t use a comment such as “we are doing something to make it easier or better.” That is vague be specific why you are doing things.

“We set up certain registers to be certain parameters to ensure success of our program.”

Do not change the conditions of the program (i.e. use space to end program immediately).

These things you should do.

Use proper punctuation to separate comments.

Comment on commands in order of their occurrence. The first time a command or function is introduced, explain it. The idea that the professor or reader will get it later is not acceptable. Do not say … doing for later? Why, what will happen later? Do you wish to be kept in the dark?

Think about what the code is doing. For example bx is a register that has many uses, think about what the current use is. Push Bx is not because BX needs to be saved, it is because the contents of BX which is something we are working on needs to be saved. What are they? Why do they need to be saved?

PROOFREAD “mov dh, 01h ; putting 1 into dl” Don’t do this.

Understand that looping will have different variables each loop.

Use “ ” around Logic functions so that the meaning is understood. “AND” means do a logical AND instead of the usual conjunction and.

Please use Most Significant digit and Least Significant digit rather than first and last digit or first and second digit. Is the most significant the first or second digit?

Do not get bogged down on what flags are doing. Do not quote a manual says a command is doing.

Examples of Documentation (Good and Bad)

Examples of what not to do:

Examples of what to do:

An example of bad looking programs: not neat, comments hard to separate from code, etc.

begin: mov ah,01h ;01h is moved into ah which is an instruction to

;wait for a key to be pressed then places ASCII

;code for character pressed into al and prints onto ;screen.

int 21h ;The interrupt call(int 21h) looks into ah and sees ;the

value 01h which waits for a key to be pressed ;then places ASCII c

ode for character pressed into

;al and prints onto screen.

Do Not Piccard! This is the extreme example of multiple lines being commented as a group.

Do not do the following:

mov ah, 02h	;preparing to print
mov dl, 41h	;preparing to print an ‘A’
int 21h	; execute printing the ‘A’ on the console

Instead do the following:

mov ah, 02h	;these three lines allow the program to print on
mov dl, 41h	; the screen. The ASCII code of the character to
int 21h	; be printed is placed in the DL register and will ; be used upon the calling of the int 21h command. ;The int 21h is a set of pre-determined functions ;which execute various DOS services depending ; on the code placed in AH.

Example of bad choices for jumps:

jc Proceed

jmp GetKey

Proceed:

instead use a single jump

jnc GetKey

Proceed:

Convoluted jumps

cmp ax, bx ;

jc NegativeNumber

FinishCalculate:

sub al, bl

das

mov bl, al ;

mov al, ah ;

sbb al, bh ;

das

mov bh, al ;

jmp DoCalcPrint ; Jump down to print the answer to the console.

NegativeNumber: ;

push ax

mov ah, 02h

mov dl, 2dh ;

int 21h

mov ax, bx ;

pop bx ;

jmp FinishCalculate

Better would be:

cmp ax, bx ;

jnc FinishCalculate

push ax

mov ah, 02h

mov dl, 2dh ;

int 21h

mov ax, bx ;

pop bx ;

FinishCalculate:

sub al, bl

das

mov bl, al ;

mov al, ah ;

sbb al, bh ;

das

mov bh, al ;

jmp DoCalcPrint ;

More examples of bad documenting from actual students in previous semesters:

mov CL,04h

Begin: mov AH,01h ;command to wait for key to be pressed

int 21h ;execute AH = 01h command (save & printed)

mov CH,AL ;save input from AL in CH

mov AH,02h ;command to place ascii char on screen

mov DL,3dh ;place "=" = 3d (hex) in DL

int 21h ;execute AH = 02h to print DL = "=" on screen

mov AL,CH ;place from CH to AL

shr AL,CL ;shift AL by CL (04h) to right

Examples of what to do:

; Dr. Dave Donovan

;Program 3 Version 2004- March 23

;This program will be an example program for demonstrating proper documentation

;comments.

;This program will create noises on an ibm personal computer using the computer’s internal

;speaker.

.model tiny

.stack

.code

.startup

; ***** put program instructions here *******************

;This section initializes several parameters that are used by the program.

mov bx,2000h ;This value is used to set up looping later in the program. The

;size ;of this value will determine the amount of time the

;computer is ;occupied thereby sustaining a current to the

;speaker to create the tone.

note: mov cx,bx ;cx will be used as a time counter. So the initial value is now

;placed in cx.

;This is the main part of this program. Speaker information is determined and then modified

;to allow the user to create a variety of noises. Note: actual tones require substantial

;calculations involving the clock speed of the computer.

in al,61h ;Get the current speaker configuration. Memory location 61h is

;reserved for the internal speaker.

and al,0feh ;The value of bit 0 determines if the speaker is controlled

;internally ;or externally.

;Set bit 0 to 1 for external control of speaker

xor al,02h ;If bit 0 is set to external control then bit 1 determines if current

;flows to the speaker or not. Current flowing to the speaker

;moves the speaker cone in one direction. No current relaxes

;the speaker cone back to its original position. This vibration of

;the speaker cone creates sound. The “xor” toggles the current

;bit. This creates our vibration.

out 61h,al ;The speaker register has not received this information that bit

; 0 is now 1 and bit 1 was toggled. This command sends that

; information to location 61h which is the speaker register.

delay: dec cx ;The decrementing of cx creates a time delay to space out in

;time the vibrations of the speaker.

jnz delay ;If we have not finished decrementing cx we continue to wait so

;we jump back and continue decrementing. When cx is zero we

;have finished creating the tone.

;Now that a tone was issued through the speaker we want to see if the user wishes to

;continue. If they do, we will also allow the user to change the tone emitted.

mov ah,0bh ;Check if a key was pressed. If key is pressed, al=FF

int 21h ; IF no key is pressed al=00

inc al ;We make al zero if a key is waiting to allow the jump command ;on the next line to continue created the same tone. If a key is ;pressed, we have two options. If the key was the “@” key we ;will end the program. If not, we will use the ASCII of the key ;pressed to create the new delay for a new tone.

jnz note ;Loop back if no key was pressed.

mov ah,07h ;If a key was pressed get the key code but do not display

;anything on screen.

int 21h

cmp al,40h ;Check for end key "@"

jz done ;If it is then end the program.

mov ah,00h ;Otherwise we will modify the ASCII code to make a reasonable

;delay value.

mov cl,0ch ;We must load a value that will be used to multiply the ASCII

;code. On the faster

shl ax,cl ;machines available 2 ^12 is reasonable.

mov bx,ax ;Since we are going to jump back to the beginning we store this

;value in bx as above it will be moved into cx. Note since cx is

;decremented, we need bx to hold the value so if we wish to

;continue with the tone the value has not been lost.

jmp note ;Jump back to continue the program.

done: ;We have received the key telling us to quit the program so now

;we do.

; ************ ********************************* **********

mov ax ,4c00h ;quit

int 21h

end

Additional GOOD documentation examples from a student’s code.

; CS330 - F07

; Student Name

; Program 4Decimal

;

; This program will work as a decimal calculator, accepting two 4 digit sets of

; hexadecimal digits (0-9) and performing either addition (+) or subtraction (-). The

; program will quit on @.

;

mov cl, 04h ;cl will be used for shifting purposes. Setting to 4

; allows to quickly manipulate/move nibbles.

Start: mov bx, 0000h ;bx is where the numbers are stored after we clean them

; of ASCII code. Since we're starting, we want to

; zero this value so nothing becomes contaminated.

Gkey: mov ah, 07h ;Grab the ASCII value of the key pressed using int 21h.

int 21h ; Setting AH to 07h allows us to grab the character

; input without echoing it to the screen. Need this

; so that we can check if it's a valid hexadecimal.

; Will print the key once it's been validated it.

;Anything that gets past these comparisons must have fallen in the 0-9 range.

mov ah, 02h ;Since we've got this far, the value we have must be good.

mov dl, al ;Print it using int 21h. Use the 02h option of int 21h to

int 21h ; print what is in dl to the screen. Move al, our key

; value, to dl & print.

;We have now printed the key which was pressed to the screen. We still have the

; ascii value for that key, not the actual decimal value of the key. As an

; example, if the key '6' was pressed, we currently have '36' in al. For printing

; this is great. For doing mathematical calculations, '36' is useless to us. We

; need to take this ascii value and convert it to the equivalent decimal value so

; we can perform calculations on it.

sub al, 30h ;We'll start by subtracting 30h from our value in al. If

; the key pressed was a number, subtracting 30 will leave

; only the actual number. Example- If 4 was pressed, we

; would have 34 in al. Subtracting 30 leaves 04, which we

; need.

;We now the actual key that was pressed located in the LSN of AL. Since we will

; accepting up to 4 digits per set of numbers, we need to save this somewhere.

; Will be using BX to save these values. Each time a new key is to be added, will

; shift the previous values left in BX. After the 4th value, any new values will

; drop the oldest value out of BX. Before we can add it to BX we need to do one

; last sterilization.

Pack: shl bx, cl ;Have a new number that needs to be placed into BX, shift

; the contents of BX to make room for it. Using cl, which

; is set to 04, so that we can shift BX by one nibble.

or bl, al ;Copy our new, freshly cleaned value into BL. Use OR

jmp Gkey ; instead of MOV because we need to keep the MSN that is

; already in BL. Had we used MOV, it would have erased

; the value of the MSN. Once done copying the value into

; BL, go grab a new key.

;Done printing the answer, get ready for a calculation by printing a carriage

; return and a new line.

mov dl, 0Dh ;Print the carriage return.

int 21h

mov dl, 0Ah ;Print a new line.

A Final Example to illustrate what documentation is all about.

Consider the following program:

	mov bp, 0200h
	mov dx, 02fbh
	mov al, 03h
	out dx, al
cdat:	mov bl, 2eh
	call Sout
	mov bl, 2eh
	call Sout
	mov bl, 2eh
	call Sout
	mov bl, 43h
	call Sout
	mov bl, 44h
	call Sout
	mov bl, 41h
	call Sout
	mov bl, 54h
	call Sout
	mov bl, 3fh
	call Sout
	mov bl, 0dh
	call Sout
	mov bl, 0ah
	call Sout
rtemp:	call Sin
	mov [bp], ch
	call Sin
	mov [bp+01h], ch
	call Sin
	mov [bp+02h], ch
	call Sin
	mov [bp+03h], ch
	jmp done
Sin:	mov dx, 02fdh
	in al, dx
	and al, 01h
	cmp al, 01h
	jnz Sin
	mov dx, 02f8h
	in al, dx
	mov ch, al
	ret
Sout:	mov dx, 02fdh
	in al, dx
	and al, 60h
	cmp al, 60h
	jnz Sout
	mov dx, 02f8h
	mov al, bl
	out dx, al
	ret
Done:

SO what does this do, how and why?

The following is the all too common kind of documenting provided by students who would later complain about a low grade:

	mov bp, 0200h	;put 0200h into bp
	mov dx, 02fbh	;put 02fbh into dx
	mov al, 03h	;put 03h into al
	out dx, al	;write al to memory register 02fbh
cdat:	mov bl, 2eh	;put 2eh into bl
	call Sout	;call the Sout subroutine
	mov bl, 2eh	;put 2eh into bl
	call Sout	;call the Sout subroutine
	mov bl, 2eh	;put 2eh into bl
	call Sout	;call the Sout subroutine
	mov bl, 43h	;put 43h into bl
	call Sout	;call the Sout subroutine
	mov bl, 44h	;put 44h into bl
	call Sout	;call the Sout subroutine
	mov bl, 41h	;put 41h into bl
	call Sout	;call the Sout subroutine
	mov bl, 54h	;put 54h into bl
	call Sout	;call the Sout subroutine
	mov bl, 3fh	;put 3fh into bl
	call Sout	;call the Sout subroutine
	mov bl, 0dh	;put 0dh into bl
	call Sout	;call the Sout subroutine
	mov bl, 0ah	;put 0ah into bl
	call Sout	;call the Sout subroutine
rtemp:	call Sin	;call the Sin subroutine
	mov [bp], ch	;put ch into the location specified in bp
	call Sin	;call the Sin subroutine
	mov [bp+01h], ch	;put ch into the location one higher than the one ;specified in bp
	call Sin	;call the Sin subroutine
	mov [bp+02h], ch	;put ch into the location two higher than the one ;specified in bp
	call Sin	;call the Sin subroutine
	mov [bp+03h], ch	;put ch into the location three higher than the one ;specified in bp
	jmp done	;jump to done
Sin:	mov dx, 02fdh	;put 02fdh into dx
	in al, dx	;get the value in memory register 02fdh
	and al, 01h	;and al with 01h
	cmp al, 01h	;compare al and 01h
	jnz Sin	;if the zero flag is not tripped go back to Sin
	mov dx, 02f8h	;mov 02f8h into dx
	in al, dx	;get the data from memory register 02f8h
	mov ch, al	;copy al into ch
	ret	;return from subroutine
Sout:	mov dx, 02fdh	;put 02fdh into dx
	in al, dx	;get the value in memory register 02fdh
	and al, 60h	;and al with 60h
	cmp al, 60h	;compare al and 01h
	jnz Sout	;if the zero flag is not tripped go back to Sout
	mov dx, 02f8h	;put 02f8h into dx
	mov al, bl	;copy bl into al
	out dx, al	;send al out to the memory register in dx
	ret	;return from subroutine
Done:		;program complete

Compare that with the following documentation. This is what would earn a higher grade:

;This program will read in the current temperature that the cryostat is maintaining at the

;time this program is run. The temperature will be read in as four parts, hundreds, tens,

;ones, and tenths of ones where the actual temperature is in units of Kelvins. The hundreds

;digit is stored at memory location 0200h, the tens digit at memory location 0201h, the ones

;digit at 0202h and the tenths of ones at 0203h.

;Program Version 2010-11-24 by D.W. Donovan

mov bp, 0200h

;set the base memory location for storing the ; temperature digits.

;Initializing of the Serial port Com2: we need to establish the serial protocol of 8 data bits,

; 1 stop bit and no parity.

mov dx, 02fbh	;location of the line control register for Com2:
mov al, 03h	;this is the appropriate bit mask for 8 data bits, 1
out dx, al	; stop bit and no parity.

;Issuing of CDAT command. This is the command that the cryostat must receive for it to

;output its current temperature. The firmware of the cryostat requires sending 3 periods(.)

;followed by the letters C, D, A, and T. Finally one must send the question mark(?) and a

;carriage return and linefeed characters for the cryostat to respond to the request.

cdat:	mov bl, 2eh	;2e is the ascii for the period
	call Sout	;Sout is a subroutine which sends the data contained ;in bl out to the serial port. So these two lines ;effectively send the period character out of the ;serial port to the cryostat.
	mov bl, 2eh	;second period is sent
	call Sout
	mov bl, 2eh	;third period is sent
	call Sout
	mov bl, 43h	;now sending the letter C
	call Sout
	mov bl, 44h	;sending the letter D
	call Sout
	mov bl, 41h	;sending the letter A
	call Sout
	mov bl, 54h	;sending the letter T
	call Sout
	mov bl, 3fh	;sending the question mark
	call Sout
	mov bl, 0dh	;sending the carriage return
	call Sout
	mov bl, 0ah	;sending the linefeed
	call Sout

;This section now reads in the four digits of the temperature and stores them in the

;appropriate memory locations 0200h through 0203h. Sin is the subroutine that reads the

;serial port incoming data.

rtemp:	call Sin	;These two lines are getting and storing the
	mov [bp], ch	; hundreds digit
	call Sin	;getting and storing the tens digit
	mov [bp+01h], ch
	call Sin	;getting and storing the ones digit
	mov [bp+02h], ch
	call Sin	;getting and storing the tenths of the ones digit
	mov [bp+03h], ch
	jmp done	;the section of code needed to read the temperature ;is completed. Go to to the end the program.

;This is the Serial In subroutine. This reads the serial port for incoming data and when it

;receives it, the data is stored in ch and then the routine returns to where it was called from.

Sin:	mov dx, 02fdh	;put location of the line status register for Com2: ;into dx
	in al, dx	;read the status register
	and al, 01h	;check if there is data received
	cmp al, 01h
	jnz Sin	;if there is no data received, check again. We stay in ;this polling loop until we receive data as we know it ;is going to arrive.
	mov dx, 02f8h	;once the data arrives read it from the receive buffer
	in al, dx
	mov ch, al	;store the data in ch so that it can be placed in the ;appropriate memory location by the main program.
	ret

;This is the Serial Out subroutine. This checks for the transmitter to be ready and able to

;send data. Then it sends the data provided out of the serial port. Afterwards it returns to

;the point of the program from which it was called.

Sout:	mov dx, 02fdh	;put location of the line status register for Com2: ;into dx
	in al, dx	;read the status register
	and al, 60h	;make sure the Transmitter buffer is empty and the
	cmp al, 60h	;transmitter is ready so that the data can be sent ;out.
	jnz Sout
	mov dx, 02f8h	;now send out the data
	mov al, bl
	out dx, al
	ret
Done:		;program to read temperature is completed.

An additional example of bad documentation

;Student

;CS330

.model tiny

.stack

.code

.startup

; ***** put program instructions here *******************

mov cl,04h ;here we are putting 4 into cl, so that we can eventually

;so we can eventually use this to shift the left hex value of al to the

;one on the right so we can use the data

begin: mov ah,01h

int 21h ;moving 01h into ah so we can execute the take in a key command, this command also echos

;what we put in so that it also appears on screen

mov ch,al

mov dl,3dh ;this group of commands is loading what we get from the answer of the first input

mov ah,02h ;and stores it into ch so we can use it later for converstion

int 21h ;we then are moving 3dh into dl, which is the ascii code for the - symbol and then

;we put 02h into ah and execute the interupt, which prints out the ASCII code

;of the hex digits in DL (which is our -)

mov al,ch ;here we are taking our original value from ch, which is where we stored it, and putting

shr al,cl ;it back into al, there we are moving the higher part of al to the lower part, and then adding

add al,30h ;30 in hex to said value, this is done so that we can then after move into the letters in the ascii chart and avoid things

cmp al,3ah ;like the colon and greater than sign, if we fall in those signs it jumps us ahead to the letters in the ascii code chart

jc hdig ; from tripping the carry flag

add al,07h

hdig: mov dl,al ; here we are moving our al in dl so that we can print out the first digit of the hexadecimal

mov ah,02h ; with the next interupt command

int 21h

mov al,ch ;now we take the original value again, move it back into al, except we are getting rid of the higher digit

and al,0fh ;by anding it with 0, we then repeat the proccess seen above of adding 30 in hex to our al register to get the

add al,30h ;next number we will be printing to the screen, and once again we have to compare it to 3ah, to make sure we are

cmp al,3ah ;not falling into the territory of the wierd symbols that cannot be a hex digit

jc ldig ;if we do fall into that territory we add 7 to our digit to get back to the letters

add al,07h

ldig: mov dl,al ;here we will take our new al value (the number/letter we wish to print) to the dl register so we can use

mov ah,02h ;an interupt to print it to the screen

int 21h

mov dl,0dh ;this line prepares the dl regiester to excecute a carriage return

int 21h

mov dl,0ah ;and here we are skipping down to the next line, so our program does not get cluttered

int 21h

mov al,ch ;now we once again move our original value into al, if it happens to match the ascii code for the

cmp al,40h ;@ symbol then we will be exiting the program, this is done by comparing it to 40, if they are the same

jnz begin ; our zero flag will be tripped, and we will walk out of the program, otherwise we will loop back to the start

; ************ ********************************* **********

mov ax ,4c00h ;quit

int 21h

end