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").
This section, by far the largest in this manual, describes each of the GSBL routines in detail.
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.
####### SUBROUTINE NAME
btubrt — set channel’s baud rate
####### SYNOPSIS
err=btubrt(chan,bdrate);
int err; zero means OK, -3 means bad baud rate
int chan; channel number
unsigned bdrate; baud rate, in bits per second
For the Model 2408, bdrate must be one of the values: 300 600 1200 or 2400
For 8250-interfaced serial devices, bdrate must be between 75 and 57,600. For the higher baud rates, the rate should divide evenly into 115,200. The default baud rate is 2400 baud, after a channel is reset by bturst().
####### DESCRIPTION
HAYES UART
Use this routine only on Hayes or RS-232 serial channels (page 6), not on Xecom modems. This function specifies the bits per second rate for a specific communications channel. Only the UART is affected. If you are also using a modem, the modem’s baud rate must be set another way. To the blackboard for a moment: Computer talks to UART, which talks to Modem. The UART (Universal Asynchronous Receiver/Transmitter) translates characters from the computer into a single signal with a pulse for each bit. The modem translates this into something that can be transmitted over phone lines (or other long distance media).
HAYES
The two most common ways that a modem’s baud rate changes are:
Case 1: incoming calls. When you send the command to answer an incoming call, the modem responds with CONNECT (for 300 baud) or with CONNECT <baud rate> for other baud rates (1200, 2400,...). After sending that message, the modem communicates at the specified baud rate — you should use btubrt() to change the UART to that baud rate.
Case 2: on demand. With the modem in command mode, simply change the UART baud rate using btubrt() and issue the null Hayes modem command AT enter. You should get an OK response from the modem (followed by cr lf) at the new baud rate.
The baud rates for a Model 2408 Breakthrough card are: 300 600 1200 and 2400. These are the valid values for the bdrate parameter of btubrt(), when operating on a channel assigned to the Model 2408.
HAYES UART
Valid baud rates for 8250-interfaced serial devices are between 75 and 57,600. If the value you supply does not evenly divide into 115,200 then you will have some truncation error, particularly with higher baud rates. For example, if you supply 110 for the bdrate parameter, the actual baud rate will be 110.03 (plenty good enough). But if you supply 35000, then the actual baud rate will be 38,400 (way off for sure!).
Technical Note: the number [115200/bdrate] is programmed into the 8250 baud rate divisor to achieve the baud rate bdrate. That is, “the greatest integer less than or equal to 115200/bdrate”. To compute:
actual baud rate = 115200 / [115200/bdrate]
Non-Technical Note: the following are perfectly good values for bdrate on 8250-interfaced channels:
| 75 | 110 | 150 | 300 | 600 | 1200 | 1800 |
| 2000 | 2400 | 4800 | 9600 | 19,200 | 38,400 | 57,600 |
####### CAUTIONS
When dealing with non-16550 UART serial hardware, you should not give btubrt() a baud rate value greater than the value set by btumxs() (maximum data speed, see page 116). If you do, you will lose characters on input, and have slow output. This is because btumxs() actually sets the modem service rate — the frequency at which all modems are polled for input and output — with a 21% safety margin. But btubrt() sets the frequency of the communication clocks in the UART device, and therefore only affects the bit rate within each byte.
When dealing with 16550 UART serial hardware, however, you can give btubrt() a baud rate value up to 4 times greater than that set by btumxs(). Since 16550s buffer data, you can get away with servicing them less often and still not lose characters.
####### RETURNS
-3 baud rate is not valid for the hardware being used
0 baud rate has been set correctly
####### SUBROUTINE NAME
btubse — set backspace-echo character
####### SYNOPSIS
err=btubse(chan,bschar);
int err; zero means OK
int chan; channel number
char bschar; how to handle a user’s backspace keystroke:
00 like any other character
08 delete last character (if any)
echo backspace - space - backspace
(default condition)
NN delete last character (if any)
echo NN
####### DESCRIPTION
This function specifies how to handle the user backspace keystroke. It applies only to ASCII input mode, not to binary input mode (page 11). While in ASCII input mode, any input character that translates to a value of 8 will be taken as a logical backspace — that is, it will delete the most recently accepted character on the current input line, if there is one. Note: the translate feature (see btuxlt(), page 162) can make the del character (7F hex) be treated just like the backspace character. In fact, this is the case in the default translate table (page 163).
The question that btubse() attempts to answer is: how will this character-delete operation be echoed back to the users terminal? On a CRT, you will probably want a backspace-space-backspace to do the work, erasing the previous character and leaving the cursor in the position where that character used to be.
If, however, a user is using a hardcopy device such as a teletype machine, it might be better to echo a backslash (\, or something, and let him figure out what he has typed and what he has deleted.
So, if the bschar parameter is 8, the backspace-space-backspace method will be used. This is the case by default, after you reset a channel (see bturst(), page 124). If bschar is some other nonzero value, then that is what’s echoed upon each backspace that the user types (when it actually deletes a character on his input line, that is).
Now, if the bschar parameter is 0, then this idea of the user’s backspace key deleting characters from his input line is thrown out altogether: ASCII code 8’s are simply passed into the input buffer just like any printable character.
####### CAUTIONS
If you are using standard CRT terminals, or terminal emulators, there is no need to call this routine.
####### RETURNS
-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
####### SUBROUTINE NAME
btubsz — respecify input and output buffer sizes
####### SYNOPSIS
err=btubsz(chan,isiz,osiz);
int err; zero means OK, -5 means bad sizes
int chan; channel number
int isiz; new size of input data buffer
int osiz; new size of output data buffer
####### DESCRIPTION
This command adjusts the size of the input and output data buffers for a particular channel. You might use this to temporarily increase the input or output buffer for special conditions. You must use integral powers of two, and their sum must not exceed that originally specified by btusiz() or by btulsz() (see cautions, below).
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():
btusiz(NCHAN,256,2048); |
parameter isiz = 256
parameter osiz = 2048
These are reasonable values for a multiuser online service such as the 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():
btubsz(chan,2048,256); |
parameter isiz = 2048
parameter osiz = 256
Then after YMODEM upload has completed, you return the buffers to their original condition:
btubsz(chan,256,2048); |
parameter isiz = 256
parameter osiz = 2048
####### CAUTIONS
The isiz and osiz parameters must each be an integral power of two (e.g. 128, 256, 512, 1024, 2048, 4096 etc.).
The sum of the isiz and osiz parameters must not exceed the space reserved for I/O buffers. That is, the sum of the isiz and osiz parameters that you specified in your original call to btusiz() or to btulsz() (whichever you used — refer to page 135 or 106).
The actual capacities of the I/O buffers are one less than the values specified in parameters isiz and osiz. If you mean to temporarily adjust input and output buffer sizes, be sure to use btubsz() to restore the original buffer sizes. Also, bturst() (page 124) restores the original buffer sizes. btubsz() automatically clears the data input and output buffers.
####### RETURNS
-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
####### SUBROUTINE NAME
btuche — enable calling of btuchi() when echo buffer becomes empty
####### SYNOPSIS
err=btuche(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1=enable calls; 0=disable
####### DESCRIPTION
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:
:
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.
####### CAUTIONS
When your btuchi() rouadr function is invoked with key-code equal to -1, no return value from the function is expected. Coding such as the example above may generate warnings by some compilers, since the function will sometimes return with an explicit return value, and at other times not. You can solve this, with only a small loss of efficiency, by coding the routine so that it always returns 0.
This function exists mainly to support certain advanced real-time protocols available for the Major BBS. Be sure that you fully understand the btuchi() function before attempting to use btuche().
####### RETURNS
-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
####### SUBROUTINE NAME
btuchi — set input character interceptor
####### SYNOPSIS
err=btuchi(chan,rouadr);
int err; zero means OK
int chan; channel number
char (*rouadr)(); address of character interceptor routine
(NULL to remove)
xc=(*rouadr)(chan,c); the character interceptor routine
char xc; new input character (0=ignore)
int chan; channel number
int c; the untranslated character received from the channel (or -1, see btuche(), page 38)
chiinp(chan,c); character input utility
int chan; channel number
char c; character to simulate input
chiout(chan,c); character output (via echo buffer)
int chan; channel number
char c; character to output
chious(chan,str); string output (via echo buffer)
int chan; channel number
char *str; string to output
chiinj(chan,s); status inject utility
int chan; channel number
int s; status to inject
####### DESCRIPTION
The btuchi() function provides a simple but powerful facility for customized handling of received characters. You can install your own C-language or assembly language routine so that it is invoked upon every byte received from a channel. This character interceptor of yours will only operate in the ASCII input mode. In Binary input mode, it is suspended.
This is one of the most complex and potentially dangerous routines in the Software Breakthrough Library. You should not attempt to use it if concepts like interrupts and reentrant code are unfamiliar to you.
We will describe the C-language method here. For the assembly language method, refer to your C compiler documentation sections on linking to assembly language routines.
To make your own input character interceptor, you must first code a C-language (or C-language compatible) function that accepts as parameters a channel number and a character. The function should return a single character value. See the synopsis of rouadr above. The syntax of that synopsis: (*rouadr)(...) simply means that the symbol rouadr represents a pointer to a function (which returns a value of type char, because xc is type char).
Next, you must call btuchi() and pass a channel number and the address of this custom handler routine of yours. If you want your custom handler to remain in effect constantly, you may call btuchi() right after the channel is defined (see btudef(), page 74).
Our character handler routine replaces the character translation function (refer to btuxlt() on page 162). However, the effects of all functions associated with ASCII input mode are still in effect. Again, your interceptor routine is not in effect when the channel is in Binary mode (page 11).
The input of a single character goes through the following sequence of steps during the ASCII input mode:
| Input Processing | Associated Library Routine |
|
|---|---|---|
| 1. | Formatting, Overrun, Parity error checking | btuerp() |
| 2. | Input lockout | btulok() |
| 3. | ASCII mode or Binary mode? | btuict() |
| 4. | XON/XOFF handling | btuxnf() |
| 5. | Output abort character | btutru() |
| 6. | Translate Table (or btuchi() routine) | btuxlt()/btuchi() |
| 7. | Backspace | btubse() |
| 8. | Line terminator | btutrm() |
| 9. | Line length limit or input word wrap | btumil() |
| 10. | Input buffer capacity | btusiz()/btulsz() |
| 11. | Echo | btuech() |
This table is provided for you to judge the interdependencies of the above library routines. For example, if your btuchi() routine returns a character code 8 (ASCII bs, backspace) then the backspace handler will swing into effect (it may echo a space-backspace-space sequence, unless you have adjusted btubse()).
To de-install your custom character interceptor routine, simply call btuchi() with a rouadr parameter value of NULL. bturst(), in resetting a channel, also de-installs any interceptor that may have been in effect.
####### EXAMPLE
Here is an example character handler that strips the high-order bit 7 off of each byte received:
char strip7(chan,c)
int chan;
char c;
{
return(c&127);
} |
Then the following call to btuchi() installs this routine on channel chan:
btuchi(chan,strip7); |
The following routine de-installs it (restores default character handling) on channel chan:
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
chiinp()
chiout()
chious()
and chiinj()
See synopses above. You may use these to cause all kinds of things to happen upon receipt of characters.
For example, in a “battleship” game, you may want the ctrl-E-D-X-S diamond on your user’s keyboard to control his screen cursor using ANSI-standard cursor control codes. Your character handler would echo (using chiout() or chious()) the appropriate cursor control codes upon receipt of the cursor commands from the user’s keyboard.
Also, keyboard macros could be implemented using chiinp(). You could translate special control codes from a user’s keyboard into a whole stream of characters. For example, you may want a user to be able to press ctrl+G when he means go forward enter.
Yet a third example would be inter-channel-chat. Let’s say you make the following character interceptor routine:
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:
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.
####### CAUTIONS
Your character handler routine (the rouadr parameter passed to btuchi(), above) must be coded to execute very fast, in order not to hinder operation of the Software Breakthrough. The Software Breakthrough has been coded in assembly language and honed into a lightning fast computing machine. That’s why we can claim 256-user capability on a single PC. You have the opportunity to change all that by intercepting input characters with a slow clunky handler routine. In particular, your routine should only interact with variables and data structures in memory (you don’t have enough time to even think about disk I/O!).
Since these routines may be called at the interrupt level, take care that any data structures used by both the rouadr character handler, and by any other of your routines, are not “skewed”. This happens when your mainline (not interrupt generated) routine changes a data structure, and halfway through such a change, the interrupt-generated handler tries to use or change the same data structure. Remember that your character handler can be invoked at any time.
The routine identified as a character interceptor (by passing its address to btuchi()) should only be used for that purpose, and called under no other circumstances.
chiinp(), chiout(), chious(), and chiinj() must be called only by the routines that are used as input character interceptors, or real-time interrupt handlers... that is, whose address is passed as a parameter to btuchi() or bturti() (page 127).
The chiout() and chious() routines are limited by the size of the echo buffer: 255 bytes.
X.25
Note to experts about interaction between echo modes and the btuchi() routine on X.25 channels:
Conditions:
1) X.25 channel
3) You are using btuchi(chan,custom) with a custom routine that returns values (intending them to be input and echoed) and those values are not the same as the values input to the custom routine.
Action:
call btuech(chan,2) when you install btuchi(chan,custom), and recover btuech(chan,whatever) when you uninstall btuchi(chan,NULL). See page 78 on the values for the btuech() echo parameter.
Reasoning: when you install the custom routine, you want the user’s PAD to stop blindly echoing everything the user types, and start having the GSBL decide what gets echoed (via return value from your custom routine). That means that you do not want echo-plex... you want the GSBL to echo.
####### RETURNS
-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
####### SUBROUTINE NAME
btuclc — clear command output buffer
####### SYNOPSIS
err=btuclc(chan);
int err; zero means OK
int chan; channel number
####### DESCRIPTION
btuclc() aborts any commands that may be in progress (refer to btucmd(), page 50), and clears the command buffer for the specified channel. A status 65 (refer to page 143) may be generated if a command was in progress.
####### RETURNS
-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
####### SUBROUTINE NAME
btucli — clear data input buffer
####### SYNOPSIS
err=btucli(chan);
int err; zero means OK
int chan; channel number
####### DESCRIPTION
Clears the data input buffer for the specified channel. Any queued input, even partial input strings or blocks, are completely cleared as though they were never received.
####### CAUTIONS
Calling this routine can cause inconsistencies between the status buffer contents and the input buffer contents. For example, if a cr-terminated string has been received but not yet processed at the time btucli() is called, the status of 3 (CR-TERMINATED INPUT DATA STRING AVAILABLE) will remain queued, but there will be no corresponding input data string available.
####### RETURNS
-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
####### SUBROUTINE NAME
btuclo — clear data output buffer
####### SYNOPSIS
err=btuclo(chan);
int err; zero means OK
int chan; channel number
####### DESCRIPTION
btuclo() aborts any data output operation underway on the specified channel, clears its data output buffer, and eliminates the effects of XOFFs received, if any (see btuxnf(), page 169).
####### CAUTIONS
Any output data pending for the specified channel will be lost when this routine is called.
####### RETURNS
-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
####### SUBROUTINE NAME
btucls — clear status input buffer
####### SYNOPSIS
err=btucls(chan);
int err; zero means OK
int chan; channel number
####### DESCRIPTION
Provided only for completeness, this routine clears the highly sensitive status-input buffer, the key area upon which the sensing of modem condition depends. You should almost never need to use btucls().
####### CAUTIONS
Do not call this routine unless you are totally confident that this is really what you want to do, since it is potentially dangerous to arbitrarily clear out what might be critical modem status information, such as “lost carrier”.
####### RETURNS
-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
####### SUBROUTINE NAME
btucmd — command channel
####### SYNOPSIS
err=btucmd(chan,cmdstg);
int err; zero means OK
int chan; channel number
char *cmdstg; command string (ASCIIZ)
####### DESCRIPTION
This routine controls functions of the UART and (if used) the modem on a channel. For example, you could dial up Galacticomm’s Demonstration System with the following C-language statement:
btucmd(chan,"WT13055837808M");
If the call goes through as expected, btusts(chan) will eventually return a value of 12 (for Hayes hardware), or 2 (for Xecom hardware), meaning that command execution has completed successfully (see page 4 for a discussion of hardware categories). Meanwhile your program can be off doing other things. Note that a status of 2 or 12 is created only when the end of the command string is reached, not on each command byte, and only when no other status from the modem is present after the last command byte in the string has been executed.
The syntax of the command string closely follows the modem command protocol developed by Xecom. However, many of these command codes can also be used on Hayes or UART category hardware. We have also added some command codes of our own which are hardware independent. The services accessed by btucmd() fall into six categories as shown in figure 4-1.
This table shows which commands are supported on which hardware:
| HAYES | XECOM | UART | |
| Modem dial commands | all | all | none |
| Modem mode commands | most | all | none |
| Baud rate commands | all | most | all |
| Framing commands | all | all | all |
| Pause commands | all | all | all |
| ANSI commands | all | all | all |
| Diagnostic commands | none | all | none |
Unsupported commands generate a status 13 on Hayes and UART category hardware, and a status 63 (a question mark) on Xecom category hardware (refer to btusts(), page 137).
In figure 4-1, Commands with an asterisk (*) in the Status column return information in the receive buffer. We recommend that you use btutrg() to select binary receive mode so that a status 4 is generated when these bytes are available.
Note 1: A status code of 13 from Hayes category hardware, or a status code of 63 (a question mark) from Xecom category hardware, means that the command is not supported on this hardware.
Note 2: On Hayes category hardware, commands which generate a status 3 return information in the receive buffer. The channel should be in the ASCII receive mode so that a status 3 indicates the availability of these bytes. This is the default mode, but if you should select binary receive mode using btutrg(), be sure to restore ASCII receive mode, also using btutrg(). In these cases, btusts() will return the status 3 after it returns the status 12.
Note 3: The baud rate, framing, pause, and ANSI commands are soft commands processed by the PC rather than by the modem hardware. If you use btucmd() with a string of commands, all of the soft commands will be executed first, and then all of the hard commands.
These soft commands are the exact set of commands that may be issued on UART category hardware.
####### Figure 4-1: Summary of Hayes and Xecom Commands
| Command | Description | HAYES statuses | XECOM statuses | |
|---|---|---|---|---|
| Modem | R | Rotary (pulse) dial mode | 12 | 2 |
| Dial | T | Touch-tone dial mode | 12 | 2 |
| Commands | 1 2 3 4 5 6 7 8 9 0 |
\ \ Dial a digit / (touch tone or rotary) / |
12 | 2 |
| a b c * # d |
\ \ Dial a special digit / (touch tone only) / |
12 | 2 | |
| Modem Mode |
W | Wait for dial tone | 12 3 | 2 B M I R T V |
| Commands | A | Answer-carrier with no frills | 12 3 | 2 I T F |
| ^A | Answer-carrier with detections | 12 3 | 2 I T F 1 v | |
| O | Originate-carrier with no frills | 12 3 | 2 I T F | |
| M | Originate-carrier with detections | 12 3 | 2 I T F B R D V | |
| D | DTMF receive mode (touch tone input) | 13 | 4 * | |
| H | Hold (off-hook, modem disconnected) | 13 | 2 | |
| Baud | ^T | Set speed to 300 bps | 12 | 2 I |
| Rate | ^H | Set speed to 1200 bps | 12 | 2 I |
| Commands | ^F | Set speed to 2400 bps | 12 | ? |
| Framing | > | Set parity to “even” | 12 | 2 |
| Commands | < | Set parity to “odd” | 12 | 2 |
| = | Set parity to “none” (no parity bit) | 12 | 2 | |
| ^S | Set character length to 7 bits | 12 | 2 | |
| ^E | Set character length to 8 bits | 12 | 2 | |
| ^N | Set stop bits to one | 12 | 2 | |
| ^W | Set stop bits to two | 12 | 2 | |
| Pause | P | Pause 5 seconds | 12 | 2 |
| Commands | p | Pause 2 seconds | 12 | 2 |
| t | Pause 1/10 second | 12 | ? | |
| ANSI | [ | Enable ANSI graphics (default) | 12 | 2 |
| Commands | ] | Disable ANSI graphics | 12 | 2 |
| Diagnostic | I | Identify modem version | 13 | 4 * |
| Commands | i | Identify revision number | 13 | 4 * |
| ^M | Continuous monitor, return line freq | 13 | 4 * | |
| L | Line analyze | 13 | 4 * | |
| l (ell) | Return 1200-bps error statistics | 13 | 4 * I | |
| ^X | Analog loopback in originate mode | 13 | ||
| ^Y | Analog loopback in answer mode | 13 | ||
| Invalid Command | (Anything else) | 13 | ? |
HAYES
On Hayes-protocol hardware, all modem dial commands, baud rate commands, framing commands, and pause commands are supported.
Most modem mode commands are supported. Some of these (^A and O) have reduced features over their Xecom-protocol counterparts. Others (D and H) are not supported on Hayes hardware.
None of the Diagnostic commands are supported on Hayes category hardware.
If you are exclusively using Hayes category hardware, you may want to use btuxmt() (the transmit routine, page 166) to handle the modem dial functions and modem mode functions, instead of btucmd().
Hayes-protocol modems have an AT command language for controlling the modem. See your modem manual for more details. The following table shows the modem mode commands that are translated into Hayes-protocol AT command codes by btucmd():
| btucmd() command char | Hayes command char | Function |
| ^A or A | A | Answer incoming call |
| W | D | Wait for dial-tone and dial a number |
| M or O | O | Go online (generate originate-carrier) |
The btucmd() modem dial commands are translated directly into parameters of the Hayes-protocol D command. For this reason, when any of the following btucmd() commands are used on Hayes category hardware, they must be placed immediately following the btucmd() W command (wait for dial-tone), which is translated into the Hayes protocol D command (dial):
| btucmd() command char | Hayes D command parameter | Function |
| R | P | Rotary (pulse) dial mode |
| T | T | Touch-tone dial mode |
| 0 through 9 | 0 through 9 | \ |
| * # | * # | > Output DTMF tone |
| a b c d | a b c d | / |
For example, the sample C-language statement mentioned above for dialing Galacticomm’s Demonstration System was:
btucmd(chan,"WT13055837808M");
For Hayes category hardware, this statement has almost the identical effect as:
btuxmt(chan,"ATDT13055837808O");
Applies to: v10
const CHAR * vs CHAR * hazard. This call passes a string literal to
btuxmt(), which v10 declaresEXPGSBL INT btuxmt(INT chan,CHAR *datstg);(BRKTHU.H:162).MBBS10.txtsays this crashes the system. Copy the string into a writable buffer first, for exampleCHAR_BUFFER(dial, 32, "ATDT13055837808\r"); btuxmt(chan, dial);(CHAR_BUFFER,GCOMM.H:40).btucmd()takesconst CHAR *(BRKTHU.H:159) and is safe with a literal.
The major difference being that when the btucmd() directive has completed, a status code of 12 is generated (page 139), assuming nothing goes wrong with the call. Minor differences include the generation of a status 5 after btuxmt() (if btuoes() has enabled it, see page 119), and that btucmd() on Hayes category hardware uses the echo buffer for output and is subject to its limitation of 255 characters at a time.
On Hayes category hardware, some commands are handled by the Software Breakthrough, and others are passed directly to the modem hardware. We will call these soft and hard commands. The soft commands are the baud rate, framing, pause, and ANSI commands. The hard commands are modem mode and dial commands, and the diagnostic commands.
Soft commands are the only commands available on UART category hardware. On Hayes category hardware, if you have a btucmd() string with mixed soft and hard commands, then all of the soft commands are executed first, followed by all of the hard commands. For example, the command string:
btucmd(chan,"Ap");
will pause for 2 seconds (p to pause is a soft command), and then answer an incoming call (A to answer is a hard command).
However, if you use the following approach:
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.
Instead of the btucmd() baud rate commands, you may want to use btubrt() (page 32) to select the baud rate on Hayes and UART category hardware.
XECOM
All of the commands of btucmd() are supported on Xecom category hardware (Galacticomm Models 16 and 4), with the single exception of the ^F command (2400 baud).
The framing and pause commands provided by btucmd() apply to all categories of hardware. These functions can be obtained through no other Software Breakthrough library routine.
Be sure to review the CAUTIONS at the end of this section on btucmd() (page 72).
LAN
Here are the letter command codes that are valid for LAN channels:
| Page | ||
| L | Listen for connection (SPX only) | 63 |
| W | Prefix to dial-out command | 67 |
| 0-9 A-F | 24-digit network/node/socket address specified for dial-out command | 67 |
| M | Suffix to dial-out command | 67 |
| T | Terminate an SPX connection | 66 |
| G | Greet another GSBL and offer to handle its input preprocessing | 61 |
| P | 5-second pause (uppercase P) | 65 |
| p | 2-second pause (lowercase p) | 65 |
| V | Disable auto PAD echo programming | 66 |
| [ | Enable ANSI-X3.64 output | 71 |
| ] | Disable ANSI-X3.64 output | 71 |
X.25
The following command codes may be used on X.25 channels:
| Page | ||
| A | Answer an incoming call | 71 |
| W | Prefix to dial-out command | 69 |
| 0-9 | Digits of address or user data field | 69 |
| A-F | Digits of user data field | 69 |
| , | Between caller and callee address | 69 |
| M | Suffix to an outgoing dial command | 69 |
| / | Prefix hexadecimal user data field | 69 |
| P | 5-second pause (uppercase P) | 65 |
| p | 2-second pause (lowercase p) | 65 |
| [ | enable ANSI-X3.64 output | 71 |
| ] | disable ANSI-X3.64 output | 71 |
Astute readers will notice that A appears twice in the above list. A is a hexadecimal digit when, in a W command, it appears after a / and before the M. Otherwise, A is an answer command.
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.
####### ANSWER-CARRIER WITH DETECTIONS (TT,VOICE)
HAYES
This command acts just like command A (Answer-Carrier With No Frills) on Hayes hardware. See page 60 for details.
XECOM
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.
####### 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.
####### SET SPEED TO 2400 BPS
HAYES UART
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.
####### SET SPEED TO 1200 BPS
HAYES UART
Sets the UART to 1200 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 1200 message.
XECOM
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.
####### CONTINUOUS MONITOR, RETURN LINE FREQ
XECOM
This command causes the modem to turn into a sort of spectrum analyzer, reporting back the frequency it hears 20 times a second. The frequency is reported as a data byte ranging in value from 0 to 255:
0 Quiet, no frequency at all
1 to 254 Frequency in tens of Hz (10 Hz to 2540 Hz)
255 Frequency greater than 2540 Hz
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).
####### ONE STOP BIT
UART
Sets the UART in this channel to use 1 stop bit. This mode is the default condition after bturst().
####### SET CHARACTER LENGTH TO 7 BITS
This mode is the default upon channel reset. This command works on all hardware categories.
####### SET SPEED TO 300 BPS
HAYES UART
Sets the UART to 300 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 message.
XECOM
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.
####### TWO STOP BITS
UART
Sets the UART in this channel to use 2 stop bits.
####### ANALOG LOOPBACK IN ORIGINATE MODE
XECOM
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.
####### ANALOG LOOPBACK IN ANSWER MODE
XECOM
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.
####### DIAL 0 to 9 (ROTARY PULSE OR TOUCH TONE)
HAYES XECOM
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).
####### DIAL SPECIAL TOUCH-TONES
The corresponding special touch-tone pair will be emitted (a through d are part of a “phantom column” in the Bell DTMF standard, but they don’t appear on any telephone we’ve ever seen).
HAYES
These codes must only be used after the W command (page 67).
XECOM
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.
####### ANSWER-CARRIER WITH NO FRILLS
HAYES
This command puts “answer carrier” on the line, and generates a status 3 if “originate carrier” is heard within 17 seconds. The status 3 indicates a received data string that you can get out of the receive buffer by using btuinp() (refer to page 99). Some examples of the string:
CONNECT when 300 baud carrier has been detected
CONNECT 2400 when 2400 baud carrier has been detected
CONNECT <baud> when other baud rates have been detected
CONNECT <baud><mode> for special compression or correction modes
If no carrier is detected in 30 seconds, the following string usually appears in the receive buffer:
NO CARRIER no originate carrier detected within 30 seconds
XECOM
This command puts answer carrier on the line, and will generate a status of 2 if originate carrier is heard within 17 seconds. Otherwise a status code is generated indicating: T (Timeout), or I (Inappropriate). This is the command you would normally use to pick up the phone when it rings (rather than the ^A command).
X.25
The A command will answer an incoming call on an X.25 line if issued immediately after receiving a status 3 with a RING message:
RING <caller> CALLING <callee>
Where <caller> is the decimal network address (if available) for the source of this call, and <callee> is your network address. The A command generates an immediate status 22.
If you set x25udt to 1, then btuinp() will return:
RING <caller> CALLING <callee> <user data field>
See page 30 for details on the limitations of this method.
####### DTMF RECEIVE MODE (ACCEPT TOUCH TONE INPUT)
XECOM
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.
####### GTC GREETING (LAN)
LAN
The Galacticomm Terminal Configuration protocol was designed for two computers that are connected via IPXV or SPX LAN channels. GTC allows one computer to preprocess the input of the other computer. The presumption is that both computers are using the GSBL to communicate.
For example, GTC can be used in a terminal emulation program talking to a 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 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.
####### HOLD (DISCONNECT MODEM, BUT REMAIN OFF-HOOK)
XECOM
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.
####### IDENTIFY MODEM VERSION
XECOM
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.
####### IDENTIFY REVISION NUMBER
XECOM
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”.
####### 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.
####### LISTEN FOR SPX CONNECTION (LAN)
LAN
This command prepares the channel to accept a connection request from another party (presumably a terminal program like SPXTALK). The channel will remain in the listen-for-connection mode until a connection is established or until the channel is reset with bturst().
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.
####### RETURN 1200-BPS ERROR STATISTICS
XECOM
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.
####### MONITOR LINE AND ORIGINATE WITH DETECTIONS
HAYES
The modem goes to the Online mode, waiting for answer carrier. If answer carrier is detected within 30 seconds, the following string appears in the receive buffer (refer to btuinp(), page 99):
CONNECT when 300 baud carrier has been detected
CONNECT 1200 when 1200 baud carrier has been detected
CONNECT 2400 when 2400 baud carrier has been detected
If no answer carrier is detected within 30 seconds, the following string appears in the receive buffer:
NO CARRIER no answer carrier detected within 30 seconds
XECOM
This command will generate a status of 2 if answer carrier is heard within 17 seconds. Otherwise a status code is generated indicating: B (Busy), R (Ringing), I (Inappropriate), T (Timeout), D (Dial Tone), or V (Voice). You should reissue the M command if you want to continue the attempt (e.g. for the first few rings).
LAN
See page 67 for using the M command on LAN channels.
####### ORIGINATE-CARRIER WITH NO FRILLS
HAYES
This command acts identically to the M command on Hayes category hardware. The modem goes to the Online mode, waiting for answer carrier. If answer carrier is detected within 30 seconds, the following string appears in the receive buffer (refer to btuinp(), page 99):
CONNECT when 300 baud carrier has been detected
CONNECT 1200 when 1200 baud carrier has been detected
CONNECT 2400 when 2400 baud carrier has been detected
If no answer carrier is detected within 30 seconds, the following string appears in the receive buffer:
NO CARRIER no answer carrier detected within 30 seconds
XECOM
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).
####### PAUSE 5 SECONDS
The “long pause”. Works on all hardware categories.
####### PAUSE 2 SECONDS
The “short pause”. Works on all hardware categories.
####### ROTARY (PULSE) DIAL SUBSEQUENT DIGITS
HAYES
This is the default condition, upon initialization or reset. This command must follow a W command.
XECOM
Use this command to dial on a phone line which does not support touch-tone dialing.
####### TOUCH-TONE DIAL SUBSEQUENT DIGITS
HAYES
This command must follow a W command.
XECOM
This is the default, upon initialization or reset.
####### TERMINATE SPX CALL (LAN)
LAN
The terminate command will gracefully end an SPX session. A status 36 on the end that issued the T command indicates that the session was terminated properly. A status 31 on the other end (in the GSBL of a program to which your program is connected) indicates the session was terminated. Here’s a diagram of how an SPX session is terminated with the T command:
Application 1 --> GSBL --/ /-- GSBL --> Application 2
\ \
-- 'T' cmd --> / /
\ \ -- status 31 -->
<-- status 36 -- / /
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.
####### WAIT 1/10 OF A SECOND
HAYES UART
Generates a status 12 after 0.1 seconds. Works only on 8250-type UARTs and modems or Model 2408 cards.
####### DISABLE AUTOMATIC PAD ECHO PROGRAMMING (X.25)
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().
####### WAIT FOR DIAL TONE (TO PLACE AN OUTGOING CALL)
HAYES
This command is usually accompanied by digit dial commands, such as:
btucmd(chan,"WT13055837808M");
(which would dial the Galacticomm Demo system from channel chan).
In this case, if connection is established within 30 seconds, a status 12 is generated, along with the following string in the receive buffer (refer to btuinp(), page 99):
CONNECT when 300 baud carrier has been detected
CONNECT 1200 when 1200 baud carrier has been detected
CONNECT 2400 when 2400 baud carrier has been detected
If no answer carrier is detected within 30 seconds, the following string appears in the receive buffer:
NO CARRIER no answer carrier detected within 30 seconds.
XECOM
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
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.
On IPX Virtual circuits, the dial-out command may also be used to establish an incoming call. In the raw-packet mode, an IPX Virtual Circuit reports the complete IPX packet to you. Then you can look at the source network/node/socket of this packet to determine who is attempting to communicate with you (page 195). You can format the results of this report into a dial-out command to complete the connection.
You can issue dial-out commands on IPX channels whenever you want. When you do, all transmits and receives since the most recent call to btuscn() will correspond to the new network address. These transmits/receives will be processed/available after the next call to btuscn().
SPX channels are more complicated. The dial-out command should only be issued on SPX channels that are in the idle state. See page 191 for details.
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).
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:
btusdf(0,2,6,0x4007,2); btucmd(0,"W000000010000C0A61018M"); btucmd(1,"W000000010000C0A61018M"); |
This is OK, however, because it uses different destination addresses:
btusdf(0,2,6,0x4007,2); btucmd(0,"W000000010000C0A61018M"); btucmd(1,"W000000010000C0CE0018M"); |
This is also OK because it uses different local socket numbers:
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).
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,"W"); btucmd(chan,"00000001"); btucmd(chan,"0000C0A81018"); btucmd(chan,"4007"); btucmd(chan,"M"); |
will have the same results as:
btucmd(chan,"W000004010000C0A810184007M"); |
X.25
To place an outgoing call on an X.25 channel, issue any of the following command string formats using btucmd():
W<caller>,<callee>/<user data field>M
W<callee>/<user data field>M
W<caller>,<callee>M
W<callee>M
You can use T (touch tone) or R (pulse dialing) in the above commands for compatibility with Xecom channels. For X.25 channels, they have no effect. For example:
btucmd(chan,"WT100657,399613M");
In this case, you are seeking network address 399613, while identifying yourself as network address 100657.
Note that an outgoing call may be specified in segments as long as there are no intervening calls to other GSBL routines. For example:
btucmd(chan,"W1234,"); btucmd(chan,"6789M"); |
will have the same results as:
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:
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:
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.
Specifying the channel for btucmd() with a dial-out command does serve the purpose of identifying the card and line to use. The PC XNet card usually puts the call on the highest unused channel that has been configured (unless the line is configured as DCE, in which case outgoing calls go over the lowest available channel).
When an outgoing call has been confirmed, status code 77 (ASCII M) is generated on the channel on which the call has been established. If an outgoing call fails, either: status code 66 (ASCII B) is generated if there is some local transmission error encountered when transmitting the call request packet (like transmit window full) or status code 21 (lost carrier) is generated if the network refuses to connect your call, perhaps because the network address you specified is busy, or does not exist, or if the service you’re dialing refuses your call for some reason (see page 88 about obtaining cause and diagnostic fields).
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)
This command affects the operation of btuxmt() when transmitting the following construct:
esc [ <for ANSI users> | <for non-ANSI users> ]
If ANSI graphics have been enabled for a channel by this command, (or by default), then the string <for ANSI users> from the above construct will be transmitted and the string <for non-ANSI users> will not be transmitted.
ANSI graphics are automatically enabled by bturst(). See page 166 for more information on ANSI graphics directives.
####### DISABLE ANSI GRAPHICS
This command affects the operation of btuxmt() when transmitting the following construct:
esc [ <for ANSI users> | <for non-ANSI users> ]
If ANSI graphics have been disabled for a channel by this command, then the string <for ANSI users> from the above construct will not be transmitted and the string <for non-ANSI users> will be transmitted. Also, ANSI graphics directives embedded in the text passed to btuxmt() will not be transmitted to that channel. See page 166 for more information on these directives. ANSI graphics are automatically enabled by bturst().
####### CAUTIONS
If data input or output is in progress when this call is made, the data operation will be allowed to complete before the command string is executed. See page 168 on the priority of transmission over commands.
The framing commands must be reissued each time you reset a channel (by bturst(), page 124).
The command buffer can hold 62 characters at a time.
HAYES
To use btucmd() on Hayes category hardware, the modem must be in command mode.
####### RETURNS
-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
####### SUBROUTINE NAME
btucpc — sets the clear pause-counter character
(puts off screen pauses when in output stream)
####### SYNOPSIS
err=btucpc(chan,cpchar);
int err; zero means OK
int chan; channel number
char cpchar; clear pause-counter character (or 0 to disable)
####### DESCRIPTION
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 the Major BBS, this function is used to prevent screen pauses by inserting the ctrl+S character at strategic points in certain text blocks.
####### RETURNS
-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
####### SUBROUTINE NAME
btudef — define channels
####### SYNOPSIS
err=btudef(schan,sport,n);
int err; zero means OK
int schan; starting channel number
int sport; starting port address
int n; number of channels
####### DESCRIPTION
After you initialize the Software Breakthrough as a whole using btusiz() (or btulsz()) and btuitz(), you use btudef() to initialize individual channel groups. You will call btudef() once for each device that you have installed in your system. See also about btusdf() (page 130) for more alternative devices.
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:
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.
For hardware on the standard serial ports COM1 and COM2, you should use the following values for the sport parameter:
COM1 0x3F8 COM3 0x3E8
COM2 0x2F8 COM4 0x2E8
btudef() can discriminate between the three categories of hardware: Hayes, UART, and Xecom (see page 4). If it fails to find a Galacticomm Breakthrough Model 16 or 4 at the base address sport, it will look for a Model 2408 card at the same address. Failing that, it will look for an 8250-type UART (which is used in both Hayes and UART category hardware).
HAYES UART
See the discussion of bturst() (page 124) for the proper sequence of initializing a Hayes or UART channel.
####### CAUTIONS
The return value from btudef() only indicates whether the mechanics of the calling sequence are correct, not whether or not the modem or UART hardware is working.
If you are changing the maximum data rate using btumxs() (see page 116), you must do that before calling btudef().
XECOM
If there is no hardware at the specified address, the channels specified will all have statuses of -10 (see btusts(), page 137). If an underpopulated card is installed (for example, a Model 16 with 8 modems), then calls to btudef() on the vacant modem slots will also generate a single status code -10 on those channels.
HAYES UART
If there is no hardware at the specified address, the channels specified will all have statuses of -10 (see btusts(), page 137). If an underpopulated card is installed (for example, a Model 2408 with 4 modems), then calls to btudef() on the vacant modem positions will not generate statuses of -10. Those channels will appear to the software to exist, but they will never be connected to anything. That’s because the 2408 card has an 8-channel UART talking to up to 8 modems. Whether the modems are installed or not, the presence of the UART is all that is sought by the reset operation.
If you have purchased the N-channel version of the Software Breakthrough, then you may only use channels 0 through N-1 to talk to real hardware. If you attempt to define channels N or higher, then these channels will each have a single status code of -10, as if there were no hardware on these channels. You may still use these channels for local emulation (described on page 114).
LAN X.25
Don’t use btudef() on LAN or X.25 channels. Use btusdf() instead (page 130).
####### RETURNS
-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 defined successfully
####### SUBROUTINE NAME
btueba — echo buffer space available, in bytes
####### SYNOPSIS
nbytes=btueba(chan);
int chan; channel number
int nbytes; room in the echo buffer for bytes to echo to the user’s terminal
####### DESCRIPTION
This routine returns a value indicating the number of bytes that the echo buffer for this channel can handle before overflowing.
The echo buffer can hold up to 255 bytes. When the echo buffer overflows, a status 252 is generated (page 146).
####### RETURNS
0 echo buffer is full
1-254 echo buffer is between full and empty
255 echo buffer is empty
####### SUBROUTINE NAME
btuech — set echo on/off
####### SYNOPSIS
err=btuech(chan,mode);
int err; zero means OK
int chan; channel number
int mode; 0 = disable echo
1 = enable echo (echo-plex on X.25 channels)
2 = enable echo (GSBL echo on X.25 channels)
####### DESCRIPTION
This routine allows input echo to be enabled or disabled while in the ASCII input mode (page 11). It defaults to the enabled state upon channel initialization or reset.
There are two typical uses for this routine:
The first is for hiding passwords: you can turn off the echo on a channel just as the user is prompted for his password, then turn it back on again once the password has been entered. In this way, prying eyes in the user’s vicinity will not see his password displayed on his screen.
The second use of btuech() is for half-duplex communications, in which the user’s terminal already echoes each keystroke that he types (therefore your system should not echo). In this case, you would simply turn off the echo as soon as a connection is established, and leave it off for the duration (you will need to disable the echo after each reset of the channel with bturst(), page 124).
X.25
Echo-plex means that the PAD (packet assembler/ disassembler) on the user’s end of the X.25 network does the echoing of characters. The GSBL programs the PAD to do this using the “Q” bit, per recommendations X.29 and X.3 (parameter 2). GSBL echo means that the GSBL echoes each input character, just as it does with modems and serial ports.
On a non-X.25 channel, btuech(chan,1) has the same effect as btuech(chan,2). On an X.25 channel, the call to btuech() controls both the echo of input from the GSBL and the echo of characters by the user’s PAD:
| Value of mode parameter in call to btuech() | Local echo from the GSBL? | X.3 pad parameter number 2 setting | Echo mode |
| 0 | OFF | 0 (echo off) | Echo off |
| 1 | OFF | 1 (echo on) | Echo-plex |
| 2 | ON | 0 (echo off) | GSBL echo |
Echo-plex can be more economical if your packet-switching network charges for data traffic based upon the number of packets input and output. Echo-plex saves the extra packet per user keystroke that would result from the GSBL echoing each keystroke. However, there are a few minor drawbacks to echo-plex for X.25 channels:
The input word-wrap feature enabled by btumil() will not work well on an X.25 channel in echo-plex mode. The GSBL will be splitting lines on word boundaries, but not displaying the effects on the user’s screen as it would in GSBL echo mode, or as it would on a non-X.25 channels. The maximum line length set by btumil() will not automatically disable echo when the limit is reached. The user’s PAD will continue to echo even after the GSBL stops accepting characters. The user backspace key erases input keystrokes fine, but does not stop when the beginning of the input line is reached, and may erase a preceding prompt. If a user types during output to his screen (“type-ahead”), then the echo is not suspended until the next prompt (as it is with GSBL echo mode or with non-X.25 channels), but is mixed in with the output. The monitored channel, when in echo-plex mode, specially handles monitored input and output to most closely resemble the users screen, including the above mentioned drawbacks.
To achieve this:
Each monitored keystroke (btumks() or btumks2()) is immediately echoed to the monitor screen buffer (for access by btumds() or btumds2()) and to the user’s screen (via the GSBL’s echo buffer). Each received character is immediately echoed to the monitor screen buffer (for btumds() or btumds2()). Carriage returns echoed to the monitor screen buffer are automatically appended with line feeds. Note: Echo-plex is automatically suspended during binary input (when btutrg(chan,nonzero) is in effect) and re-enabled when ASCII input resumes (btutrg(chan,0)).
See also page 40 regarding echo considerations for your custom character interceptor routine, specified by btuchi().
####### CAUTIONS
Half-duplex communications modes are not recommended for reasons of user-friendliness, flexibility, and standardization.
####### RETURNS
-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
####### SUBROUTINE NAME
btuend — shut down the Software Breakthrough
####### SYNOPSIS
btuend();
####### DESCRIPTION
Prepare the PC for return to DOS. This routine must be called as part of your exit cleanup procedure.
####### CAUTIONS
If your program has called btuitz() (initialization, page 103), you must call btuend() before your program returns to DOS. The Software Breakthrough alters certain PC hardware settings for its own ends, and these must be restored, or else the operating system will become very confused.
Only call btuend() upon exiting your program altogether. The Software Breakthrough routines will no longer function once you have called btuend().
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.
####### SUBROUTINE NAME
btuerp — pass/block input bytes with errors
####### SYNOPSIS
err=btuerp(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1 = accept characters with PE/FE/OE errors, setting
the high-order bit of each (default)
0 = ignore characters with PE/FE/OE errors
####### DESCRIPTION
This feature gives you control over the handling of input characters received with parity errors, framing errors, or overrun errors.
If error-passthru is enabled (onoff = 1), then any character received with one of these errors will have its high-order bit set (i.e. if not already in the range from 128 to 255 it will be brought there by adding 128 to it). Then this new value is used as an index into the global input-character translation table (see btuxlt(), page 162).
If error-passthru is disabled (onoff = 0), then any character received with one of these errors will be ignored.
By default, this feature is enabled (onoff = 1). With the default input character translation table (page 163), this means that 7-bit ASCII characters with parity, framing, or overrun errors are received as if they had nothing wrong with them: their high bits are set, but the translate table effectively strips them off.
####### CAUTIONS
When running protocols requiring 8-bit data, such as XMODEM, you should probably disable error-passthru because otherwise you will not be able to distinguish between valid received characters with their high-order bits set and invalidly received characters. Anyway, during XMODEM input, parity errors are not possible, framing errors are rare, and overrun errors are unlikely.
####### RETURNS
-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
####### SUBROUTINE NAME
btuffo — enable receiver FIFO on 16550 UART
####### SYNOPSIS
err=btuffo(chan,onoff);
int err; 0 is ok
int chan; channel number
int onoff; 1=enable 16-byte FIFO’s
0=disable (for exact 16450 compatibility)
####### DESCRIPTION
HAYES UART
This routine enables the 16-byte FIFOs on the 16550 UART. This can be used to avoid losing received characters. There are many diverse reasons why incoming characters could be lost. If any code, such as disk-caching software, keeps interrupts disabled for too long, for example, then the resulting jitter in sampling can cause characters to “fall between the cracks”. If this happens, the btuerp() routine (page 82) can allow overrun errors to be reported as data bytes with the high bit set (and then possibly stripped by the translate table, page 163), resulting in double characters (for example frog would turn into frrg).
The 16550 UART is a pin-compatible replacement for the 16450 UART (itself compatible with the original 8250 UART). UART stands for Universal Asynchronous Receiver Transmitter. It is the heart of almost all serial devices on the IBM PC and compatibles, and is also used in most modems, internal and external.
The 16550 UART however, has 16-byte deep first-in first-out queues, one in the receiver circuit and one in the transmitter. That means that
(1) the GSBL is almost certain not to miss any incoming characters, and
(2) the port can be polled less often (see page 117).
To enable this FIFO feature, call btuffo with a 1 for the onoff parameter.
HAYES UART
btuffo() has no effect on 8250 or 16450 UART. It will return -18 to let you know they’re not 16550’s.
XECOM LAN X.25
btuffo() has no effect on Xecom, LAN, or X.25 category hardware (it always returns 0).
####### CAUTIONS
Calling btuffo() on a channel with a 16550 UART can cause you to lose any characters that are in the FIFO transmitter or receiver circuitry at the moment that you call btuffo().
On a non-hardware channel that was defined using btudef() (or btusdf() with chtype=0), btuffo() will always return 0. On a non-hardware channel that was defined using btusdf() with chtype=3 (8250), the btuffo() return value is undefined. See page 130 for more about btusdf(), or page 74 for btudef().
####### RETURNS
-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
####### SUBROUTINE NAME
btuhcr — set the hard-cr character (for output word wrap)
####### SYNOPSIS
err=btuhcr(chan,hardcr);
int err; zero means OK
int chan; channel number
char hardcr; hard-cr, translated to 0DH on output
####### DESCRIPTION
The hard carriage return is an output character that is unconditionally converted into an ASCII cr (carriage return). This occurs during ASCII output mode, when output word wrap is in effect. ASCII output mode, discussed on page 14, is performed using btuxmt() (page 166). Output word wrap is controlled by btutsw() (page 153).
The hard carriage return defaults to ASCII cr (13 decimal) when a channel is initialized or reset, which is to say that crs are passed through unchanged.
By default, all crs are also appended with lfs on output. This feature is controlled by btulfd() (page 104).
You can think of a hard cr as representing “end of paragraph” if you have output word wrap enabled. Usually the default value of 13 will be fine, but there may be cases in which you want to use some printable character, such as @ or < to indicate paragraph boundaries.
####### RETURNS
-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
####### SUBROUTINE NAME
btuhdr — capture information on X.25 or LAN channel
####### SYNOPSIS
err=btuhdr(chan,nbytes,buffer);
int err; zero means OK
int chan; channel number
int nbytes; number of bytes to capture
char *buffer; where to put them
####### DESCRIPTION
This routine can be used to capture the contents of special internal data structures for the channel.
The nbytes parameter should be even (if odd, btuhdr() will only copy nbytes-1 bytes).
LAN
Here are some useful values of nbytes for LAN channels:
46 for most recent listen ECB
76 for most recent listen ECB + listen IPX header
88 for most recent listen ECB + listen SPX header
176 for most recent listen ECB + listen SPX header + send ECB + send SPX header
####### ECBs used by the GSBL
The ECBs (Event Control Blocks) used by the GSBL are 46 bytes long. This includes the 42-byte structure defined by Novell for an ECB with one fragment descriptor, plus 4 bytes used internally by the GSBL.
The contents of this ECB can be found in the ecbgsbl structure in IPX.H:
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
After calling btusdf() for a channel group, btuhdr() can be used to find the local network/node address of the machine on which the GSBL is running. It will reside in the dstnet and dstnod fields of the listen IPX header buffer. This occurs even before any packets are received, and offers your program the first opportunity to determine your local node address (if your computer never logs into a file server, this information might not be available for the first minute or so of operation).
Note that the IPX/SPX header part of this information is redundant in raw packet mode – you always get the entire packet in the input buffer.
X.25
Here are some useful values for nbytes when calling btuhdr() on X.25 channels:
2 for cause and diagnostic of last clear packet (see about status 21 on page 139)
52 for cause and diagnostic, plus information about the last received X.29 string (see about status 24 on page 139)
Here is the full 52-byte structure for the data captured by btuhdr() on an X.25 channel:
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().
Calling btuhdr() clears the x29flg&X3NEW flag. Each received X.29 string sets X3NEW. So, if the X3NEW flag is set, then a new X.29 string has been received since you last called btuhdr(). Incoming X.29 strings are also heralded by a status 24 (page 139).
All other flag bits, the x29num field, and the x3list array are from the most recently received X.29 string. The X3OVF flag indicates that more than 24 parameter/value pairs were in the last incoming X.29 string.
An incoming X.29 string means that the other DTE on the X.25 network is trying to query (X3READ), set (X3SET), or both set and query (X3READ+X3SET) your X.3 parameters. Obviously this DTE thinks it is talking to a PAD. To respond to a query as if you were a PAD, you can call btux29() (page 159) with a message code of 0 (meaning query-reply).
####### RETURNS
-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
####### SUBROUTINE NAME
btuhit — hook into a COM port interrupt
and use it to invoke channel servicing
####### SYNOPSIS
err=btuhit(irqno);
int err; zero means OK
int irqno; 2-7 IRQ number to intercept
####### DESCRIPTION
The GSBL is normally based on timed polling of all ports. This function can be used to make the GSBL instead take its cue from the UART interrupts of a very limited number of serial ports (typically 1 or 2, but possibly up to 6).
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:
btuhit(3); btuhit(4); |
Normally you would use this feature in a multitasking environment such as Windows or OS/2.
####### CAUTIONS
btuhit() can only be used when the GSBL has been initialized with btuitm() (page 102), not with btuitz() (page 103).
Only one port per IRQ line can be serviced using this scheme.
####### RETURNS
-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
####### SUBROUTINE NAME
btuhpk Handle keystrokes during screen-pause mode
####### SYNOPSIS
err=btuhpk(chan,hpkrou);
int err; zero means OK
int chan; channel number
int (*hpkrou)(); pointer to function to be called
rc=(*hpkrou)(chan,c);
character interceptor routine during screen-pause mode
char rc; 0=ignore
1=next page
2=continue nonstop
int chan; channel number
char c; character received
####### DESCRIPTION
First, a channel goes into screen-pause mode when:
2. A special pause-character defined by btupbc() has been transmitted (page 121) and printable output has been transmitted to the user since the last time he pressed enter.
After a channel goes into screen-pause mode, each character received triggers a call to the hpkrou routine, which may be coded in C. In other words: you will use btuhpk() to identify that the hpkrou routine will handle each character received on any channel during screen-pause mode.
There are several functions that can be implemented by the hpkrou routine, based on the keystroke(s) received during screen-pause mode. You can compose a very short (e.g. 40-character) menu of these functions in the stg message of the -xoff form of btuxnf(). Within the hpkrou routine:
1. To handle a “continue” key, just return 1.
2. To handle a “go nonstop” key, return 2.
3. To handle an “abort” key, you must inform your mainline program. For example, inject a status 7 (this is what happens in the Major BBS) and have the mainline program handle the status by clearing output using btuclo(), and changing states (to stop stuffing the output buffer).
The channel remains in screen-pause mode when you return 0. Otherwise, screen-pause mode ends and output resumes.
The character handed off to the hpkrou routine is not automatically echoed, but you could use chiout() to echo it if you wish.
####### CAUTIONS
See also page 43 for cautions relating to interrupt-called functions. Design of the hpkrou routine is fraught with pitfalls. Don’t design lengthy complex code to run at interrupt level. Don’t invoke DOS (because it is not reentrant). You may use the special chixxx() routines (page 42), but not any other Breakthrough Library routines. Beware of data skewing, since a real-time interrupt may occur between any two machine-language instructions of your mainline code.
####### RETURNS
-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
####### SUBROUTINE NAME
btuhwh — enable hardware handshaking using RTS/CTS
####### SYNOPSIS
err=btuhwh(chan,inpcut);
int err; zero means OK
int chan; channel number
char inpcut; input buffer byte count cutoff point
(or 0 to disable handshaking)
####### DESCRIPTION
By default, hardware handshaking is disabled to permit simple serial cables (ground, receive, transmit, carrier-detect, and DTR). With high-speed modems, though, hardware flow may be necessary. The btuhwh() function, when called with a nonzero inpcut parameter has two effects:
1. A high-to-low transition on the CTS (clear-to-send) input signal will inhibit transmission of output data until CTS goes high again.
2. The RTS (request-to-send) output signal will be asserted only when there are less than inpcut bytes waiting in the channel’s input buffer. This use of RTS is not RS232-C standard, but complies with the de facto standard of hardware manufacturers. The meaning is essentially “ready to receive”.
These features allow effortless (non-software) throttling of data flow in both directions. Calling btuhwh() with inpcut equal to zero restores the default condition: CTS is ignored, and RTS is always active.
####### CAUTIONS
The sensing of the falling edge of CTS means that if CTS is always inactive, then there is no throttling of the outgoing data.
####### RETURNS
-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
####### SUBROUTINE NAME
btuibw — Input Bytes Waiting: report the number of bytes received
and waiting in the input buffer
####### SYNOPSIS
inpbcw=btuibw(chan);
int inpbcw; input bytes waiting, or error code
int chan; channel number
####### DESCRIPTION
This routine simply returns the count of bytes currently present in the channel’s input data buffer. This can be used to keep track of a block-oriented input process, or to detect user keystrokes without removing them from the input buffer. The total capacity of the input buffer is:
Total capacity = isiz - 1
where isiz is the parameter passed to btusiz() (page 135) or btulsz() (page 106). Therefore the current capacity of the input buffer is:
Current capacity = isiz - 1 - btuibw(chan)
####### RETURNS
-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
####### SUBROUTINE NAME
btuica — input from a channel: reading in whatever bytes
are available, up to a limit
####### SYNOPSIS
nbytes=btuica(chan,inbuff,siz);
int nbytes; bytes transferred (negative if error)
int chan; channel number
char *inbuff; pointer to buffer for input bytes
int siz; maximum number of bytes to get
####### DESCRIPTION
Only use btuica() when you have already prepared for the binary input method by calling btutrg() with nbyt > 0 (see pages 149 and 11). Use btuinp() instead (page 99) for the ASCII input method.
This routine copies whatever bytes have been received so far into a location you specify with the inbuff and siz paramters. The siz parameter specifies the maximum number of bytes that btuica() will put at inbuff. If more are available, they’ll be left in the input buffer.
The key difference between this routine and btuict() is that btuict() always takes a prearranged number of bytes from the input buffer (prearranged by btutrg(), page 149) or it will take none at all. btuica() always reads in as many as possible, up to the siz limit.
This is the preferred method for binary input. Your application should use it to process incoming data as a stream of bytes.
####### RETURNS
-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
####### SUBROUTINE NAME
btuict — input from a channel: by the byte count prearranged
with btutrg()
####### SYNOPSIS
nbytes=btuict(chan,inbuff);
int nbytes; bytes transferred (negative if error)
int chan; channel number
char *inbuff; pointer to buffer for input bytes
####### DESCRIPTION
Only use btuict() when you have already prepared for the binary input method by calling btutrg() with nbyt > 0 (see pages 149 and 11). Use btuinp() instead (page 99) for the ASCII input method.
btuict() checks to see if at least nbyt (the trigger number) bytes have been received in the input data buffer and, if so, transfers them to your buffer whose starting address you’ve supplied in inbuff. This data is flushed from the input buffer. If not enough bytes have been received, btuict() transfers as many as it can, and does not flush any of them from the input buffer. In this case, the global variable ictact can be used to find out how many bytes were transferred (see page 24).
The key differences between this routine and btuinp() are:
1. btuict() reads in a count of characters (prespecified by btutrg()), whereas btuinp() reads in a variable number of characters ending in cr.
2. The characters returned by btuict() are arbitrary binary data, so they may include embedded zeros, or any other 8-bit value.
3. btuict() does not terminate the returned buffer contents with a zero byte, as btuinp() does.
4. btuict() performs no translation or special handling of the bytes it receives. See page 11 for more on ASCII versus binary input methods.
5. btuict() sets global variable ictact, indicating number of bytes transferred.
####### CAUTIONS
Normally, you should call this routine only after btusts() has returned a status of 4 (BYTE-COUNT-TRIGGERED INPUT DATA AVAILABLE, page 138) for the channel.
Do not call btuict() when in the ASCII input mode.
####### RETURNS
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-2 insufficient bytes available in input buffer
N>0 length of returned input block (will be the same
as the nbyt value passed to btutrg()
when nbyt > 0, page 149)
The sequence of bytes at address inbuff:
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()).
####### SUBROUTINE NAME
btuinj — “inject” a status code into a channel
####### SYNOPSIS
err=btuinj(chan,status);
int err; zero means OK
int chan; channel number
char status; status to be injected
####### DESCRIPTION
This routine simulates a status condition for a given channel. Each channel has a status queue that can accumulate multiple status codes if necessary. Those status codes are accessed by the main program one at a time using the btusts() routine (page 137). In some cases, it is handy to be able to put status codes directly into that queue. Then btusts() will return that code (after it returns any others that may be pending).
Status codes 200-249 are nominally reserved for you to define for special application-specific purposes and insert in the status stream using btuinj().
####### RETURNS
-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
####### SUBROUTINE NAME
btuinp — input from channel (ASCIIZ string)
####### SYNOPSIS
len=btuinp(chan,inbuff);
int len; returned string length or error code
int chan; channel number
char *inbuff; pointer to buffer for input string (the line terminator is replaced with a 0-byte)
####### DESCRIPTION
btuinp() transfers a complete input data line into your buffer. This routine should normally be called only when btusts() returns status 3 (CR-TERMINATED INPUT DATA STRING AVAILABLE). When you call btuinp() after a status 3 has been detected, then the received line is copied into your buffer (inbuff) and removed from the channel’s input buffer. The carriage return that terminated the input line is replaced with a single byte of 0 value in your buffer. In this case the len return of btuinp() will always be non-negative, giving the actual number of characters transferred (not counting the terminating zero byte).
If btuinp() is called when btusts() has not returned a status of 3 for this channel, then the len return code will probably equal -1, indicating that no cr-terminated data string exists in the buffer. If this happens, whatever characters were available are copied into your buffer anyway, and a zero is placed at the end of them. These characters are not flushed from the receive buffer in this case — you will see them again once a complete line has been received.
You may use btutrm() (page 150) to change the line terminator character from ASCII cr to some other character.
####### CAUTIONS
Unless you are doing something unusual, you should only call this routine after btusts() returns a status of 3.
Be sure that the memory area addressed by inbuff is big enough to contain the maximum size string anticipated (including the terminating zero). btumil() (page 110) will set a limit on the input length, but to be safe, you should probably expect up to the size of the input buffer (isiz, as specified in btusiz() or btulsz()).
####### RETURNS
The function’s return value (the variable len, above):
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-1 a complete input line is not yet available (no cr yet)
N>=0 the length of the returned string
(not including line terminator, not including 0-terminator)
The character string (address inbuff in synopsis):
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.
####### SUBROUTINE NAME
btuirp — define alternate GSBL timing source using COM1/2/3/4
####### SYNOPSIS
err=btuirp(comno);
int err; zero means OK
int comno; 0=use real-time interrupt (8253)
1=use COM1: 03F8, interrupt 4
2=use COM2: 02F8, interrupt 3
3=use COM3: 03E8, interrupt 4
4=use COM4: 02E8, interrupt 3
####### DESCRIPTION
The GSBL is based on timed polling of all ports. Normally the system timer interrupt is intercepted and then its rate is multiplied by a factor sufficient to catch all characters at the highest baud rate.
The btuirp() routine specifies an MS-DOS asynchronous communication port, or COM port, to use as an alternate timing source. The port’s baud rate and transmit interrupt are configured to provide a regular interrupt for polling all ports. This may be helpful in operating systems or MS-DOS-like environments in which the 8253 timing device is not available.
####### CAUTIONS
You must only call btuirp() once, immediately following the call to btuitz(), and coming before any other calls to GSBL routines that also follow btuitz(). The COM port interrupts 3 and 4 are probably at a lower priority in your system than the interrupt 0 generated by the 8253 timer. This may mean that btuirp(1-4) will increase jitter and increase the possibility of missed incoming characters.
####### RETURNS
-17 comno is not 0/1/2/3/4, or COM port specified is not available
0 all is well
####### SUBROUTINE NAME
btuitm — initialize the Software Breakthrough for use
in a multitasking environment
####### SYNOPSIS
err=btuitm(region);
int err; 0 is OK
char *region; pointer to memory region
(size indicated by btusiz() or btulsz())
####### DESCRIPTION
This alternative to btuitz() is used to initialize the GSBL in a multitasking environment such as Windows or OS/2. The main differences between btuitm() and btuitz() are:
1. btuitz() hooks the GSBL into the timer interrupt IRQ0 (CPU interrupt 08). At each timed interrupt, all channels will be serviced.
2. btuitm() does not hook into the timer interrupt. Instead, it’s left up to you to call btuhit() (page 90) to explicitly designate which of several interupts to hook into, IRQ2 to IRQ7 (CPU interrupts 0A through 0F hex).
####### CAUTIONS
See starting on page 103 for the descriptions and cautions associated with btuitz().
####### RETURNS
0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed
####### SUBROUTINE NAME
btuitz — initialize the Software Breakthrough
####### SYNOPSIS
err=btuitz(region);
int err; 0 is OK
char *region; pointer to memory region
(size indicated by btusiz() or btulsz())
####### DESCRIPTION
This routine initializes the Software Breakthrough package.
btuitz() must be called after either btusiz() or btulsz(), and before any other GSBL routine. See line 7 of the example program on page 172 for an example of using btuitz(). The region parameter must be a pointer to a memory region set aside for GSBL’s exclusive use. The size of this region, in bytes, must be equal to the value returned by either btusiz() or btulsz(), whichever was previously called. Use btusiz() if the size of memory you will need is less than 64K. Use btulsz() if more, or if you are not sure.
If using protected mode, the region pointer passed to btuitz() must have an offset portion of 0 and be based upon a selector capable of being tiled by the GSBL using operating system calls.
####### CAUTIONS
btuitz() assumes that no errors had been reported by btusiz() or btulsz() (whichever you used, pages 135, 106) — in particular, that neither had returned an error code and that your dynamic memory allocator, if any, was able to allocate a block of the requested size.
This routine must be called exactly once at the beginning of execution, and btuend() must be called before btuitz() can be called again.
####### RETURNS
0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed
####### SUBROUTINE NAME
btulfd — set linefeed character (what follows every carriage return)
####### SYNOPSIS
err=btulfd(chan,lfchar);
int err; zero means OK
int chan; channel number
char lfchar; > 0 character to output after each carriage return
(defaults to 10, the ASCII linefeed character)
= 0 disabled
####### DESCRIPTION
This routine enables automatic generation of linefeeds after carriage returns during the ASCII output mode (page 14). There is a lack of standardization in communications today regarding whether a “carriage return” also implies advancing to the next line or not. On some terminals, displaying a cr (ASCII code 13) causes the cursor to merely return to column 1 of the current line. On others, it also moves the cursor down the screen one line (or scrolls the screen, or advances the paper as the case may be).
The default upon channel initialization or reset is to assume the former: that is, that an explicit lf byte (ASCII code 10) is necessary following each cr in order to move on to the next line. However, this will cause lines to appear double-spaced under some conditions. You can eliminate the lf, or replace it with some other ASCII code, using the btulfd() routine. The btulfd()-defined linefeed character also has a minor effect in ASCII input mode: after a carriage return (defined by btutrm()) is echoed, the linefeed character is also echoed.
####### RETURNS
-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
####### SUBROUTINE NAME
btulok — set input lockout on/off
####### SYNOPSIS
err=btulok(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1 = lockout, 0 = remove lockout
####### DESCRIPTION
Allows a channel’s input to be locked out. You might use this in a “deaf good-bye” scheme. This is a log-off sequence in which you do not want the user to be able to throttle output (via XOFF, see btuxnf(), page 169), or to issue further commands, during the output of a final message.
####### RETURNS
-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
####### SUBROUTINE NAME
btulsz — size of dynamic memory needed
(long version, used when more than 64K needed)
####### SYNOPSIS
lsiz=btulsz(nchan,isiz,osiz);
long lsiz; total size needed, in bytes
int nchan; number of channels to allow for
int isiz; input data buffer size per channel
int osiz; output data buffer size per channel
####### DESCRIPTION
Calculates the size of the memory region needed by the Software Breakthrough package. Either this routine or btusiz() must be called prior to calling btuitz() to initialize the system. The input and output data buffer sizes specified must be integral powers of two (128, 256, 512, 1024, etc). The actual number of bytes that each buffer can hold will be 1 less than the size you specify. For example, if you specify an input data buffer size of 128, then blocks of up to 127 characters at a time may be input without overflowing. This routine specifies the total number of channels you will support, and the sizes of the input and output buffers associated with each channel. This can be done in either of two ways:
1. If the language you are using supports dynamic memory allocation (this is usually called a heap or a pool), you can simply pass the return value of btusiz() or btulsz() to your allocator, specifying the number of bytes you want to allocate. This is the preferred method.
2. If you have no capability for dynamic memory allocation, and you must allocate all your data structures before your program runs, this is what you can do: write a separate little test program to call btusiz() or btulsz() with the appropriate parameters and simply print out the result. This is the number of bytes that the Software Breakthrough will need. Then create a fixed-length array of this size in the main program (the one that will be actually doing the communications). If you do this, you still must call btusiz() or btulsz() in your main program just before you call btuitz().
Whether you use method 1 or method 2, the address of a memory region this many bytes long must be passed to btuitz().
####### CAUTIONS
Even when using method 2 above, either btusiz() or btulsz() must be called before calling btuitz(). There is no other way to inform the Software Breakthrough of the total number of channels and of their buffer sizes. Method 1 is preferred over method 2. Under method 2, the size test procedure must be redone every time you receive an update to the Software Breakthrough, while relinking is all that is required under method 1. You will use method 2 only when you require static memory (that is, when you cannot use dynamically allocated memory).
LAN
On LAN channels, input buffers and output buffers should usually be of sufficient size to accommodate full packet contents (546 bytes for IPX channels, 534 bytes for SPX channels). If either buffer is smaller than a full packet, then even SPX channels cannot necessarily be guaranteed against data loss (unless you’re sure the main program won’t require it).
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:
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.
####### RETURNS
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
####### SUBROUTINE NAME
btumds — get next displayed character from the monitored channel
(as specified by btumon(), see page 114)
####### SYNOPSIS
dspchr=btumds();
int dspchr; character that was output or echoed (0 if no characters)
####### DESCRIPTION
Returns the next buffered output character from the monitored channel, or returns 0 if the display monitor buffer is empty. Use btumon() (page 114) to select the monitored channel.
####### CAUTIONS
When you are monitoring a channel, be sure to call this routine often enough that the monitor-output buffer will not overflow (it can hold up to 2047 characters). Also, when you do get around to calling this routine, we recommend that you call it repeatedly until it returns 0, to flush out its buffer.
####### RETURNS
0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer
####### SUBROUTINE NAME
btumds2 — get next displayed character from the monitored channel (as specified by btumon2(), see page 115)
This function is a clone of btumds(), for emulating a second channel.
####### SYNOPSIS
dspchr=btumds2();
int dspchr; character that was output or echoed (0 if no characters)
####### DESCRIPTION
Returns the next buffered output character from the monitored channel, or returns 0 if the display monitor buffer is empty. Use btumon2() (page 115) to select the monitored channel.
####### CAUTIONS
When you are monitoring a channel, be sure to call this routine often enough that the monitor-output buffer will not overflow (it can hold up to 2047 characters). Also, when you do get around to calling this routine, we recommend that you call it repeatedly until it returns 0, to flush out its buffer.
####### RETURNS
0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer
####### SUBROUTINE NAME
btumil — set maximum input line length, input word wrap on/off
####### SYNOPSIS
err=btumil(chan,maxinl);
int err; zero means OK
int chan; channel number
int maxinl; if > 0 then input word wrap is disabled and
maxinl is the maximum input line length
if = 0 then input word wrap is disabled and there is
no limit to the length of an input line
(see status 251, page 145)
if < 0 then input word wrap is enabled and
abs(maxinl) is maximum input line length
####### DESCRIPTION
This routine may be used to restrict each line of input data to a specified field width. If a user should attempt to type more than the limit of characters on a single line, characters after the limit will neither be stored in the input buffer nor echoed back to the user (but status 251’s will be generated).
In interactive applications, you often want to restrict the length of a user’s input line — maybe you only have 15 characters in which to store his name. Rather than accept data that is too lengthy, and truncate it after the user has pressed enter, it is nicer for the user to “feel” the restriction while he is typing. He can then backspace and retype some kind of abbreviation.
This routine also selects the input word wrap feature. To turn it on, make maxinl the negative of the screen width. For example, if maxinl is -79, then a user with an 80-column wide screen may type electronic mail without worrying about the right margin. Note: the last column should never actually be used, to prevent the display device from auto-scrolling. For example, if maxinl = -79, then word wrapping kicks in upon typing the 80th character of the line — so that each line can be no longer than 79 characters.
####### RETURNS
-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
####### SUBROUTINE NAME
btumks — simulate a keystroke on the monitored channel
(as specified by btumon(), see page 114)
####### SYNOPSIS
btumks(kyschr);
char kyschr; simulated-input character
####### DESCRIPTION
Simulates a keystroke on the user’s terminal. The kyschr character is placed into the receive buffer just as if it had been received from the channel. This can be used to parallel the system operator’s keyboard with that of the monitored user.
####### CAUTIONS
Use of key macros or other means of rapidly issuing large blocks of keystrokes should be avoided with this routine, since the input-keystroke buffer can hold only 15 entries.
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.
####### SUBROUTINE NAME
btumks2 — simulate a keystroke on the monitored channel
(as specified by btumon2(), see page 115)
This function is a clone of btumks(), for emulating a second channel.
####### SYNOPSIS
btumks2(kyschr);
char kyschr; simulated-input character
####### DESCRIPTION
Simulates a keystroke on the user’s terminal. The kyschr character is placed into the receive buffer just as if it had been received from the channel. This can be used to parallel the system operator’s keyboard with that of the monitored user.
####### CAUTIONS
Use of key macros or other means of rapidly issuing large blocks of keystrokes should be avoided with this routine, since the input-keystroke buffer can hold only 15 entries.
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.
####### SUBROUTINE NAME
btumon — start/stop monitoring a channel
####### SYNOPSIS
err=btumon(chan);
int err; zero means OK
int chan; channel number (-1 to disable monitoring)
####### DESCRIPTION
btumon() sets up a specific channel for monitoring, which means that each character transmitted to the channel can be obtained by calling btumds(), and you can simulate input from the channel by calling btumks(). Monitoring can be turned off by passing -1 to btumon().
The three routines btumon(), btumds(), and btumks() are designed for tuning in to any desired online channel from a master console. When monitoring a channel, the system operator can see everything the user of that channel is seeing: each keystroke echoed, and each block of text output. Also, the system operator’s keyboard can be placed in parallel with that user’s keyboard, in the sense that anything typed on the system operator’s keyboard is processed exactly as though it had come from the monitored user’s keyboard — it even echoes to both displays. There are two uses for the channel monitoring feature:
1. When a user is on the channel: to “look over a user’s shoulder” and see what he is doing, maybe even help him along a little, by typing for him.
####### RETURNS
-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
####### SUBROUTINE NAME
btumon2 — start/stop monitoring a channel
This function is a clone of btumon() for emulating a second channel.
####### SYNOPSIS
err=btumon2(chan);
int err; zero means OK
int chan; channel number (must be a non-hardware channel), or -1 to disable monitoring
####### DESCRIPTION
tumon2() sets up a specific channel for monitoring, which means that each character transmitted to the channel can be obtained by calling btumds2(), and you can simulate input from the channel by calling btumks2(). Monitoring can be turned off by passing -1 to btumon2().
The three routines btumon2(), btumds2(), and btumks2() are designed for tuning in to a non-hardware channel from a master console.
The only use for channel monitoring with btumon2() is when the channel is a non-hardware channel, for the console operator to act as a user himself, as if he had dialed up the system with a modem and a terminal. This is called local emulation. This method can be used only on a channel with no actual modem hardware.
####### RETURNS
-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
####### SUBROUTINE NAME
btumxs — set maximum data speed
####### SYNOPSIS
err=btumxs(bdrate);
int err; error return: 0=OK, -3=rate no good
unsigned bdrate; baud rate (bits per second)
Default=2400 min=300 max=38400
####### DESCRIPTION
This routine specifies the maximum data rate (in bits per second) of all channels on your system.
This directly affects the rate at which all channels are serviced. The byte rate is derived from the baud rate (bdrate) that you specify with btumxs():
bytes per second = bdrate / 10
A 21% margin is added to this rate to get the channel service rate:
service rate = bytes per second * 1.21
For example, with the default bdrate of 2400 baud, data is expected for receiving and transmitting at 240 bytes per second. Therefore each channel is serviced about 290 times a second.
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 the 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.
####### Using 16550 FIFOs
When you use 16550 UARTS, you may be able to set the btumxs() rate even slower than the maximum baud rate. That’s because the 16550 UARTS have hardware FIFOs in them and don’t need to be polled as often. This can save your computer a lot of processing overhead, because it doesn’t have to poll your channels as rapidly.
To take advantage of this, you need to distinguish ports with 16550 UARTs from those with standard 8250 UARTs. The btuffo() routine (see page 84) returns 0 for 16550 ports, and -18 for 8250 or 16450 ports (it also returns 0 for Xecom or any other non-8250 based port).
So, to figure the bdrate parameter for btumxs(), compute the maximum of all of the polling rates that are required for all the channels. The polling rate required for each channel is:
16550 channel: the baud rate / 4Non-16550 channel: the baud rateHere are some examples:
8250 port at 2400 bps btuffo(chan,1) = 0
16550 port at 4800 bps btuffo(chan,1) = 1
btumxs(2400)
8250 port at 2400 bps btuffo(chan,1) = 0
16550 port at 9600 bps btuffo(chan,1) = 1
16550 port at 19200 bps btuffo(chan,1) = 1
btumxs(4800)
####### CAUTIONS
If you make the bdrate parameter smaller than the baud rate of the fastest channel on your system, you may lose received characters and you may be transmitting at less than capacity. If you make the bdrate parameter larger than the baud rate of the fastest channel on your system, you will be wasting CPU time servicing channels more often than they require.
####### RETURNS
0 the maximum data speed has been set
-3 bad baud rate: bdrate was not between 300 and 38400
####### SUBROUTINE NAME
btuoba — Output Bytes Available: report the amount of space
(number of bytes) available in the output buffer
####### SYNOPSIS
outbca=btuoba(chan);
int outbca; output buffer size, or error code
int chan; channel number
####### DESCRIPTION
This routine simply returns the size of the vacant portion of the output data buffer for the specified channel. It is intended for use in two ways (although you may find others):
1. You can find out whether or not an output message will fit in the space available, thereby avoiding a status of 253 (DATA OUTPUT CIRCULAR BUFFER OVERFLOW), and allowing your program to take remedial action (such as outputting a beep string to let the user know an output block has been lost).
2. You can find out when the buffer is empty, if that makes a difference to you in some situation (such as for performance monitoring, in which you might want to get some feel for the fraction of online time spent outputting). The output buffer is empty when btuoba() returns a value of osiz-1, where osiz is the size of the output buffer specified in the original call to btusiz() (page 135) or btulsz() (page 106).
####### RETURNS
-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
####### SUBROUTINE NAME
btuoes — enable/disable Output-Empty status codes
####### SYNOPSIS
err=btuoes(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; = 1 generate a single status 5 when the
output buffer becomes empty
= 0 don’t generate status 5’s
####### DESCRIPTION
You may wish to be notified when the data output buffer goes empty on a channel, such as with certain block-oriented protocols like XMODEM. By default, no status 5 (see page 138) is generated. This routine turns the generation of this status on or off.
####### CAUTIONS
If the output buffer on the channel is already empty when this routine is called, no status 5 is generated. The test for generation of status 5 only occurs as the channel transitions from the not-empty state to the empty state.
####### RETURNS
-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
####### SUBROUTINE NAME
btuolk — set output pausing on/off
####### SYNOPSIS
err=btuolk(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1 = pause, 0 = resume, pause off
####### DESCRIPTION
This routine pauses a channel’s output until the pause is turned off by btuolk(). You might use this in some scheme to throttle output. For example, to implement a file transfer protocol that uses XON/XOFF in binary mode, your mainline program will need to process these characters and pause or resume output.
####### RETURNS
-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
####### SUBROUTINE NAME
btupbc — set screen-pause character (pauses screen when in output stream)
####### SYNOPSIS
err=btupbc(chan,pausch);
int err; zero means OK
int chan; channel number
char pausch; pause character (0 to disable)
####### DESCRIPTION
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. The Major BBS uses ctrl+T for the pause character.
Characters received during the screen-pause mode are handled by a routine identified by btuhpk(). That routine specifies how to get out of screen-pause mode.
####### RETURNS
-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
####### SUBROUTINE NAME
btupmt — set prompt character
####### SYNOPSIS
err=btupmt(chan,pmchar);
int err; zero means OK
int chan; channel number
char pmchar; prompt character (0 to disable)
####### DESCRIPTION
This routine selects automatic prompting of the user with a single character. In this example, > is the prompt character, and the user’s keystrokes are shown in boldface:
System ready
>What time is it?
Oh, about half past eight
>Download the marketing report.
OK, the marketing report will be downloaded when you log off.
(Type "NOW" to do it now.)
>
Even when enabled, prompting is only active during the ASCII output mode (page 14) — that is, when using btuxmt() to transmit (page 166).
The prompt character is automatically sent each time a transition is made from an outputting state to an inputting state. To disable this feature (the default condition), call btupmt() with a pmchar value of 0.
####### RETURNS
-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
####### SUBROUTINE NAME
bturep — report channel statistics
####### SYNOPSIS
value=bturep(chan,statid);
long value; value of the statistic
int chan; channel number
char statid; 0 = count of characters (LAN, X.25)
1 = count of packets (LAN, X.25)
2 = count of overruns (8250)
3 = count of parity errors (8250)
4 = count of framing errors (8250)
####### DESCRIPTION
These statistical values are set to zero by bturst() (page 124), or to any value by btuset() (page 133).
LAN X.25
The output 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.
UART
The output of this function is only defined for 8250-type UART channels when statid is 2-4. This function reports a running count of overrun, framing, and parity errors in the UART of the channel.
Overrun errors in non-16550-FIFO mode can mean one or more characters lost per error. In 16550 mode (page 84), up to 16 characters or more can be lost per overrun error.
Framing errors usually mean baud-rate incompatibility or line noise. Technically they result from the lack of a high (mark) state when a stop bit was expected.
####### RETURNS
bturep() returns the current long integer value of the statistic.
####### SUBROUTINE NAME
bturst — reset a channel
####### SYNOPSIS
err=bturst(chan);
int err; 0 = OK (Xecom hardware)
1 = OK (Hayes or UART hardware)
2 = OK (X.25 hardware)
3 = OK (LAN hardware)
less than zero means error (see page 126)
int chan; channel number
####### DESCRIPTION
bturst() completely resets a channel, in both hardware and software, to its initial default conditions. This is also the recommended method for “hanging up”, since the default condition of the switch hook is on-hook (disconnected).
Note: when btudef() (page 74) is used to define a channel or group of channels, the bturst() reset operation is automatically performed on these channels.
HAYES
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:
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 . . .
btulok(chan,0); btuoes(chan,0); |
This procedure is used in the TELCONH.C example program on page 172.
This should also be done to every channel after it is defined (see btudef(), page 74). This is the rationale of each of these statements:
bturst(chan);
Reset the channel.
btulok(chan,1);
Lock out input from the channel. This inhibits trash incoming characters from inhibiting transmission of the upcoming command string.
btuoes(chan,1);
This enables status code 5 generation when the transmit buffer goes empty. This will be used to detect when the command string completes transmission to the modem.
btuech(chan,0);
This turns off the echo in the Software Breakthrough (a different echo than that of the Hayes-compatible modem). For interactive applications, you will turn your echo on again after in incoming call has been answered.
btubrt(chan,2400);
This sets the baud rate of the UART that communicates with the modem. 2400 is the default baud rate, and if that’s what you want, you can omit this statement. But if you want some other rate during communication with the modem in command mode, then set that rate here.
btuxmt(chan,"ATE0S0=1S2=1&C1&D2\r");
This command string selects various modes of the modem. AT is the standard prefix to all Hayes protocol commands.
E0 turns output echo off. Without this, the Hayes-compatible modem would echo back to us every character that we sent it, certainly not what we want.
S0=1 enables auto-answer mode, so that incoming calls are automatically answered and presented with answer-carrier. You may wish to omit this setting if you have phone lines that you don’t wish to answer.
S2=1 selects ‘\1’ (ASCII 01, ctrl+A) as the escape character. Per the Hayes modem control standard, transmitting the escape code three times (between 1 second pauses) results in switching from the online to the command mode. The default escape character is 43 (+). Since we do not want users to be able to issue the escape sequence, we make the escape character something that cannot be echoed back. Note that the default translate table (page 163) has ASCII 01’s translated to 00 (ignored).
&C1 makes the modem DCD output indicate the presence of data carrier.
&D2 makes the modem DTR input reset the modem.
\r this is the C-language notation for a carriage return.
The &C1 and &D2 commands may not be desirable or necessary on certain hardware. See your modem manual for details.
btucli(chan);
This instruction discards any trash input characters that may have been received up to this point.
. . . wait for status 5 from this channel . . .
To continue the reset procedure, we must wait for the status code 5 that indicates that the UART on this channel has completely transmitted the command sequence to the modem. In a multi-user program, remember that other channels may require servicing in this interval. You must structure your code such that all other channels will continue to be serviced, and when this status 5 does come in, the reset procedure will continue. The program on page 172 does this.
btulok(chan,0);
Remove input lockout.
btuoes(chan,0);
Turn off status code 5 generation.
####### CAUTIONS
LAN
bturst() should always be called for each LAN channel just before you call btuend(). This ensures that SPX connections are completely aborted.
####### RETURNS
-10 channel is not defined (see btudef(), page 74), or no UART has been detected at the I/O address where it was defined. If you have purchased the N-channel version of the Software Breakthrough, then you may only use channels 0 through N-1 to talk to real hardware. If you attempt to reset channel N or higher, then you will get this error return code. You may still use these channels for local emulation (page 114), however.
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
XECOM
0 means that a functional Xecom category modem has been detected on this channel
HAYES UART
1 means that functional Hayes or UART category hardware has been detected on this channel
X.25
2 means that functional X.25 driver and PC XNet hardware have been detected on this channel
LAN
3 means that a functional LAN interface has been detected on this channel
####### SUBROUTINE NAME
bturti — define routine to be called in real-time
####### SYNOPSIS
err=bturti(hertz,rtirou);
int err; zero means OK
int hertz; number of rti’s per second
int (*rtirou)(); pointer to function to be called
####### DESCRIPTION
This sets a specified routine to be called a specified number of times per second. The call takes place at interrupt level: once your program calls bturti(), no maintenance is necessary. Call timing is not affected by other activity such as disk I/O or lengthy mainline computation loops.
####### CAUTIONS
The hertz parameter may not exceed 0.12 times the maximum baud rate specified by btumxs() (page 116), or 288 if btumxs() has not been called. The time between rti’s is quantized into discrete units equal to 0.12 times the btumxs()-specified maximum baud rate. So, as the specified rti rate approaches this maximum, the variation in intervals between calls to the rtirou routine can be as much as 100%. The average rate per second will be much more accurate, however (closer than 0.1%).
See also page 43 for cautions relating to interrupt-called functions. Design of the rtirou routine is fraught with pitfalls. Don’t design lengthy complex code to run at interrupt level. Don’t invoke DOS (because it is not reentrant). You may use the special chixxx() routines (page 42), but not any other Breakthrough Library routines. Beware of data “skewing”, since a real-time interrupt may occur between any two machine-language instructions of your mainline code.
####### RETURNS
-6 too many rti calls per second (hertz is too large)
0 all is well
####### SUBROUTINE NAME
btuscn — scan for channels in need of service (with nonzero status)
####### SYNOPSIS
chan=btuscn();
int chan; channel number (0 to nchan-1)
or -1, if no channels require service
####### DESCRIPTION
Scans all defined channels, searching for one with a nonzero status. If it finds one, the number of that channel is returned. This number will be between 0 and nchan-1, where nchan is the total number of channels allocated in btusiz() page 135 or btulsz() page 106. If no channels require service, -1 is returned, indicating that the status queues of all channels are empty. When btuscn() reports that a channel requires service, subsequent calls to btuscn() resume scanning with the channel immediately following, so that all channels have the same priority. This routine will most likely be the focal point of the main program. The main loop will repeatedly call btuscn() to find out what to do next — that is, which channel needs servicing. You could do the same thing with repeated calls to btusts(), but btuscn() is far more time-efficient. Also, btuscn() gives equal priority to all channels.
LAN X.25
The btuscn() function has added purpose on LAN and X.25 channels. It scans all channels for incoming packets, and processes them. It scans all channels with output data for the opportunity to transmit packets. The standard function of btuscn() applies to all channels: to look for the next channel with a status code to report.
####### CAUTIONS
LAN X.25
On LAN and X.25 channels, you must call btuscn() regularly. If you do not, you won’t have any input or output on those channels.
####### RETURNS
-1 no channels require service: they all have a status of 0
N>=0 channel number of the next channel with a nonzero status
####### SUBROUTINE NAME
btuscr — set the soft-cr character (for output word wrap)
####### SYNOPSIS
err=btuscr(chan,softcr);
int err; zero means OK
int chan; channel number
char softcr; soft-cr, becomes space once wrapped
(0 to disable soft-cr translation)
####### DESCRIPTION
The soft carriage return (see the discussion of word wrap under btutsw(), page 153) is an output character that gets converted into a cr or cr lf sequence (cr lf if you have never called btulfd()) as long as no output word wrap has taken place yet. Otherwise, it is converted into a space (ASCII code 32). It defaults to the disabled condition (softcr=0) when a channel is initialized or reset. Soft carriage returns are processed by btuxmt() during transmission — that is, they are only active during the ASCII output mode (page 14).
Background: when output word wrap is enabled, btuxmt() keeps track of whether or not a forced wrap has occurred within the current paragraph. After it has, appearances of the soft cr character are treated exactly like spaces. Before this point, appearances of the soft cr character are treated exactly like carriage returns. See the example on page 155, where the soft carriage return is set to 10 (\n in C language).
####### RETURNS
-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
####### SUBROUTINE NAME
btusdf — super-define channel groups
####### SYNOPSIS
err=btusdf(schan,n,chtype,...);
int err; zero means OK (see below)
int schan; starting channel number
int n; number of channels
int chtype; channel interface type:
0 wildcard (auto-determine whether type 1, 2 or 3)
(this is the same as btudef())
1 Xecom 120x (as on Breakthrough Model 16 or 4)
2 Xecom 2400 (as on Breakthrough Model 2408)
3 8250-type UART/modem
4 X.25 packet switching network channels
5 Novell Netware IPX Direct circuit channels
6 Novell Netware IPX Virtual circuit channels
7 Novell Netware SPX channels
... the remaining parameters depend on the value of chtype:
| Format of call to btusdf() | Purpose |
| err=btusdf(schan,n,0,ioaddr); | same as btudef() |
| err=btusdf(schan,n,1,ioaddr); | Model 16/4 |
| err=btusdf(schan,n,2,ioaddr); | Model 2408 |
| err=btusdf(schan,n,3,ioaddr); | 8250-type UART |
| err=btusdf(schan,n,4,card,line,slcn); | X.25 network |
| err=btusdf(schan,n,5,socket,necbs); | LAN IPX Direct |
| err=btusdf(schan,n,6,socket,necbs); | LAN IPX Virtual |
| err=btusdf(schan,n,7,socket,necbs); | LAN SPX |
int ioaddr; starting port address
int card; PC XNet card number (0-7)
int line; PC XNet line (0=25-pin 1=15-pin)
int slcn Starting logical channel number
int socket; local socket number, or 0=define
int necbs; number of listen ECB’s to open
####### DESCRIPTION
You can use these symbols from BRKTHU.H for the chtype parameter:
#define SDFANY 0 /*GSBL btusdf() argument for XECOM/UART hdw */
#define SDFX25 4 /*GSBL btusdf() argument for X.25 hardware */
#define SDFIPXD 5 /*GSBL btusdf() argument for IPX Direct hdw */
#define SDFIPXV 6 /*GSBL btusdf() argument for IPX Virtual hdw*/
#define SDFSPX 7 /*GSBL btusdf() argument for SPX hardware */
Here is how the hardware categories compare with the chtype parameter for various types of hardware:
| Communications hardware | Hardware category | chtype |
| Breakthrough Model 4 | Xecom | 1 |
| Breakthrough Model 16 | Xecom | 1 |
| Breakthrough Model 2408 | Hayes | 2 |
| Hayes 2400B internal modem | Hayes | 3 |
| IBM Async adapter card | UART | 3 |
| OST PC XNet card | X.25 | 4 |
| Novell LAN, IPX Direct | LAN | 5 |
| Novell LAN, IPX Virtual | LAN | 6 |
| Novell LAN, SPX | LAN | 7 |
Calling btusdf(schan,n,0,ioaddr) is exactly the same as calling btudef(schan,ioaddr,n). The GSBL will automatically figure out the channel type among the Model 4/16, Model 2408, 8250 possibilities. See page 74.
Using btusdf() with the chtype parameter value of 1, 2 or 3 forces the GSBL to treat the channel as a Model 16/4, Model 2408, 8250 UART.
LAN
For LAN channel definition, the socket number is specified in the sensible, easy-to-use “lo-hi” order (it gets byte-swapped into “hi-lo” order before being handed off to NetWare). See page 188 for details on socket numbering.
The necbs parameter defines the number of ECB’s per channel to allocate for receiving packets. This parameter should probably be a minimum of 2. Maximum possible value for necbs is 64. Memory overhead will be about 640 bytes per ECB per channel. Setting the necbs parameter to 0 will define a non-hardware LAN channel. Every channel should have at least 2 ECBs at its disposal. You may be able to set necbs to 1 if you are defining more than one channel in a group — since all ECBs for a given socket number are shared (among all the channels that use that socket number), then theoretically every channel will have at least 2 ECBs at its disposal.
####### CAUTIONS
LAN X.25
There is no btuudf() (un-define) for LAN or X.25 channels. Defining a LAN or X.25 channel (calling btusdf() with chtype from 4 to 7) is permanent and can occur only once for a given channel over the run-time life of your program.
The only way to re-define LAN or X.25 channels is by calling btuend() to shut down the entire Software Breakthrough, and starting over again with btuitz(). And since you can only run btuitz() and btuend() once per program load, this means that LAN and X.25 channels can only be defined once for the run-time life of your program.
LAN
Defining a LAN channel group of one channel with one ECB per channel will have undefined results.
####### RETURNS
0 all is OK
-11 channel number is out of range
-12 sequence error — overlapping channel groups
X.25
-13 X.25 interface not available (only returned when chtype is 4
and you are using GSBL without the X.25 option)
LAN
-14 LAN interface not available (only returned when chtype is 6 or 7)
-15 out of memory
####### SUBROUTINE NAME
btuset — set and report channel statistics
####### SYNOPSIS
value=btuset(chan,statid,newval);
long value; value of the statistic
int chan; channel number
char statid; 0 - count of characters (LAN, X.25)
1 - count of packets (LAN, X.25)
2 - count of overruns (8250)
3 - count of parity errors (8250)
4 - count of framing errors (8250)
long newval; new value for the statistic
####### DESCRIPTION
These statistical values are set to zero by bturst() (page 124). The value returned by btuset() is the value of the statistic immediately before it gets set to the new value. A common practice is to call btuset() with newval=0L and use the result to keep a separate total.
LAN X.25
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:
long pdelta; static long ptotal=0L; long btuset(); |
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.
This function reports a running count of overrun, framing, and parity errors in the UART of the channel.
Overrun errors in non-16550-FIFO mode can mean one or more characters lost per error. In 16550 mode (page 84), up to 16 characters or more can be lost per overrun error.
Framing errors usually mean baud-rate incompatibility or line noise. Technically they result from the lack of a high (mark) state when a stop bit was expected.
####### RETURNS
The value of the statistic immediately before it gets set to the new value.
####### SUBROUTINE NAME
btusiz — size of dynamic memory needed (only if < 64K)
####### SYNOPSIS
size=btusiz(nchan,isiz,osiz);
unsigned size; total size needed, in bytes, or 65535 if too much
memory needed (meaning you should use btulsz())
int nchan; number of channels to allow for
int isiz; input data buffer size per channel
int osiz; output data buffer size per channel
####### DESCRIPTION
btusiz() calculates the total size of the memory region required by the Galacticomm Software Breakthrough Library to manage the communication channels. The address of a region this big must be passed to btuitz() (page 103) to initialize the Software Breakthrough.
If the parameters are such that more than 65535 bytes are needed, this routine returns 65535. In this case, you should use btulsz() (page 106) instead of btusiz(), because btulsz() returns a long integer (32-bit) quantity.
The input and output data buffer sizes specified must be powers of two (128, 256, 512, 1024, etc). The actual number of bytes that each buffer can hold will be 1 less than the size you specify. For example, if you specify an input data buffer size of 128, then blocks of up to 127 characters at a time (plus terminator) may be input without overflowing.
This routine specifies the total number of channels you will support, and the sizes of the input and output buffers associated with each channel.
This can be done in two ways:
1. If the language you are using supports dynamic memory allocation (this is usually called a heap or a pool), you can simply pass the return value of btusiz() or btulsz() to your allocator, specifying the number of bytes you want to allocate. This is the preferred method.
2. If you have no capability for dynamic memory allocation, and you must allocate all your data structures before your program runs, write a separate test program to call btusiz() or btulsz() with the appropriate parameters and simply print out the result. This is the number of bytes that the Software Breakthrough will need. Then create a fixed-length array of this size in the main program (the one that will be actually doing the communications). If you do this, you still must call btusiz() or btulsz() in the main program just before calling btuitz().
In either event, the address of a memory region this many bytes long must be passed to btuitz().
####### CAUTIONS
Even using method 2 above, either btusiz() or btulsz() must be called before calling btuitz(). There’s no other way to inform the Software Breakthrough of the total number of channels and their buffer sizes.
Method 1 is preferred over method 2. Under method 2, the size test procedure must be redone every time you receive an update to the Software Breakthrough, while relinking is all that is required under method 1. You should use method 2 only when you require static memory (that is, when you cannot dynamically allocate memory).
LAN
On LAN channels, input buffers and output buffers should usually be of sufficient size to accommodate full packet contents (546 bytes for IPX channels, 534 bytes for SPX channels). If either buffer is smaller than a full packet, then even SPX channels cannot necessarily be guaranteed against data loss (unless you are sure the main program won’t require it).
####### RETURNS
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
####### SUBROUTINE NAME
btusts — status of a channel
####### SYNOPSIS
status=btusts(chan);
int status; channel status code
int chan; channel number
####### DESCRIPTION
Several events can occur on your communication channels that need your attention: an incoming call can RING, a user can type in his name and press his enter key, etc. In other cases, a command that you issue (see btucmd(), page 50) can be completed. You will want to respond to these and other conditions, and that is what btusts() is all about.
This routine returns the next status code from the status buffer of the specified channel. The status buffer is a “first-in-first-out” structure, meaning that btusts() gives you the status codes in the same order in which they are generated.
Some of the status codes returned by btusts() are reporting conditions sensed by software running in the PC. Other conditions are sensed directly by the individual modem. Some status codes indicate normal, expected conditions; others indicate errors. Each status code is discussed in detail below.
Be sure to review the CAUTIONS at the end of this section on btusts() (page 147).
####### RETURNS
####### 0 = Quiet, Nothing Special To Report
If you use btuscn() to scan for channels that need service, you will never see this status code. btuscn() (page 128) identifies channels that have a status code of anything but zero, and when none do, it returns -1.
####### 1 = Xecom RING-Indicate Or Lost-Carrier (Break)
The Xecom modem module XE1201 uses the same bit to indicate both incoming ring and loss of carrier. Since incoming ring can only happen when the phone is on the hook, and loss of carrier can only happen when it is off the hook, it is simply matter of context to distinguish between the two. You can always reset the channel to be sure (bturst(), page 124).
####### 2 = Xecom Command Execution Completed OK
If the modem has not generated any status codes by the time it finishes processing a command string (see btucmd(), page 50), then this status code is generated, indicating successful completion of the command string.
####### 3 = CR-Terminated Input String Available
Indicates that a complete line of input data has been received over a channel that is in ASCII input mode (page 11). Use btuinp() (page 99) to retrieve this string.
HAYES
In command mode, Hayes category hardware can indicate several conditions by way of status 3. A subsequent call to btuinp() will retrieve a description of the condition like BUSY or NO ANSWER.
X.25
See page 203 about the RING xxx CALLING xxx status 3 message that represents an incoming call.
####### 4 = Byte-Count-Triggered Input Data Available
Indicates that the trigger count specified for this channel (see btutrg(), page 149) has been reached, and that a logical block of transparent-mode data is ready for examination via btuict() (page 96).
####### 5 = Output Buffer Empty
This status code is generated when (1) the btuoes() routine has been called to enable it (see page 119), and (2) the output data buffer makes a transition from being not empty to being empty. This might be used when your program needs to know when a block of output has been completely transmitted, before the program can proceed to some other task.
####### 6 = Output Aborted By User
This status code may be generated when the user aborts output. The btutrs() routine enables/disables status 6 generation. The user aborts ASCII output by typing the truncate character defined by btutru().
####### 11 = Hayes Lost Carrier
The carrier signal (a tone normally sounded continuously over the phone line) was interrupted, most often caused by the user hanging up.
####### 12 = Hayes/UART Command Execution Completed OK
This status code is generated when btucmd() completes execution of the soft commands (and for Hayes hardware, before execution of the hard commands). See page 54 for a discussion of hard and soft commands.
####### 13 = Hayes/UART Invalid btucmd() Command Byte
An invalid command byte was passed to btucmd() for Hayes or UART hardware. Look for 13s in the last column of figure 4-1 (page 52).
####### 21 = X.25 Incoming Clear Packet (End Of Session)
An incoming clear packet was received on this X.25 channel. This could either be from the other party on the network, indicating that he ended the session, or from the network itself, indicating there was some error with the connection. See page 87 about how to obtain the cause and diagnostic fields of a clear packet.
####### 22 = X.25 Command Or Pause Completed
A btucmd() command on this channel has completed successfully. Either a P or p pause or an A answer could generate this code.
####### 23 = X.25 Invalid btucmd() Command Byte
An invalid command byte was passed to btucmd() for this X.25 channel.
####### 24 = X.25 Incoming X.29 String
This status occurs when an X.29 string is recieved (a data packet with the “Q” bit set. You can use btuhdr() to retrieve the data (see page 87).
####### 31 = LAN SPX Connection Terminated By Other Side
The other party issued a T command (page 66) to terminate the SPX session.
Note on statuses 31 and 39: If an SPX session terminates immediately after it receives data, then your program may find out about both at the same time: after calling btuscn(), there will be new data in the buffer, and a status 31 or 39 in the status buffer. You may want to be sure all input data is processed before using a status 31 to reset your channel.
####### 32 = LAN Pause Command Completed
A pause command (P or p, see page 65) on this LAN channel has just finished the 5 or 2 second delay.
####### 33 = LAN Invalid btucmd() Command Byte
Either you issued an invalid btucmd() command code, or your outgoing call command (W...M) did not have exactly 24 hex digits, or the channel transmitter is busy right now. The latter may happen while transmitting, dialing out, listening for a connection, or terminating a connection.
####### 34 = LAN SPX Incoming Connection Established
An L command (page 63) was issued on this channel to listen for an incoming SPX call. This status indicates that the call has been received and the connection is established.
####### 35 = LAN SPX Outgoing Connection Established
A W command (page 67) was issued on this channel to establish an outgoing SPX connection. This status indicates the connection is complete.
####### 36 = LAN SPX Termination Complete By This Side
You issued a T command to terminate the SPX connection (page 66) on this channel. This status indicates that the termination of the connection is complete.
####### 37 = LAN Receiver Error
This status indicates that the listen ECB completion code was not 00h or EDh. Some kind of low-level communications or interface error has occurred. Error status 37 would show up on any channel arbitrarily in a group with the same socket number.
####### 38 = LAN Received Unknown Or Unexpected Packet
For IPX Direct channels, an unsolicited packet was received.
For IPX Virtual channels, all channels on this socket are full.
For SPX channels, a packet with an unknown connection ID was received.
Error status 38 would show up on any channel arbitrarily in a group with the same socket number. Status 38’s are likely if you define multiple channel groups on the same local socket number but don’t define them on consecutive channels (refer to page 189).
####### 39 = LAN Connection Error
For IPX channels, the outdial command could not find the network path to the destination node (in this case, the status 39 may come after a perplexing pause of several seconds, during which the system seems to be hung), or some error occurred when transmitting (e.g. network failure).
For SPX channels, the connection may have terminated due to the watchdog, or to a transmitter error (e.g. remote abort), or some error was encountered trying to establish or terminate a connection (e.g. SPX connection table full, other partner disappeared, abort connection failed).
Note on statuses 31 and 39: If an SPX session terminates immediately after it receives data, then your program may find out about both at the same time: after calling btuscn(), there will be new data in the buffer, and a status 31 or 39 in the status buffer. You may want to be sure all input data is processed before using a status 31 to reset your channel.
####### 40 = LAN GTC Input Mode: Locked Out
The terminal should accept no input. This mode is the result of btulok(chan,1) by the other party.
Note on statuses 40-44: These occur only on IPXV or SPX LAN channels when you’ve issued the G command (page 61), as for a terminal emulation application. The G command is a GTC (Galacticomm Terminal Control) Greeting. It means you volunteer to preprocess terminal input for the other party. Page 199 has more on GTC.
####### 41 = LAN GTC Input Mode: Binary
Transparent input mode — the terminal should just forward characters verbatim. This mode is the result of btutrg(chan,nonzero), or of btuchi(chan,nonnull) by the other party.
See the note under status 40 about the G command.
####### 42 = LAN GTC Input Mode: ASCII, No Echo
Buffer a string of characters, terminate with a cr, and send the whole string without echoing anything. This mode can be used to enter passwords. It is activated by btuech(chan,0) from the other party when he’s in ASCII input mode.
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 the Major BBS this would preserve some of the effects of ^O=abort and ^S=pause.
See the note under status 40 about the G command.
####### 43 = LAN GTC Input Mode: ASCII, With Echo
Same as status 42 except echo every character. After echoing the cr, also echo a lf. The line length specifies the maximum number of pre-cr characters to accept. Extra characters should be ignored by the terminal. This is the most common, plain vanilla, input mode.
Note on statuses 43 and 44: Immediately after a status 43 (or a status 44) is another single status code indicating the maximum length of the input line (when 1 to 255) or unlimited line input (when 0). This means that the routine that services a status 43 or 44 must call btusts() exactly once and treat its result differently from all other values returned by btusts().
See the note under status 40 about the G command.
####### 44 = LAN GTC Input Mode: ASCII, W/Echo And Wrap
Same as 43 except that when the line length limit is reached, and another character is typed:
Case 1 if the character is white-space (space or cr), then just terminate the line with cr and move on;
Case 2 if the character is printable and there are previous spaces on the line, then just forward the line up to and before the space (with a cr on it), erase the rest from the line on the terminal’s display, then move this rest down to a new input line and resume as if it had just been typed;
Case 3 if a complete line of non-white-space has been typed, then terminate and forward the line up to before the new character and make a new entry line with the character.
The line length status code (see above) should be used by the main program to wrap input words when the line would exceed this length. This mode is used for multi-line text entry.
See the note under status 40 about the G command.
####### 49 (ASCII 1) = Xecom DTMF 1 Sensed
This code can only happen in response to a ^A (controlled answer) command byte (see page 56). It indicates that the modem module has sensed the DTMF tones for 1 (the “1” on a touch-tone phone) while the modem was waiting for originate-carrier.
####### 63 (ASCII ?) = Xecom Invalid btucmd() Command Byte
This happens if you pass an invalid command byte to btucmd() for Xecom hardware. Look for ?’s in the next to the last column of figure 4-1 (page 52).
####### 65 (ASCII A) = Xecom Aborted Command Prematurely
Can only happen if a command is in progress, and your program calls btuclc() for that channel, which both clears the command output buffer and aborts the currently active command, if any.
####### 66 (ASCII B) = Xecom/X.25 Busy Signal Sensed
With Xecom hardware, can only happen in response to an L, M, or W command byte (pages 63 to 67), indicating that the modem module has sensed a phone busy signal.
With X.25 hardware, after a dial-out command, this status indicates that the call failed for some internal reason, like transmit window full.
####### 68 (ASCII D) = Xecom Dial Tone Sensed
Can only happen in response to an L or M command byte (see page 63). Indicates that the modem module has unexpectedly sensed dial tone on the line (if, for example, a touch-tone call were placed on a pulse-dial line).
####### 70 (ASCII F) = Xecom Failed For Other Reasons
Indicates that carrier was heard but that the originate/answer handshake failed for some reason, probably due to noise on the phone line, or an intermittent or very weak signal.
####### 73 (ASCII I) = Xecom Inappropriate Command
This status can be returned anytime you issue a command byte that is inappropriate in the current context. For example, passing an A to btucmd() when there is already a modem-to-modem connection underway is inappropriate.
This status provides a way to distinguish between 300 and 1200 baud connections on Xecom hardware. There is no other way to do this if the baud rate was automatically determined by a calling user’s carrier signal (after you issue an A or ^A command). If you issue a ^H command (page 57) after a 300 baud connection has been established, you get this status code. If you issue a ^H command after a 1200 baud connection has been established, you’ll get the OK status code 2 (assuming the ^H command is by itself in the command string).
####### 77 (ASCII M) = Modem Carrier Sensed
With Xecom hardware, can only happen in response to a W command byte (see btucmd(), page 67). Indicates the modem module has sensed answer carrier on the phone line.
With X.25 hardware, after a dial-out command, this status indicates that the call succeeded and the connection has been established.
####### 82 (ASCII R) = Xecom Ringing Sensed, But No Answer
Can only happen in response to an L, M, or W command byte (see btucmd(), page 63). Indicates that the modem module has sensed ringing on the phone line. This happens after you place a call, while you hear the telephone company’sring backsound, but before the other party picks up.
####### 84 (ASCII T) = Xecom Timeout (Silence Sensed)
Can only happen in response to a ^A, ^X, ^Y, A, L, M, O, or W command (see pages 56 to 69). Indicates the modem module timed out after 17 seconds waiting for carrier signal (W waits only 5 seconds for dial tone).
####### 86 (ASCII V) = Xecom Voice Sensed
Can only happen in response to an L, M, or W command byte (see pages 63 to 67). Indicates the modem module has sensed a rapidly varying spectrum of activity on the phone line. This can also indicate excessive line noise, or the cable may not be connected to the telephone company.
####### 118 (ASCII v) = Xecom Voice Sensed (By ^A Command)
This status code can only occur in response to a ^A command (see btucmd() and page 56). Otherwise it is identical to status code 86.
####### 250 = X.25 Transmission Error
This status indicates an internal transmission error on this X.25 channel. Some data may have been lost.
####### 251 = Data Input Circular-Buffer Overflow
More data has been received than can fit in the input buffer for this channel. Either the capacity of the input buffer was reached before the termination condition was reached (the termination condition is: cr in ASCII mode, byte count in Binary mode), or the main program has not been servicing the channel often enough — using btuinp() (for ASCII mode) or btuict() (for Binary mode). Exceeding the maxinl line length specified by btumil() will also generate status 251.
In interactive applications, this status may merely mean that the user has typed an input line that is too long, and thus the condition can be safely ignored.
####### 252 = Echo Output Circular-Buffer Overflow
An attempt was made to buffer more data for echo than the echo buffer could hold. This status can usually be safely ignored since it indicates merely that the user has not had all of his input echoed back to him. The echo buffer can hold up to 255 bytes, so this status can happen if both the input buffer size is specified larger than 128 (see btusiz() and btulsz(), pages 135 and 106), and if the user manages to type more than 255 characters during an extended period in which echoes are locked out — for example, during the transmission of a very long, continuous block of output data. The chiout() or chious() routines (page 42) of btuchi() or bturti() can also overflow the echo buffer.
####### 253 = Data Output Circular-Buffer Overflow
An attempt was made to buffer more data for transmission than the output buffer can hold. This can happen if your program tries to output more, or larger, blocks of data than it has allowed for in the output buffer size parameter osiz passed to btusiz() or btulsz() (pages 135 and 106). This status can only occur as a result of a call to btuxmt() (page 166) or btuxct() (page 161). There is usually little your program can do but ignore this status if it arises, but you should consider increasing your data output buffer size if it arises very often. See also the caution on btuxmt() block terminator characters in the output buffer (page 168).
####### 254 = Status Input Circular-Buffer Overflow
This is a serious error condition, and probably merits resetting the channel if it occurs. It indicates that status information has been lost, which means that you may have a false sense of the condition of the channel. For example, you may have missed a lost-carrier status (1 or 11). Fortunately, as the status buffer can contain up to 31 bytes, it is almost impossible for this status to crop up in peace-time conditions.
####### 255 = Command Output Circular-Buffer Overflow
This is a serious error condition, and probably merits resetting the channel (if not the entire machine) if it occurs. You can buffer up to 63 bytes of commands before getting this status, which is far more than most programs should need. The most likely cause of this status is a limited program crash of some sort: some unrelated piece of software corrupted the channel data blocks.
####### -10 = Channel Not Defined
This status can only happen once after a call to btudef(). It indicates that the channel hardware did not respond properly to a reset attempt, which means that it is either malfunctioning or absent altogether. Yet another possibility is that you have purchased an N-channel version of the Software Breakthrough, and you have attempted to define channel N or higher. In this case, all channels except 0 through N-1 will always appear to have no hardware. These channels may still be used for local emulation however (refer to page 114).
####### -11 = Channel Number Out Of Range
Indicates that the chan parameter passed to btusts() itself is outside the range of valid channel numbers, as defined in the original call to btusiz() or btulsz() (pages 135 and 106).
####### CAUTIONS
Most probably, you will not have to deal with each and every one of these status codes whenever you call btusts(). In any given situation there are only a few that you should expect. See figure 4-1 (page 52) for a summary of what commands can be expected to directly generate which status codes. Other status codes are asynchronous, of course (ringing, lost carrier, input data received, etc). Any unexpected status codes should be handled by resetting the channel (bturst(), page 124).
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.
| 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 |
####### SUBROUTINE NAME
btutrg — set input byte trigger quantity
####### SYNOPSIS
err=btutrg(chan,nbyt);
int err; zero means OK
int chan; channel number
int nbyt; input byte trigger quantity:
> 0 for Binary input mode, bytes per block
(use btuict() or btuica() for input)
= 0 for ASCII input mode
(use btuinp() for input)
####### DESCRIPTION
If nbyt is nonzero, input characters will be processed in transparent Binary mode. There is no translation through the global input-character translation table, no backspace handling, and no cr-triggered end-of-line status handling (echoing is also automatically disabled when in transparent mode). Instead, characters are simply accepted as they come in and, when the trigger count of nbyt has been reached, a status of 4 (BYTE-COUNT-TRIGGERED INPUT DATA AVAILABLE) is generated for the channel. Each group of nbyt input characters generates this same status.
If nbyt is zero, then input is in ASCII mode (the default). See page 11 for more details on Binary versus ASCII input modes.
####### CAUTIONS
This routine should only be used in special situations such as machine-to-machine communications (XMODEM, etc.), or to capture individual user keystrokes in real time (nbyt=1). For the latter, consider a custom character interceptor routine. See btuchi() on page 40.
####### RETURNS
-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
####### SUBROUTINE NAME
btutrm — set input line terminator character
####### SYNOPSIS
err=btutrm(chan,crchar);
int err; zero means OK
int chan; channel number
char crchar; input line terminator (0 to disable)
####### DESCRIPTION
The input line terminator character is the character which, when typed at an interactive user’s console, indicates that all editing of the input line is complete, and that it is time for your program to take the line as a whole and perform whatever processing it may require. The default line-terminator is a carriage return (ASCII code 13), but there may be occasions when you need to set it to something else. This routine gives you that option.
####### CAUTIONS
You will want to use this routine only in very unusual circumstances.
####### RETURNS
-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
####### SUBROUTINE NAME
btutrs — generate status 6 when output aborted by user?
####### SYNOPSIS
err=btutrs(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1=generate 0=don’t generate (bturst() defaults to 0)
####### DESCRIPTION
In ASCII output mode (page 14), any data block in the process of being transmitted to a channel is aborted if the character specified in btutru() is received from the channel. To notify your mainline program, btutrs(chan,1) will trigger a status 6 whenever the user aborts output in this manner.
See page 152 for more on output abort.
####### RETURNS
-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
####### SUBROUTINE NAME
btutru — set output-abort character (truncates current output block)
####### SYNOPSIS
err=btutru(chan,trunch);
int err; zero means OK
int chan; channel number
char trunch; truncate character (0 to disable)
####### DESCRIPTION
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 the Major BBS. On other systems, ctrl+X is preferred.
Only the block currently being transmitted is truncated, or aborted — the rest of the output buffer is left alone. This way, it is less likely that users will inadvertently abort asynchronous messages such as Sysop alerts or messages from other users, or their next prompt. Each separate call of btuxmt() (see page 166) generates a different output block which is individually clobbered by the abort character.
This feature is disabled by default, since its use is potentially harmful. Be sure to educate your users about the proper use of output block truncation if you enable it in your particular system.
####### RETURNS
-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
####### SUBROUTINE NAME
btutsw — set terminal screen width and select output word wrap
####### SYNOPSIS
err=btutsw(chan,width);
int err; zero means OK
int chan; channel number
int width; > 0 turn on output word wrap, where
width is the screen width
= 0 turn off output word wrap
(default condition)
####### DESCRIPTION
This routine turns on the output word wrap feature, specifying the screen width to which text output should conform during ASCII output (page 14). Specifying a screen width of 0 turns off 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.
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.
This is achieved by translating spaces into carriage returns in the output data string specified by btuxmt() (page 166). To prevent the user’s terminal from doing its own line wrapping, each line is actually limited to width-1 characters.
btutsw() is the primary controller of output word wrap, but it operates in concert with other Software Breakthrough routines:
| Routine | Involvement with output word wrap | Page |
| btuhcr() | specifies the hard carriage return character | 86 |
| btuscr() | specifies the soft carriage return character | 129 |
| btulfd() | specifies the linefeed character to append to every carriage return | 104 |
| btuxmt() | specifies the output string, and actually performs the output word wrap processing | 166 |
The hard and soft carriage return characters are special characters in your output data string that affect the operation of output word wrap.
Hard carriage returns are always interpreted as the end of the line. They are translated into the ASCII cr character, which is appended with lf if btulfd() has so specified. Conceptually, hard carriage returns form paragraph boundaries.
Soft carriage returns may be interpreted as a single space, or as a carriage return, depending upon where they are positioned in the paragraph. The rule is this:
When output word wrap has taken place in a paragraph, all subsequent soft carriage returns are converted into spaces.
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.
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:
btuxmt(chan,"This is one line of text.\r");
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.
The following conditions are similar to those in the Major BBS (although screen width is user-selectable):
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:
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:
The blue form of Koyama's Spruce is |
Without turning on word wrap, this hypothetical 20-column wide screen would look something like:
The blue form of the Engelmann Spruce is native to the mount ains of western Nort h America. Koyama's Spruce is n ative to central Jap an (at altitudes of 1500 to 1800 meters) and also to Korea. |
####### RETURNS
-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
####### SUBROUTINE NAME
btuudf — un-define channels
####### SYNOPSIS
err=btuudf(schan,n);
int err; zero means OK
int schan; starting channel number
int n; number of ports in this group
####### DESCRIPTION
This command undoes the effects of btudef() (page 74). This capability is provided in case you need to completely remove a channel, or group of channels, from service without affecting the operation of any other channels. In most cases this will not be necessary, but it may come in handy if you are doing something exotic. Many of the other Software Breakthrough routines will return a code of -10 on a channel that has been un-defined.
####### CAUTIONS
LAN X.25
There is no btuudf() (un-define) for LAN or X.25 channels. Defining a LAN or X.25 channel (calling btusdf() with chtype from 4 to 7) is permanent and can occur only once for a given channel over the run-time life of your program.
####### RETURNS
-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
####### SUBROUTINE NAME
btuusp — special UART polling method
####### SYNOPSIS
err=btuusp(chan,onoff);
int err; zero means OK
int chan; channel number
int onoff; 1=special method (IIR bit 0)
0=standard method (LSR bit 0)
####### DESCRIPTION
UART
This function only has an effect on 8250-type UART channels. It would most likely be used on 16550 UARTs (see btuffo() on page 84). The standard method (onoff=0) for polling UARTs is to disable interrupts and poll the Data Ready bit (bit 0) of the Line Status Register (offset 5). The special method (onoff=1) is to turn off OUT2 (MCR bit 3 is 0), enable received-data interrupts (IER bit 0 is 1), and to poll the Interrupt Pending bit (bit 0) of the Interrupt Identification Register (offset 2). No interrupts are actually received by the processor because OUT2 is turned off, which by IBM PC convention is used to gate the UART interrupt onto the bus. The special method is more reliable for some brands of UART, specially on fast computers, due to a sluggishness of the Data Ready bit to turn off after the last byte is read from the 16550’s hardware FIFO. Compared with the Data Ready bit, the Interrupt Pending bit is the reverse sense: 0=interrupt pending=data available, 1=no interrupts=input FIFO empty.
####### CAUTIONS
UART
The special method may not work on some non-standard types of UART or non-standard serial hardware (though we haven’t seen any yet).
HAYES XECOM LAN X.25
Do not use this function on non-8250 ports. Such operation is undefined.
####### RETURNS
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)
0 OK, special mode turned off
1 OK, special mode turned on
####### SUBROUTINE NAME
btux29 — transmit an X.29 string across an X.25 network
to the remote user’s PAD
####### SYNOPSIS
err=btux29(chan,nbyt,datstg);
int err; zero means OK
int chan; channel number
int nbyt; number of bytes
char *datstg; data bytes, formatted X.29 string
####### DESCRIPTION
The source-code syntax of btux29() is identical to that of btuxct(), but there are two differences in function:
btux29() transmits the message in a packet with the “Q” bit set, per X.29. btuxct() puts data into a circular buffer and transmits when the hardware says it’s ready. btux29() attempts to transmit immediately, and if the hardware refuses, btux29() returns the 0x500 hex status code, in which case you will probably want to try and transmit again later. The X.29 message programs one or more parameters in the user’s PAD. The message is coded as follows:
byte 0 message code (2=set)
byte 1 number of first parameter
byte 2 value for first parameter
byte 3 number of second parameter
byte 4 value for second parameter
byte 5 ...and so on...
It is possible to use other message codes (4=read, 6=read and set, etc.) that cause the PAD to respond back with messages that have the “Q” bit set. The GSBL does not process incoming X.29 messages. These messages will be received just like any other data from the user (the “Q” bit is ignored). If you want to receive them, use btuict() or btuica(), and be sure to select binary input mode (using btutrg()).
CCITT recommendation X.3 defines the numbering and meaning of PAD parameters. Many PAD manufacturers define their own extensions to X.3 to support specific features. Here is a sample of the parameters as used by OST’s Europad III (unless otherwise mentioned, 0=off and 1=on):
1 Escape from data transfer (for user to enter X.28 commands) (0=disabled 1=enabled for ctrl+P)
2 Echo (0=off 1=on)
3 Transmit when (0=full packet, 2=after cr, 126=after a control character)
4 Transmit when (0=full packet, n=after n/20 seconds of no data from user)
5 Enable PAD to XON/XOFF throttle user transmissions (or CTS throttle if on-standard “FWC” PAD option is set to Yes)
6 Display PAD service signals (indicating call progress)
7 Handling of Break-detect (0=off, otherwise see PAD manual)
8 Discard data output
9 Padding after cr (0=none, n=append n nul bytes)
10 Line folding (0=none, n=automatic cr after n characters on line)
11 Line speed, in bits per second:
0 = 110 bps 4 = 600 bps 10 = 50 bps 14 = 9600 bps
1 = 134 bps 5 = 75 bps 11 = 75/1200 bps 31 = 1200/75 bps
2 = 300 bps 6 = 150 bps 12 = 2400 bps 32 = 3600 bps
3 = 1200 bps 7 = 1800 bps 13 = 4800 bps 33 = 7200 bps
12 Enable PAD to respond to XON/XOFF throttling by the user
13 Linefeed insertion (0=none, 4=echo lf after echoing cr)
14 Padding after lf (0=none, n=append n nul bytes)
15 Local user editing of each transmitted line
16 Character-Delete character (0=none, or ASCII value, e.g. 8=backspace)
17 Line-Delete character (0=none, or ASCII value, e.g. 24=ctrl+X)
18 Line-Display character (0=none, or ASCII value, e.g. 18=ctrl+R)
####### RETURNS
-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-13 X.25 interface not available (only returned when you are
using GSBL without the X.25 Software Option)
0x500 (hexadecimal) transmit window full - try again later
0 channel number is good
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).
####### SUBROUTINE NAME
btuxct — transmit to channel (by byte count)
####### SYNOPSIS
err=btuxct(chan,nbyt,datstg);
int err; zero means OK
int chan; channel number
int nbyt; number of bytes to send
char *datstg; data block to be sent
####### DESCRIPTION
This routine transmits a data block to the specified channel in Binary output mode (see btuxmt(), page 166 for ASCII output mode). There are no restrictions on the length of the block, as long as there is room for it in the output data buffer. The block may contain any data, including zeros. Each byte will be transmitted when its turn comes.
The btuxct() routine does not have the output-suspended-while-inputting feature of btuxmt() (page 166). If you need to use btuxmt() but want to disable this suspension feature, then after using btuxmt() you might code:
btuxct(chan,0,"");
####### CAUTIONS
If there is not enough room in the output buffer for the block, btuxct() still returns 0 but a status of 253 (DATA OUTPUT CIRCULAR-BUFFER OVERFLOW) is queued for btusts(), and none of the data block is output. If your program needs to know right away whether the data will fit, use btuoba() (page 118) ahead of time to find out how much space is available in the transmit buffer.
####### RETURNS
-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
####### SUBROUTINE NAME
btuxlt — set input translation table
####### SYNOPSIS
btuxlt(oldchr,newchr);
char oldchr; character to be translated
char newchr; character to translate into (0 to ignore)
####### DESCRIPTION
The global input-character translation table applies to all channels in ASCII input mode (page 11) where you have not installed a custom character interceptor using btuchi() (page 40). As each character is received from the outside world, its ASCII value is used as an index into the translation table. If the resulting lookup value is zero, the character is ignored. Otherwise, the lookup value is passed on to the main program as if it had been received in place of the original (indexing) character.
By default, backspace (ASCII 8) and carriage return (ASCII 13, enter) are translated as themselves. All other control characters are ignored. All printable characters (ASCII 32 through 126) are translated as themselves. The rubout character (ASCII 127) is translated to backspace since many older terminals do not have a backspace key. Characters above ASCII 127 are translated as if below 127 (the high-order 8th bit is always translated to 0). Parity, framing, and overrun errors are ignored.
The following chart shows the 256 table values in hexadecimal. To use the chart, start with the raw input character to be translated, expressed as a hexadecimal number. Use the first hex digit to select a row of the chart, then use the second to select a column. The number found at the intersection of the row and the column is what your original raw input character will translate to.
btuxlt() lets you change the translation table one character at a time.
####### Default Translation Table
2 n d d i g i t
0 1 2 3 4 5 6 7 8 9 A B C D E F
0 00 00 00 00 00 00 00 00 08 00 00 00 00 0D 00 00
1 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
2 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
1 3 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
s 4 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
t 5 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
6 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F
d 7 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 08
i 8 00 00 00 00 00 00 00 00 08 00 00 00 00 0D 00 00
g 9 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
i A 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
t B 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
C 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
D 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
E 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F
F 70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 08
The translation table serves several purposes. Different people have different ideas as to what ASCII control characters they do or do not like. By default, only backspace (8) and carriage return (13, enter) are accepted and the translation table entries for all other characters in the range from 0 to 31 are zero. If you like BEL (ASCII 7), you could write:
btuxlt(7,7);
This changes the translation table to permit the bell character (ctrl+G), when typed at a user’s keyboard, to be passed through to your main program normally just like any ordinary printable ASCII character.
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:
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:
1. Reject them: use btuxlt() to set all index values in the range 128-255 to zero, thereby causing erroneous input to be completely ignored.
2. Blot them out: use btuxlt() to translate all bytes in the range 128-255 to some nonzero “error” character, such as bel (7), or X (88).
3. Tag them: use btuxlt() to cause values in the range 128-255 to be passed through unchanged. In this way, you defer the decision as to what to do about them to your main program. If it wants to accept or reject them in a context or user-dependent way, it may do so.
4. Accept them: the translation table defaults to this arrangement, whereby values in the range 128-255 effectively have 128 subtracted from them (in other words, their high bit is cleared). Accepting these characters means ignoring the error — this is the default because many interactive applications do not want to insist that the caller have the right parity.
####### CAUTIONS
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.
####### SUBROUTINE NAME
btuxmn — transmit ASCII string that btuclo() will not be able to clear. (btubsz() will clear, however.)
####### SYNOPSIS
err=btuxmn(chan,outstg);
int err; zero means OK
int chan; channel number
char *outstg; string to send (nul-terminated)
####### DESCRIPTION
This transmits a character string to a channel in the ASCII output mode (page 14). There must be room for the string in the output buffer. The string may contain any number of line terminators (see below).
btuxmn() is almost identical to btuxmt() (page 166), but btuxmn() puts strings in the output buffer that btuclo() cannot clear. btuxmn() can transmit a message to a user that he won’t be able to skip or abort.
####### CAUTIONS
If there is not enough room in the output buffer for the string, btuxmn() returns 0, but a status 253 (DATA OUTPUT CIRCULAR-BUFFER OVERFLOW) is queued for btusts() and the data string will not be output. If your program needs to know right away whether data will fit, use btuoba() (page 118) to find out first how much space is in the output data buffer. Like btuxmt(), each call to btuxmn() puts a new block into the output buffer, terminated by a hex 01 byte (ctrl+A), versus btuxmt()’s hex 00. btuxmn() temporarily writes a \x01 byte over the terminating \x00 nul, then restores the nul, so the outstg location must be writable.
####### RETURNS
-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
####### SUBROUTINE NAME
btuxmt — transmit to channel (ASCIIZ string)
####### SYNOPSIS
err=btuxmt(chan,outstg);
int err; zero means OK
int chan; channel number
char *outstg; string to send (nul-terminated)
####### DESCRIPTION
This transmits a character string to a channel in ASCII output mode (page 14). There must be room for the string in the output buffer. The string may contain any number of line terminators (see below). btuxmt() is the primary way to transmit data to a user during an interactive session.
If the user is typing an input line when btuxmt() is called, output is postponed until he clears the line by pressing enter or by backspacing to the beginning of the line. Once output begins, anything the user types while output is still in progress is not echoed until output of the current block completes. This asynchronous input and output makes for a very readable user display, especially during teleconferencing and the like. If this feature is undesirable, use btuxct() (page 161). The following routines control operation of btuxmt() by selecting various ASCII output modes:
btutsw() Output word wrap
btuhcr() Hard carriage-returns
btuscr() Soft carriage-returns
btulfd() Linefeeds appended to carriage returns
btutru() Output abort character
btuxnf() XON/XOFF handshaking
btupmt() Prompt characters
You will probably want to terminate each line in your data string with ASCII cr (\r in C notation), the hard carriage return. For transmitting a paragraph of text, you may want to use the soft carriage return, ASCII lf (\n, see page 153). For prompting, you might have no terminator character at the end of your data string.
If your users have ANSI graphics capabilities, you may transmit these escape sequences to them using btuxmt() (use no spaces):
esc [<row>;<column>H Move cursor to <row>,<column>
esc [<row>;<column>f Move cursor to <row>,<column>
esc [<nrows>A Move up <nrows> rows
esc [<nrows>B Move down <nrows> rows
esc [<ncols>C Move forward <ncols> columns
esc [<ncols>D Move backward <ncols> columns
esc [s Save cursor position
esc [u Restore cursor position
esc [2J Erase display
esc [K Erase to end of current line
####### Display Attributes
Note: m directives may be combined. For example, to select blinking black on blue, you could code: btuxmt(chan,"\x1B[5;30;44m");
esc [0m Normal
esc [1m Bold
esc [4m Underscore
esc [5m Blink
esc [7m Reverse
esc [8m Invisible
####### Foreground Color Background Color
esc [30m Black esc [40m Black
esc [31m Red esc [41m Red
esc [32m Green esc [42m Green
esc [33m Yellow esc [43m Yellow
esc [34m Blue esc [44m Blue
esc [35m Magenta esc [45m Magenta
esc [36m Cyan esc [46m Cyan
esc [37m White esc [47m White
The following special IF-ANSI construct interacts with the [ and ] commands of btucmd():
esc [[<for-ANSI-users>¦<for-non-ANSI-users>]
Only one of these strings will be transmitted, depending on which of the [ or ] btucmd() commands was last issued for the channel (see page 71). There is more to these commands: the ] command disables ANSI graphics and, if in effect, btuxmt() will not transmit any of the above directives.
The tilde (~) character is used as an escape character by btuxmt(). The following character pairs may be used to avoid conflicts with the IF-ANSI construct:
~¦ represents a single ¦ (vertical bar)
~] represents a single ] (closed bracket)
~~ represents a single ~ (tilde)
####### CAUTIONS
If there is not enough room in the output buffer for the string, btuxmt() returns 0, but a status 253 (DATA OUTPUT CIRCULAR-BUFFER OVERFLOW) is queued for btusts() and the data string will not be output. If your program needs to know right away whether data will fit, use btuoba() (page 118) to find out first how much space is in the output data buffer.
Each call to btuxmt() puts a new block into the data output buffer. A block is the sequence of characters pointed to by the datstg parameter, and is terminated by a 0-byte. btuxmt() stores the 0-byte in the output buffer to determine block boundaries. This may become critical with regard to output buffer capacity if you are doing numerous small transmissions with btuxmt(). The alternative is to use btuxct() (page 161), which does not put termination characters in the output buffer.
There is a razor’s edge situation in which the priority of transmission over command execution must be considered:
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.
####### RETURNS
-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
####### SUBROUTINE NAME
btuxnf — set xon/xoff characters, select page mode
####### SYNOPSIS
err=btuxnf(chan,xon,xoff); (for non-page mode)
-or-
err=btuxnf(chan,xon,-xoff,cnt,stg); (for non-page mode)
int err; zero means OK
int chan; channel number
int xon; character taken as xon, or “resume”
(0 to take anything)
int xoff; character taken as xoff, or “suspend”
(0 to disable, negative for page mode)
int cnt; number of lines on screen (page mode only)
char *stg; page-break pause message (page mode only)
####### DESCRIPTION
This feature is only in effect during the ASCII output mode (page 14). A user can suspend text output to his terminal by sending the xoff character that you specify here. The xon character will cause output to resume. Make the xon parameter 0 if you want any character to resume output. Make the xoff parameter 0 to disable xon/xoff altogether.
The page mode feature of ASCII output mode automatically pauses output between each screen of text. This gives the user a chance to review one screen before typing a key to move on to the next screen. The user resumes output the same way as after an xoff pause: he types the xon character (if the xon parameter is nonzero), or he types any character (if xon is 0).
To select page mode, simply substitute for the xoff parameter its negative value (for example -19 instead of 19). In this case, you must also pass the cnt and stg parameters to btuxnf() (see the second line of the synopsis above). cnt is the total number of lines on the user’s screen. stg is a pointer to the message to display between each screen (a 0-terminated character string).
The default values after initialization or reset operate just as if the following call had been made:
btuxnf(chan,0,19); |
This means:
chan For this channel number,
xon = 0 any character resumes after a pause
xoff = 19 ctrl+S pauses, page mode is not selected.
Here is an example of how you would enable page mode:
btuxnf(chan,0,-19,24,"Strike any key to continue..."); |
This means:
chan For this channel number,
xon = 0 Any character resumes after a pause
xoff = -19 ctrl+S pauses, page mode is selected
cnt = 24 The user’s screen has 24 lines
stg points to: "Strike any key to continue..." is shown at the end of each block of 22 lines
####### CAUTIONS
The Software Breakthrough cannot count wrap-arounds and line-breaks enforced by the user’s terminal, so be sure that the width of the user’s screen has been properly set by btutsw() (page 153).
####### RETURNS
-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