You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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)

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

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)

3
4   main()

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

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

Greeting for the system operator.

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

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.

 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.

12   while (!kbhit()) {

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

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

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

14   status=btusts(chan);

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

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.

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.

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.

18   btulok(chan,0);

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

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.

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

A string was received. What could it be?

22   btuinp(chan,ibf);

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

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?

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.

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?

27   btubrt(chan,1200);

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

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?

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.

31   }
32   else {
33        break;
34   }

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

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.

36   state[chan]=1;

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

37   }
38   break;

End of the channel state 0 case.

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

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

40   if (status == 12) {

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

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

If yes, say hello to this new caller.

42   btucli(chan);

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

43   btuech(chan,1);

Now we will start echoing his keystrokes to his terminal.

44   state[chan]=2;

And he is online.

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

47   rstchn(chan);

...we’ll reset the channel.

48   }
49   break;

End of the channel state 1 case.

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

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

51   if (status == 3) {

Have we received something from him?

52   btuinp(chan,ibf);

Yes, let’s get ahold of it.

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.

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

Welcome him to the fray.

55   state[chan]=3;

Now he is online.

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

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

58   rstchn(chan);

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

59   }
60   break;

End of the channel state 2 case.

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

Now that he is online...

62   if (status == 3) {

...does he have anything to say?

63   btuinp(chan,ibf);

Let’s hear it...

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.

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

For every channel...

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

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

67   btuxmt(i,obf);

...transmit the message.

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

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

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

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

73   rstchn(chan);

...means that we hang up on him.

74   }
75   break;

End of the channel state 3 case.

76   }

End of all possible values of the channel state.

77   }

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

78   }

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

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

Tell him goodbye,

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

hang up all channels,

83   btuend();

shut down the Software Breakthrough,

84   }

and return to the operating system.

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

This function runs the initialization sequence recommended on page 124.

88   {
89        bturst(chan);

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

90   btulok(chan,1);

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

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.

92   btuech(chan,0);

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

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.

94   btucli(chan);

Clear any trash input from the channel.

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.

96   }

End of the rstchn() function.

Teleconference for Xecom Hardware (TELCONX.C)

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

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)

103
104  main()

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

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

Greeting for the system operator.

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

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.

109  while (!kbhit()) {

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

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

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

111  switch (btusts(chan)) {

Now let’s treat each possible status condition differently.

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

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.

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.

115  state[chan]=1;

We now expect originate carrier to be detected.

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

118  bturst(chan);

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

119  state[chan]=0;

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

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.

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

Ask this caller to give us his name.

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.

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.

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

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

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

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

129  state[chan]=2;

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

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.

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

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

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

Check every channel...

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

135  btuxmt(othchn,obf);

Transmit this user’s message to the other user.

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

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

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.

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:

144  bturst(chan);

Hang up the channel...

145  state[chan]=0;

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

146       break;
147  }

This is the end of the possible status codes.

148  }

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

149  }

The system operator has pressed a key...

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

Tell him goodbye . . .

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.

154       btuend();
155  }

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

  • No labels