Versions Compared

Key

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

Library Routines

Applies to: v10

const CHAR * vs CHAR * hazard. The examples in this chapter pass literals to btuxmt() and similar routines. In v10 that crashes at run time. See chapter 29, section 29.4 ("HAZARD: const char * string literals versus char * parameters").

...

The prototypes for these routines, plus many of the constants and symbols you can use in programming with the GSBL, are in the header file BRKTHU.H.

btubrt

####### SUBROUTINE NAME

btubrt — set channel’s baud rate

...

-3 baud rate is not valid for the hardware being used
0 baud rate has been set correctly

btubse

####### SUBROUTINE NAME

btubse — set backspace-echo character

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btubsz

####### SUBROUTINE NAME

btubsz — respecify input and output buffer sizes

...

Typical application: YMODEM uploads. This protocol requires an unusually large input buffer. Since YMODEM data packets are 1024 bytes long plus overhead, you will require an isiz parameter of 2048, which allows 2047 bytes in the input buffer. Let’s say a much smaller value had been supplied for isiz in your initial call to btusiz():

Code Block
        btusiz(NCHAN,256,2048);

parameter isiz = 256
parameter osiz = 2048

These are reasonable values for a multiuser online service such as Worldgroupthe Major BBS. Particularly in terminal mode, the heaviest traffic on an online service is usually in the direction toward the users. Output traffic may include an entire screenful of text: 80 X 24 = 1920 characters plus overhead. Input traffic, coming from each user’s keyboard, is relatively light, requiring an input buffer big enough to hold an 80-character line of text. C/S mode reduces this disparity to a great extent, but output still generally outnumbers input.

Now when a YMODEM upload is required, you can swap the capacities of the data I/O buffers for channel chan. Here’s a subsequent call to btubsz():

Code Block
        btubsz(chan,2048,256);

parameter isiz = 2048
parameter osiz = 256

Then after YMODEM upload has completed, you return the buffers to their original condition:

Code Block
        btubsz(chan,256,2048);

parameter isiz = 256
parameter osiz = 2048

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-5 buffer sizes are invalid: either one of them is not an
integral power of two (128, 256, etc.), or their sum
exceeds the total data buffering capacity of the channel,
as set by the original call to btusiz() (see page 135)
0 all is well

btuche

####### SUBROUTINE NAME

btuche — enable calling of btuchi() when echo buffer becomes empty

...

Normally, the routine specified in btuchi() (see page 40) is only invoked when an input character is received, and your program has no way of telling when the channel’s echo buffer is empty. This function allows you to turn on or off a feature whereby each time the channel’s echo buffer becomes empty, the btuchi() rouadr function is invoked with the channel number and pseudo-key-code of -1 as parameters. For example:

Code Block
:
btuchi(3,&idle);
btuche(3,1);
:
idle(chan,c)
int chan,c;
{
     if (c == -1) {
          chiout(chan,'~');
     }
     else {
          chiout(chan,c);
          return(0);
     }
}

In this example, '~' is constantly output on channel 3 when no input is being received. When an input character is received, it echoes normally, then the '~' output continues. Note that this process will not begin until the first character is received.

...

This function exists mainly to support certain advanced real-time protocols available for Worldgroupthe Major BBS. Be sure that you fully understand the btuchi() function before attempting to use btuche().

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuchi

####### SUBROUTINE NAME

btuchi — set input character interceptor

...

Here is an example character handler that strips the high-order bit 7 off of each byte received:

Code Block
char strip7(chan,c)
int chan;
char c;
{
     return(c&127);
}

Then the following call to btuchi() installs this routine on channel chan:

Code Block
btuchi(chan,strip7);

The following routine de-installs it (restores default character handling) on channel chan:

Code Block
btuchi(chan,NULL);

####### ADVANCED USAGE

Four routines in the Galacticomm Software Breakthrough Library are provided only for use by your input character interceptor (btuchi()) or real-time interrupt (bturti(), page 127) routines. These are

...

Yet a third example would be inter-channel-chat. Let’s say you make the following character interceptor routine:

Code Block
uchat(chan,c)
int chan;
char c;
{
     chiout(chana,c);
     chiout(chanb,c);
     return(0);
}

Then you could install this routine as the input character interceptor for both channels A and B:

Code Block
btuchi(chana,&uchat);
btuchi(chanb,&uchat);

Now whatever character is typed by either the user on channel A or the user on channel B is immediately echoed to the screens of both users.

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuclc

####### SUBROUTINE NAME

btuclc — clear command output buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btucli

####### SUBROUTINE NAME

btucli — clear data input buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuclo

####### SUBROUTINE NAME

btuclo — clear data output buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btucls

####### SUBROUTINE NAME

btucls — clear status input buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btucmd

####### SUBROUTINE NAME

btucmd — command channel

...

However, if you use the following approach:

