1. CS 450 Module R1

2. R1 Introduction In Module R1, you will implement a user interface (command handler). There are a couple of options: ▫Command Line: interface similar to DOS, where users type in a command and your program parses it and determines what the user wants to do. This type of interface is user friendly and easy to maintain. ▫Menu: User is presented with a menu of options from which to choose. This type of interface is somewhat cumbersome to use and difficult to maintain. ▫GUI: requires a lot of work. Probably not worth your time. This is also extra credit.

3. How to handle commands You will write a function that gets commands from the user in a loop (COMHAN). This function will then parse through the user’s input and decide what the user wants to do. Then, it will have to execute whatever action the user requested. There are many ways to handle these user requests. In your command handler, you will have some sort of decision statement that will check to see which command was entered. Once your system recognizes a command was entered, you could handle the command right there in the decision statement. However, it might be better to create a “handler” function for each command. This handler function will be called from COMHAN when it recognizes that a command has been entered by the user. You can either call this command in the typical way, or by using function pointers.

4. User Interface Issues There are a number of issues that you will need to settle before implementing your interface: ▫Syntax for commands ▫Will syntax be case sensitive? ▫Will arguments go on the same line as the command, or will your system prompt for them? ▫Will your command handler function get the arguments, or will the handler for the individual commands get the arguments ▫How will your system handle unexpected input?  Invalid commands  No arguments present when arguments are required  Too many arguments present  Argument of the wrong data type ▫Will your system accept wildcards? ▫How will you handle help? ▫White space should be ignored!

5. Organization of MPX As your project evolves, you will need to have multiple source files. One idea is to have a single source file for each module. However you choose to design your code, be careful not to have too many or too few source files. Do not put your command handler in main! Create separate function(s) for your command handler and have main call these functions. This will save you a lot of work later. Main does not need to do much else other than calling initialization functions and your command handler at this point.

6. Structure of COMHAN Call initialization functions Display a welcome message (this is required) Get commands from the user in some sort of loop ▫You need to print out a prompt symbol (‘>’ for example), then get the command from the user, analyze it, and call the appropriate function to execute the command, or display an error message ▫Loop until the user directs MPX to terminate Display a closing message Call cleanup functions

7. Commands These are the commands that you must implement for Module R1: ▫Help ▫Version ▫Display/Change date ▫Display MPX Directory ▫Terminate MPX

8. Help You will implement a help system similar to that of DOS. There should be a command to show a summary of all commands in the system and a brief blurb about each command. There should also be a command to show more detailed help for a specific command, including syntax and a description of the command. An example of how to use the command could also be included. There are many ways to implement this. To get to the help summary, you could have the user type “help” or “/?” at the command line. To get to the help for a specific command, you could have the user type “help command_name” or “command_name /?”, etc. One way to implement help is to have a separate file with the help for each command. If you implement this correctly, adding help for new commands in later modules will be as simple as dropping another help file into your directory. TIP: if you try to read from a file with a name more than approx. 10 characters, you might encounter problems, such as the file not being found. This seems to be a DOS error. Keep this in mind as you debug, as you might need to devise a workaround.

9. Version Displays the current version of the MPX project and the completion date of the current version. Version numbers are designed to keep track of different versions of your source code as it evolves. One suggestion is to have each deliverable be version # = module #, then increment the version number as you begin to build the next module. ▫For example, what you demo for module R1 would be version 1.0 ▫As you begin working on R2, your version would increase to 1.1, 1.2, 1.2.5, etc, as your program evolves. ▫What you demo for R2 would then be given version number 2.0

10. Display Date You need to implement a command that will display the current date on the screen. Possible syntax is “showdate”, “date”, “getdate”, etc. A support function is available which will help you with retrieving the system date. ▫void sys_get_date(date_rec *date_p); ▫Date_rec is a data structure defined in the support software with the following attributes:  int month  int day  int year ▫To get the current system date, you will need to declare a new date_rec variable, then pass a pointer to that variable to the sys_get_date function, which will set the date. You can then access the attributes of the date_rec variable and print out the date to the screen.

11. Set Date You also need to implement a command that will allow the user to change the system date. You can either have the user type the new date as an argument with the set date command (ex: “setdate 12-20-2008”) or prompt for the new date in any reasonable format once the setdate command is entered. The user may enter any valid date- however you must check that the date is valid (make sure they don’t try to put 31 days in April). If the date is invalid, you should display an error message. If the date is valid, you should change the system date, using the support function sys_set_date: ▫int sys_set_date(date_rec *date_p);  Returns 0 if date successfully set  Returns ERR_SUP_INVDAT if the date is invalid  Returns ERR_SUP_DATNCH if the date was not changed ▫You will create a new date_rec variable, and manually set the day, month, and year to what the user entered, and then call sys_set_date to change the date. Make sure to check the return value and see if an error was detected.

