Document StdErr StdErr.E is a product of the Cheese Olfactory Workshop. Eat your greens. 0. Distributability ------------------- If you were able to get this, you may use it. If you are willing to distribute it FREE OF CHARGE, by all means distribute it. I would ask, for the sake of following your own conscience, that if you MUST charge someone money for this, that you not charge more than DevCon would charge for their PD disks (roughly $5 US or less a disk). 1. Usage -------- Very simple, really.. all depending on your needs. First thing to remember, however, is that you must err_Dispose() by the end of your program (or, at LEAST err_Close().. but err_Dispose() is the recommended method to use). If you fail to do this, you will leave a filehandle open (possibly), which would be very bad... it could also waste memory to do so. The next thing to remember is that StdErr.E really works best with EPP. EPP can make your life very easy. It's truly a remarkable program. If you're an E programmer working without EPP, you're making your life more difficult than necessary. Insure you download the very latest version of this useful utility by Barry Wills. Amusingly, I did not use EPP to write StdErr.E. Otherwise... 1.1. stderr.filename -------------------- If you want to change where your error messages are sent, you may reassign stderr.filename wherever you want the messages to go. For example: stderr.filename:='RAM:error.txt' will cause it to be appended to a file called 'error.txt' in the RAM: (yes, StdErr.E automatically appends messages to files, rather than overwriting the file). stderr.filename:=stdout will direct error messages to the stdout filehandler. It is the only case where a filehandler may be used instead of a string. stderr.filename:='CONSOLE:' will direct error messages to the stderr port (like C does). That is, if run from a shell, it'll print its messages to the shell, rather than to any potentially redirected output (eg. if someone typed 'command >moo.txt' the errors would not go into moo.txt, but to the console instead). 1.2. err_New(filename) ---------------------- VOID err_New(LONG filename) err_New() takes one argument, a string pointer (?) that will be inserted as the filename for the stderr port. err_New() does NOT open a file.. it only allocates storage for the stderr port. It is intended to be used if the stderr port is to be initialized to a particular area prior to writing any error messages (that is, you already know you want your error messages to go to, say, 'ram:boo.bob', so you use err_New('ram:boo.bob') to prepare the program to do so). You may want to read `stderr.filename' for more information. 1.3. err_Close() ---------------- VOID err_Close(VOID) err_Close() takes no arguments... in fact, you should really avoid using it. If E were C++, I would have hidden this as a private method. As it is, you COULD use it, but I don't recommend it. But, for the curious, err_Close() will close the filehandle (if it is safe to do so). I would STRONGLY recommend using `err_Dispose()' instead of this command. 1.4. err_Dispose() ------------------ VOID err_Dispose(VOID) This command will safely close the filehandle used by `err_Close()', and Dispose() of all bits of memory allocated earlier. You really should use this command at the end of your application, just before exiting, in order to safely close the filehandle and Dispose() allocated memory (although E will do the deallocating of memory automatically, I try to be a clean programmer). Remember.. before your ENDPROC main(), err_Dispose(). 1.5. err_Open() --------------- VOID err_Open(VOID) You should NEVER call this procedure. The only thing you might consider doing to this procedure is modifying the format string appearing DEEP in a VfPrintf() statement that displays the date, time, and weekday as a sort of file-header.. you might want to change the word 'ERROR:' to the name of your program or something. Otherwise, basically, this procedure opens a filehandler for stderr (making sure it can do so legally). It does a lot of checking and fool-proofing, allowing you to change `stderr.filename' easily. It also closes filehandles if you've changed stderr.filename. It's a fairly smart procedure. If any bugs exist in it, please let me know. 1.6. err_WriteF(format,items) ----------------------------- VOID err_WriteF(LONG format, LONG items) format - a bit of text to be printed out, similiar to WriteF(), but   without '\s' statements. items - a list of numbers that you may wish to have printed according to the format above. Basically, this is the procedure you use to write your error messages. Simply speaking, this statement works very similiarly to WriteF(), except that you cannot format strings, and the numbers you might format have to be in an E-list format (eg. [12,234,15,6]). So, you must use it like: err_WriteF('MyProg: \d cols is not enough!\nNeither is \d lines!\n', [col,lines]) If col = 5 and lines = 2, then the above should print: MyProg: 5 cols is not enough! Neither is 2 lines! err_WriteF() will call `err_Open()', insuring it has a place to write information into. 1.7. Possible Problems ---------------------- StdErr should generally work fairly well, but since it needs to allocate memory, and it needs to open files, there always exists the possibility that it will fail. StdErr has been designed to be as careful of these matters as possible, but I strongly recommend any programmer using StdErr to use RAISE IF statements (with Open and New) to protect his/her program from inexplicable errors. StdErr has been designed with error handling in these matters, with text being written via WriteF() (a most reliable way to write information) should it fail. Use of the StdErrExample.E as a guide is recommended. 1.8. General Pattern of Use --------------------------- Basically, use PMODULE 'PMODULE:StdErr' in your program, then invoke it something like: PROC main() DEF ... err_New(NIL) /* stderr, as in C */ blah blah blah err_WriteF('You are missing line #\d',[line]) /* error message */ blah blah blah err_Dispose() ENDPROC 2. About The Author ------------------- I'm surprised you care! My name is Joseph Edwards Van Riper III (although I'm generally called 'Trey'). I have written another program called 'Quip', which is a fortune cookie program that will eat your brain ... it has more features than any other fortune cookie program in existence. A dubious honour, authoring that monster. I've uploaded two datafiles for that program.. QuipZen and QuipMusic. Currently, I am a junior at the University of North Carolina, Asheville, working towards my Bachelor of Arts in Music (with an emphasis on Composition). I have one more year left here, and it would appear that I will finish with my degree in that year, totally four years of college life for me (a shorter time than some of my companions, I've noticed). I was in the US Army as a bandsman/journalist for five years and a month, two years of which I spent in Japan (Camp Zama, for the curious). I would care not to repeat that experience. I type blindingly fast for a non-clerical student, and I work with computers with an intuitive feel for them; when something goes wrong, I can intuitively sense where the problem is, and find a solution. I think computers will steal my soul if I'm not careful. I am a vegetarian (vegan, and becoming even stricter in my eating practices), and a non-denominational Christian. You may mail me at jvanriper@uncavx.unca.edu. If you can find the Mosaic server at UNCA, you can poll my account for MIDI specs and more junk about myself. You can also find me lurking around the Amiga E mailing list. Moo. 3. About The Program -------------------- StdErr.E was originally an idea born inside Quip.E (that is, Quip the Fortune Cookie Program from Hell, not the QWK reader). I was having a horrible time handling my error messages. I had some very specific needs, considering icons and stuff. I worked out all my problems with Quip, finally getting something to work the way I wanted it to do. Then I realized that there may be others who needed something similar to Quip's stderr handling, although reading through Quip.E to find the necessary bits of code would require someone with more patience than Job. I thought, therefore, I should extract the core of my routines, re-form them to be simpler to use, and add a few extra nifty features. Thus, StdErr.E was born. StdErr, being reworked from Quip's stderr handling, works better, and is far more organized. I attempted to follow an Object Oriented approach, despite the fact that Amiga E is not an Object Oriented language. To this end, I used the 'err_' prefix, while using fairly common commands such as 'WriteF' and 'Open' to keep things organized and simple to understand in function. I also created an Object, and purposely renamed one of the members in the object a value that wouldn't have as much meaning to people, since I didn't want anyone messing with it. I decided to use 'stderr' as a global variable, because essentially nobody else should have a need for such a variable name, once these methods are employed, and it seemed to be a very easy variable name to remember. StdErr.E has been tested, and should not leak memory or crash. It tries to be very durable. 4. To Do -------- The only things I can think of that would really improve this code tremendously would be: * Allow strings to be formatted in the text. * Include Fault() handling as an option.