Code Block
btucmd(chan,"A");
btucmd(chan,"p");

then the answer will precede the pause. See also page 168 for a description of the priority that transmitting takes over command execution.

...

Command codes T and R are ignored on X.25 channels. All other codes will produce a status 23 (page 139), and the remainder of the command string will not be processed.

^A (ctrl+A)

####### ANSWER-CARRIER WITH DETECTIONS (TT,VOICE)

...

This command puts “answer carrier” on the line, and will generate a status of 2 if “originate carrier” is heard within 17 seconds. It acts just like the regular A command, but adds extra monitoring capability — the answer sequence may be aborted by the caller in two ways. If the caller presses the DTMF “1” key, a status code of 49 (ASCII “1”) is generated. If the caller speaks, a status code of 118 (ASCII “v”) is generated. In either case the answer carrier tone is terminated.

^E (ctrl+E)

####### SET CHARACTER LENGTH TO 8 BITS

This mode can be used for binary data protocols such as XMODEM, etc. This command works on all hardware categories.

^F (ctrl+F)

####### SET SPEED TO 2400 BPS

...

Sets the UART to 2400 baud. For Hayes category hardware, this command (or a call to btubrt()) must be issued after an answer command (command A, page 60) results in a CONNECT 2400 message.

^H (ctrl+H)

####### SET SPEED TO 1200 BPS

...

For outgoing calls, sets the preferred speed of the modem to 1200 bits per second. For incoming calls, results in a status I (for Inappropriate) when a 300 baud connection is already established.

^M (ctrl+M)

####### CONTINUOUS MONITOR, RETURN LINE FREQ

...

This function can only be terminated by a call to either bturst() (which resets the channel) or btuclc() (which clears the command buffer and aborts any command currently underway).

^N (ctrl+N)

####### ONE STOP BIT

UART

Sets the UART in this channel to use 1 stop bit. This mode is the default condition after bturst().

^S (ctrl+S)

####### SET CHARACTER LENGTH TO 7 BITS

This mode is the default upon channel reset. This command works on all hardware categories.

^T (ctrl+T)

####### SET SPEED TO 300 BPS

...

For outgoing calls, sets the “preferred speed” of the modem to 300 bits per second. For incoming calls, will result in a status code of I (Inappropriate) when a 1200 baud connection is already established. This is the default upon channel initialization or reset.

^W (ctrl+W)

####### TWO STOP BITS

UART

Sets the UART in this channel to use 2 stop bits.

^X (ctrl+X)

####### ANALOG LOOPBACK IN ORIGINATE MODE

...

This command initiates a local loopback in the originate band. The filters for transmit and receive are set for the originate frequencies and are looped to each other. Transmitted data is routed through the full analog-digital path before being received back at the receiver port. May be used at any “preferred speed” to test all possible encode/decode components in a modem module. Once put in this mode, the channel must be reset (see bturst(), page 124) to get out of it.

^Y (ctrl+Y)

####### ANALOG LOOPBACK IN ANSWER MODE

...

This command initiates a local loopback in the answer band. The filters for transmit and receive are set for the answer frequencies and are looped to each other. Transmitted data is routed through the full analog-digital path before being received back at the receiver port. May be used at any “preferred speed” to test all possible encode/decode components in a modem module. Once put in this mode, the channel must be reset (see bturst(), page 124) to get out of it.

0 to 9

####### DIAL 0 to 9 (ROTARY PULSE OR TOUCH TONE)

...

The corresponding digit will be rotary dialed or touch-tone dialed depending on the current mode (previous R or T command). On Hayes category hardware, these codes must only be used after the W command (page 67).

*, #, a, b, c, d

####### DIAL SPECIAL TOUCH-TONES

...

Any of these codes will generate a status of I (Inappropriate) if the current mode is rotary dial.

>

####### SET PARITY TO “EVEN”

Sets up to generate an even parity bit on every byte transmitted, and demand even parity on every byte received. If an odd parity byte is received, the results are controlled by btuerp() (the error pass-through routine, page 94), and by your input translation table, if in ASCII mode (btuxlt() controls the translation table, see page 163). Even parity is the default condition upon channel initialization or reset. This command works on all hardware categories.

<

####### SET PARITY TO “ODD”

Sets up to generate an odd parity bit on every byte transmitted, and demand odd parity on every byte received. If an even parity byte is received, the results are controlled by btuerp() (the error pass-through routine, page 82), and by your input translation table, if in ASCII mode (btuxlt() controls the translation table, see page 163). This command works on all hardware categories.

=

####### SET PARITY TO “NONE” (NO PARITY BIT)

Disables generation and checking of parity bits. This command works on all hardware categories.

A

####### ANSWER-CARRIER WITH NO FRILLS

...

See page 30 for details on the limitations of this method.

D

####### DTMF RECEIVE MODE (ACCEPT TOUCH TONE INPUT)

...

