Library Routines
Applies to: v10
const CHAR * vs CHAR * hazard. The examples in this chapter pass literals to
btuxmt()and similar routines. In v10 that crashes at run time. See chapter 29, section 29.4 ("HAZARD:const char *string literals versuschar *parameters").
...
The prototypes for these routines, plus many of the constants and symbols you can use in programming with the GSBL, are in the header file BRKTHU.H.
btubrt
####### SUBROUTINE NAME
btubrt — set channel’s baud rate
...
-3 baud rate is not valid for the hardware being used
0 baud rate has been set correctly
btubse
####### SUBROUTINE NAME
btubse — set backspace-echo character
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btubsz
####### SUBROUTINE NAME
btubsz — respecify input and output buffer sizes
...
These are reasonable values for a multiuser online service such as Worldgroupthe Major BBS. Particularly in terminal mode, the heaviest traffic on an online service is usually in the direction toward the users. Output traffic may include an entire screenful of text: 80 X 24 = 1920 characters plus overhead. Input traffic, coming from each user’s keyboard, is relatively light, requiring an input buffer big enough to hold an 80-character line of text. C/S mode reduces this disparity to a great extent, but output still generally outnumbers input.
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-5 buffer sizes are invalid: either one of them is not an
integral power of two (128, 256, etc.), or their sum
exceeds the total data buffering capacity of the channel,
as set by the original call to btusiz() (see page 135)
0 all is well
btuche
####### SUBROUTINE NAME
btuche — enable calling of btuchi() when echo buffer becomes empty
...
This function exists mainly to support certain advanced real-time protocols available for Worldgroupthe Major BBS. Be sure that you fully understand the btuchi() function before attempting to use btuche().
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuchi
####### SUBROUTINE NAME
btuchi — set input character interceptor
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuclc
####### SUBROUTINE NAME
btuclc — clear command output buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btucli
####### SUBROUTINE NAME
btucli — clear data input buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuclo
####### SUBROUTINE NAME
btuclo — clear data output buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btucls
####### SUBROUTINE NAME
btucls — clear status input buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btucmd
####### SUBROUTINE NAME
btucmd — command channel
...
Command codes T and R are ignored on X.25 channels. All other codes will produce a status 23 (page 139), and the remainder of the command string will not be processed.
^A (ctrl+A)
####### ANSWER-CARRIER WITH DETECTIONS (TT,VOICE)
...
This command puts “answer carrier” on the line, and will generate a status of 2 if “originate carrier” is heard within 17 seconds. It acts just like the regular A command, but adds extra monitoring capability — the answer sequence may be aborted by the caller in two ways. If the caller presses the DTMF “1” key, a status code of 49 (ASCII “1”) is generated. If the caller speaks, a status code of 118 (ASCII “v”) is generated. In either case the answer carrier tone is terminated.
^E (ctrl+E)
####### SET CHARACTER LENGTH TO 8 BITS
This mode can be used for binary data protocols such as XMODEM, etc. This command works on all hardware categories.
^F (ctrl+F)
####### SET SPEED TO 2400 BPS
...
Sets the UART to 2400 baud. For Hayes category hardware, this command (or a call to btubrt()) must be issued after an answer command (command A, page 60) results in a CONNECT 2400 message.
^H (ctrl+H)
####### SET SPEED TO 1200 BPS
...
For outgoing calls, sets the preferred speed of the modem to 1200 bits per second. For incoming calls, results in a status I (for Inappropriate) when a 300 baud connection is already established.
^M (ctrl+M)
####### CONTINUOUS MONITOR, RETURN LINE FREQ
...
This function can only be terminated by a call to either bturst() (which resets the channel) or btuclc() (which clears the command buffer and aborts any command currently underway).
^N (ctrl+N)
####### ONE STOP BIT
UART
Sets the UART in this channel to use 1 stop bit. This mode is the default condition after bturst().
^S (ctrl+S)
####### SET CHARACTER LENGTH TO 7 BITS
This mode is the default upon channel reset. This command works on all hardware categories.
^T (ctrl+T)
####### SET SPEED TO 300 BPS
...
For outgoing calls, sets the “preferred speed” of the modem to 300 bits per second. For incoming calls, will result in a status code of I (Inappropriate) when a 1200 baud connection is already established. This is the default upon channel initialization or reset.
^W (ctrl+W)
####### TWO STOP BITS
UART
Sets the UART in this channel to use 2 stop bits.
^X (ctrl+X)
####### ANALOG LOOPBACK IN ORIGINATE MODE
...
This command initiates a local loopback in the originate band. The filters for transmit and receive are set for the originate frequencies and are looped to each other. Transmitted data is routed through the full analog-digital path before being received back at the receiver port. May be used at any “preferred speed” to test all possible encode/decode components in a modem module. Once put in this mode, the channel must be reset (see bturst(), page 124) to get out of it.
^Y (ctrl+Y)
####### ANALOG LOOPBACK IN ANSWER MODE
...
This command initiates a local loopback in the answer band. The filters for transmit and receive are set for the answer frequencies and are looped to each other. Transmitted data is routed through the full analog-digital path before being received back at the receiver port. May be used at any “preferred speed” to test all possible encode/decode components in a modem module. Once put in this mode, the channel must be reset (see bturst(), page 124) to get out of it.
0 to 9
####### DIAL 0 to 9 (ROTARY PULSE OR TOUCH TONE)
...
The corresponding digit will be rotary dialed or touch-tone dialed depending on the current mode (previous R or T command). On Hayes category hardware, these codes must only be used after the W command (page 67).
*, #, a, b, c, d
####### DIAL SPECIAL TOUCH-TONES
...
Any of these codes will generate a status of I (Inappropriate) if the current mode is rotary dial.
>
####### SET PARITY TO “EVEN”
Sets up to generate an even parity bit on every byte transmitted, and demand even parity on every byte received. If an odd parity byte is received, the results are controlled by btuerp() (the error pass-through routine, page 94), and by your input translation table, if in ASCII mode (btuxlt() controls the translation table, see page 163). Even parity is the default condition upon channel initialization or reset. This command works on all hardware categories.
<
####### SET PARITY TO “ODD”
Sets up to generate an odd parity bit on every byte transmitted, and demand odd parity on every byte received. If an even parity byte is received, the results are controlled by btuerp() (the error pass-through routine, page 82), and by your input translation table, if in ASCII mode (btuxlt() controls the translation table, see page 163). This command works on all hardware categories.
=
####### SET PARITY TO “NONE” (NO PARITY BIT)
Disables generation and checking of parity bits. This command works on all hardware categories.
A
####### ANSWER-CARRIER WITH NO FRILLS
...
See page 30 for details on the limitations of this method.
D
####### DTMF RECEIVE MODE (ACCEPT TOUCH TONE INPUT)
...
When placed in this mode, a modem will recognize incoming DTMF tone pairs as data input. The ASCII representations of 0-9, a-d, *, and # will be buffered as input data characters when they are detected. Note that DTMF information can be transmitted by issuing the normal digit dial commands. This mode is cancelled by a H, M, O, or A command.
G
####### GTC GREETING (LAN)
...
For example, GTC can be used in a terminal emulation program talking to a Worldgroup Major BBS server. The G command is executed in the terminal program once connection is established and says in effect: “Offer to preprocess the input of the server”. This includes buffering an input line with or without echo, input word wrap, etc. Executing the G command paves the way for status codes 40 - 44 to appear for the terminal program to handle (informing it of changing server input modes). For the Worldgroup Major BBS server program all aspects of this exchange are handled by the GSBL and need no special handling by the server’s C program. The key point to remember here is that you only have to consider handling GTC if you execute the G command.
See page 199 for more on the GTC protocol.
H
####### HOLD (DISCONNECT MODEM, BUT REMAIN OFF-HOOK)
...
Performs a “logical disconnect” of the modem from the phone line, but does not terminate the physical connection (i.e. the phone remains off-hook). This command can be used to quiet the line for voice or other use during a connection.
I
####### IDENTIFY MODEM VERSION
...
Causes a single ASCII letter representing the version of the modem module to be generated as an input data character. Version codes are assigned consecutively, starting with A (65 decimal). Version number changes correspond to “significant unity upgrades”, whereas revision numbers (see i immediately following) represent incremental enhancements.
i
####### IDENTIFY REVISION NUMBER
...
Causes a single ASCII digit representing the revision code of the modem module to be generated as an input data character. This will usually be of no concern to you, since only “version numbers” (see I immediately above) correspond to “significant unity upgrades”.
L
####### LINE ANALYZE
XECOM
This command acts the same as the M command but generates three special data input bytes if successful. The first byte represents the carrier frequency error, the second the S/N ratio, and the third the received carrier level. The calculations necessary for meaningful interpretation of this information are covered in Xecom data sheets.
L
####### LISTEN FOR SPX CONNECTION (LAN)
...
The listen command should only be issued on SPX channels that are in the idle state (see page 191). The L command will have no effect on an IPX channel.
l (lowercase+L)
####### RETURN 1200-BPS ERROR STATISTICS
...
This command may be used during a 1200 bps connection to check the phase demodulation statistics. An I (Inappropriate) status is generated if no 1200 bps connection exists. Otherwise two data bytes are queued: the first gives the average phase error of the signal, and the second gives the number of phase hits since the last request. The calculations necessary for extracting meaningful information from these values are covered in Xecom data sheets.
M
####### MONITOR LINE AND ORIGINATE WITH DETECTIONS
...
See page 67 for using the M command on LAN channels.
O
####### ORIGINATE-CARRIER WITH NO FRILLS
...
This command will generate a status of 2 if answer carrier is heard within 17 seconds. Otherwise a status code is generated indicating: T (Timeout), or I (Inappropriate). This command is primarily useful when the physical connection is already established, and your program decides to begin using it for data communications. When making a new connection, use the M command (page 64).
P
####### PAUSE 5 SECONDS
The “long pause”. Works on all hardware categories.
p
####### PAUSE 2 SECONDS
The “short pause”. Works on all hardware categories.
R
####### ROTARY (PULSE) DIAL SUBSEQUENT DIGITS
...
Use this command to dial on a phone line which does not support touch-tone dialing.
T
####### TOUCH-TONE DIAL SUBSEQUENT DIGITS
...
This is the default, upon initialization or reset.
T
####### TERMINATE SPX CALL (LAN)
...
The terminate command should only be issued on SPX channels that are in the connected state (see page 191). At any other time, the terminate command will have no effect. The T command will have no effect on an IPX channel.
t
####### WAIT 1/10 OF A SECOND
...
Generates a status 12 after 0.1 seconds. Works only on 8250-type UARTs and modems or Model 2408 cards.
V
####### DISABLE AUTOMATIC PAD ECHO PROGRAMMING (X.25)
...
Normally, turning echo on and off with btuech(), or switching between binary and ASCII input modes with btutrg() would automatically cause programming of parameter 2 of the remote PAD. This command disables that feature until the next bturst().
W
####### WAIT FOR DIAL TONE (TO PLACE AN OUTGOING CALL)
...
This command will generate a status of 2 if a dial tone is sensed within 5 seconds. Otherwise a status code is generated indicating: B (Busy), M (Modem Carrier Sensed), I (Inappropriate), R (Ringing), T (Timeout), or V (Voice).
LAN Dial-out Command
...
W, digit, and M
...
LAN
This command is used to make an outgoing call on the network and establish connection with another address on the network. For SPX channels, a dial-out command means to establish a connection with a remote network/node/socket. You can have multiple SPX connections between the same pair of network/node/sockets. For IPX, a dial-out command specifies who we will talk to and who we will listen to. After an IPX dial-out command on a particular channel, all transmissions on the channel will go to the specified network address, and all packets received from that address (and directed to the same local socket number) will be routed to the input buffer of the channel.
...
If you use a dial-out command to specify a network that is not connected, then the GSBL may appear to hang for several seconds, and then issue a status 39 (page 141).
...
Unique Network Addresses for IPX Dial-outs
...
Among channels with the same local socket number, the network/node/socket of an IPX dial-out command should be unique. That is, once you specify a certain network/node/socket for the dial-out command on one channel, you should not specify the same network/node/socket for the dial-out command on any other channel that shares the same local socket.
...
The result of IPX dial-outs from two channels with the same local socket calling the same network address is that received packets may wind up in the input buffer of either channel, arbitrarily. Transmitted packets have no such ambiguity (although the other party may not be able to distinguish the originating channel).
...
Special Syntax of the Dial-out Command
...
An outgoing call may be specified by multiple btucmd() calls, as long as there are no other intervening calls to breakthrough routines. For example:
...
btucmd(chan,"W000004010000C0A810184007M");X.25 Dial-out Command:
...
W, digits, slash, hex digits, and M
...
X.25
To place an outgoing call on an X.25 channel, issue any of the following command string formats using btucmd():
...
To terminate a call, bturst() disconnects the virtual circuit. When a call gets terminated, either by the network or by the remote user, status code 21 is generated on the channel.
[
####### ENABLE ANSI GRAPHICS (default)
...
ANSI graphics are automatically enabled by bturst(). See page 166 for more information on ANSI graphics directives.
]
####### DISABLE ANSI GRAPHICS
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btucpc
####### SUBROUTINE NAME
btucpc — sets the clear pause-counter character
(puts off screen pauses when in output stream)
...
When the cpchar character is discovered in the output stream (btuxmt() page 166 or btuxmn()page 165), the internal line counter is reset to 0. This line counter is used to determine when to display the pause message set by btuhpk() (page 91). The character itself is never actually output. Use cpchar=0 to disable this feature.
In Worldgroupthe Major BBS, this function is used to prevent screen pauses by inserting the ctrl+S character at strategic points in certain text blocks.
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btudef
####### SUBROUTINE NAME
btudef — define channels
...
0 the specified channels were defined successfully
btueba
####### SUBROUTINE NAME
btueba — echo buffer space available, in bytes
...
0 echo buffer is full
1-254 echo buffer is between full and empty
255 echo buffer is empty
btuech
####### SUBROUTINE NAME
btuech — set echo on/off
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuend
####### SUBROUTINE NAME
btuend — shut down the Software Breakthrough
...
btuend() does not hang up your phone lines. You should call bturst() for every channel you have defined before calling btuend(). If you do not, your phone lines may remain off-hook with the carrier signal on, appearing to any users online at the time that your system has “locked up”. Better to let them think that you are rude than that your system is malfunctioning.
####### RETURNS
Nothing.
btuerp
####### SUBROUTINE NAME
btuerp — pass/block input bytes with errors
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuffo
####### SUBROUTINE NAME
btuffo — enable receiver FIFO on 16550 UART
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-18 channel has an 8250 or 16450 UART on it
0 either the channel does not have an 8250-type UART on it, or it
has a 16550 type UART on it, and the FIFO mode has been set
btuhcr
####### SUBROUTINE NAME
btuhcr — set the hard-cr character (for output word wrap)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuhdr
####### SUBROUTINE NAME
btuhdr — capture information on X.25 or LAN channel
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuhit
####### SUBROUTINE NAME
btuhit — hook into a COM port interrupt
and use it to invoke channel servicing
...
-20 irqno is neither 2, 3, 4, 5, 6, nor 7,
or btuitm() was not used to initialize (see page 102)
0 all is well
btuhpk
####### SUBROUTINE NAME
btuhpk Handle keystrokes during screen-pause mode
...
3. To handle an “abort” key, you must inform your mainline program. For example, inject a status 7 (this is what happens in Worldgroupthe Major BBS) and have the mainline program handle the status by clearing output using btuclo(), and changing states (to stop stuffing the output buffer).
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuhwh
####### SUBROUTINE NAME
btuhwh — enable hardware handshaking using RTS/CTS
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuibw
####### SUBROUTINE NAME
btuibw — Input Bytes Waiting: report the number of bytes received
and waiting in the input buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK,
but that channel’s input buffer is empty
N>0 this is the number of bytes waiting in the channel’s input buffer
btuica
####### SUBROUTINE NAME
btuica — input from a channel: reading in whatever bytes
are available, up to a limit
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK,
but that channel’s input buffer is empty
N>0 this is the number of bytes actually moved
from the channel’s input buffer to inbuff
btuict
####### SUBROUTINE NAME
btuict — input from a channel: by the byte count prearranged
with btutrg()
...
the input block (the length of which you have already specified by calling btutrg()). This string is not 0-terminated (as is the output of btuinp()).
btuinj
####### SUBROUTINE NAME
btuinj — “inject” a status code into a channel
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuinp
####### SUBROUTINE NAME
btuinp — input from channel (ASCIIZ string)
...
The input line entered by this user on this channel (not including the line terminator, but terminated instead by a 0-byte), is stored in the character array pointed to by the parameter inbuff.
btuirp
####### SUBROUTINE NAME
btuirp — define alternate GSBL timing source using COM1/2/3/4
...
-17 comno is not 0/1/2/3/4, or COM port specified is not available
0 all is well
btuitm
####### SUBROUTINE NAME
btuitm — initialize the Software Breakthrough for use
in a multitasking environment
...
0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed
btuitz
####### SUBROUTINE NAME
btuitz — initialize the Software Breakthrough
...
0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed
btulfd
####### SUBROUTINE NAME
btulfd — set linefeed character (what follows every carriage return)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btulok
####### SUBROUTINE NAME
btulok — set input lockout on/off
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btulsz
####### SUBROUTINE NAME
btulsz — size of dynamic memory needed
(long version, used when more than 64K needed)
...
N >= 0L This is the size, in bytes, of the memory region
needed by the Software Breakthrough
-1L Error: one of the buffer size parameters is not
an integral power of two
btumds
####### SUBROUTINE NAME
btumds — get next displayed character from the monitored channel
(as specified by btumon(), see page 114)
...
0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer
btumds2
####### SUBROUTINE NAME
btumds2 — get next displayed character from the monitored channel (as specified by btumon2(), see page 115)
...
0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer
btumil
####### SUBROUTINE NAME
btumil — set maximum input line length, input word wrap on/off
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btumks
####### SUBROUTINE NAME
btumks — simulate a keystroke on the monitored channel
(as specified by btumon(), see page 114)
...
This routine has no effect if btumon() (page 114) has not been called, or if it was last called with a parameter of -1.
####### RETURNS
Nothing.
btumks2
####### SUBROUTINE NAME
btumks2 — simulate a keystroke on the monitored channel
(as specified by btumon2(), see page 115)
...
This routine has no effect if btumon2() (page 115) has not been called, or if it was last called with a parameter of -1.
####### RETURNS
Nothing.
btumon
####### SUBROUTINE NAME
btumon — start/stop monitoring a channel
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btumon2
####### SUBROUTINE NAME
btumon2 — start/stop monitoring a channel
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btumxs
####### SUBROUTINE NAME
btumxs — set maximum data speed
...
This parameter also affects the service rate of channels that are monitored using btumds() and btumds2() (pages 108 and 109), even if no hardware is connected to this channel (see use #2 on page 114). For example, using Worldgroupthe Major BBS, when you emulate a non-hardware channel (one that appears as “-“ in the user matrix on the console), the display rate is controlled by the bdrate parameter of btumxs(). For this reason, you may want to set the service rate higher than that required by your hardware, so that your emulated screen is updated faster.
...
0 the maximum data speed has been set
-3 bad baud rate: bdrate was not between 300 and 38400
btuoba
####### SUBROUTINE NAME
btuoba — Output Bytes Available: report the amount of space
(number of bytes) available in the output buffer
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK but that channel’s output buffer is full
N>0 the number of bytes available in the channel’s output buffer
btuoes
####### SUBROUTINE NAME
btuoes — enable/disable Output-Empty status codes
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuolk
####### SUBROUTINE NAME
btuolk — set output pausing on/off
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btupbc
####### SUBROUTINE NAME
btupbc — set screen-pause character (pauses screen when in output stream)
...
When the pausch character is transmitted to the user in ASCII output mode, output pauses and the channel goes into the screen-pause mode (page 91). Clear screen characters (ASCII formfeed and ANSI esc [2J) are automatically preceded by the pause character when btuxmt() stuffs them into the output buffer. Worldgroup The Major BBS uses ctrl+T for the pause character.
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btupmt
####### SUBROUTINE NAME
btupmt — set prompt character
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
bturep
####### SUBROUTINE NAME
bturep — report channel statistics
...
bturep() returns the current long integer value of the statistic.
bturst
####### SUBROUTINE NAME
bturst — reset a channel
...
3 means that a functional LAN interface has been detected on this channel
bturti
####### SUBROUTINE NAME
bturti — define routine to be called in real-time
...
-6 too many rti calls per second (hertz is too large)
0 all is well
btuscn
####### SUBROUTINE NAME
btuscn — scan for channels in need of service (with nonzero status)
...
-1 no channels require service: they all have a status of 0
N>=0 channel number of the next channel with a nonzero status
btuscr
####### SUBROUTINE NAME
btuscr — set the soft-cr character (for output word wrap)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btusdf
####### SUBROUTINE NAME
btusdf — super-define channel groups
...
-14 LAN interface not available (only returned when chtype is 6 or 7)
-15 out of memory
btuset
####### SUBROUTINE NAME
btuset — set and report channel statistics
...
The value of the statistic immediately before it gets set to the new value.
btusiz
####### SUBROUTINE NAME
btusiz — size of dynamic memory needed (only if < 64K)
...
0 to 65534 This is the size, in bytes, of the memory region
needed by the Software Breakthrough
65535 Error: more than 65534 bytes are needed,
or either buffer size is not a power of two
btusts
####### SUBROUTINE NAME
btusts — status of a channel
...
If a control character other than ^H=backspace or ^M=enter comes in, you may want to immediately send the character directly to the other party, bypassing the line input buffer. For example, with Worldgroup the Major BBS this would preserve some of the effects of ^O=abort and ^S=pause.
...
Up to 31 bytes of status can be queued, per channel, before the status queue overflows. See the note on status 43 and 44 (page 142) about how btusts() follows these status return codes with a status that could be anywhere between 0 and 255.
Figure 4-2: Summary of btusts() Status Codes
| Status Code | ASCII | Description |
|---|---|---|
| 0 | Quiet, Nothing Special To Report | |
| 1 | RING-Indicate Or Lost-Carrier (Xecom) | |
| 2 | Command Execution Completed OK (Xecom) | |
| 3 | cr-Terminated Input String Available | |
| 4 | Byte-Count-Triggered Input Data Available | |
| 5 | Output Buffer Empty | |
| 6 | Output Aborted By User | |
| 7 | (Reserved For Screen-Pause/Quit Command) | |
| 11 | Hayes Lost Carrier | |
| 12 | Hayes/UART Command Execution Completed | |
| 13 | Hayes/UART Invalid btucmd() Command Byte | |
| 21 | X.25 Incoming Clear Packet (End Of Session) | |
| 22 | X.25 Command Or Pause Completed | |
| 23 | X.25 Invalid btucmd() Command Byte | |
| 24 | X.25 Incoming X.29 String | |
| 31 | LAN SPX Connection Terminated By Other Side | |
| 32 | LAN Pause Command Completed | |
| 33 | LAN Invalid btucmd() Command Byte | |
| 34 | LAN SPX Incoming Connection Established | |
| 35 | LAN SPX Outgoing Connection Established | |
| 36 | LAN SPX Termination Complete By This Side | |
| 37 | LAN Receiver Error | |
| 38 | LAN Received Unknown Or Unexpected Packet | |
| 39 | LAN Connection Error | |
| 40 | LAN GTC Input Mode: Locked Out | |
| 41 | LAN GTC Input Mode: Binary | |
| 42 | LAN GTC Input Mode: ASCII, No Echo | |
| 43 | LAN GTC Input Mode: ASCII, With Echo | |
| 44 | LAN GTC Input Mode: ASCII, With Echo And Wrap | |
| 49 | 1 | Xecom DTMF 1 Sensed |
| 63 | ? | Xecom Invalid Command Byte |
| 65 | A | Xecom Aborted Command Prematurely |
| 66 | B | Xecom Busy Signal Sensed (Or X.25 Call Failed) |
| 68 | D | Xecom Dial Tone Sensed |
| 70 | F | Xecom Failed For Other Reasons |
| 73 | I | Xecom Inappropriate Command |
| 77 | M | Xecom Modem Carrier (Or X.25 Call Completed) |
| 82 | R | Xecom Ringing Sensed, But No Answer |
| 84 | T | Xecom Timeout (Silence Sensed) |
| 86 | V | Xecom Voice Sensed |
| 118 | v | Xecom Voice Sensed (by ^A Command) |
| 200-249 | Reserved For Your Special Purposes Using btuinj() or chiinj() | |
| 250 | Transmission Error (X.25) | |
| 251 | Data Input Circular-Buffer Overflow | |
| 252 | Echo Output Circular-Buffer Overflow | |
| 253 | Data Output Circular-Buffer Overflow | |
| 254 | Status Input Circular-Buffer Overflow | |
| 255 | Command Output Circular-Buffer Overflow | |
| -10 | Channel Not Defined | |
| -11 | Channel Number Out Of Range |
btutrg
####### SUBROUTINE NAME
btutrg — set input byte trigger quantity
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btutrm
####### SUBROUTINE NAME
btutrm — set input line terminator character
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btutrs
####### SUBROUTINE NAME
btutrs — generate status 6 when output aborted by user?
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btutru
####### SUBROUTINE NAME
btutru — set output-abort character (truncates current output block)
...
In ASCII output mode (page 14), any data block in the process of being transmitted to a channel is aborted if the character you specify here is received from the channel. On DEC systems, the character that users are accustomed to for this purpose is ctrl+O. This is what we have used for Worldgroupthe Major BBS. On other systems, ctrl+X is preferred.
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btutsw
####### SUBROUTINE NAME
btutsw — set terminal screen width and select output word wrap
...
First, we will describe output word wrap and the effects of related Software Breakthrough routines. Then we will describe the default situation (what happens when you call none of these routines). Finally, we will present an example.
How Output Word Wrap Works
The output word wrap feature prevents words (strings of non-space characters) from being split across line boundaries. This means, for example, that 80-column wide messages will be readable both to users with 80-column wide terminals, and to users with 40-column wide terminals.
...
Word wrap means that a line has been shortened to conform to the screen width by changing one of its spaces into a soft carriage return. Paragraphs are defined as strings of characters between hard carriage returns. Note that conversion of a soft carriage return into a space does not preclude its reconversion into a carriage return by the word wrap procedure. In this manner, wide paragraphs are completely reflowed to fit the available screen width. Note, however, that narrow paragraphs are not reflowed to fit wide screens.
Default Conditions
After a channel is reset by bturst(): the output word wrap feature is turned off; the hard carriage return is 13 (ASCII cr); and there is no soft carriage return. The linefeed character is 10 (ASCII lf). In this situation, when transmitting messages, the line terminator should be the ASCII cr character:
...
The \r is the C-language representation for ASCII cr. Since this is the hard carriage return character, it is translated into ASCII cr (that is, it is not changed). It is appended with ASCII lf.
Example of Output Word Wrap
The following conditions are similar to those in Worldgroup the Major BBS (although screen width is user-selectable):
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuudf
####### SUBROUTINE NAME
btuudf — un-define channels
...
-11 channel number(s) out of range: the specified range of channels
(schan to schan+n-1) is not within the inclusive range 0 to
nchan-1, where nchan has been defined in btusiz() (page 135)
or btulsz() (page 106)
0 the specified channels were un-defined successfully
btuusp
####### SUBROUTINE NAME
btuusp — special UART polling method
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 OK, special mode turned off
1 OK, special mode turned on
btux29
####### SUBROUTINE NAME
btux29 — transmit an X.29 string across an X.25 network
to the remote user’s PAD
...
all other return values indicate some error returned by the DATASD transmit function of the PC XNet driver. Refer to the documentation from OST (specifically, the PCXNET.H source file).
btuxct
####### SUBROUTINE NAME
btuxct — transmit to channel (by byte count)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well
btuxlt
####### SUBROUTINE NAME
btuxlt — set input translation table
...
Any changes made to the translation table apply instantly to the system as a whole. Unless you are doing something unusual, this means that your btuxlt() calls, if any, should all appear at the beginning of your program, just after your call to btuitz().
####### RETURNS
Nothing.
btuxmn
####### SUBROUTINE NAME
btuxmn — transmit ASCII string that btuclo() will not be able to clear. (btubsz() will clear, however.)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 channel number is good
btuxmt
####### SUBROUTINE NAME
btuxmt — transmit to channel (ASCIIZ string)
...
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 channel number is good
btuxnf
####### SUBROUTINE NAME
btuxnf — set xon/xoff characters, select page mode
...