Versions Compared

Key

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

Programming Examples

Applies to: v10

const CHAR * vs CHAR * hazard. Examples that pass literals (or #defined literals) to char * routines such as btuxmt() must be changed before they run on v10. See chapter 29, section 29.4 ("HAZARD: const char * string literals versus char * parameters").

The two programs in this section were written in C. They illustrate the use of the most important Software Breakthrough routines. One program runs on Hayes category hardware (AT command set modems), and the other on Xecom category hardware like the Galacticomm Models 16 and 4 Breakthrough cards. See page 4 for a description of hardware categories. Each program is a complete multiuser teleconferencing system, albeit a simple one. Except for the hardware differences, the two programs function the same.

The Hayes program, page 172, with line numbers 1 to 96, are explained line-by-line starting on page 174. The lines of the Xecom program, page 182, with line numbers 101 to 155, are explained starting on page 183.

When a user calls up this teleconferencing system with a modem and a terminal, modem communication is established and the user is asked to enter his name. He is then placed online with the other users. While online, anything that one user types will appear on the displays of all others who are also online. All input and output is line-buffered, so that messages do not clobber one another.

For example, someone dialing up this teleconferencing system might see the following on his display (what the user types is shown in boldface):

To log on, please enter your name: Farkel

Okay, you're online.

>Hello out there

*** Message sent ***

>***

From Ferd: Hello, Farkel, how's the wife?

>why, Fanny's fine, Ferd.

*** Message sent ***

>***

From Ferd: Ah, good, good, and the children?

>Flora has the flu, but Simon and Gar Farkel are feeling fine

*** Message sent ***

>

Teleconference for Hayes Hardware (TELCONH.C)

Code Block
 1  int chan,status,state[8],i;
 2  char name[8][21],ibf[128],obf[163],*malloc();
 3
 4  main()
 5  {
 6       printf("TELECONFERENCE DEMONSTRATION -- HIT ANY KEY TO STOP\n");
 7       btuitz(malloc(btusiz(8,128,1024)));
 8       btudef(0,0x2F0,8);
 9       for (chan=0 ; chan < 8 ; chan++) {
10            rstchn(chan);
11       }
12       while (!kbhit()) {
13            if ((chan=btuscn()) >= 0) {
14                 status=btusts(chan);
15                 switch (state[chan]) {
16                 case 0:   /*--- CHANNEL STATE 0:  Initialized condition ---*/
17                      if (status == 5) {
18                          btulok(chan,0);
19                          btuoes(chan,0);
20                      }
21                      else if (status == 3) {
22                          btuinp(chan,ibf);
23                          if (strcmp(ibf,"CONNECT") == 0) {
24                               btubrt(chan,300);
25                          }
26                          else if (strcmp(ibf,"CONNECT 1200") == 0) {
27                               btubrt(chan,1200);
28                          }
29                          else if (strcmp(ibf,"CONNECT 2400") == 0) {
30                               btubrt(chan,2400);
31                          }
32                          else {
33                               break;
34                          }
35                          btucmd(chan,"p");
36                          state[chan]=1;
37                      }
38                      break;
39                 case 1:   /*-- CHANNEL STATE 1:  Waiting for 2 sec pause --*/
40                      if (status == 12) {
41                          btuxmt(chan,"\rTo log on, please enter your name: ");
42                          btucli(chan);
43                          btuech(chan,1);
44                          state[chan]=2;
45                      }
46                      else {
47                          rstchn(chan);
48                      }
49                      break;
Code Block
50                 case 2:   /*--- CHANNEL STATE 2:  Waiting for name --------*/
51                      if (status == 3) {
52                           btuinp(chan,ibf);
53                           sprintf(name[chan],"%1.20s",ibf);
54                           btuxmt(chan,"Okay, you're online!\r>");
55                           state[chan]=3;
56                      }
57                      else if (status != 251) {
58                           rstchn(chan);
59                      }
60                      break;
61                 case 3:   /*--- CHANNEL STATE 3:  Online ------------------*/
62                      if (status == 3) {
63                           btuinp(chan,ibf);
64                           sprintf(obf,"***\rFrom %s: %s\r>",name[chan],ibf);
65                           for (i=0 ; i < 8 ; i++) {
66                                if (i != chan && state[i] == 3){
67                                     btuxmt(i,obf);
68                                }
69                           }
70                           btuxmt(chan,"*** Message sent ***\r>");
71                      }
72                      else if (status != 251) {
73                           rstchn(chan);
74                      }
75                      break;
76                 }
77            }
78       }
79       printf("TELECONFERENCE DEMONSTRATION OVER, RETURNING TO DOS\n");
80       for (chan=0 ; chan < 8 ; chan++) {
81            bturst(chan);
82       }
83       btuend();
84  }
85
86  rstchn(chan)        /* Reset Channel */
87  int chan;
88  {
89       bturst(chan);
90       btulok(chan,1);
91       btuoes(chan,1);
92       btuech(chan,0);
93       btuxmt(chan,"ATE0S0=1S2=1&C1&D2\r");
94       btucli(chan);
95       state[chan]=0;   /* Now we wait for a status 5 on this channel */
96  }
Line-by-Line Synopsis
Code Block
1   int chan,status,state[8],i;

Declare the integer variables:

chan channel or user number

status current status code

state[] channel-specific state code:
0 waiting for incoming call
1 waiting for 2 seconds after carrier is detected
2 waiting for user to type in his name
3 online

i scratch variable, used to count through the other channels

Code Block
2   char name[8][21],ibf[128],obf[163],*malloc();

Declare several character variables:

name[][] array of names for each user

ibf[] input buffer (one user at a time)

obf[] output buffer (one user at a time)

*malloc() the standard memory allocation utility (it returns a pointer to character)

Code Block
3
4   main()

Define the “main” function, the main part of the program.

Code Block
5   {
6        printf("TELECONFERENCE DEMONSTRATION . . .\n");

Greeting for the system operator.

Code Block
7   btuitz(malloc(btusiz(8,128,1024)));

btusiz() specifies the buffer sizes (input 128, output 1024), and the total number of channels (8). It also computes the total number of bytes required for the Software Breakthrough. Note that in this example, the total memory required will not be anywhere near 65535 bytes, so that we do not use btulsz(), nor check for an erroneous return value from btusiz().

malloc() The standard dynamic memory allocation utility.

btuitz() Initializes the Software Breakthrough and “formats” its data structures in the memory block allocated by malloc().

Code Block
8   btudef(0,0x2F0,8);

Define 8 channels (numbered 0 to 7) with an I/O base address of 2F0 hex. This works for a Galacticomm Breakthrough Model 2408 card. For a single Hayes-compatible modem on the COM1 serial port, change this to btudef(0,0x3F8,1). Of course, you should also change the number of channels from 8 to 1, which is hard-coded throughout the program.

Code Block
 9   for (chan=0 ; chan < 8 ; chan++) {
10        rstchn(chan);
11   }

All channels must be reset and subjected to the initialization sequence. This sequence is performed by function rstchn(), coded on lines 86 to 96.

Code Block
12   while (!kbhit()) {

The main loop of the program continues until the system operator presses a key on the main console keyboard.

Code Block
13   if ((chan=btuscn()) >= 0) {

The first channel number requiring service (if any) is put into chan.

Code Block
14   status=btusts(chan);

The variable status now contains the status code of the channel that requires service.

Code Block
15   switch (state[chan]) {

Now, let’s treat each of the channel states separately. The state codes 0-3 are described above, with the explanation of line 1.

Code Block
16   case 0:   /*--- CHANNEL STATE 0:  Initialized ---*/

Two possibilities: (A) status 5, meaning that the Hayes-protocol command in rstchn() has been sent to the modem and we need to complete the init sequence; or (B) status 3, indicating that the modem has sent us a message (RING, OK, NO CARRIER, CONNECT), etc. We are only interested in CONNECT.

Code Block
17   if (status == 5) {

This is the status 5 that should eventually result from the btuxmt() call on line 93 in the rstchn() function, below. It means that the command string on that line has been completely transmitted to the modem. Now we will complete the initialization procedure that was started by the rstchn() function. We are following the procedure described on page 124 for resetting Hayes category hardware.

Code Block
18   btulok(chan,0);

This turns input lockout off, undoing line 90 in function rstchn().

Code Block
19   btuoes(chan,0);

This turns off output empty status. The output empty status option was enabled by line 91. We needed this to find out when the Hayes initialization command completed. Turning this option on is what caused the status 5 that got us into this code in the first place. We will no longer take special heed of the transition-to-empty event of the output data buffer.

Code Block
20   }
21   else if (status == 3) {

A string was received. What could it be?

Code Block
22   btuinp(chan,ibf);

Let’s get ahold of it and see...

Code Block
23   if (strcmp(ibf,"CONNECT") == 0) {

Was it a message from the modem on this channel, indicating that a user has called up at 300 baud and that we have made connection with him?

Code Block
24   btubrt(chan,300);

If yes, we must set the baud rate of the UART to 300 baud, because all subsequent communications with the modem will take place at 300 baud. We’ve just made the transition from command mode to online mode.

Code Block
25   }
26   else if (strcmp(ibf,"CONNECT 1200") == 0) {

Or is the message that we’ve connected with a user’s modem at 1200 baud?

Code Block
27   btubrt(chan,1200);

If yes, we must set our UART’s baud rate to 1200 baud.

Code Block
28   }
29   else if (strcmp(ibf,"CONNECT 2400") == 0) {

Or is the message that we’ve connected with a user’s modem at 2400 baud?

Code Block
30   btubrt(chan,2400);

Actually, this statement is unnecessary. We default the UART’s baud rate to 2400 baud after you reset the channel. Even this CONNECT 2400 message, like all of the CONNECT messages, has come to us at 2400 baud.

Code Block
31   }
32   else {
33        break;
34   }

If some other string is received from the channel, just ignore it.

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

If one of the above connect messages (for 300, 1200 or 2400 baud) has been received, we now must wait for the connection to settle. Our modem may have just changed baud rates, and so might the modem of the user that has just called up. To avoid losing any characters, we pause for 2 seconds.

Code Block
36   state[chan]=1;

Channel state 1 means we are waiting for this 2 second period to pass.

Code Block
37   }
38   break;

End of the channel state 0 case.

Code Block
39   case 1:   /*--- CHANNEL STATE 1:  Wait for pause ---*/

We have been waiting for the 2 second pause to elapse...

Code Block
40   if (status == 12) {

Do we have a “command-done” status condition?

Code Block
41   btuxmt(chan,"\rTo log on, please enter your name: ");

If yes, say hello to this new caller.

Code Block
42   btucli(chan);

Ignore anything he’s typed up to his point by clearing our data input buffer.

Code Block
43   btuech(chan,1);

Now we will start echoing his keystrokes to his terminal.

Code Block
44   state[chan]=2;

And he is online.

Code Block
45   }
46   else {

If we have received any other status code from this channel while waiting for the 2 seconds to elapse, something bizarre is going on so...

Code Block
47   rstchn(chan);

...we’ll reset the channel.

Code Block
48   }
49   break;

End of the channel state 1 case.

Code Block
50   case 2:   /*--- CHANNEL STATE 2:  Wait for name ---*/

We have been waiting for the user to type in his name...

Code Block
51   if (status == 3) {

Have we received something from him?

Code Block
52   btuinp(chan,ibf);

Yes, let’s get ahold of it.

Code Block
53   sprintf(name[chan],"%1.20s",ibf);

And store it in the name[][] array. This will be his “handle” for the duration of his session. In case it is longer than 20 characters, we only store the first 20. This kind of precaution is necessary so that whatever a user does, he cannot crash the system. A good policy.

Code Block
54   btuxmt(chan,"Okay, you're online!\r>");

Welcome him to the fray.

Code Block
55   state[chan]=3;

Now he is online.

Code Block
56   }
57   else if (status != 251) {

However, any other status (except input buffer overflow)...

Code Block
58   rstchn(chan);

...means that we will hang up on him.

Code Block
59   }
60   break;

End of the channel state 2 case.

Code Block
61   case 3:   /*--- CHANNEL STATE 3:  Online ---*/

Now that he is online...

Code Block
62   if (status == 3) {

...does he have anything to say?

Code Block
63   btuinp(chan,ibf);

Let’s hear it...

Code Block
64   sprintf(obf,"***\rFrom %s: %s\r>",name[chan],ibf);

...and format a message for everybody else to hear. The message will include his “handle” that he typed when he logged on.

Code Block
65   for (i=0 ; i < 8 ; i++) {

For every channel...

Code Block
66   if (i != chan && state[i] == 3) {

...not including chan, the one sending the message, and that is also online...

Code Block
67   btuxmt(i,obf);

...transmit the message.

Code Block
68        }
69   }
70   btuxmt(chan,"*** Message sent ***\r>");

Tell the sender that the message was sent to everyone who is listening.

Code Block
71   }
72   else if (status != 251) {

Otherwise, any other condition (except that he typed in too long of a line)...

Code Block
73   rstchn(chan);

...means that we hang up on him.

Code Block
74   }
75   break;

End of the channel state 3 case.

Code Block
76   }

End of all possible values of the channel state.

Code Block
77   }

End of check on btuscn() for channels needing service.

Code Block
78   }

End of the main loop — system operator has pressed a key.

Code Block
79   printf("TELECONFERENCE DEMONSTRATION OVER ...\n");

Tell him goodbye,

Code Block
80   for (chan=0 ; chan < 8 ; chan++) {
81        bturst(chan);
82   }

hang up all channels,

Code Block
83   btuend();

shut down the Software Breakthrough,

Code Block
84   }

and return to the operating system.

Code Block
85
86   rstchn(chan)     /* Reset Channel */
87   int chan;

This function runs the initialization sequence recommended on page 124.

Code Block
88   {
89        bturst(chan);

First the channel is reset: data structures are cleared, and the UART is initialized.

Code Block
90   btulok(chan,1);

Lock out input from this channel. This inhibits trash receive characters from inhibiting the upcoming transmission by btuxmt().

Code Block
91   btuoes(chan,1);

Enable the generation of a status 5 when the transmit buffer goes from non-empty to empty. This will indicate that the Hayes-protocol command string has been fully transmitted to the modem.

Code Block
92   btuech(chan,0);

Turn off the Software Breakthrough’s echo of every character it receives.

Code Block
93   btuxmt(chan,"ATE0S0=1S2=1&C1&D2\r");

Send an init string to the modem:
AT Begins almost all Hayes modem commands
E0 Modem echo off
S0=1 Auto answer mode on
S2=1 Escape character = ctrl+A
&C1 modem DCD indicates carrier detect
&D2 modem DTR input resets the modem

For more details on these commands, see your modem manual.

Code Block
94   btucli(chan);

Clear any trash input from the channel.

Code Block
95   state[chan]=0; /*Now we wait for a status 5 on this channel*/

We have done as much resetting of this channel as we can right now. The only work that remains is to turn off the input lockout and to turn off status 5 generation. For that we must wait for the status 5 that will come when the above Hayes-protocol command string has been fully transmitted to the modem. This is detected and serviced in lines 17-20 of this program.

Code Block
96   }

End of the rstchn() function.

Teleconference for Xecom Hardware (TELCONX.C)

Code Block
101  int chan,state[16],othchn;
102  char name[16][21],ibf[128],obf[163],*malloc();
103
104  main()
105  {
106       printf("TELECONFERENCE DEMONSTRATION -- HIT ANY KEY TO STOP\n");
107       btuitz(malloc(btusiz(16,128,1024)));
108       btudef(0,0x2F0,16);
109       while (!kbhit()) {
110            if ((chan=btuscn()) >= 0) {
111                 switch (btusts(chan)) {
112                 case 1:   /*--- STATUS 1:  Phone ring or lost carrier ---*/
113                      if (state[chan] == 0) {
114                           btucmd(chan,"Ap");
115                           state[chan]=1;
116                      }
117                      else {
118                           bturst(chan);
119                           state[chan]=0;
120                      }
121                      break;
122                 case 2:   /*--- STATUS 2:  Command complete ---*/
123                      btuxmt(chan,"To log on, please enter your name: ");
124                      break;
125                 case 3:   /*--- STATUS 3:  Input string available ---*/
126                      if (btuinp(chan,ibf) > 0 && state[chan] == 1) {
127                           sprintf(name[chan],"%1.20s",ibf);
128                           btuxmt(chan,"Okay, you're online!\r>");
129                           state[chan]=2;
130                      }
131                      else if (state[chan] == 2) {
132                           sprintf(obf,"***\rFrom %s: %s\r>",name[chan],ibf);
133                           for (othchn=0 ; othchn < 16 ; othchn++) {
134                                if (othchn != chan && state[chan] == 2) {
135                                     btuxmt(othchn,obf);
136                                }
137                           }
138                           btuxmt(chan,"*** Message sent ***\r>");
139                      }
140                      break;
141                 case 251:   /*--- STATUS 251:  Input buffer overflow ---*/
142                      break;
143                 default:    /*--- STATUS unknown ---*/
144                      bturst(chan);
145                      state[chan]=0;
146                      break;
147                 }
148            }
149       }
150       printf("TELECONFERENCE DEMONSTRATION OVER, RETURNING TO DOS\n");
151       for (chan=0 ; chan < 16 ; chan++) {
152            bturst(chan);
153       }
154       btuend();
155  }
Line-by-Line Synopsis
Code Block
101  int chan,state[16],othchn;

Declare integer variables:

chan channel or user number

state[] user-specific state code:
0 waiting for ring
1 waiting for carrier or waiting for name
2 online

othchn the other channel

Code Block
102     char name[16][21],ibf[128],obf[163],*malloc();

Declare several character variables:

name[][] array of names for each user

ibf[] input buffer (one user at a time)

obf[] output buffer (one user at a time)

*malloc() the standard memory allocation utility (it returns a pointer to character)

Code Block
103
104  main()

Define the “main” function, the main part of this program.

Code Block
105  {
106       printf("TELECONFERENCE DEMONSTRATION . . .\n");

Greeting for the system operator.

Code Block
107  btuitz(malloc(btusiz(16,128,1024)));

btusiz() specifies the buffer sizes (input 128, output 1024), and the total number of channels (16). Computes the total number of bytes required for the Software Breakthrough

malloc() The standard dynamic memory allocation utility

btuitz() Initializes the Software Breakthrough and “formats” its data structures in the memory block allocated by malloc()

Code Block
108  btudef(0,0x2F0,16);

Define 16 channels (numbered 0 to 15) with an I/O base address of 2F0 hex. This would also work for the 4 channels of a Model 4.

Code Block
109  while (!kbhit()) {

The main loop of the program continues until the system operator presses a key.

Code Block
110  if ((chan=btuscn()) >= 0) {

If any channel requires service, its channel number will be put in the variable chan.

Code Block
111  switch (btusts(chan)) {

Now let’s treat each possible status condition differently.

Code Block
112  case 1:   /*--- STATUS 1: Phone ring/lost carrier ---*/

A status code 1 can mean two very different things. If we are on-hook, it means the phone is ringing. In this case we will want to answer it. If we are off-hook, it means that we have lost the carrier signal. In that case we will want to hang up that channel (go on-hook).

Code Block
113  if (state[chan] == 0) {

If this channel state is zero, then the status 1 means that we detect the ringing of an incoming call.

Code Block
114  btucmd(chan,"Ap");

We will answer the incoming call (A answer command), and give the channel time to settle (p pause command). Answering a channel consists of going off-hook and beginning to sound the answer carrier signal.

Code Block
115  state[chan]=1;

We now expect originate carrier to be detected.

Code Block
116  }
117  else {

If the channel state is nonzero, then the status 1 means that we are no longer getting the quiescent carrier signal from this channel — the user has probably hung up on us...

Code Block
118  bturst(chan);

...so we hang up on him...

Code Block
119  state[chan]=0;

...and wait for more calls on this channel.

Code Block
120       }
121       break;
122  case 2:   /*--- STATUS 2:  Command complete ---*/

The status code of 2 means that the command string specified using btucmd() (in line 14) has completed successfully. This means we have detected originate carrier from this channel.

Code Block
123  btuxmt(chan,"To log on, please enter your name: ");

Ask this caller to give us his name.

Code Block
124       break;
125  case 3:   /*--- STATUS 3:  Input string available ---*/

This status code means that a carriage-return terminated string has been received from this channel. Either this is a new caller’s name (in response to the question in line 23), or a message that he wants sent to other users.

Code Block
126  if (btuinp(chan,ibf) > 0 && state[chan] == 1) {

We have gotten a string of at least one character, and we are expecting a new caller’s name.

Code Block
127  sprintf(name[chan],"%1.20s",ibf);

Record his name, but limit its length to 20 characters maximum.

Code Block
128  btuxmt(chan,"Okay, you're online!\r>");

Let him in the door. Note the > prompt for his first message.

Code Block
129  state[chan]=2;

We will treat all further information from him as messages to other users.

Code Block
130  }
131  else if (state[chan] == 2) {

Now, here is the case where an input string came in and we were expecting a message from him.

Code Block
132  sprintf(obf,"***\rFrom %s: %s\r>",name[chan],ibf);

Format the complete message to be sent to the other users who are online.

Code Block
133  for (othchn=0 ; othchn < 16 ; othchn++) {

Check every channel...

Code Block
134  if (othchn != chan && state[chan] == 2) {

...except for channel chan, the one that is sending the message. If there is a user on another channel, and he is online...

Code Block
135  btuxmt(othchn,obf);

Transmit this user’s message to the other user.

Code Block
136       }
137  }
138  btuxmt(chan,"*** Message sent ***\r>");

Let the sender of the message know that he is being heard.

Code Block
139       }
140       break;
141  case 251:   /*--- STATUS 251: Input buffer overflow ---*/

This status indicates that the input from the user on this channel has exceeded the size of the input buffer (128 bytes, as specified in btusiz(), line 107). We will just ignore this condition. This will result in missing characters from the user’s input string.

Code Block
142       break;
143  default:    /*--- STATUS unknown ---*/

Several status codes indicate that the answer command (line 14) was not successful. These conditions are treated in the same way:

Code Block
144  bturst(chan);

Hang up the channel...

Code Block
145  state[chan]=0;

...and wait for the next call on it.

Code Block
146       break;
147  }

This is the end of the possible status codes.

Code Block
148  }

This is the end of the case where btuscn() indicates that some channel needed servicing.

Code Block
149  }

The system operator has pressed a key...

Code Block
150  printf("TELECONFERENCE DEMONSTRATION OVER . . .");

Tell him goodbye . . .

Code Block
151  for (chan=0 ; chan < 16 ; chan++) {
152       bturst(chan);
153  }

And reset every channel, hanging up any calls that may have been in progress.

Code Block
154       btuend();
155  }

De-install the Software Breakthrough (a very important step).


Previous: Major BBS v10: 16 Library Routines  |  Contents  |  Next: Major BBS v10: 18 LAN Programming