When placed in this mode, a modem will recognize incoming DTMF tone pairs as data input. The ASCII representations of 0-9, a-d, *, and # will be buffered as input data characters when they are detected. Note that DTMF information can be transmitted by issuing the normal digit dial commands. This mode is cancelled by a H, M, O, or A command.

G

####### GTC GREETING (LAN)

...

For example, GTC can be used in a terminal emulation program talking to a Worldgroup Major BBS server. The G command is executed in the terminal program once connection is established and says in effect: “Offer to preprocess the input of the server”. This includes buffering an input line with or without echo, input word wrap, etc. Executing the G command paves the way for status codes 40 - 44 to appear for the terminal program to handle (informing it of changing server input modes). For the Worldgroup Major BBS server program all aspects of this exchange are handled by the GSBL and need no special handling by the server’s C program. The key point to remember here is that you only have to consider handling GTC if you execute the G command.

See page 199 for more on the GTC protocol.

H

####### HOLD (DISCONNECT MODEM, BUT REMAIN OFF-HOOK)

...

Performs a “logical disconnect” of the modem from the phone line, but does not terminate the physical connection (i.e. the phone remains off-hook). This command can be used to quiet the line for voice or other use during a connection.

I

####### IDENTIFY MODEM VERSION

...

Causes a single ASCII letter representing the version of the modem module to be generated as an input data character. Version codes are assigned consecutively, starting with A (65 decimal). Version number changes correspond to “significant unity upgrades”, whereas revision numbers (see i immediately following) represent incremental enhancements.

i

####### IDENTIFY REVISION NUMBER

...

Causes a single ASCII digit representing the revision code of the modem module to be generated as an input data character. This will usually be of no concern to you, since only “version numbers” (see I immediately above) correspond to “significant unity upgrades”.

L

####### LINE ANALYZE

XECOM

This command acts the same as the M command but generates three special data input bytes if successful. The first byte represents the carrier frequency error, the second the S/N ratio, and the third the received carrier level. The calculations necessary for meaningful interpretation of this information are covered in Xecom data sheets.

L

####### LISTEN FOR SPX CONNECTION (LAN)

...

The listen command should only be issued on SPX channels that are in the idle state (see page 191). The L command will have no effect on an IPX channel.

l (lowercase+L)

####### RETURN 1200-BPS ERROR STATISTICS

...

This command may be used during a 1200 bps connection to check the phase demodulation statistics. An I (Inappropriate) status is generated if no 1200 bps connection exists. Otherwise two data bytes are queued: the first gives the average phase error of the signal, and the second gives the number of phase hits since the last request. The calculations necessary for extracting meaningful information from these values are covered in Xecom data sheets.

M

####### MONITOR LINE AND ORIGINATE WITH DETECTIONS

...

See page 67 for using the M command on LAN channels.

O

####### ORIGINATE-CARRIER WITH NO FRILLS

...

This command will generate a status of 2 if answer carrier is heard within 17 seconds. Otherwise a status code is generated indicating: T (Timeout), or I (Inappropriate). This command is primarily useful when the physical connection is already established, and your program decides to begin using it for data communications. When making a new connection, use the M command (page 64).

P

####### PAUSE 5 SECONDS

The “long pause”. Works on all hardware categories.

p

####### PAUSE 2 SECONDS

The “short pause”. Works on all hardware categories.

R

####### ROTARY (PULSE) DIAL SUBSEQUENT DIGITS

...

Use this command to dial on a phone line which does not support touch-tone dialing.

T

####### TOUCH-TONE DIAL SUBSEQUENT DIGITS

...

This is the default, upon initialization or reset.

T

####### TERMINATE SPX CALL (LAN)

...

The terminate command should only be issued on SPX channels that are in the connected state (see page 191). At any other time, the terminate command will have no effect. The T command will have no effect on an IPX channel.

t

####### WAIT 1/10 OF A SECOND

...

Generates a status 12 after 0.1 seconds. Works only on 8250-type UARTs and modems or Model 2408 cards.

V

####### DISABLE AUTOMATIC PAD ECHO PROGRAMMING (X.25)

...

Normally, turning echo on and off with btuech(), or switching between binary and ASCII input modes with btutrg() would automatically cause programming of parameter 2 of the remote PAD. This command disables that feature until the next bturst().

W

####### WAIT FOR DIAL TONE (TO PLACE AN OUTGOING CALL)

...

This command will generate a status of 2 if a dial tone is sensed within 5 seconds. Otherwise a status code is generated indicating: B (Busy), M (Modem Carrier Sensed), I (Inappropriate), R (Ringing), T (Timeout), or V (Voice).

LAN Dial-out Command

...

W, digit, and M

...

LAN

