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
...
Typical application: YMODEM uploads. This protocol requires an unusually large input buffer. Since YMODEM data packets are 1024 bytes long plus overhead, you will require an isiz parameter of 2048, which allows 2047 bytes in the input buffer. Let’s say a much smaller value had been supplied for isiz in your initial call to btusiz():
| Code Block |
|---|
btusiz(NCHAN,256,2048); |
parameter isiz = 256
parameter osiz = 2048
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.
Now when a YMODEM upload is required, you can swap the capacities of the data I/O buffers for channel chan. Here’s a subsequent call to btubsz():
| Code Block |
|---|
btubsz(chan,2048,256); |
parameter isiz = 2048
parameter osiz = 256
Then after YMODEM upload has completed, you return the buffers to their original condition:
| Code Block |
|---|
btubsz(chan,256,2048); |
parameter isiz = 256
parameter osiz = 2048
...
-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
...
Normally, the routine specified in btuchi() (see page 40) is only invoked when an input character is received, and your program has no way of telling when the channel’s echo buffer is empty. This function allows you to turn on or off a feature whereby each time the channel’s echo buffer becomes empty, the btuchi() rouadr function is invoked with the channel number and pseudo-key-code of -1 as parameters. For example:
| Code Block |
|---|
: btuchi(3,&idle); btuche(3,1); : idle(chan,c) int chan,c; { if (c == -1) { chiout(chan,'~'); } else { chiout(chan,c); return(0); } } |
In this example, '~' is constantly output on channel 3 when no input is being received. When an input character is received, it echoes normally, then the '~' output continues. Note that this process will not begin until the first character is received.
...
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
...
Here is an example character handler that strips the high-order bit 7 off of each byte received:
| Code Block |
|---|
char strip7(chan,c) int chan; char c; { return(c&127); } |
Then the following call to btuchi() installs this routine on channel chan:
| Code Block |
|---|
btuchi(chan,strip7); |
The following routine de-installs it (restores default character handling) on channel chan:
| Code Block |
|---|
btuchi(chan,NULL); |
####### ADVANCED USAGE
Four routines in the Galacticomm Software Breakthrough Library are provided only for use by your input character interceptor (btuchi()) or real-time interrupt (bturti(), page 127) routines. These are
...
Yet a third example would be inter-channel-chat. Let’s say you make the following character interceptor routine:
| Code Block |
|---|
uchat(chan,c) int chan; char c; { chiout(chana,c); chiout(chanb,c); return(0); } |
Then you could install this routine as the input character interceptor for both channels A and B:
| Code Block |
|---|
btuchi(chana,&uchat); btuchi(chanb,&uchat); |
Now whatever character is typed by either the user on channel A or the user on channel B is immediately echoed to the screens of both users.
...
-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
...
However, if you use the following approach:
| Code Block |
|---|
btucmd(chan,"A"); btucmd(chan,"p"); |
then the answer will precede the pause. See also page 168 for a description of the priority that transmitting takes over command execution.
...
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.
For example, this is not a good idea because it uses the same local socket number, the same destination network/node/socket, twice:
| Code Block |
|---|
btusdf(0,2,6,0x4007,2); btucmd(0,"W000000010000C0A61018M"); btucmd(1,"W000000010000C0A61018M"); |
This is OK, however, because it uses different destination addresses:
| Code Block |
|---|
btusdf(0,2,6,0x4007,2); btucmd(0,"W000000010000C0A61018M"); btucmd(1,"W000000010000C0CE0018M"); |
This is also OK because it uses different local socket numbers:
| Code Block |
|---|
btusdf(0,1,6,0x4007,2); btusdf(0,1,6,0x4008,2); btucmd(0,"W000000010000C0A61018M"); btucmd(1,"W000000010000C0A61018M"); |
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:
| Code Block |
|---|
btucmd(chan,"W"); btucmd(chan,"00000001"); btucmd(chan,"0000C0A81018"); btucmd(chan,"4007"); btucmd(chan,"M"); |
will have the same results as:
| Code Block |
|---|
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():
...
Note that an outgoing call may be specified in segments as long as there are no intervening calls to other GSBL routines. For example:
| Code Block |
|---|
btucmd(chan,"W1234,"); btucmd(chan,"6789M"); |
will have the same results as:
| Code Block |
|---|
btucmd(chan,"W1234,6789M"); |
The user data field of an outgoing call request packet is normally empty. To put data into the user data field, code it in hexadecimal after the / (slash) command. For example:
| Code Block |
|---|
btucmd(chan,"W1234,6789/41423031M"); |
That example will put the 4-byte ASCII string AB01 into the user data field. This data need not be ASCII. To code three zero bytes and a byte with value 01 hex:
| Code Block |
|---|
btucmd(chan,"W1234,6789/00000001M"); |
Important note: The outgoing call, if completed, may not actually be made over the same channel that you specify in btucmd(). The PC XNet card driver will decide the actual virtual circuit to use for the call.
...
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
...
When you called btusiz() or btulsz(), you specified the total number of channels in the first parameter nchan. btuitz() initialized the data structures for that many channels, numbered 0 to nchan-1. Now you will use btudef() to associate those channels with actual hardware. The following example in C illustrates a typical initialization sequence for one each of the Galacticomm Breakthrough Models 16, 4, and 2408 and a Hayes-compatible modem on COM1:
| Code Block |
|---|
btuitz(malloc(btulsz(40,128,1024))); btudef(0,0x2F0,16); /* Define Model 16 at 2F0 (hex) */ btudef(16,0x2F2,4); /* Define Model 4 at 2F2 (hex) */ btudef(20,0x2F4,8); /* Define Model 2408 at 2F4 (hex) */ btudef(28,0x2F8,1); /* Define 1 Hayes modem */ /* on a COM2 port at 2F8 (hex) */ btudef(29,0x3F8,8); /* Define 8 Hayes modems in a */ /* GalactiBox, each at the COM1 */ /* port address of 3F8 (hex) */ |
For Galacticomm Breakthrough cards, the sport parameter identifies the I/O base address for the card, as set on the card’s DIP switches. Refer to the Installation Manual for your particular model.
...
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
...
The contents of this ECB can be found in the ecbgsbl structure in IPX.H:
| Code Block |
|---|
struct ecbgsbl { /* Event Control Block (for use with GSBL btuhdr()) */ void *link; void (*esr)(); /* event service routine */ char inuse; /* 0=not in use FE=listening FF=sending */ char complt; /* 0=good, nonzero=command-specific error code */ int socket; /* sending socket (hi-lo) */ char ipxwsp[4]; /* IPX workspace */ char drvwsp[12]; /* driver workspace */ char immnod[6]; /* immediate node address */ int frgcnt; /* fragment count (lo-hi) */ void *frgadr; /* address of first fragment */ int frgsiz; /* size of first fragment (lo-hi) */ int prtseg; /* protected mode segment (GSBL-specific usage) */ int chanx2; /* channel number * 2 (GSBL-specific usage) */ }; |
####### Local Network/Node Address
...
Here is the full 52-byte structure for the data captured by btuhdr() on an X.25 channel:
| Code Block |
|---|
struct x25hdr { /* X.25 info from btuhdr() */ char cause; /* clear packet cause */ char diag; /* clear packet diagnostic */ char x29num; /* number of parameters in x3list */ char x29flg; /* flags, see below */ struct x3list { /* array of up to 24 X.3 pairs: */ char par; /* parameter number */ char val; /* value */ } x3list[24]; }; /* Masks for x29flg flag bits: */ #define X3SET 0x02 /* request to set X.3 values */ #define X3READ 0x04 /* request to read X.3 values */ #define X3NEW 0x80 /* new X.3 message has been rec'd */ #define X3OVF 0x40 /* more than 24 parameters rec'd */ |
Each incoming clear packet generates a status 21 (page 139), and comes with a cause and a diagnostic field. As you can see above, you can obtain these values with btuhdr().
...
-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
...
The most common practical values for irqno will be 3 and/or 4. You can call btuhit() on as many of the IRQ numbers 2-7 as you wish, but only once per IRQ number:
| Code Block |
|---|
btuhit(3); btuhit(4); |
Normally you would use this feature in a multitasking environment such as Windows or OS/2.
...
-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)
...
Be sure to declare btulsz() as a function returning a long (32-bit) integer in one of the variable declaration sections of your C-language calling program. For example:
| Code Block |
|---|
main() { int i,j,k; char *farmalloc(); long btulsz(); btuitz(farmalloc(btulsz(64,1024,2048))); : : btuend(); } |
Note: farmalloc() is a library routine of Borland’s C++ compiler. You will need a memory allocation routine, like this one, that accepts a long parameter instead of merely integer.
...
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
...
We recommend that as part of resetting any channel with Hayes category hardware, you issue the following sequence of instructions, selecting certain non-default options on which our interface scheme depends:
| Code Block |
|---|
bturst(chan); btulok(chan,1); btuoes(chan,1); btuech(chan,0); btubrt(chan,2400); btuxmt(chan,"ATE0S0=1S2=1&C1&D2\r"); btucli(chan); |
. . . wait for status 5 from this channel . . .
| Code Block |
|---|
btulok(chan,0); btuoes(chan,0); |
This procedure is used in the TELCONH.C example program on page 172.
...
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 operation of this function is only defined for X.25 and LAN channels when statid is 0 or 1. A count of characters and packets that have been transferred in both direction since channel reset is reported. For example, you could keep track of packet traffic with code like this:
| Code Block |
|---|
long pdelta; static long ptotal= |
0L; long btuset(); |
| Code Block |
|---|
pdelta=btuset(chan,1, |
0L); ptotal+=pdelta; printf("%ld packets input/output, %ld total!\n",pdelta,ptotal); |
UART
The operation of this function is only defined for 8250-type UART channels when statid is 2-4.
...
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):
| Code Block |
|---|
btutsw(chan,20); btuhcr(chan,13); btuscr(chan,10); |
Now, hard carriage returns are ASCII crs and ASCII lf is the soft carriage return. The terminal screen width is limited to 20 characters for simplicity. Now let’s suppose that the following statements were executed:
| Code Block |
|---|
btuxmt(chan,"The blue form of the Engelmann Spruce\n"); btuxmt(chan,"is native to the mountains of western\n"); btuxmt(chan,"North America.\n"); btuxmt(chan,"\r"); btuxmt(chan,"Koyama's Spruce is native to central\n"); btuxmt(chan,"Japan (at altitudes of 1500 to 1800\n"); btuxmt(chan,"meters) and also to Korea.\n"); btuxmt(chan,"\r"); |
The result with word wrap on the terminal of channel chan would be:
...
-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
...
Another purpose of the translation table is to permit you to translate UPPER case to lower case, or vice versa. This may improve the efficiency of the application software, in that you will not need to consider case when comparing strings, storing them in a database, etc. The following simple loop sets things up so that all channels in the ASCII mode automatically demote capitals to lower case:
| Code Block |
|---|
for (i='A' ; i <= 'Z' ; i++){ btuxlt(i,i-'A'+'a'); } |
A third use of the translation table is to to deal with parity, overrun, and framing errors. With “error-passthru” (see btuerp(), page 82), enabled by default, bytes read in with these errors will be received and their high bits will be set. Thus they will form translation table indices in the range from 128 to 255, as opposed to proper ASCII characters, which will have values of 0 to 127. There are, then, four main ways you might elect to deal with input characters involving these errors, by setting the upper half of the global translate 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)
...
There is a razor’s edge situation in which the priority of transmission over command execution must be considered:
| Code Block |
|---|
btucmd(chan,"p") btuxmt(chan,"Before or after pause?\r"); |
In this example, you can’t be sure the command will be executed before the string is transmitted because the interrupt-level code, when presented with commands and transmissions simultaneously, chooses transmissions. How can this be? The service rate (page 116) is low enough that, most probably, no service cycle will come between the above two instructions. If this occurs, the effects of these two statements will appear to the interrupt-level code simultaneously, and the data transmission will come before the pause.
...
-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
...
The default values after initialization or reset operate just as if the following call had been made:
| Code Block |
|---|
btuxnf(chan,0,19); |
This means:
chan For this channel number,
...
Here is an example of how you would enable page mode:
| Code Block |
|---|
btuxnf(chan,0,-19,24,"Strike any key to continue..."); |
This means:
chan For this channel number,
...
-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
...
Previous: Major BBS v10: 15 Global Variables | Contents | Next: Major BBS v10: 17 Programming Examples