Category : BBS Programs+Doors
Archive   : TGKIT25.ZIP
Filename : SOFTDEV.DOC

 
Output of file : SOFTDEV.DOC contained in archive : TGKIT25.ZIP



------------------------------------------------------------------
---/ Telegard Bulletin Board System -- Version 2.5 Standard \---
---( Copyright 1988,89,90 by Eric Oman, Martin Pollard, )---
---\ and Todd Bolitho - All Rights Reserved /---
------------------------------------------------------------------

**> Telegard Software Development Kit <**
Released on 26-Mar-1990

Documentation by Todd Bolitho and Martin Pollard


______________

INTRODUCTION
______________

Greetings fellow programmers!

We are delighted that you wish to support Telegard by writing support
utilities. To facilitate your efforts, we have provided information
about the structures of Telegard's data files. This information takes
shape in the form of header files, designed to be "included" in your
programs. Headers for both Turbo Pascal and C are included, as well
as conversion functions in C to ease the burden on C programmers.
Also, this documentation includes sections on how to implement the
headers and use the information in your programs.

Note that this package is aimed towards programmers who have some
expertise with the C and Turbo Pascal languages; thus, our examples
and explanations assume you know what you are doing, and are familiar
with the language(s). If you're a beginning programmer, our advice is
to gain more expertise with the language(s) before attempting to write
a full-scale Telegard utility.

The Telegard development team uses Borland International's Turbo
Pascal 5.5 and Turbo C 2.0 compilers for its projects. We encourage
you to use them as well, as they are fine products (and it makes it
easier for us to answer any questions!).


__________________________

TURBO PASCAL PROGRAMMING
__________________________

Writing a Telegard utility in Turbo Pascal is probably the easiest to
do, since Telegard is currently written in Turbo Pascal. Thus, no
conversion of data fields is required (unlike C, which we will discuss
later).

Almost every Telegard utility you will write will require that you
read the STATUS.DAT file, which contains the current system
information. The example program, shown below, is a simple program
that reads STATUS.DAT and prints the BBS name, phone number, and SysOp
name.

Program Example;

{$I TGREC.PAS }



Var Status: Systatrec;
F: File of Systatrec;
BBSName, BBSPhone, SysOpName: String;

Function StripColor(S: String):String;
Var Temp: String;
I, Len: Integer;
Begin
Len := Length(S);
I := 1;
Temp := '';
Repeat
If ((S[I] = Chr($03)) Or (S[I] = '^')) Then
Inc(I)
Else
Temp := Temp + S[I];
Inc(I);
Until (I > Len);
StripColor := Temp;
End;

Begin
Assign(F, 'STATUS.DAT');
{$I-} Reset(F); {$I+}
If (IOResult <> 0) Then Begin
Writeln('Could not open STATUS.DAT');
Halt(1);
End;
Seek(F, 0);
Read(F, Status);
Close(F);

BBSName := StripColor(Status.BBSName);
BBSPhone := StripColor(Status.BBSPhone);
SysOpName := StripColor(Status.SysOpName);

Writeln('The system name is: '+BBSName);
Writeln('The phone number is: '+BBSPhone);
Writeln('The SysOp name is: '+SysOpName);

Halt(0);
End.

Notice that the program is written in traditional upper/lower case
Pascal style. This is not required, as Turbo Pascal is not particular
about case. (You can write your code in all-upper or all-lower case
if you like.)

Of interest in this program is the StripColor function. This function
removes Telegard's color codes from strings, and is a virtual
necessity if you wish to use these strings in the output of your
program. The operation of StripColor can be gleaned from the example
program, thus we will not go into specifics here.



_______________

C PROGRAMMING
_______________

Since C is not Telegard's native language, it is a bit more difficult
to write Telegard utilities using this language. However, it can be
done; several popular Telegard utilities, such as Martin Pollard's
USERLIST and Todd Bolitho's File Manager, are written in C.

Data types are almost identical between Turbo Pascal and C; the
exceptions are real number variables (type "Real" in Turbo Pascal,
type "float" or "double" in C) and strings (type "String" in Turbo
Pascal, "char" arrays in C). Of these two, the only one you will have
trouble with when writing Telegard utilities is string variables.
Here's why:

Turbo Pascal strings are stored as a single byte denoting the length
of the string, followed by the characters of the string. C strings,
on the other hand, are stored as the characters of the string,
followed by a zero (0x00) byte that terminates the string. You can
immediately see the problem: C can't display or manipulate Turbo
Pascal strings because (1) they aren't terminated with a zero byte,
and (2) the first character is not a valid character of the string.

What is needed are routines that convert strings from Turbo Pascal to
C format and back again. The following example program is patterned
after the Turbo Pascal example program, but shows the use of the
string converter (the Turbo C compiler is assumed):

#include
#include
#include
#include
#include
#include "tgrec.h"

char *strtp2c(const char *s)
{
register int i, j, len;
static char temp[256];

len = s[0];
i = 1;
j = 0;
while (i <= len)
{
if (s[i] == 0x03 || s[i] == '^')
++i;
else
temp[j++] = s[i];
++i;
}
temp[j] = '\0';
return(temp);
}

(continued on next page)



main()
{
int fd;
char bbsname[81], bbsphone[13], sysopname[31];
systatrec status;

if ((fd = open("STATUS.DAT", O_RDONLY|O_BINARY)) == -1)
{
puts("Could not open STATUS.DAT");
exit(1);
}
lseek(fd, 0L, SEEK_SET);
read(fd, (void *)&status, sizeof(systatrec));
close(fd);

strcpy(bbsname, strtp2c(status.bbsname));
strcpy(bbsphone, strtp2c(status.bbsphone));
strcpy(sysopname, strtp2c(status.sysopname));

printf("The system name is: %s\n", bbsname);
printf("The phone number is: %s\n", bbsphone);
printf("The SysOp name is: %s\n", sysopname);

exit(0);
}

The example program functions just like the Turbo Pascal version; the
differences being the way that C performs file I/O, and the Turbo
Pascal to C string conversion function. Notice that the function also
performs the task of stripping Telegard's color codes; thus, you kill
two birds with one stone.


____________

CONCLUSION
____________

A final note on using the conversion functions: If you have need to
save the original strings (for writing back to the data file), make
sure you either use duplicate strings for internal processing, or save
the original strings themselves.

Both example programs, as well as the string conversion functions
(StripColor, strtp2c(), and strc2tp()), and the Turbo Pascal and C
header files, are included in the archive accompanying this
documentation.

If you have any questions, contact one of the Telegard development
team members at any of the Telegard systems listed on the next page.



System Name Number Hours FidoNet Main SysOp
---------------------- ------------ ------ --------- --------------
Grosse Pointe Centrale 313-885-1779 24 hrs 1:120/188 Eric Oman
Warp Speed 313-544-0405 8p-8a 1:120/186 Todd Bolitho
The I/O Bus * 313-755-7786 10p-9a 1:120/187 Martin Pollard

* = Temporary phone number! It WILL be changing!

All systems currently support 1200 and 2400 baud only.




  3 Responses to “Category : BBS Programs+Doors
Archive   : TGKIT25.ZIP
Filename : SOFTDEV.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/