This command is used to make an outgoing call on the network and establish connection with another address on the network. For SPX channels, a dial-out command means to establish a connection with a remote network/node/socket. You can have multiple SPX connections between the same pair of network/node/sockets. For IPX, a dial-out command specifies who we will talk to and who we will listen to. After an IPX dial-out command on a particular channel, all transmissions on the channel will go to the specified network address, and all packets received from that address (and directed to the same local socket number) will be routed to the input buffer of the channel.

...

If you use a dial-out command to specify a network that is not connected, then the GSBL may appear to hang for several seconds, and then issue a status 39 (page 141).

...

Unique Network Addresses for IPX Dial-outs

...

Among channels with the same local socket number, the network/node/socket of an IPX dial-out command should be unique. That is, once you specify a certain network/node/socket for the dial-out command on one channel, you should not specify the same network/node/socket for the dial-out command on any other channel that shares the same local socket.

For example, this is not a good idea because it uses the same local socket number, the same destination network/node/socket, twice:

Code Block
btusdf(0,2,6,0x4007,2);
btucmd(0,"W000000010000C0A61018M");
btucmd(1,"W000000010000C0A61018M");

This is OK, however, because it uses different destination addresses:

Code Block
btusdf(0,2,6,0x4007,2);
btucmd(0,"W000000010000C0A61018M");
btucmd(1,"W000000010000C0CE0018M");

This is also OK because it uses different local socket numbers:

Code Block
btusdf(0,1,6,0x4007,2);
btusdf(0,1,6,0x4008,2);
btucmd(0,"W000000010000C0A61018M");
btucmd(1,"W000000010000C0A61018M");

The result of IPX dial-outs from two channels with the same local socket calling the same network address is that received packets may wind up in the input buffer of either channel, arbitrarily. Transmitted packets have no such ambiguity (although the other party may not be able to distinguish the originating channel).

...

Special Syntax of the Dial-out Command

...

An outgoing call may be specified by multiple btucmd() calls, as long as there are no other intervening calls to breakthrough routines. For example:

Code Block
btucmd(chan,"W");
btucmd(chan,"00000001");
btucmd(chan,"0000C0A81018");
btucmd(chan,"4007");
btucmd(chan,"M");

will have the same results as:

Code Block
btucmd(chan,"W000004010000C0A810184007M");
X.25 Dial-out Command:

...

W, digits, slash, hex digits, and M

...

X.25

To place an outgoing call on an X.25 channel, issue any of the following command string formats using btucmd():

...

Note that an outgoing call may be specified in segments as long as there are no intervening calls to other GSBL routines. For example:

Code Block
btucmd(chan,"W1234,");
btucmd(chan,"6789M");

will have the same results as:

Code Block
btucmd(chan,"W1234,6789M");

The user data field of an outgoing call request packet is normally empty. To put data into the user data field, code it in hexadecimal after the / (slash) command. For example:

Code Block
btucmd(chan,"W1234,6789/41423031M");

That example will put the 4-byte ASCII string AB01 into the user data field. This data need not be ASCII. To code three zero bytes and a byte with value 01 hex:

Code Block
btucmd(chan,"W1234,6789/00000001M");

Important note: The outgoing call, if completed, may not actually be made over the same channel that you specify in btucmd(). The PC XNet card driver will decide the actual virtual circuit to use for the call.

...

To terminate a call, bturst() disconnects the virtual circuit. When a call gets terminated, either by the network or by the remote user, status code 21 is generated on the channel.

[

####### ENABLE ANSI GRAPHICS (default)

...

ANSI graphics are automatically enabled by bturst(). See page 166 for more information on ANSI graphics directives.

]

####### DISABLE ANSI GRAPHICS

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btucpc

####### SUBROUTINE NAME

btucpc — sets the clear pause-counter character
(puts off screen pauses when in output stream)

...

When the cpchar character is discovered in the output stream (btuxmt() page 166 or btuxmn()page 165), the internal line counter is reset to 0. This line counter is used to determine when to display the pause message set by btuhpk() (page 91). The character itself is never actually output. Use cpchar=0 to disable this feature.

In Worldgroupthe Major BBS, this function is used to prevent screen pauses by inserting the ctrl+S character at strategic points in certain text blocks.

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btudef

####### SUBROUTINE NAME

btudef — define channels

...

When you called btusiz() or btulsz(), you specified the total number of channels in the first parameter nchan. btuitz() initialized the data structures for that many channels, numbered 0 to nchan-1. Now you will use btudef() to associate those channels with actual hardware. The following example in C illustrates a typical initialization sequence for one each of the Galacticomm Breakthrough Models 16, 4, and 2408 and a Hayes-compatible modem on COM1:

Code Block
btuitz(malloc(btulsz(40,128,1024)));
btudef(0,0x2F0,16);      /* Define Model   16 at 2F0 (hex) */
btudef(16,0x2F2,4);      /* Define Model    4 at 2F2 (hex) */
btudef(20,0x2F4,8);      /* Define Model 2408 at 2F4 (hex) */
btudef(28,0x2F8,1);      /* Define 1 Hayes modem           */
                         /* on a COM2 port at 2F8 (hex)    */