12. Display MPX Directory This is similar to the “dir” command in DOS. You will implement a command that will list all files with the.MPX extension in a given directory. You must display the name of the file and size in bytes. You can define in your code a default directory to always search, or allow the user to enter a specific directory from the command line. There are some support procedures to help you out ▫int sys_open_dir(char dir_name[]); -This function simply opens a directory to be searched  Returns 0 if no error  Returns ERR_SUP_INVDIR if dir_name is not a valid directory  Returns ERR_SUP_DIRNOPN if directory couldn’t be opened ▫int sys_get_entry(char name_buf[], int buf_size, long *file_size_p); -automatically searches the open directory for the next.MPX file that hasn’t been retrieved  name_buf: a buffer you create- sys_get_entry will store the name of an MPX file here  buf_size: size of name_buf  file_size_p: sys_get_entry puts the size of the file here  Returns 0 if no error  ERR_SUP_DIRNOP if the directory is not open  ERR_SUP_NOENTR if there are no more.MPX files  ERR_SUP_RFDFAIL if the read failed  ERR_SUP_NAMLNG if the file name was too long for your buffer ▫int sys_close_dir(void); -closes the currently open directory

13. How to get a directory listing 1.Open the directory using sys_open_dir When you call sys_open_dir, you can open the current directory by passing “\0” as the first parameter 2.Call sys_get_entry and display the information about each file. Continuously call sys_get entry until ERR_SUP_NOENTR is returned. 3.Close the directory using sys_close_dir

14. Terminate MPX Single command with no arguments, such as quit, exit, etc. However, it must confirm that the user wants to exit MPX by asking something like “Are you sure you want to exit?” and requiring the user to confirm their intentions. Once the user has confirmed, you should terminate the system, making sure to reclaim any memory you allocated.

15. Sys_init/exit support functions int sys_init(int module); ▫This should be the first line of code you execute. You will update this line with each module. For now, you should use MODULE_R1 as the parameter. This function initializes certain support software variables. void sys_exit(); ▫Should be the last line of code you call in your code. It will terminate MPX.

16. Sys_req int sys_req(int op_code, int device_id, char buffer[], int *buff_size_p); Sys_req is used for many things, including reading/writing to devices and generating interrupts. You must use sys_req to get input from the keyboard. Do not use scanf, fgetc, or any other C function. They will crash your system in later modules, so do not use them at all. Printf will work for output to the screen, however you can use sys_req for screen output as well if you choose.

17. Sys_req (con’t) Paremeters: ▫Op_code:  READ/WRITE: reads or writes data to/from a device  CLEAR/GOTOXY: TERMINAL only- clears the screen or moves cursor to a specific point  IDLE/EXIT: IDLE means a process is requesting to temporarily stop processing, EXIT means a process wants to exit (This is not the same as sys_exit) ▫Device_id: TERMINAL, COM_PORT ▫Buffer: if reading, information that is read is placed in this buffer. If writing, information is read from this buffer and then written to the device ▫Buff_size_p: if reading, the total size of the buffer. If writing, the number of bytes that should be written from the buffer Returns: ▫A number of errors- consult the R1 manual Sample usage for getting input from the keyboard: char buf[80]; int buf_size = 80; int error; error = sys_req(READ, TERMINAL, buf, &buf_size);

18. Sys_alloc/free_mem There are support functions for allocating and deallocating memory. You must use these, do not use malloc or calloc or any other C function. void *sys_alloc_mem(size_t size); ▫Allocates the number of bytes you specify. Sample allocation of an array of 80 chars:  char *buffer = (char*) sys_alloc_mem(sizeof(char) * 80); int sys_free_mem(void *ptr); ▫Frees memory allocated by sys_alloc_mem. Simply pass to it a pointer to the first address of the allocated memory:  int err = sys_free_mem(buffer);  Error codes listed in R1 manual.

19. Extra Credit You may do 3 of the following. They are worth 1% each on your MPX grade and can be turned in with any module ▫History  Display a list of the previous commands entered by the user ▫Batch files  run commands from a batch file or script ▫Change prompt  Allow users to change the prompt symbol (strings of a reasonable size should be allowed) ▫Aliasing  Allow the user to map different command names

20. Demonstration Due on February 5 Groups will be chosen at random Demonstration will consist of trying out all required functionality and any extra credits completed ▫If extra credit crashes the system - you will lose points, so don’t include it if it isn’t finished and tested. Demonstration will also include testing how your system handles invalid inputs. It should display an appropriate error message when an invalid input is encountered. If your commands are case sensitive, make sure that is documented in your manuals and in the help.

21. Tips Paging: Anytime an entire output from your MPX system, such as a help file, will not fit on the screen entirely, you need to display the portion that fits on the screen and pause until the user asks for the rest (i.e. “press enter to continue”). Keyboard input retrieved via sys_req will have a ‘\n’ character at the end Declare the sizes of all arrays as symbolic constants, and anytime you need to reference the size, reference the symbolic constant. Make sure any symbolic constants you use have different names from any files you use (i.e., if you have a MODULER1.C file, do not have a constant named MODULER1 or MODULER1.C) Make sure not to name any of your functions the same name as any C keywords Be careful with pointers and memory allocation. You will need to add and delete commands in later modules- design your system to make this as easy as possible