Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 versus char * 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
ASCIIDescription
0Quiet, Nothing Special To Report
1RING-Indicate Or Lost-Carrier (Xecom)
2Command Execution Completed OK (Xecom)
3cr-Terminated Input String Available
4Byte-Count-Triggered Input Data Available
5Output Buffer Empty
6Output Aborted By User
7(Reserved For Screen-Pause/Quit Command)
11Hayes Lost Carrier
12Hayes/UART Command Execution Completed
13Hayes/UART Invalid btucmd() Command Byte
21X.25 Incoming Clear Packet (End Of Session)
22X.25 Command Or Pause Completed
23X.25 Invalid btucmd() Command Byte
24X.25 Incoming X.29 String
31LAN SPX Connection Terminated By Other Side
32LAN Pause Command Completed
33LAN Invalid btucmd() Command Byte
34LAN SPX Incoming Connection Established
35LAN SPX Outgoing Connection Established
36LAN SPX Termination Complete By This Side
37LAN Receiver Error
38LAN Received Unknown Or Unexpected Packet
39LAN Connection Error
40LAN GTC Input Mode: Locked Out
41LAN GTC Input Mode: Binary
42LAN GTC Input Mode: ASCII, No Echo
43LAN GTC Input Mode: ASCII, With Echo
44LAN GTC Input Mode: ASCII, With Echo And Wrap
491Xecom DTMF 1 Sensed
63?Xecom Invalid Command Byte
65AXecom Aborted Command Prematurely
66BXecom Busy Signal Sensed (Or X.25 Call Failed)
68DXecom Dial Tone Sensed
70FXecom Failed For Other Reasons
73IXecom Inappropriate Command
77MXecom Modem Carrier (Or X.25 Call Completed)
82RXecom Ringing Sensed, But No Answer
84TXecom Timeout (Silence Sensed)
86VXecom Voice Sensed
118vXecom Voice Sensed (by ^A Command)
200-249Reserved For Your Special Purposes Using btuinj() or chiinj()
250Transmission Error (X.25)
251Data Input Circular-Buffer Overflow
252Echo Output Circular-Buffer Overflow
253Data Output Circular-Buffer Overflow
254Status Input Circular-Buffer Overflow
255Command Output Circular-Buffer Overflow
-10Channel Not Defined
-11Channel 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

...