...
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").
...
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
...
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
...
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.
...
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.
...
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.
...
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).
...
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
...
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.
...
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.
...
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().
...
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.
...
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.
...
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.
...
The operation of this function is only defined for X.25 and LAN channels when statid is 0 or 1. A count of characters and packets that have been transferred in both direction since channel reset is reported. For example, you could keep track of packet traffic with code like this:
| Code Block |
|---|
long pdelta; static long ptotal= |
0L; long btuset(); |
| Code Block |
|---|
pdelta=btuset(chan,1, |
0L); ptotal+=pdelta; printf("%ld packets input/output, %ld total!\n",pdelta,ptotal); |
UART
The operation of this function is only defined for 8250-type UART channels when statid is 2-4.
...
The following conditions are similar to those in 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:
...
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:
...
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.
...
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