btudef(29,0x3F8,8);      /* Define 8 Hayes modems in a     */
                         /* GalactiBox, each at the COM1   */
                         /* port address of 3F8 (hex)      */

For Galacticomm Breakthrough cards, the sport parameter identifies the I/O base address for the card, as set on the card’s DIP switches. Refer to the Installation Manual for your particular model.

...

0 the specified channels were defined successfully

btueba

####### SUBROUTINE NAME

btueba — echo buffer space available, in bytes

...

0 echo buffer is full
1-254 echo buffer is between full and empty
255 echo buffer is empty

btuech

####### SUBROUTINE NAME

btuech — set echo on/off

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuend

####### SUBROUTINE NAME

btuend — shut down the Software Breakthrough

...

btuend() does not hang up your phone lines. You should call bturst() for every channel you have defined before calling btuend(). If you do not, your phone lines may remain off-hook with the carrier signal on, appearing to any users online at the time that your system has “locked up”. Better to let them think that you are rude than that your system is malfunctioning.

####### RETURNS

Nothing.

btuerp

####### SUBROUTINE NAME

btuerp — pass/block input bytes with errors

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuffo

####### SUBROUTINE NAME

btuffo — enable receiver FIFO on 16550 UART

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
-18 channel has an 8250 or 16450 UART on it
0 either the channel does not have an 8250-type UART on it, or it
has a 16550 type UART on it, and the FIFO mode has been set

btuhcr

####### SUBROUTINE NAME

btuhcr — set the hard-cr character (for output word wrap)

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuhdr

####### SUBROUTINE NAME

btuhdr — capture information on X.25 or LAN channel

...

The contents of this ECB can be found in the ecbgsbl structure in IPX.H:

Code Block
struct ecbgsbl {        /* Event Control Block (for use with GSBL btuhdr()) */
     void *link;
     void (*esr)();                                /* event service routine */
     char inuse;                    /* 0=not in use FE=listening FF=sending */
     char complt;            /* 0=good, nonzero=command-specific error code */
     int socket;                                  /* sending socket (hi-lo) */
     char ipxwsp[4];                                       /* IPX workspace */
     char drvwsp[12];                                   /* driver workspace */
     char immnod[6];                              /* immediate node address */
     int frgcnt;                                  /* fragment count (lo-hi) */
     void *frgadr;                             /* address of first fragment */
     int frgsiz;                          /* size of first fragment (lo-hi) */
     int prtseg;            /* protected mode segment (GSBL-specific usage) */
     int chanx2;                /* channel number * 2 (GSBL-specific usage) */
};

####### Local Network/Node Address

...

Here is the full 52-byte structure for the data captured by btuhdr() on an X.25 channel:

Code Block
struct x25hdr {        /* X.25 info from btuhdr()        */
     char cause;       /* clear packet cause             */
     char diag;        /* clear packet diagnostic        */
     char x29num;      /* number of parameters in x3list */
     char x29flg;      /* flags, see below               */
     struct x3list {   /* array of up to 24 X.3 pairs:   */
          char par;    /*      parameter number          */
          char val;    /*      value                     */
     } x3list[24];
};
                       /* Masks for x29flg flag bits:    */
#define X3SET  0x02    /* request to set X.3 values      */
#define X3READ 0x04    /* request to read X.3 values     */
#define X3NEW  0x80    /* new X.3 message has been rec'd */
#define X3OVF  0x40    /* more than 24 parameters rec'd  */

Each incoming clear packet generates a status 21 (page 139), and comes with a cause and a diagnostic field. As you can see above, you can obtain these values with btuhdr().

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuhit

####### SUBROUTINE NAME

btuhit — hook into a COM port interrupt
and use it to invoke channel servicing

...

The most common practical values for irqno will be 3 and/or 4. You can call btuhit() on as many of the IRQ numbers 2-7 as you wish, but only once per IRQ number:

Code Block
btuhit(3);
btuhit(4);

Normally you would use this feature in a multitasking environment such as Windows or OS/2.

...

-20 irqno is neither 2, 3, 4, 5, 6, nor 7,
or btuitm() was not used to initialize (see page 102)
0 all is well

btuhpk

####### SUBROUTINE NAME

btuhpk Handle keystrokes during screen-pause mode

...

3. To handle an “abort” key, you must inform your mainline program. For example, inject a status 7 (this is what happens in Worldgroupthe Major BBS) and have the mainline program handle the status by clearing output using btuclo(), and changing states (to stop stuffing the output buffer).

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuhwh

####### SUBROUTINE NAME

btuhwh — enable hardware handshaking using RTS/CTS

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuibw

####### SUBROUTINE NAME

btuibw — Input Bytes Waiting: report the number of bytes received
and waiting in the input buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK,
but that channel’s input buffer is empty
N>0 this is the number of bytes waiting in the channel’s input buffer

