Programming Examples
Applies to: v10
const CHAR * vs CHAR * hazard. Examples that pass literals (or
#defined literals) tochar *routines such asbtuxmt()must be changed before they run on v10. See chapter 29, section 29.4 ("HAZARD:const char *string literals versuschar *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