Chapter 6
© 2000, The TRAC Foundation
Extended Input and Communication Primitives
This chapter describes the extended input and communication primitives.
6.1 Introduction to the Extended Input and Communication Primitives
The extended input and communication primitives handle input and output (I/O) through two physical channels. With these primitives, you can pass around control of the TRAC processor between various channels or ports, while one channel observes the action at another channel (the master, or default, channel). You can also start a task on an I/O channel and communicate with that task from another task running on a different channel.
The channel is designated by a numeric index, <j>, which follows the letters of the mnemonic in a primitive statement, but precedes an i or d suffix. For example, the following primitive statement takes in and interprets 14 characters from channel 2.
At any time, there is a default control channel. Initially, the default channel is channel 1, which is the channel to the local machine. When the channel index is omitted in a primitive statement, the default channel (whatever its real channel number is) is understood to be the location of the TRAC processor action.
Directing an I/O action to any other channel is usually a nonlocking or temporary operation; that is, it does not change the default channel. You can lock the channel change with an it primitive statement, which sets the default channel to the designated index.
The extended input and communication primitives have the following subgroups:
Channel Utilities
These primitives change various states and parameters of a channel.
The channel utility primitives are:
ia2 Get or set the port number.
ic Get or set the terminate input or dump input meta characters.
ib2 Get or set the baud rate.
ie Echo the input.
if Do not echo the input.
ip Do not edit the input (use pure input).
iq Automatically edit the input characters.
iw Wait.
iy Determine if input is available on a channel.
iz Flush the input buffer (zero the input buffer).
Display Channel State
The I/O status primitive is displays the state of both channels.
The display channel state primitive is:
is Display I/O status.
Monitor Channel
The monitor primitive im sends to a remote screen over the specified monitor channel a mirror copy of all the keyboard and screen transactions of the local system. Most of the internal built-in diagnostic messages from the processor also appear on the monitor channel.
The monitor channel may be another terminal, a printer, or a connection via modem and data link to a remote terminal. Thus, the monitor facility can provide real-time observation and diagnosis of the actions of a remote system. In particular, the full display of the TRAC trace mode is sent over the monitor channel, and can be printed out.
The in primitive turns the monitor channel off.
The monitor primitives are:
im Monitor on.
in Monitor off.
Move Data (I/O)
The input primitive i and the output primitive o are described in Chapter 2, "Primary
Primitives." The data movement primitives are:
i Input on specified channel. See Chapter 2, "Primary Primitives."
o Output on specified channel. See Chapter 2, "Primary Primitives."
Transfer Control
The control transfer primitive it transfers control of the TRAC processor from the default channel (channel 1) to channel 2. The iu primitive returns control to the default channel.
You can, for example, start the processor on channel 1 and then transfer control to channel 2, which could be connected via a modem to another terminal thousands of miles away. Any activity on channel 2 can be observed on channel 1 by using the monitor primitive im.
The control transfer primitives are:
it Transfer control.
iu Restore control.
6.2 Extended Input and Communication Primitive Reference
This section provides the syntax, input arguments, value string, and description of each extended input and communication primitive in alphabetical order.
ia2 - Get or Set Com Port
Syntax
:(ia2, <com-port>)
Input Arguments
<com_port> For setting the serial port, the com port to set as the serial port.
Description
The ia2 primitive sets or reports the local machine's communications port for the serial port channel.
When you do not specify a value for the <com_port> argument, an ia2 primitive statement is value-producing and produces the current com port being used as the serial port.
When you specify a value for the <com_port> argument, an ia2 primitive statement is null-valued and sets the serial port. As the <com_port> argument, you can specify one of the following corn ports if it is a valid serial port on the computer:
AUX COM1 COM2 COM3 COM4
Example
The following command sets the com port for the serial port channel to COM2:
:(ia2, COM2)'
The following command produces the com port in use:
:(ia2)'COM2
ib2 - Get or Set Channel Baud Rate
Syntax
:(ib2,<N>)
Input Arguments
<N> Positive decimal integer that specifies the baud rate to set for the serial port.
Description
The ib2 primitive sets or reports the baud rate of the serial port channel.
When you do not specify a value for the <N> argument, an ib2 primitive statement is value-producing and produces the current baud rate for the serial port.
When you specify a value for the <N> argument, an ib2 primitive statement is null-valued and sets the baud rate for the serial port. As the <N> argument, you can specify one of the following baud rates:
110 2400 14400 57600
300 4800 19200 115200
600 9600 38400 230400
1200
The TIC processor ignores other values for the <N> argument.
Example
The following command sets the baud rate for the serial port channel to 4800:
:(ib2, 4800)'
The following command produces the baud rate set for the serial port:
:(ib2)'4800
is - Get or Set Input Meta Characters
Syntax
:(ic<j>,<termchar>,<dumpchar>)
Input Arguments
<j> The input channel on which to change the meta or dump character.
<termchar> The new terminate input meta character.
<dumpchar> The new dump input buffer character.
Description
The is primitive reports or resets the current meta character that terminates keyboard input, and the current dump input buffer meta character.
To get the current meta characters, enter an ic primitive statement with no data arguments. When getting the meta characters, an ic primitive statement is value-producing. It produces the current terminate input meta character and dump input meta character as decimal values, and reports whether or not dumping is activated.
To set a new terminate input or dump input meta character, or both, enter an ic primitive statement and specify one or both data arguments. When setting the meta characters, an ic primitive statement is null-valued. The new terminate input or dump input meta character remains in effect until you change it to some other character.
If the argument for <termchar> is a null string, then the terminate input meta character does not change. If the argument for <dumpchar> is a null string, then dumping of the input buffer is deactivated.
The terminate input meta character is initially the apostrophe character ', (the single quote character). In ordinary keyboard input, the TRAC processor does not interpret the keyboard input until you type the termination meta character. For example, in the following call to the i primitive the processor accepts input from the keyboard until you type the termination meta character:
:(i)
The dump input buffer character is initially the at sign @. When you type the dump input meta character key at the keyboard, the processor discards the current input string, which may be many lines long. The dump input meta character does not terminate input, so you can continue inputting characters until you input the termination meta character.
In scripts, it is often useful to change a meta character with a statement like:
:(ic,:(tca,35))
This has the effect of changing the termination meta character to the pound sign #. By use of the tca or bxo primitives, you can avoid including the literal character in the script.
Example
The following command changes the terminate input meta character from the default apostrophe to the pound sign:
:(ic,#)'
The following command changes the dump input meta character to an exclamation point:
:(ic,,!)'
The following command reports the current terminate input and dump input meta characters, and the state of dumping:
:(ic,35,33,dump)'
The following commands deactivate dumping and reports the meta characters and dumping state:
:(ic,,)'
:(ic,35,33,nodump)'
See Also
bxo, tca
ie - Input Echo
Syntax
(ie<j>)
Input Arguments
<j> The channel on which to echo the input.
Description
The null-valued ie primitive restores the echoing of characters on the input channel after an if primitive statement has turned off echoing. If no input channel is specified, the TRAC processor displays on the local screen the characters you type at the keyboard. If <j> is 2, the TRAC processor displays on the local screen the characters it receives over the serial port channel. The initial state for both channels has echoing turned on.
Example
The following command restores the echoing of input characters to the local screen:
:(ie)'
The following command restores the echoing of input characters for the serial port:
:(ie2)'
See Also
if
if - Input Echo Off
syntax
:(if<j>)
Input Arguments
<j> The channel on which to stop echoing the input.
Description
The null-valued if primitive suppresses input line echo on channel <j>. If no input channel is primitive specified, this primitive suppresses the local screen display of what you type at the keyboard. If <j> is 2, if supresses the local screen display of the characters it receives over the serial port channel. The ie primitive restores the echo. The initial state for both channels has echoing turned on.
Example
The following command turns off the echoing of input characters to the local screen:
:(if)'
The following command turns off the echoing of input characters for the serial port:
:(if2)'
See Also
ie
im - Monitor On
Syntax
:(im<j>)
Input Arguments
<j> Channel to use as the monitor channel.
Description
The null-valued im primitive sets up a processor state in which all input and all output from the default channel (normally the user terminal channel) is additionally sent out via channel <j>. Only one channel may operate as the monitor. The processor remains in the monitor state until an in primitive statement is executed.
An internal processor interlock prevents setting the monitor channel to the current default channel.
Example
:(im2)'
See Also
in
in - Monitor off
Syntax
:(in)
Input Arguments
None.
Description
The null-valued in primitive turns off the monitor channel.
Example
:(in)'
See Also
im
ip - Pure input
Syntax
:(ip<j>)'
Input Arguments
<j> The channel on which to receive pure unedited input.
Description
The null-valued ip primitive inactivates the TRAC processor's automatic editing of the strings it receives over input channel <j> (like the UNIX raw mode). If no input channel is specified, then input is from the keyboard. A <j> argument of 2 specifies input from the serial port. The iq primitive restores automatic editing, which is the processor's default state.
The ip primitive does the following:
Note: The ip primitive does not affect the echo state of the channel, so the Backspace key still deletes a character from the screen display, but does not remove the character from TRAC workspace.
Since Windows may strip some characters in its manipulation of keyboard input, the ip primitive is most useful for receiving pure input from the serial port or network interface.
Example
The following command specifies pure input for the serial port.
:(ip2)'
See Also
ic, iq
iq - Qualified Input
Syntax
:(iq<j>)
Input Arguments
<j> The channel on which to receive pure unedited input.
Description
The null-valued iq primitive restores the TRAC processor's automatic editing of the strings it receives over input channel <j> (which is like the UNIX cooked mode) after you have called the ip primitive. The ip primitive disables the automatic editing. If no <j> argument is specified, input is from the keyboard. A <j> argument of 2 specifies input from the serial port. The iq primitive does not affect the echo state of the channel.
By default, the TRAC processor automatically edits the input stream it receives so that:
Example
The following example restores the automatic editing of the input for channel 2.
:(iq2)'
See Also
ic, ip
is - I/O Status
Syntax
:(is)
Input Arguments
None.
Description
The null-valued is primitive presents a screen display showing the state of, and utilization of, the I/O channels.
The display is:
contr = 1 montr = 0
channel=1 echo=1 meta= ' pure=0 printer=0
channel=2 echo=1 meta= ' pure=0 printer=0
The entry contr = 1 indicates that the default control channel is channel 1, and montr = 0 indicates that the monitor is off. If the monitor were on, it would display a digit 1 to 2 representing a channel number.
The next lines specify, for each channel number, that the echo is on, that the meta character is ', that pure is off, which means that the editing of input characters occurs, and that a channel has not been specifically assigned to a printer.
The following channel assignments are built in:
channel l User terminal screen and keyboard
channel 2 Serial port (for Dialer) or network interface (for WTNVT)
See Also
ip, iq
it - Transfer Control
Syntax
:(it<j>)
Input Arguments
<j> Channel to become the default channel.
Description
The null-valued it primitive transfers control of the TRAC processor from the main computer terminal to any other terminal connected to an I/O port.
The it primitive transfers control to channel <j>, thereby changing the default channel to channel <j>. The default channel stays at <j> until control is released by an iu primitive statement or changed to some other channel by another it statement.
Initially, control (the default channel) is channel 1, which is the local terminal. Upon transfer of control to another channel, the local terminal no longer has control. Only one channel at a time may have control.
Control may be regained by the initial terminal only through a suitable command within an executing script, or by a command from the channel in control. An :(it1) command has the same effect as an :(iu) command.
See Also
iu
iu - Restore Control
Syntax
:(iu)
Input Arguments
None.
Description
The null-valued iu primitive restores control of the TRAC processor to the main computer terminal I/O port, which is channel 1 by default, after control has been transferred to some other channel by an it primitive statement.
See Also
it
iv - Display Version
Syntax
:(iv)
Input Arguments
None.
Description
The value-producing iv primitive produces version information for the TRAC I/O module. An iv statement produces the following:
iw - Wait
Syntax
:(iw,<N>)
Input Arguments
<N> The number of milliseconds to wait.
Description
The null-valued iw primitive pauses the processing of a primitive statement for <N> milliseconds. The iw primitive does not have a timeout period.
Example
The following example makes the processor wait for five thousand milliseconds before continuing the execution of a primitive statement.
:(s,test,(
:(o,(Display this...))
:(iw, 5000)
:(o, (then display this.))
))'Display this ...then display this.
iy - Determine if Input Is Available
Syntax
:(iy<j>,<yes>,<no>)
Input Arguments
<j> Channel to test for input.
<yes> Value string to produce if channel <j> has input.
<no> Value string to produce if channel <j> does not have input.
Description
The value-producing iy primitive determines if input is available on channel <j>. If input is available, the primitive statement produces the <yes> argument as the value string. If input is not available, the primitive statement produces the <no> argument.
Example
:(iy,yes,no)'no
iz - Zero Input Buffer
Syntax
:(iz<j>)
Input Arguments
<j> Suffix specifying the channel on which to discard, or flush, the input.
Description
The null-valued iz primitive flushes out and discards characters in the channel <j> input buffer. This primitive is often useful for discarding noise or other characters that may be waiting in the operating system character buffer prior to reading in data.
Example
The following command discards any characters in the serial port channel buffer.
:(iz2)'