btuica

####### SUBROUTINE NAME

btuica — input from a channel: reading in whatever bytes
are available, up to a limit

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK,
but that channel’s input buffer is empty
N>0 this is the number of bytes actually moved
from the channel’s input buffer to inbuff

btuict

####### SUBROUTINE NAME

btuict — input from a channel: by the byte count prearranged
with btutrg()

...

the input block (the length of which you have already specified by calling btutrg()). This string is not 0-terminated (as is the output of btuinp()).

btuinj

####### SUBROUTINE NAME

btuinj — “inject” a status code into a channel

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuinp

####### SUBROUTINE NAME

btuinp — input from channel (ASCIIZ string)

...

The input line entered by this user on this channel (not including the line terminator, but terminated instead by a 0-byte), is stored in the character array pointed to by the parameter inbuff.

btuirp

####### SUBROUTINE NAME

btuirp — define alternate GSBL timing source using COM1/2/3/4

...

-17 comno is not 0/1/2/3/4, or COM port specified is not available
0 all is well

btuitm

####### SUBROUTINE NAME

btuitm — initialize the Software Breakthrough for use
in a multitasking environment

...

0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed

btuitz

####### SUBROUTINE NAME

btuitz — initialize the Software Breakthrough

...

0 all is well
-16 region pointer parameter is NULL (all zeros)
-15 memory allocation error
-19 protected mode memory tiling failed

btulfd

####### SUBROUTINE NAME

btulfd — set linefeed character (what follows every carriage return)

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btulok

####### SUBROUTINE NAME

btulok — set input lockout on/off

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btulsz

####### SUBROUTINE NAME

btulsz — size of dynamic memory needed
(long version, used when more than 64K needed)

...

Be sure to declare btulsz() as a function returning a long (32-bit) integer in one of the variable declaration sections of your C-language calling program. For example:

Code Block
main()
{
     int i,j,k;
     char *farmalloc();
     long btulsz();

     btuitz(farmalloc(btulsz(64,1024,2048)));
     :
     :
     btuend();
}

Note: farmalloc() is a library routine of Borland’s C++ compiler. You will need a memory allocation routine, like this one, that accepts a long parameter instead of merely integer.

...

N >= 0L This is the size, in bytes, of the memory region
needed by the Software Breakthrough
-1L Error: one of the buffer size parameters is not
an integral power of two

btumds

####### SUBROUTINE NAME

btumds — get next displayed character from the monitored channel
(as specified by btumon(), see page 114)

...

0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer

btumds2

####### SUBROUTINE NAME

btumds2 — get next displayed character from the monitored channel (as specified by btumon2(), see page 115)

...

0 the monitor-output buffer is empty
dspchr > 0 the next character from the monitor-output buffer

btumil

####### SUBROUTINE NAME

btumil — set maximum input line length, input word wrap on/off

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btumks

####### SUBROUTINE NAME

btumks — simulate a keystroke on the monitored channel
(as specified by btumon(), see page 114)

...

This routine has no effect if btumon() (page 114) has not been called, or if it was last called with a parameter of -1.

####### RETURNS

Nothing.

btumks2

####### SUBROUTINE NAME

btumks2 — simulate a keystroke on the monitored channel
(as specified by btumon2(), see page 115)

...

This routine has no effect if btumon2() (page 115) has not been called, or if it was last called with a parameter of -1.

####### RETURNS

Nothing.

btumon

####### SUBROUTINE NAME

btumon — start/stop monitoring a channel

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btumon2

####### SUBROUTINE NAME

btumon2 — start/stop monitoring a channel

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btumxs

####### SUBROUTINE NAME

btumxs — set maximum data speed

...

