EXPERIMENT TWELVE: USING DISK FILES

INTRODUCTION
Because just about any program ever written requires the use of a disk file to store or retrieve data, this experiment shows how to create, read, write, append, and close disk files. It also details the use of the file handle, which also functions to read and write data to the computer console (keyboard and display). Disk files are first accessed by file name to determine the file handle. Once the file handle is obtained, they are then referenced through the handle to speed the operation of DOS. Files are accessed on the floppy disk drive or hard disk drive in any directory or subdirectory.

OBJECTIVES
1. Create a disk file and write data to it using assembly language instructions and DOS INT 21H function calls. 2. Read any part of a disk file using the move file pointer function available from DOS. 3. Append a file with new data using the move file pointer and write functions available from DOS.

PROCEDURE
As with a filing cabinet, a DOS disk file must be opened before it can be read or written and then closed once access is complete. If a new file is needed, it is created, which also opens it, then it is written, and closed. As with other features of the personal computer, the DOS INT 21H functions are used to accomplish these tasks. Example 12-1 lists a macro that creates a file and saves the file handle (used to refer to the file until it is closed) in a word-sized memory location. The _CREAT macro also contains another parameter that indicates the data segment offset address of the ASCII-coded file name. Both the offset address of the file name and the location of the file handle must be stored in the data segment as addressed by DS. Note that DOS returns the file handle in AX. Example 12-1
_CREAT MACRO MOV XOR MOV HANDLE,FNAME AH,3CH CX,CX DX,OFFSET FNAME ;create FNAME, save HANDLE ;;create function number ;;make it read/write

INT MOV ENDM

21H HANDLE,AX

;;save HANDLE

STEP 1: Add this macro to the macro file MACS.INC on your floppy disk. It will shortly be used to create a disk file. Once a file is created, it often has data written to it. Example 12-2 shows a macro sequence that writes data to a file. Its also shows a macro that closes the file. These macros also use the HANDLE stored by the create macro to access the file. This allows the simultaneous use of multiple files. The write macro also contains a parameter that indicates the number of bytes to be written (1 to 64K) and the offset location of a buffer containing information to be written. Note that the file handle and the buffer must both be located within the data segment to use these macros. Example 12-2
_WRITE MACRO MOV MOV MOV MOV INT ENDM MACRO MOV MOV INT ENDM HANDLE,BUFFER,COUNT AH,40H ;;file write function BX,HANDLE CX,COUNT DX,OFFSET BUFFER 21H

_CLOSE

HANDLE AH,3EH BX,HANDLE 21H

;;file close function

All three macros presented thus far in this experiment detect errors. If an error occurs, the carry flag = 1 to indicate an error. Because the scope and nature of the errors can vary, none of these macros handle the error conditions. It is the responsibility of the program that invokes the macro to handle the error with a JC (jump if carry = 1) instruction following the macro call. Extended information detailing the exact nature of an error is obtained by using DOS INT 21H, function 59H. This function also suggests recommended actions for the error through a number returned in BL. For additional detail on function 59H see Appendix B. STEP 2: Add the _WRITE and _CLOSE macros to your macro file for later use in this experiment. Example 12-3 shows a short program that creates a file on floppy disk A in the root directory and then closes it. Notice that this program uses a single segment. The data segment register is loaded with the code segment address to place the data segment on top of the code segment. Example 12-3

CODE

SEGMENT 'code' ASSUME CS:CODE INCLUDE MACS.INC DW DB PROC FAR MOV AX,CS MOV DS,AX _CREAT _CLOSE _EXIT HANI,NAME1 HAN 1

;indicate start of CODE segment ;indicate that CODE is CS ;include macro file

HAN1 NAME1 MAIN

? 'A:\MYFILE.TST',0 ;indicate start of MAIN procedure ;make DS = CS

;create MYFILE.TST ;close MYFILE.TST

MAIN CODE

ENDP ENDS END

;indicate end of MAIN procedure ;indicate end of CODE segment ;indicate end of file and start

MAIN

