Welcome to PROBE2. This program is a serial port data-scope with in-built (very) dumb terminal facilities.
It allows you to monitor communications traffic on more than one serial port at the same time, displaying the information in a similar manner to a dedicated data 'scope machine. In addition, it can capture comms traffic to a file, send data from a file to a comms port and interact with a comms port under script language control. <%HEADINGSUB%> Requirements
In order to work, PROBE2 requires:
PROBE2 appears to function correctly under MS-DOS 6.22, Windows 95, Windows 98, Windows NT, Caldera's OpenDOS and later versions of MultiUser DOS. (We have had a report that it runs under Linux's DOSEMU 0.7 utility, but we cannot confirm that.) <%HEADINGSUB%> Package Contents
You should have the following:
| p2.exe | The PROBE2 executable file. |
|---|---|
| p2.hlp | The program's context-sensitive help file. |
| chat.fth | An example script language source. |
| sys.fth | A script language "header" file. |
| p2tutor.fth | A script file that is used in the PROBE2 tutorial. |
| *.pat | Files that contain various diagnostic patterns. |
| %P2VERSIONSHTML% | Change history of the PROBE2 program. |
| %P2TUTORHTML% | PROBE2's tutorial document. |
| %INDEXHTML% | This introduction to PROBE2. |
| %P2FAQHTML% | A file of Frequently Asked Questions. |
To actually run PROBE2, only the executable is required . (If you save the PROBE2 configuration, then it will create one or more .INI text files.)
If you are a first-time user of PROBE2, I suggest that you run through the lessons described in the tutorial. <%HEADINGSUB%> Licence
PROBE2 is a public domain program. You are free to re-distribute PROBE2 to third parties if:
We'd better get the bottom-covering disclaimer out of the way:
PROBE2 was written by Mark ("Eddie") Edmunds, who wrote the serial comms drivers and timer facilities, and Mark ("Captain ChAoS") Davis who wrote everything else.
By virtue of the fact that ChAoS had a hand in writing this:
I'm not sure that the terms "public domain" and "copyright" aren't mutually exclusive. Even so, this software is:
Thanks to Borland for their "C" compilers and TurboVision software library.
Thanks, too, to the authors of 4tH which we currently use as PROBE2's scripting language. They can be contacted via their web site or their email address. <%HEADINGSUB%> Contacting The Authors
If you have any bug reports or suggestions, you can contact either of the authors at the PROBE2 email address.
Since ChAoS is the licencee of an amateur radio station (G0KHB), you can contact him by writing to that station's correspondence address.
If you like PROBE2, perhaps you'll like the rest of the ChAoS Utilities - please visit the web site. #close * ;=========================================================================== #define QOpen When I run P2 under Windows, why won't it always open the serial ports? #define QJunk Sometimes, when I re-size a P2 comms channel window, I get all sorts of rubbish displayed in it. Why? #define QSend I open a comms channel and it immediately starts sending the contents of a data file to the channel just opened. Why? #define QBlip Why do funny things happen when I try to run P2 on an MDA (old "mono") screen. #define QTime When I run P2 under Windows, why does the heart-beat speed up? #define QTiNT P2 crashes when I use OS=WIN95 under WinNT. Why? #define QHang When I run my P2 script, P2 "hangs". #say Generating FAQ HTML file. #send P2FAQhtml
| 1.4.042 20010707 | The ALT-Z button used to change to the next window. It now invokes the scope window, instead. When the baud rate of any scoped channel is changed, the scope window now clears and shows the latest comms channel information. A bug was fixed concerning the displaying, in the scope window, of baud rate information relating to non-scoped channels. This occurred when the speed of a non-scoped channel was changed. A bug was fixed that caused P2 to crash when ludicrously high baud rates were entered. The scope window now acts more like the "normal" comms channel windows: when the scope window is invoked using a short-cut button, the window may be opened or selected depending on it's current state but it will no longer be closed if the button is pushed when the scope window already has focus. |
|---|---|
| 1.4.000 20010523 | The old MSdos timer code has been put back into P2. While the new timer code ran much better under Win95 (if one used "OS=WIN95") and ran at all under WinNT (if one used "OS=WINNT"), it appeared that the code did not run better under MSdos. Hence, there are now three different timer service providers that get selected via the "OS" keyword. The program will now detect when the Windows timer function is not accessible and "fall back" to using the MSdos timer service. The WinNT timer service has been slowed down by a factor of two. The default "MILLITICK" value (see the next paragraph) is now the same as for the MSdos timer service. It appears that some computers have timers that run at a different rate to the "norm". Hence, a new key-word, "MILLITICK" has been added that allows the user to "tune" the MSdos and WinNT timer services. The default rate is "1193" and, for example, if your P2 timers appear to be running at twice the speed that they should, you'd use something like "MILLITICK=2386". (The Win95 timer does not suffer from this problem and, hence, is not configurable.) Note that like the "OS" key-word, the MILLITICK value is not saved in the configuration file. |
| 1.3.000 20010425 | Since the ASCII table and calculator facilities don't seem terribly useful, these have been removed. The benefit is an extra 10 KB of heap space - now that's much more useful, IMHO... |
| 1.2.043 20010424 | P2 now uses a more reliable timer strategy and, as a result of these changes, it will now also run happily under WinNT. In addition, one can now select an improved Windows-based timer strategy if one is running under Win95 or Win98. (This new scheme does not work under WinNT.) As a result of these changes, P2 will now accept an extra configuration parameter that allows the user to invoke any special code that only works under one operating system or another. (At present, only the timer code makes use of this new parameter.) The new key-word is "OS" and possible values are "MSDOS", "WIN95", "WIN98" and "WINNT". (For example, "P2 OS=WIN95".) These may be expanded at a later date. You are advised, for best performance and reliability, to always employ the correct operating system parameter. This new parameter is not saved when the system configuration is written to a .INI file since one may want to share a .INI file between a P2 running under different operating-systems. (You are advised to let it default to MSDOS when running under MSdos and place the corresponding item in .LNK or .PIF files when running under Windows.) |
| 1.1.002 20010311 | Adopt the new "standard" format for the files that keep track of the program's version number. This will allow easy generation of the current version of the program and, in particular, the web site can automatically generate a list of current program version numbers. |
| 1.0e02 19990805 | Added short-cut key help pages. |
| 1.0e01 19990526 | Added an extra hex mode. Mode three displays a character as in mode zero, unless it lies between 0x00 and 0x1F, in which case it displays the character's ASCII name. (Try it...) |
| 1.0d01 19990316 | As well as being able to capture a snap-shot of the script window, you can now "log" it as well. (The former captures the current buffer on a once-only basis;; the latter continuously logs to a named file until you stop it or the program is terminated.) |
| 1.0c03 19990219 | Added a little more help;; this time, it was about tab stops. |
| 1.0c02 19990218 | A little cosmetic change to the help context of the comms and scope windows. Also, a little text was added to the help system with reference to the Configs / All dialogue box. |
| 1.0c01 19990214 | The "last typed" field is only retained in a string history list saved if it is equal to or longer than a minimum length. In previous versions, this length has been four characters. In this version, however, this can be changed by using the Config / All dialogue. This value is saved as part of the configuration file. While on the subject of the "last typed" history, the program now applies back-space character processing to the last typed command before placing it into the command history. The above-mentioned length test is done after this back-space processing is carried out, so it the final length of the string that is important. This behaviour now defaults "on" but can be disabled via Config / All. |
| 1.0b29 19990206 | Altered the trigger edit dialogue to remember which trigger was the last to be edited (on a per-channel basis) and make the dialogue box display that trigger the next time that it is opened. |
| 1.0b28 19990128 | Added the global option, "screen bliping". This defaults to "true" and, if enabled, will switch video modes, twice, on start up. This, for some reason, speeds up the display of characters on the screen. The downside to bliping is that if you want to start P2 on the MDA screen of a PC that has dual video cards, bad things may happen. Most of the time, of course, bliping causes no trouble and has a very beneficial effect. (The screen bliping has been carried out by P2 at start up for some time. It was only when I wanted to run it on an MDA screen when running under Windows 95 that I came across this problem and had to add this switch.) |
| 1.0b27 19981026 | The hex mode selected is now displayed on the status bar in the character translation field if the current translation mode is "hex". |
| 1.0b26 19981022 | The file history of the Configs / Write As dialogue has been changed so that is it not common with the file receive and transmit stuff. (See the following change for the justification for this.) The capture, receive, transmit and script file names are now in separate histories and these histories and now persistent. That is, the file names are saved in the .INI file along with the rest of the configuration information. (I got fed up with typing in the same file names after I'd stopped and re-started P2...) |
| 1.0b25 19981019 | Changed the code so that, for comms windows only, tab characters (ASCII 0x09) are intercepted and sent to the associated output channel. |
| 1.0b24 19981018 | You can now set a tab stop value for a channel via the channel's options dialogue. Any tabs encountered in the input stream will be tab expanded if the tab stop value is greater than zero and the display mode is plain ASCII. |
| 1.0b23 19981018 | When the default channel associated with the script window is displayed, the channel's description is displayed rather than the channel's number. |
| 1.0b23 19981016 | When the default channel associated with the script window is displayed, it now displays the channel's name rather than the channel's number. |
| 1.0b22 19981015 | I have just found out why the script window takes up so much memory - the number of text lines in that window default to the maximum (400). I have, therefore, added an option to Configs / All that allows you to alter the number of text lines in the script window. |
| 1.0b20 19981009 | When the scope baud rate, data bits, stop bits or parity is altered, then the changes are now rippled through to all open channels that have the "scoping" attribute turned on. This means that if you are monitoring a couple of channels and they are running at the same speed, you can now change speed for both channels by altering the scope channel's speed. This also applies to the speed change short-cut keys. It should be noted that altering the speed of a particular (non-scope) channel will behave as before - that is, only that channel's speed will be affected. The handling of the "scoping" switch has been altered. As a result of making the above change, I noticed that if one turned the scoping switch off when the channel already was being monitored by the scope window, that the channel's output would still appear in the scope window. This entailed a bit of fiddling with the main idle loop that handles incoming serial traffic and farms it out to the correct place(s). |
| 1.0b19 19981004 | Bind the toggling of scoping to control-F8, the toggling of beeping to alt-F8 and and the toggling of piping to control-F9. (All of these toggle the "per-channel" switches rather than the global switches.) Also, PROBE2 is now compiled using the '286 instruction set thus saving a little memory. |
| 1.0b18 19981001 | More help added plus the help now always comes up full-screen. |
| 1.0b17 19980929 | Yet more help added... |
| 1.0b16 19980928 | More help added... |
| 1.0b15 19980927 | Started to add the help pages. Also, removed the channel enable option from the facilities menu as it seemed a bit out of place and I don't think that users are likely to require that option much after the initial configuration on a particular machine. |
| 1.0b11 19980926 | Bind the alt-minus key to File / Resend Last and alt-equal (or alt-plus) to File / Resend Command. |
| 1.0b10 19980926 | Bind the grey plus key to do a "next window" command and the grey minus to do a "previous window" command. |
| 1.0b09 19980926 | Changed the code so that the text sent via a File / Resend Command was logged in such a way that it appears in the File / Resend Last history list. |
| 1.0b08 19980926 | Added code to set the line and character pacing after the dialogue that they appear on has been closed. |
| 1.0b07 19980925 | Changed the "freq" field of the trigger dialogue box to accept the frequency of the sound required rather than half the period in milli-seconds. Note that, at present, the highest frequency that can be emitted is actually only one kiloHertz due to the way that the speaker is handled. However, we hope to change the system timers such that the usable range is not limited by PROBE2 itself. |
| 1.0b06 19980923 | PROBE2 is now officially "P2". |
| 1.0b05 19980919 | Changed the text on the File / Run Script menu option. |
| 1.0b04 19980913 | A "right margin" channel variable has been added. Whereas the left margin variable is an offset from the start of line (that is, a zero left margin is the first character of the line), the right "margin" is actually the character offset where no characters will appear. That is, it actually sets the width of the formatted text. The default is the line buffer width for ASCII translation mode and the window width otherwise. Setting the margin too large or too small results in the default behaviour. |
| 1.0b03 19980908 | A new option has been added to all windows - the "tileable" flag. If this flag is not set, then a window will be unaffected by a Windows / Tile operation. By default, the scope, information and script windows are not tileable and all other windows are tileable. Note that while the comms windows (including the scope window) can have their tileable option set via a dialogue, the information and script windows cannot, although they can be set by editing the .INI file. |
| 1.0b01 19980905 | Added a little bit of code to save the last line a user types in and allow it to be entered. This is a bit like the "command line" functions of prior version except that the commands that you entered are not saved between PROBE2 sessions. Therefore, if you want a command to be saved, you must still invoke the Files / Resend Command option and type it in. If you've already typed it in, you can use Files / Resend Last, instead. Note that the key that invoked Resend Command is now used for Resend Last and that the latter facility may be a bit wobbly - I seem to have hit some sort of size limit on the main module again. This means that I won't be adding any further code until I've shifted something out of the main module. The default size of the information window has been increased slightly to take into account the addition of a few extra items. |
| 1.0a97 19980905 | When opening the scope window, it sometimes (always?) corrupted the menu bar. This has been fixed. (For once, this was not my (MSD's) cock-up - a certain other person left some diagnostic code in one of their modules...) |
| 1.0a96 19980904 | Altered the "escaping" of command-line history strings to treat a trailing back-slash as a "space". Hence, if the last character in the command-line is a back-slash, a space character will be sent to the comms channel. Also, it doesn't, now, matter if you edit a command-line history string, in the .INI file, using an editor that strips trailing spaces because the back-slash escaping will put it back on when the string is executed. |
| 1.0a95 19980904 | Alter the "info box" messages to be centred. |
| 1.0a94 19980904 | Added the "thaw" (un-freeze) trigger action. |
| 1.0a93 19980903 | One problem with "freezing" a comms window is that you no longer have any indication when there is any "traffic" on that channel. I have now added a traffic indicator on the status line - if the currently focused channel has had any incoming traffic, then the channel "description" on the status line will turn red until the status line is next updated. (It will stay red if there is enough activity on the focused channel.) |
| 1.0a92 19980902 | Cured a bug in the capturing of the windows;; the file was being opened as a "binary" file and, hence, the carriage-return / line-feed line terminator weren't being generated correctly. Also, while in that area of the code, the saving of trailing spaces on each line was inhibited. |
| 1.0a91 19980831 | The display of the CPS figures in the info window were incorrect - the "totals" field would often assume the value of the "in" or "out" fields. This has been fixed. |
| 1.0a90 19980830 | Fixed a little bug whereby non-printable characters were not being translated to full-stops, as I had intended, when a window's contents was captured to a text file. |
| 1.0a89 19980830 | Altered the file capture options to discard all blank lines until some text is found. This stops the file containing mostly blank lines when the text in a window hasn't yet scrolled far enough to start being lost off of the top of the window's text buffer. |
| 1.0a88 19980827 | The "beep" period and frequency is now kept on a per-trigger basis which means that you can make different types of beeps depending upon the trigger condition. For example, a short, high-frequency beep can be used as a "traffic" indicator with a longer, lower-frequency beep based upon a timed trigger meaning "no traffic". |
| 1.0a86 19980826 | A bit of fiddling was done to pretty up the trigger info window entries and also to add the "before lines", "after lines" and "mode" values to the display. This does mean, however, that the window must be "zoomed" full-screen before the "value" field can be seen. |
| 1.0a85 19980825 | A little bit of faffing around with date and time stamps in configuration files and captured comms, information and script window files. |
| 1.0a84 19980825 | Altered the trigger actions to be check boxes rather than radio buttons. That is, you can now do more than one action at the same time. However, the order in which the actions are performed depends upon the way that they are coded. At present, the actions are carried out in the order that they appear in the trigger dialogue. Note that the "line feed" action has been removed since the same action can now be obtained by merely not selecting any actions. The "before lines" and "after lines" are carried out, regardless of the rest of the trigger's configuration, unless the relevant field is set to zero. In addition, some of the start-up default values of the triggers, the comms channel switches and the global switches have been fiddled with - for example, all triggering switches now default to "enabled". |
| 1.0a83 19980824 | Added the "beep" trigger action. |
| 1.0a82 19980824 | The ctrl-backtick, alt-backtick and ctrl-backspace buttons now all cause a CMPREV instead of a CMNEXT command. This means that they will step onto the previous window rather than the next window. The reason for the change is that the CMPREV command processing in TurboVision appears to have a little bug whereby it brings the window selected to the top of the Z-order whereas CMNEXT does not. Therefore, when "bring to top" is switched off, one can still use CMPREV to bring a window to the top of the Z-order. Associating the aforementioned buttons makes this facility a little easier to access. (That is, it's a little easier to press those buttons using one hand than shift-F6.) |
| 1.0a81 19980823 | Addressed the problem of the program updating the screen much more than was necessary. There is now an extra timer in the system which, if set to a non-zero value, will make the program only update the screen when that timer expires. If the timer's value is set to zero, then the screen will be updated on the same basis as before. Namely, it will be updated when any part of the program requests it. (If debugging is on, then the idle loop counter and frame rate counter will be displayed as an extra line at the bottom of the info window.) |
| 1.0a79 19980822 | Added a facility whereby one can set the left margin of the channel windows. Also, an escape mechanism has been built into the "before lines" and "after lines" numbers of the trigger dialogue. If the lines requested is negative, then a margin release is done before the following text. Also, the meanings of the requested number of lines has changed. Now, a value of zero means that no new-lines are required, a value of one means that a new line is required and a value of N that N-1 blank lines is required. The best way to understand all of this drivel is to have a play with the settings and see what happens. A good setting to try on the scope window is a left margin of seven (the length of the string "[COMx:]") and, upon channel change trigger, "before" lines of -1 and "after" lines of zero - this will make channel changes pretty obvious because they will be "margin released" and appear at column zero of the scope text window. |
| 1.0a78 19980822 | Changed the trigger "flush" action onto a "date and time" action instead. |
| 1.0a77 19980820 | Added a new option: Configs/WriteAs. This option prompts for a configuration file name before saving the configuration information in that file. The entered name is also used as the default config name so any subsequent use of Config/Write, for example, will go to that newly-created file. |
| 1.0a76 19980820 | Changed the way that configuration files are handled. Now, if the program finds a "response" file name on the command-line, it will use that name for the configuration file and will save using that name when the configuration information is written away. (Two passes are now made over the parameters;; the first gathers the response file name, the configuration information is read in and then the second actually executes the command-line arguments as if they'd come from a configuration file.) |
| 1.0a75 19980820 | Fixed a bug whereby timed triggers would still be triggered and their actions carried out even if the channel concerned had data turned off. |
| 1.0a74 19980820 | The freeze/thaw and data on/off button action used to check in the other was in the non-operative state before taken any action. (For example, if you pressed the "freeze" button and the channel was set to "data off", the freeze action would be ignored. This is no longer the case - you are assumed to know what you are doing and to be able to read the channel's status information line... |
| 1.0a73 19980820 | Altered to display the scope channel's RX file name, if any. |
| 1.0a72 19980819 | Clear window and clear line now work regardless of whether the window is frozen or not. A new option has been added, Facilities/ClearAll, that clears a window and does not display the status report. There are now three "value" fields associated with each trigger. The first, merely labelled "value" on the dialogue, is the trigger-type specific "on what?" field. (That is, the trigger character for character triggers, the milli-second time interval for timed triggers and so on.) The second and third fields, labelled "before" and "after" are the numbers of new-lines to be throw before and after any new text displayed upon the screen as a result of the trigger action. Note that leaving these both as zero when the action is "new-line" will the equivalent of a "flush" action;; hence, the flush action is now spare and the functionality of action zero may change pretty soon... |
| 1.0a71 19980818 | Added a new trigger action that causes the channel's description to be sent out as "system text". This is used to identify channels in captured text from the scope window. |
| 1.0a69 19980818 | Fixed the F9 button - wasn't working on the scope channel. |
| 1.0a68 19980817 | Added an option which allows setting of the info window and status bar update rates. (Both times are in milli-seconds.) |
| 1.0a66 19980817 | Fixed timed triggers on the 'scope channel. (They would only trigger if the channel that the character came from had channel triggering enabled.) |
| 1.0a65 19980816 | Added a per-channel trigger enable/disable option. Other cosmetic changes. |
| 1.0a63 19980816 | Tidied up the "physical" and "options" dialogues. Also, some cosmetic changes to the info window. |
| 1.0a61 19980815 | Added the percentage load page to the info window. |
| 1.0a60 19980812 | A new trigger action has been added: "banner". This generates a system message in the triggered channel's window. The "DISCARDED DATA" system message has been altered to display either "DATA ON" or "DATA OFF" as appropriate. A new trigger type, "timed", has been added. The "value" field specifies the number of milli-seconds that must elapse on a channel before the channel is deemed to have timed out. |
| 1.0a60 19980812 | A new trigger action has been added: "banner". This generates a system message in the triggered channel's window. The "DISCARDED DATA" system message has been altered to display either "DATA ON" or "DATA OFF" as appropriate. |
| 1.0a59 19980811 | Triggers may now occur due to channel changes on the 'scope channel. However, at present, they may only be set up via direct editing of the .INI file. (Use "TRIGTYP = 1".) |
| 1.0a56 19980810 | You can now specify the crystal speed of the UART. Also, the program now reports the actual speed (if different from the the requested speed) when the channel is opened. |
| 1.0a55 19980803 | Enabled triggers for scoping and extended info window to scope. |
| 1.0a54 19980802 | Added trigger dialogue and trigger before/after flags. |
| 1.0a50 199807?? | Added triggers. |
| 1.0a48 19980722 | Changed line pacing to work on CR as well as LF.
|
This "tutorial" assumes that you are about to run P2 under an MSdos-compatible system. While P2 will run under WinNT, the timers seem to behave erratically;; thus, at present, we do not recommend running P2 under 'NT. In particular, the tutorial's demonstration script will not run correctly.
Copy the P2.EXE, SYS.FTH and P2TUTOR.FTH files into a newly-created temporary directory, making sure that you do not have a .INI file present.
Place a loop-back tester, that loops back at least the RX and TX pins, on the comm port connector that you intend to use for this session. (If you don't have a loop-back tester, cut up and paper-clip and stuff that into the RX and TX holes of the connector.)
Invoke P2 by typing the name of the .EXE file. <%HEADINGSUB%> Enabling A Comms Channel Whenever P2 is run and it can't find a configuration .INI file, it will display a warning message telling you that all of the comms channels are disabled. This is because Bad Things may happen if it were to attempt to install interrupt handlers for comms channels that you do not have. Therefore, the first thing to do is to ascertain what channels you do have and enable those channels that you wish to use using P2's configuration options.
For the purposes of this tutorial, I'll assume that COM1 is available and is not in use by any other program - if you have to use a different channel to COM1, just substitute that channel's name whenever COM1 is mentioned.
In the top, left-hand corner of the screen, you should see a beating heart character. This is there merely there to show that P2 is still active and hasn't "died".
Press the "OK" button and the warning message should disappear. Note that you are presented with a blank screen. This is because there are no comms channels open. Therefore, the first thing we need to do is to enable the channel that we are going to use for the duration of this tutorial. Select Configs / Options and then COM1 (or whatever). Rather than describe all options of each menu that appears, I'll just describe the most important ones - full details of the others may be found in the context-sensitive "help" pages.
For the moment, ignore all of the options except for the one labelled "Enabled" - that is the option that will allow you to access the comms port that we require. "Check" that box, using the mouse or the "space" key. Close that menu by selecting the "OK" button by using the mouse or "return" key.
From now on, I'll assume that the user is competent enough to navigate these menus without out "spoon-feeding" them. Note that many of the menu options have short-cut keys and that the names of these keys appear next to the corresponding menu entry. <%HEADINGSUB%> The Status Bar Select Channel / Open All. Since only one channel is enabled, the comms window for that channel only should appear. The text in the window tells you the state of various options and again, on the last line of the screen, most of these options' state is duplicated. In general, the status bar entries are in red when a "dangerous" state is selected and black otherwise.
The first item on the status bar is the name of the selected comms channel. Note that the names are configurable. The name will be in red when there is comms traffic on that channel.
The second item is the "translation mode" of the channel. There are three modes: ASCII, HYBRID and HEX. ASCII translation, as you might expect, makes P2 display the text rather like a dumb terminal program would. Note that the text wraps, by default, at column eighty, regardless of the window width;; the other modes cause the text to wrap at the edge of the visible window. (When in ASCII mode, formatting of text destined for a dumb terminal might be disturbed were this not so;; in the other translation modes, the formatting, by definition, will be disturbed, so wrapping at the window edge allows all of the text for a channel to be visible and no scrolling is therefore required to see it all.)
The third item is the "frozen" status. If a window is frozen, then the window is not updated regardless of the amount of traffic on that channel. However, you can still tell if traffic is present because the channel description, mention above, will be changing colour if there is traffic. (If there is enough traffic, it will stay red.) If a window is frozen, the traffic is still being captured and formatted according to the mode that you have selected. However, you won't see any of this text until you "thaw" the window. Note that because the window is never updated when frozen, you should not change screen mode, tile the windows, or in any way disturb the status quo of the program's display - if you do, the window will display rubbish until you thaw the window.
The fourth item on the status line is the data capture switch. If data is being captured, this flag is black. If it has been disabled, then it is in red because you may be missing something important. This switch allows you to freeze a window's buffer in a similar manner to the freeze option above, except that you can scroll back through the buffer and that incoming data on the channel is discarded while the window has data turned off.
Any channel that has the "piping", the fifth status line item, option enabled, will have the incoming data transmitted to all other channels that have the piping flag enabled. This allows P2 to be used in two different modes: piping mode and probe mode.
Probe mode is when you make a special cable up that you insert in the link between to ends of a comms link. The cable must be a straight-through cable except that the RX and TX lines are taken to two of the P2 machine's RX lines. Hence, when scoping, the two ends of the comms link will behave just as if the probe machine wasn't connected.
If, however, piping mode is used, the link between the two ends of the link is broken by cables connecting them to the probe machine. The probe machine then reflect all incoming data from one channel to the other. If the probe machine is fast enough, there will be very little difference between these two modes but, obviously, the comms link will not behave exactly the same when piping. Clearly, a probed link is better than a piped link.
The sixth item on the status line reflects the status of the channel's trigger option. If this field is in red, then triggering for that channel is enabled.
The seventh item on the status line is the scoping flag. If this flag is in black, then scoping has been enabled for this channel. This means that when the scope window is opened, this channel's output will appear in it, mixed with data from the other channels that also have the scoping flag enabled. The scope window is, of course, P2's raison d'etre.
P2 can send and receive files. This facility is intended for testing purposes but can be used, for example, to capture files sent by other systems. On the status line, the RX and TX fields hold the name of the files currently being sent or received. If the fields are in black, then the files are not being used. If they are in red, then the system is accessing them.
Well, it could be time to actually send some comms traffic, if you haven't already been unable to resist the temptation to "tickle the ivories".
Type in your name, or any other text you fancy. Since we have a loop-back connector fitted (we have done this, haven't we?), the text should appear on the screen in, if you are using COM1 in the default colours, white on blue. Each channel has its' own colour scheme to enable the channels to be distinguished from each other when their output is displayed in the scope window. Note that unlike other terminal programs, the default background colour of the window is not the same as the background colour of displayed text. Hence, you can, for example, see if trailing spaces are being transmitted at the end of each line. Of course, that sort of thing is best done by playing with the translation modes... <%HEADINGSUB%> Character Display Mode Press the carriage-return key and note that the cursor returns to the left-hand margin. Select the menu option Facilities / Xlate Mode. This option cycles between the ASCII, hybrid and hexadecimal translation modes. Since, before selecting this option, we were in ASCII mode, the mode should have changed to hybrid. Hybrid mode is similar to ASCII except that non-printable characters are displayed in the current hexadecimal format and, since the formatting of plain text is therefore disrupted, it wraps at the visible window width. Type in some text and then press the carriage-return button again. This time, the carriage-return should have been displayed in hexadecimal. This is because, although it affects the layout of text, it's not actually printable.
The next translation mode is hexadecimal. Invoke the Facilities / Xlate Mode menu item again. This time, full hex mode is selected and all characters appear on the screen in hexadecimal. Since you may not like the default hex display mode (hex mode zero), others are provided. To select the other modes, invoke Facilities / Hex Mode. Type in some more text and play with the hex modes to find out what they look like and then change back into ASCII mode. <%HEADINGSUB%> Local Keyboard Echo Sometimes, it's nice to know what key you actually pressed on the key-board. The Facilities / Local Echo will cause typed keys to appear on the screen. Select this menu entry and type some more text. Each key should appear in the local-echo colour followed by the incoming (looped back) text in the channel's "traffic" colour. Turn local echo off by selecting the menu item once more.
When one is interacting with a device via the key-board or causing data to be sent to a remote device, it is sometimes useful to be able to create a "break" in the window text so that one can easily separate the different dialogues. Hence, the different window clearing options on the Reports menu. Selecting menu item Reports / Clear Line will generate a blank line on the screen. If I am generating lots of small mini-dialogues on the screen, I sometimes like to use this between each one so that I can get a better picture of the differences between them. Reports / Clear Window, as you might expect, clears the window to the state it was in when you first opened the comms channel. Reports / Clear All does the same but inhibits the status text placed in the window after it's cleared. <%HEADINGSUB%> Script Language To demonstrate most of P2's facilities, we need some comms traffic. Since the tutorial has to know what the user will have on the screen, we need known traffic. P2 has a built-in scripting language, currently provided by the "4tH" scripting system. (To find out more about this Forth scripting machine, access http://visitweb.com/hansoft or email hansoft@visitweb.com - I'm pretty sure that they would welcome your interest.) 4tH is a dialect of Forth. For now, we merely need to know how to run a simple script to provide test traffic for this tutorial. Therefore, do the following:
From the menu system, select File / Run Script. The script window will open and it tells you on which channel the transmitted text will appear. Invoke the File / Run Script again. This time, because the script window already had the focus, the script selection box appears. Choose the file P2TUTOR.FTH. Note that the script runs and that an announcement to this effect appears in the script window. Also in the script window, is an incrementing line number counter. This line number should also appear in the comms channel window. (If you inspect the script source, you will see that I've deliberately sent the line count to both windows.) <%HEADINGSUB%> Window Freezing Use Windows / Next to give the comms channel window the focus. Now that we have some output appearing in the comms window, the difference between freezing a window and turning the data capture off can be demonstrated. Invoke Facilities / Freeze Window. The window's output will stop scrolling up and the freeze item on the status line turns red. Note that the left-hand item on the status line, the comms channel name, is blinking red and black. This is because although the comms window is frozen, there is still traffic on that line. Noting the last line number displayed in the comms window, select Facilities / Freeze Window again. Line numbers, once again, scroll up the screen. You will see, though, that the line numbers that were displayed while the window frozen were captured and are now scrolling up the screen. <%HEADINGSUB%> Data Discarding Select Facilities / Discard Data. The scrolling will stop but, unlike when the window was frozen, some text appears in the comms window telling you that data is being discarded. As before, the comms channel name on the status line is flashing red to indicate that the incoming traffic is still present. This time, however, you can use the comms window scroll bars to scroll back through the captured data buffer. (At present, the scroll-back buffer is limited to 400 lines and, in fact, we would recommend that you use the smallest number that you can - we are experiencing memory shortage problems and, until we can get P2 to run in protected mode, memory is at a premium. In particular, the script window is a bit of a memory hog...) Do so now and leave the window displaying the very top (earliest captured text) end of the buffer. Now, press an (ASCII) key. The buffer view point immediately returns to the end of the buffer. Usually, when one has typed some text, one wants to see the results and that's why P2 returns to the end of the buffer when a key is pressed;; note that this behaviour can be disabled via one of the menu options. Re-enable data capture by re-invoking the Facilities / Discard Data option. Note that, this time, traffic that passed when data capture was turned off has been lost. <%HEADINGSUB%> Trigger Facilities Well, it's about time that the triggering facilities were demonstrated. Make sure that you selected comms channel is in ASCII mode. Select Configs / Trigger and indicate the comms channel that you are using. You should now be present with a fairly large (for P2) dialogue box.
In the top, left-hand corner of the trigger dialogue box, the trigger number is displayed. The first part of this number is the channel number, which numbers from "one", and the second part is the trigger number which numbers from "zero". Hence, "1/0" would be the first trigger of the first comms channel.
The function of the trigger enable/disable check box should be fairly obvious. The "single shot" check box, if "ticked", will disable the trigger after it has been triggered and the trigger's actions carried out.
The field labelled "value" is used in conjunction with the trigger "type" field. If the trigger is to be triggered upon the detection of a certain character value, then that is what is placed in this field. If the trigger is a "timed" trigger, then the length of quiet (no traffic) time before the trigger is triggered is placed in this field. If the trigger is triggered when a change of channel is detected (scope window only), then this field is ignored.
One can cause blank lines to be displayed, both before and after the triggered event, by filling in the "before" and "after" value fields. Negative values perform a "margin release" operation.
The "beep" value is the duration, in milli-seconds, of any sound emitted by the system as a result of the "beep" check-box being ticked. The "freq" value field is the frequency, in Hertz, of the beep sound.
The ASCII / HYBRID / HEX check boxes allow you to select in which modes the trigger will be active. Note that if none of these is checked, then the trigger will never be triggered.
The Before / After check boxes dictates whether the trigger's action are carried out before or after the window is updated with the character which caused the triggering. (With timed triggers, the this field should be set to "after".)
Finally, the large check box cluster sets the action(s) to be performed when the trigger is fired.
The "beep" box will cause the system speaker to emit a beep of a duration and frequency that depends upon the settings of the numeric fields at the top of the dialogue box. If "clear" is selected, then the window is cleared. If "chantext" is selected, the channel on which the triggered character was found will be displayed in the window and, if "date&time" is selected, the date and time will be printed. The "banner" field will merely make the trigger displays its identifier (that is, channel and trigger number). "Discard" will turn data capture off and "freeze" will turn window freezing on while thaw, of course, turns freezing off.
Note that these are selected from a check box, not a "radio" box and, therefore, more than one action can be slated at the same time. The order in which they are performed is, however, dictated by the trigger's number (lower numbers first) and the trigger action (in the order that they appear in the check box cluster).
Right, it's time to make a trigger. Fill in trigger zero's dialogue box thus:
Now "OK" that dialogue box and - nothing happens. This is because you have created a trigger that will only work in hybrid and hex modes. Select Facilities / Xlate Mode. Now things start to happen. Not only should the text run across the screen but, after every line number is displayed, the system should beep. The line numbers are displayed at (roughly) one second intervals and, in the "value" field of the trigger dialogue box, you set the trigger to be fired after 100 milliseconds of channel inactivity. Re-open the trigger dialogue box and after the "value" field to be 2000. Now, the trigger is never fired because the gap between line numbers is less than one second. Change the trigger back to a 100 millisecond time-out and set the "after" field to be one.
Now, when the trigger is fired, the system beeps and a new-line action is performed in the comms channel window. Change the "after" field to two and you should get an empty line between each line number.
Type "0x0A" into the value field, of the trigger, uncheck the "beep" box, change the trigger type from "time" to "char", reset the "after" field to zero and set the value in the "before" field to one. The display should be much as before but the beeping should have stopped.
You can set left and right margins in the comms windows. The settings for these are kept on a per-channel basis. Invoke Config / Options, select your comms channel and change the Left margin to 17 - the text should move across and start at column 18. (The left margin setting is zero-based.) Now alter the trigger and check the "date&time" box. Note that the date and time text obeys the left margin setting. Alter the channels options and set the right margin to be 21;; this will set the width of the output in the comms window to be 21 characters wide. Now, the display looks pretty messy. Wouldn't it be nice if the date and time text could be "margin released", as it were? Set the "before" field of the trigger to be minus one instead of one. A negative "line-feed" count causes a margin-release to be done before the line-lines are thrown.
You may see a little "jitter" on the screen as the text is scrolled. With larger "messages" on the comms line, this effect is more noticeable. Frequently, it would be advantageous to only update the window when a trigger has been fired. In P2, we take a slightly different approach - one can freeze the window on a trigger. If the window is already frozen when the trigger occurs, then the window is unfrozen, the window is updated and then refrozen. Thus, you see snap-shots of the window at each trigger point. Try this: alter the trigger by ticking the "freeze" box. Now, if you did see any jitter, it should have gone away because the window is only being updated when the trigger is triggered. (Note that the "freeze" indicator on the status line is in red.) There is one thing to watch out for here. Un-check the "freeze" box on the trigger and the window will stay frozen until you manually thaw it (or another trigger freezes or thaw the window). Thaw the window by using Facilities / Freeze Window and the window starts to update again. <%HEADINGSUB%> Scope Window Earlier, it was mentioned that the scope window is very important to P2. Unless you only want to use P2 as a (very) dumb terminal, you will probably spend a lot of time looking at the scope window rather than the comms channel window. In fact, the scope window is merely a special case of the channel windows - many of the options and actions that you have seen can be applied equally well to the scope window. (Note that in order to keep the complexity of P2 to a minimum, separate dialogues have not been provided for the scope window. Thus, some options, even though you select them, will have no effect on the scope window.)
Invoke Channel / Scope and a full-screen scope window should appear. Since all channels, by default, have scoping enabled, you should see the output from the comms channel that we have been playing with. Note that it may have control-line information in it as well as the character traffic displayed. In order to remove this "clutter", select Config / Physical and, after remembering to select the scope channel, un-tick the "lines" and "errors" boxes. (Note that this dialogue has entries for port, IRQ, baud rate, clock crystal speed, FIFO usage, data bits, stop bits and parity none of which apply to the scope channel...)
The scope window behaves in a very similar manner to the comms channel windows, except that, for example, key-board input to the scope channel is discarded. Normally, with more than one channel active, you'd see inter-mixed input from several channels at one (however many had scoping enabled, of course). Herein lies the usefulness of one of the trigger actions: "chantext". When the triggering system detects a change in the input stream, it will fire any triggers that have the "chan" trigger type. Usually, it's a good idea to use a left margin of seven (the length of the string "[COMn:]"), use minus-one as the "before" value field use the trigger action "chantext". This will make channel that incoming data is one obvious. Of course, on the screen, the different channels are colour-coded, by P2 has the capability to capture in-coming raw data to a file (on the comms channels) or to capture the displayed text to a file (on the scope channel). To reduce screen clutter, now close the scope channel window. <%HEADINGSUB%> Info Window The same type of text window is used in P2 to display general information;; this is the "info" window. Having returned the focus to the comms channel window, select Reports / All. Another window should open and, in the top, left-hand corner, should be the page description "load(%)". This page lists the percentage load on each comms channel. Since, at present, there is only one channel in use and that is under script control, the percentages should be pretty low.
Just as with the channel and scope windows, you can use the standard buttons (page-up, page-down, etc) to scroll back through the text buffer in a window. In this case, the default window size has been chosen so that each "page" is the same size. Try selecting the previous page to the "load" page. You should now be presented with the CPS (character-per-second) page. Before that, is the "chars" (total characters throughput) page, and so on.
Going back even further, you should come across the trigger pages, that detail each channel's trigger settings, and near the start of the text buffer, you should find each channel's physical attributes and option settings listed.
Close the info window using Reports / All again. <%HEADINGSUB%> Configuration P2 keeps its configuration information as plain ASCII text and any of the stuff that appears in these files can be used on the P2 command line. For example, P2 normally starts in 25-line mode unless otherwise ordered. The field in the configuration file that controls this is in section "[ALL]" and its name is "ROWS". Each line in the configuration file is either a section header (and is surrounded by square brackets) or is of the form "<;fieldname>; = <;value>;". Hence, for a 50-line display you'd expect a line like "ROWS = 50" to appear in the configuration file. As a result, a command-line like "P2 [ALL] ROWS=50" would start P2 up in 50-line mode.
By default, P2 will look for an .INI file in the current directory. Failing that, it will look in the directory where the .EXE file is located. You can over-ride this behaviour by using a "re-direction" item on the command-line. For example, something like this: "P2 @C:\Z\XXX" will make P2 attempt to use the file C:\Z\XXX.INI as its configuration file. If the file is not found, it will still use it as the configuration file named should the configuration information be saved while P2 is running. In other words, if the XXX.INI file, in the previous example, didn't exist, any use of Configs / Write would create it. <%HEADINGSUB%> Miscellaneous Options We have tried to make P2 as easy to drive as possible. In particular, you may want to boot it on a floppy with only two serial port and thus not have the use of a mouse. You will find that nearly everything that you can do from the menu system has a corresponding short-cut key. Also, operations that are performed more frequently, will have more convenient keys. (For example, one key-press gets you to the trigger dialogues because you usually have to fiddle with them quite a bit before you have them set the way that you want.)
In addition to capturing traffic or window text in a continuous manner, you can capture the displayed contents of any text window using the File / Capture Text menu option.
There are two command-line history buffers for use when using P2 as a dumb terminal. The first, File / Resend Last captures all text, above a certain length, that appears between any carriage-returns typed. You can then re-send the same text by just picking from a list box attached to the File / Resend menu. A second version of this facility, File / Resend Command, will resend from a history list box that is maintained in the P2 configuration file and so, if you save the configuration of P2 on exit, it will be there, ready for use, the next time P2 is used.
One menu that has not been covered is the Configs / All. The items on this menu are global and apply to P2 as a whole. Briefly, the items are as follows:
Auto-tile will, when any window is opened or closed, tile all tileable (set by a separate option) windows. Auto-save will automagically save the configuration when P2 is terminated. Global piping, triggering and beeping will turn their respective options on or off on a global basis. (Thus, for example, triggers can be controlled at a trigger, channel or global level.)
Shadows and select-to-top control the behaviour of the under-lying TurboVision window system. On some GUI systems, the window which has the focus is always the top-most window;; that is, it's brought to the front in the Z-order. With TurboVision (the system used to generate P2), however, this behaviour is configurable and we have chosen to allow the user the flexibility to choose whether they want this or not. In fact, there appears to be a rather convenient bug in TurboVision (if it is a bug) which means that the system behaves differently depending upon the direction in which one steps through the windows. If one uses the Windows / Next option, the windows will be selected and will not be brought to the top of the pile unless one has selected this (default) behaviour. However, if Windows / Previous is used instead, the "to top" behaviour is different - play with this feature to get the idea of how it works.
The "display heap" option will allow you to keep tabs on your memory usage. At present, and until we manage to get P2 running under a flat-memory scheme, we are pretty short on memory. In particular, the script window is a memory-hog and, since we're pretty sure that not all of the windows behave themselves when starved of memory. I (MSD) have not found memory shortage to be a serious problems except when testing P2 and opening a lot of windows.
The debugging switch enables any debugging code that happens to be compiled into P2. At present, it will make extra output appear at the bottom of the info window that gives details of the screen update rate.
The info, status and heart-beat update rates fields specify, in milliseconds, the rate at which these items are updated.
The final item, frame update rate, is a little special. Earlier versions of P2 updated the screen basically whenever anything changed a window. I wondered whether this was causing unnecessary updates, especially when there was a lot of comms traffic. Setting the frame update rate to a non-zero (milli-seconds) update rate will cause the screen to updated at that rate. This may, or may not, help performance on slower machines. (There didn't seem any point in taking the code out again once it had been written.) #close * ;=========================================================================== #if MAKECLEAN #say #say Making clean - all generated HTML files will be deleted. #delete INDEXhtml #delete P2TUTORhtml #delete P2VERSIONShtml #delete P2FAQhtml #say Making clean - complete. #endif