This parameter also affects the service rate of channels that are monitored using btumds() and btumds2() (pages 108 and 109), even if no hardware is connected to this channel (see use #2 on page 114). For example, using Worldgroupthe Major BBS, when you emulate a non-hardware channel (one that appears as “-“ in the user matrix on the console), the display rate is controlled by the bdrate parameter of btumxs(). For this reason, you may want to set the service rate higher than that required by your hardware, so that your emulated screen is updated faster.

...

0 the maximum data speed has been set
-3 bad baud rate: bdrate was not between 300 and 38400

btuoba

####### SUBROUTINE NAME

btuoba — Output Bytes Available: report the amount of space
(number of bytes) available in the output buffer

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 the channel number is OK but that channel’s output buffer is full
N>0 the number of bytes available in the channel’s output buffer

btuoes

####### SUBROUTINE NAME

btuoes — enable/disable Output-Empty status codes

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuolk

####### SUBROUTINE NAME

btuolk — set output pausing on/off

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btupbc

####### SUBROUTINE NAME

btupbc — set screen-pause character (pauses screen when in output stream)

...

When the pausch character is transmitted to the user in ASCII output mode, output pauses and the channel goes into the screen-pause mode (page 91). Clear screen characters (ASCII formfeed and ANSI esc [2J) are automatically preceded by the pause character when btuxmt() stuffs them into the output buffer. Worldgroup The Major BBS uses ctrl+T for the pause character.

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btupmt

####### SUBROUTINE NAME

btupmt — set prompt character

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

bturep

####### SUBROUTINE NAME

bturep — report channel statistics

...

bturep() returns the current long integer value of the statistic.

bturst

####### SUBROUTINE NAME

bturst — reset a channel

...

We recommend that as part of resetting any channel with Hayes category hardware, you issue the following sequence of instructions, selecting certain non-default options on which our interface scheme depends:

Code Block
bturst(chan);
btulok(chan,1);
btuoes(chan,1);
btuech(chan,0);
btubrt(chan,2400);
btuxmt(chan,"ATE0S0=1S2=1&C1&D2\r");
btucli(chan);

. . . wait for status 5 from this channel . . .

Code Block
btulok(chan,0);
btuoes(chan,0);

This procedure is used in the TELCONH.C example program on page 172.

...

3 means that a functional LAN interface has been detected on this channel

bturti

####### SUBROUTINE NAME

bturti — define routine to be called in real-time

...

-6 too many rti calls per second (hertz is too large)
0 all is well

btuscn

####### SUBROUTINE NAME

btuscn — scan for channels in need of service (with nonzero status)

...

-1 no channels require service: they all have a status of 0
N>=0 channel number of the next channel with a nonzero status

btuscr

####### SUBROUTINE NAME

btuscr — set the soft-cr character (for output word wrap)

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btusdf

####### SUBROUTINE NAME

btusdf — super-define channel groups

...

-14 LAN interface not available (only returned when chtype is 6 or 7)
-15 out of memory

btuset

####### SUBROUTINE NAME

btuset — set and report channel statistics

...

The operation of this function is only defined for X.25 and LAN channels when statid is 0 or 1. A count of characters and packets that have been transferred in both direction since channel reset is reported. For example, you could keep track of packet traffic with code like this:

Code Block
long pdelta;
static long ptotal=
0L
0L;
long btuset();
Code Block
pdelta=btuset(chan,1,
0L
0L);
ptotal+=pdelta;
printf("%ld packets input/output, %ld total!\n",pdelta,ptotal);

UART

The operation of this function is only defined for 8250-type UART channels when statid is 2-4.

...

The value of the statistic immediately before it gets set to the new value.

btusiz

####### SUBROUTINE NAME

btusiz — size of dynamic memory needed (only if < 64K)

...

0 to 65534 This is the size, in bytes, of the memory region
needed by the Software Breakthrough
65535 Error: more than 65534 bytes are needed,
or either buffer size is not a power of two

btusts

####### SUBROUTINE NAME

btusts — status of a channel

...

If a control character other than ^H=backspace or ^M=enter comes in, you may want to immediately send the character directly to the other party, bypassing the line input buffer. For example, with Worldgroup the Major BBS this would preserve some of the effects of ^O=abort and ^S=pause.

...

Up to 31 bytes of status can be queued, per channel, before the status queue overflows. See the note on status 43 and 44 (page 142) about how btusts() follows these status return codes with a status that could be anywhere between 0 and 255.

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

btutrg

####### SUBROUTINE NAME

btutrg — set input byte trigger quantity

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btutrm

####### SUBROUTINE NAME

btutrm — set input line terminator character

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btutrs

####### SUBROUTINE NAME

btutrs — generate status 6 when output aborted by user?

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btutru

####### SUBROUTINE NAME

btutru — set output-abort character (truncates current output block)

...

In ASCII output mode (page 14), any data block in the process of being transmitted to a channel is aborted if the character you specify here is received from the channel. On DEC systems, the character that users are accustomed to for this purpose is ctrl+O. This is what we have used for Worldgroupthe Major BBS. On other systems, ctrl+X is preferred.

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btutsw

####### SUBROUTINE NAME

btutsw — set terminal screen width and select output word wrap

...

First, we will describe output word wrap and the effects of related Software Breakthrough routines. Then we will describe the default situation (what happens when you call none of these routines). Finally, we will present an example.

How Output Word Wrap Works

The output word wrap feature prevents words (strings of non-space characters) from being split across line boundaries. This means, for example, that 80-column wide messages will be readable both to users with 80-column wide terminals, and to users with 40-column wide terminals.

...

Word wrap means that a line has been shortened to conform to the screen width by changing one of its spaces into a soft carriage return. Paragraphs are defined as strings of characters between hard carriage returns. Note that conversion of a soft carriage return into a space does not preclude its reconversion into a carriage return by the word wrap procedure. In this manner, wide paragraphs are completely reflowed to fit the available screen width. Note, however, that narrow paragraphs are not reflowed to fit wide screens.

Default Conditions

After a channel is reset by bturst(): the output word wrap feature is turned off; the hard carriage return is 13 (ASCII cr); and there is no soft carriage return. The linefeed character is 10 (ASCII lf). In this situation, when transmitting messages, the line terminator should be the ASCII cr character:

...

The \r is the C-language representation for ASCII cr. Since this is the hard carriage return character, it is translated into ASCII cr (that is, it is not changed). It is appended with ASCII lf.

Example of Output Word Wrap

The following conditions are similar to those in Worldgroup the Major BBS (although screen width is user-selectable):

Code Block
btutsw(chan,20);
btuhcr(chan,13);
btuscr(chan,10);

Now, hard carriage returns are ASCII crs and ASCII lf is the soft carriage return. The terminal screen width is limited to 20 characters for simplicity. Now let’s suppose that the following statements were executed:

Code Block
btuxmt(chan,"The blue form of the Engelmann Spruce\n");
btuxmt(chan,"is native to the mountains of western\n");
btuxmt(chan,"North America.\n");
btuxmt(chan,"\r");
btuxmt(chan,"Koyama's Spruce is native to central\n");
btuxmt(chan,"Japan (at altitudes of 1500 to 1800\n");
btuxmt(chan,"meters) and also to Korea.\n");
btuxmt(chan,"\r");

The result with word wrap on the terminal of channel chan would be:

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuudf

####### SUBROUTINE NAME

btuudf — un-define channels

...

-11 channel number(s) out of range: the specified range of channels
(schan to schan+n-1) is not within the inclusive range 0 to
nchan-1, where nchan has been defined in btusiz() (page 135)
or btulsz() (page 106)
0 the specified channels were un-defined successfully

btuusp

####### SUBROUTINE NAME

btuusp — special UART polling method

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 OK, special mode turned off
1 OK, special mode turned on

btux29

####### SUBROUTINE NAME

btux29 — transmit an X.29 string across an X.25 network
to the remote user’s PAD

...

all other return values indicate some error returned by the DATASD transmit function of the PC XNet driver. Refer to the documentation from OST (specifically, the PCXNET.H source file).

btuxct

####### SUBROUTINE NAME

btuxct — transmit to channel (by byte count)

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

btuxlt

####### SUBROUTINE NAME

btuxlt — set input translation table

...

Another purpose of the translation table is to permit you to translate UPPER case to lower case, or vice versa. This may improve the efficiency of the application software, in that you will not need to consider case when comparing strings, storing them in a database, etc. The following simple loop sets things up so that all channels in the ASCII mode automatically demote capitals to lower case:

Code Block
for (i='A' ; i <= 'Z' ; i++){
     btuxlt(i,i-'A'+'a');
}

A third use of the translation table is to to deal with parity, overrun, and framing errors. With “error-passthru” (see btuerp(), page 82), enabled by default, bytes read in with these errors will be received and their high bits will be set. Thus they will form translation table indices in the range from 128 to 255, as opposed to proper ASCII characters, which will have values of 0 to 127. There are, then, four main ways you might elect to deal with input characters involving these errors, by setting the upper half of the global translate table:

...

Any changes made to the translation table apply instantly to the system as a whole. Unless you are doing something unusual, this means that your btuxlt() calls, if any, should all appear at the beginning of your program, just after your call to btuitz().

####### RETURNS

Nothing.

btuxmn

####### SUBROUTINE NAME

btuxmn — transmit ASCII string that btuclo() will not be able to clear. (btubsz() will clear, however.)

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 channel number is good

btuxmt

####### SUBROUTINE NAME

btuxmt — transmit to channel (ASCIIZ string)

...

There is a razor’s edge situation in which the priority of transmission over command execution must be considered:

Code Block
btucmd(chan,"p")
btuxmt(chan,"Before or after pause?\r");

In this example, you can’t be sure the command will be executed before the string is transmitted because the interrupt-level code, when presented with commands and transmissions simultaneously, chooses transmissions. How can this be? The service rate (page 116) is low enough that, most probably, no service cycle will come between the above two instructions. If this occurs, the effects of these two statements will appear to the interrupt-level code simultaneously, and the data transmission will come before the pause.

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 channel number is good

btuxnf

####### SUBROUTINE NAME

btuxnf — set xon/xoff characters, select page mode

...

The default values after initialization or reset operate just as if the following call had been made:

Code Block
btuxnf(chan,0,19);

This means:

chan For this channel number,

...

Here is an example of how you would enable page mode:

Code Block
btuxnf(chan,0,-19,24,"Strike any key to continue...");

This means:

chan For this channel number,

...

-10 channel is not defined (see btudef(), page 74)
-11 channel number is out of range
(see btusiz(), page 135 or btulsz(), page 106)
0 all is well

...

Previous: Major BBS v10: 15 Global Variables  |  Contents  |  Next: Major BBS v10: 17 Programming Examples