Notice how the file name is stored in this example as an ASCII-Z string. An ASCII-Z string always ends with a zero or null instead of a carriage return, line feed combination, or a dollar sign. The file name must be stored as an ASCII-Z string for all DOS file functions. Also notice that the word-size data is stored before the byte-sized data. This is important to the microprocessor so word-sized data are stored at a word-sized memory boundary. If doubleword data are also present, it would be declared before word-sized data. The microprocessor executes and uses data in any order, but not as efficiently as when ordered with doubleword data first, followed by word data, and then byte data. This can be forced if the order is different by using the ALIGN directive. An ALIGN 4, for example, aligns data on a doubleword-sized boundary. This program does not detect any errors, so make sure that a formatted disk is in drive A before execution. STEP 3: Enter and assemble the program from Example 12-3 and execute it. Note that you may need to include a path with the INCLUDE statement if your MACS.INC file is not stored in the current default directory. Place a floppy disk into drive A and execute the program. A directory of drive A should reveal the file MYPROG.TST with zero bytes of data after execution. STEP 4: Now that macros are available for creating ( _CREAT), writing ( _WRITE) and closing a file ( _CLOSE), write a program that creates the file FROG.JMP in the root directory of drive A. Store five bytes of data (48H, 65H, 6CH, 6CH, and 6FH) in this file, and then close it. The data must be stored in the data segment using either the DB directive or the BYTE directive. Execute this program and then check to see if drive A contains the file. A _________ is displayed when the TYPE A:\FROG.JMP command is typed at the DOS prompt. Now that a file is created and written to, the open and read functions are discussed. Note that when a file is created using DOS INT 21H, function number 3CH, no check is made to see if it already exists. An existing file with the same name will be erased. If this is

bothersome, DOS INT 21H, function number 5BH can be used. Function 5BH works exactly as function 3CH except it first checks to see if the file is present and if so returns with carry = 1 without erasing it. Example 12-4 shows the _READ and _OPEN macros that are used to read bytes (up to 64K bytes at a time) of data from a file and open an existing file for a read or write operation. As before these macros include the HANDLE parameter to specify the file handle. The _OPEN macro also includes the file name (FNAM) parameter that addresses the ASCII-Z string in DS for the file name. The _READ macro contains a BUFFER and COUNT parameter to transfer the offset address of a memory area in the data segment to read the file data to and the number of bytes (1 to 64K) to be read from the file. Example 12-4
_OPEN MACRO MOV MOV INT MOV ENDM MACRO MOV MOV MOV MOV INT ENDM HANDLE,FNAM AX,3D02H DX,OFFSET FNAM 21H HANDLE,AX ;open file FNAM, and save HANDLE ;;open read/write file

;;save handle

_READ

HANDLE,BUFFER,COUNT AH,3FH BX,HANDLE CX,COUNT DX,OFFSET BUFFER 21H

;read file to BUFFER

STEP 5: Using the _OPEN and _READ macros, develop a program that reads the FROG.JMP file, created in STEP 4, and display its contents on the video display using DOS INT 21H, function number 09H. Don't forget that this function requires that a character string must end with a 24H ($). Now that a file exists containing data, FROG.JMP, we add to the file by appending it with new information. When a file is opened, the file pointer addresses the first byte of the file. If a file is opened and new data are written, it overwrites the current contents of the file. To avoid this, the move file pointer function (DOS INT 21H, function 42H) is used to move the file pointer to the end of the file before writing new information. Example 12-5 lists a macro called _ENDF, which moves the file pointer to the end of the file. As with other file macros, a HANDLE is included to identify the file. Example 12-5
_ENDF MACRO MOV XOR XOR MOV INT HANDLE AX,4202H CX,CX DX,DX BX,HANDLE 21H ;move file pointer to end of file ;;move file pointer function

ENDM

The move file pointer performs three different types of file pointer moves: (1) if AL = 0, the file pointer is moved from the start of the file, (2) if AL = 1, the file pointer is moved from its current position, and (3) if AL = 2 (as in Example 12-5), the file pointer is moved from the end of the file. The number of bytes the file pointer is moved is determined by the 32-bit number located in the CX (leftmost 16 bits) and DX (rightmost 16 bits) registers. Note that the macro in Example 12-5 uses a count of zero in CX and DX and uses move the file pointer from the end of the file. This macro, in other words, moves the file pointer to the end of the file so it can be appended with new information. STEP 6: Write a program that opens FROG.JMP, moves the file pointer to the end of the file, and then appends the file with a space followed by your name. Enter, assemble, and execute this program. If you use the TYPE A: \FROG. JMP command at the DOS prompt, the computer should greet you with the salutation Hello if the program functions correctly. STEP 7: Write a program that modifies the data in FROG.JMP and places the word there between the word Hello and your name. Create a file called FROG.TST and write this new information to FROG.TST. Do not change FROG.JMP. Enter, assemble, and execute this program and then use the TYPE command at the DOS prompt to verify its correct operation. Enter and execute the following program (Example 12-6) to create a data file for the next portion of this experiment. This program creates a file called TEST.DAT that contains 128K (131,072) bytes of information. Note that a path may need to be included for the file name TEST.DAT and also for the MACS.INC macro file. Example 12-6
CODE SEGMENT 'code' ASSUME CS:CODE INCLUDE MACS.INC DW DB DB PROC MOV MOV MOV CLD ;indicate start of CODE segment ;indicate that CS = CODE ;include your macro file

