Versions Compared

Key

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

...

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").

...

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
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 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