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.
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.
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...
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.
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.
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.)
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.
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.
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.
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.
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.)