HAN NAM BUF MAIN

? ;file handle 'TEST.DAT',0 ;file name 256 DUP (?) ;data buffer FAR AX,CS DS,AX ES,AX ;start MAIN procedure ;make DS = CS ;make ES = CS ;select autoincrement ;create TEST.DAT file ;number of 256 byte writes needed

_CREAT HAN,NAM MOV MAIN1: MOV MOV MOV BP,512

AX,BP ;generate 256 bytes of test data CX,256 ;set count DI,OFFSET BUF

REP STOSB _WRITE HAN,BUF,256 DEC JNZ BP MAIN1 ;write 256 bytes

;repeat 512 times ;close TEST.DAT file ;exit to DOS ;end of MAIN ;end of CODE

_CLOSE HAN _EXIT MAIN CODE ENDP ENDS END

MAIN

STEP 8: Write a program that searches TEST.DAT for any 256 byte section that contains 41H in each location. Create a new file called TEST.DET where you will store the sections from file TEST.DAT that contain 41H data. Note that when a file is read with the READ macro, the number of bytes actually read are returned in AX. This is used in this program to determine when the end of the TEST.DAT file is reached. Enter, assemble, and execute your program. To see if it has functioned correctly, use the TYPE command at the DOS prompt to display the contents of TEST.DET. What is observed on the video screen? While discussing handles and files, earlier it was mentioned that direct access to the computer console is available through a file handle. Table 12-1 lists the file handles used by DOS as defaults for various system devices. Table 12-1. DOS default handles. Handle number 0000H 0001H 0002H 0003H 0004H Function reads the keyboard (CON:) display on the video display (CON:) error display (CON:) uses the COM1 port (AUX:) uses the printer port (PRN:)

The macros presented in this experiment are used to address the video display ( _WRITE) or the console keyboard ( _READ) if the correct handle is provided to the macro. They can also address the COM port (the port number can be changed with the DOS MODE command, or the parallel printer port (PRN), which is usually LPT1. Example 12-7 lists a short program that displays a message on the video display by using the handle (0001H) for the display with the _WRITE macro. Note that the _WRITE macro in this program uses a handle of 1 to display the contents of MES. Also note how the number of bytes to write are determined by taking the difference of DUMMY-MES. Example 12-7

CODE

SEGMENT 'code' ASSUME CS:CODE INCLUDE MACS.INC DB DB PROC FAR MOV AX,CS MOV DS,AX

;indicate start of code segment ;identify CODE as CS

MES DUMMY MAIN

13,10,'This is interesting!' ? ;start main procedure

_WRITE 1,MES,DUMMY-MES _EXIT MAIN CODE ENDP ENDS END

MAIN

STEP 9: Write a program that displays two lines of information of your own choosing on the video display with the WRITE macro. If a printer is available on the LPT1 line printer port, change the handle to 4 and try running the program again to print data.

QUESTIONS
12-1. Refer to the Appendix A, the DOS INT 21H functions, and describe the options available in the CX register for the create function (3CH). 12-2. Can the DOS file creation function be used to create a new directory name? If so, how? 12-3. Explain why a file must be closed, especially after a write operation. 12-4. How can more that 64K byte of data be written to a file? 12-5. What is an ASCII-Z string? 12-6. How is an error indicated by the DOS file functions? 12-7. What is the file pointer? 12-8. Write a macro called _TOPF that moves the file pointer to the start of a file.

12-9. Write a program that creates two new file (UP.DAT and DOWN.DAT). Write a 02H into each of the 256 bytes of the UP.DAT file and a 03H into each of the 256 bytes of the DOWN. DAT file. 12-10. Using the file handle for the keyboard, develop a macro that reads one character from the keyboard. Call your new macro _KEYF