TNT Software T.A.G. Developer's Library
Version 0.76 Gamma
Written by Joe McElmeel
Introduction
════════════
*** NOTE: Due to a huge error on my part, the last release didn't even work!
*** This one works fine -- I tried it. The problem was that I forgot to
*** re-compile the unit when I upgraded to the T.A.G. 2.7 record structs.
TNTDEV is a developer's kit for T.A.G. BBS programmers so they don't have to
re-invent the wheel. In other words, several ready-made Functions and
Procedures have been included with this package for you to use at your free
will at abosolutely no charge.
All routines have been written by me, unless otherwise specified. All routines
have been cleaned-up and documented by me as well.
Requirements
════════════
- An 8086/8088-compatible processor.
- An MS-DOS-compatible operating system (such as MS-DOS, PC-DOS, OS/2).
- Borland or Turbo Pascal v7.0.
- T.A.G. BBS Version 2.7 (if you want to test your programs!).
- A decent amount of knowledge in all of the above.
Implementation
══════════════
All you need to do is add the "TNTDEV" unit name in your USES clause at the
beginning of your program. For instance:
PROGRAM TAGMate;
USES
CRT, DOS, TNTDEV;
[..]
...The rest should be easy. Just use the routines that you want. Below is a
listing and description of all of the constants, variables, functions, and
procedures that are available for you to use. If you find any bugs, please
LET ME KNOW RIGHT AWAY. This is only a Gamma release, and these docs aren't
as complete as I like them to me. Please get in contact with me if you have
any bug reports, feature additions, code submissions, etc, etc.
Reference
═════════
Unit Constants
──────────────
DevVersion : String[5] = '0.76'; {* Stores unit version number *}
DevVerType : String[8] = 'Gamma'; {* Stores unit type (Alpha, Beta, etc) *}
DevTagVer : String[5] = '2.7'; {* Stores version of TAG designed for *}
Unit Variables
──────────────
Year, Month, Date, Day, {* Variables for time/date storage that *}
Hour, Min, Sec, Sec100 : Word; {* are read in upon program execution *}
StartClock, StopClock : LongInt; {* Variables that are set aside for the *}
{* timer procedures in the unit *}
Functions and Procedures
────────────────────────
===============================================================================
FUNCTION Int_To_Str(Number : LongInt): String;
Changes any integer value ("Number") to a String representing that value.
This routines courtesy of Turbo TechnoJock's ToolKit.
Example:
I := 10;
S := Int_to_Str(I);
WriteLn('The number is: '+S,'.');
The number is: 10.
===============================================================================
FUNCTION WithCommas(W : LongInt): String;
Like Int_To_Str, except that it inserts commas at the appropriate places
in the number ("W"). For instance, "1000" becomes "1,000" when converted to
a String using this function.
This routine courtesy of David Mitchell.
Example:
I := 30000;
S := WithCommas(I);
WriteLn('The number is: '+S,'.');
The number is: 30,000.
===============================================================================
FUNCTION Exist(Fil : String): Boolean;
Returns TRUE if file "Fil" exists. Be sure to specify a valid filespec for
"Fil" or else you could come up with a path not found runtime error. If the
file does not exist, and the directory leading to that file is valid, then
this function returns FALSE.
Example:
If Exist('C:\COMMAND.COM') then WriteLn('C:\COMMAND.COM exists!');
C:\COMMAND.COM exists!
===============================================================================
PROCEDURE TC(I : Byte);
Simply a shorter way of changing TextColor(). All it does is call the
TextColor() internal Turbo Pascal procedure -- just saves you some typing.
Example:
TC(7);
===============================================================================
PROCEDURE ResetColor;
A shorter way of setting TextColor to 7 and TextBackground to 0 (the
default MS-DOS colors).
Example:
ResetColor;
===============================================================================
PROCEDURE NL;
A shorter way of typing "WriteLn;". This procedure merely adds a blank
line to the display by calling WriteLn() with no parameters.
Example:
NL;
===============================================================================
PROCEDURE CStr(S : String);
A replacement for the internal Turbo Pacal "Write()" command. It allows
full support of Renegade pipe codes to change color in your output on-the-
fly! See the example below. This routine does not add a carriage return
and line feed at the end of the line -- if you want to do that, please
refer to CStrLn(). For more information on the pipe codes, please refer to
the Renegade BBS documentation -- most are self-explanatory, 00-15 are
the same as TextColor(), and 16 changes background to 0, 17 to 1, etc.
This routine courtesy of John Freese, although it has been cleaned up a bit
and the bug where you couldn't have two pipe characters in a row has been fixed
by me.
Example:
CStr('|15This is in bright white!');
This is in bright white!_
^ Cursor
Note:
CStr() automatically resets the color attributes to the default via a call to
ResetColor once it's done displaying what you tell it to.
===============================================================================
PROCEDURE CStrLn(S : String);
The exact same as CStr(), except that a carriage return and line feed
character are added at the end of the line via a call to "NL".
Example:
CStrLn('|15This is in bright white!');
This is in bright white!
_
^ Cursor
===============================================================================
PROCEDURE CenterStr(S : String);
This procedure centers a string in on an 80-column line fully-supportive of
the CStr/CStrLn pipe color-codes!
Example:
CenterStr('|15■ |14This is centered! |15■');
■ This is centered! ■
===============================================================================
FUNCTION AllCaps(S : String): String;
This function converts any string into all caps. This is especially good
for the now-standard way of displaying path/filenames in all capital
letters.
Example:
Temp := 'this will be in all caps';
CStrLn(AllCaps(Temp));
THIS WILL BE IN ALL CAPS
===============================================================================
FUNCTION RemoveCtrlP(Stri : String): String;
This function removes all ^C# codes out of a string such as the file board
and message board descriptions in T.A.G. BBS data files.
Example:
S := '0Green 1Grey 2White 3Cyan';
CStrLn(RemoveCtrlP(S));
Green Grey White Cyan
===============================================================================
FUNCTION FullDate : String;
This function grabs the current system date and spits out the date in a
longer, nicer-looking format (see below).
Example:
CenterStr(FullDate);
Monday May 9, 1994
===============================================================================
FUNCTION Lower(Str : String): String;
This functions converts an entire string into all lower-case characters
ignoring non-letter characters such as numbers, symbols, and high-ASCII.
Example:
WriteLn(Lower('TNT SOFTWARE'));
tnt software
===============================================================================
FUNCTION Proper(Str : String): String;
This functions takes a string, sets it to all lower-case via the Lower()
function, then capitalizes the first character of every word in the string.
In other words, it "properizes" it.
This routine courtesy of Turbo TechnoJock's Toolkit.
Example:
T := 'THIS WILL BE PROPERIZED';
WriteLn(Proper(T));
This Will Be Properized
===============================================================================
PROCEDURE ClockOn;
This procedure enables the program timer (usefull in seeing exactly how
long a certain portion of your code, or the whole program, takes to run)
and initalizes the "StartClock" variable. See also "ClockOff".
Example:
ClockOn;
===============================================================================
PROCEDURE ClockOff;
This procedure stops the program timer and initalizes the "StopClock"
unit variable. Below is an example on how to determine the time it took
from "ClockOn" to "ClockOff" calls. These two procedures are very useful
in determining how many seconds a certain portion of your code took to
execute.
Example:
ClockOn;
[..]
ClockOff;
TC(14);
WriteLn('[> The program was active for ',(StopClock-StartClock),' seconds.');
===============================================================================
FUNCTION Ynq(S : String; Mode : Byte): Boolean;
This procedure comes up with a Yes/No prompt for the user that they can
select with the cursor keys, Y, N, Esc, or return. It returns TRUE if the
user has chosen Yes, FALSE if they chose No. "S" is the prompt that will be
displayed and "Mode" is the default choice (1 = Yes, 2 = No).
This routine courtesy of John Freese.
Example:
DoThey := Ynq('Do you like this library?',1);
Do you like this library? [Yes] No
===============================================================================
PROCEDURE FixSpaces(var S : String);
This procedure simply replaces all "_" (underscore) characters in a string
with space characters (" "). This can sometimes be useful for command line
parameter operations.
Example:
S := 'This_is_an_example.';
FixSpaces(S);
WriteLn(S);
This is an example.
===============================================================================
FUNCTION ListARFlags(AR : ARFlagSet): String;
This function lists an AR flag set exactly the same way the T.A.G. BBS SDR
code does it: "AB-D-FGHIJKLMNOP-RSTUV-XYZ". You must feed it a AR flags set
from a user record or some other record in order for it to work.
Example:
VAR
UserSt : UserRec;
S := ListARFlags(UserSt.AR);
CStrLn(S);
ABCDEFG-IJKLMNO-QRST-VWXY-
===============================================================================
FUNCTION ListSFFlags(SF : FlagSet): String;
This function works exactly the same way as the previous one, except for
special (SF) flags.
Example:
VAR
UserSt : UserRec;
S := ListSFFlags(UserSt.Flags);
CStrLn(S);
-B----G-----MN--QR-TUVW---
===============================================================================
FUNCTION UnPakTagDate(TagDate : Word): String;
This function un-packs a T.A.G. "semi MS-DOS 1900 format" stored date that
is used in the user records for all date fields into a 00/00/00 string.
This (and all Pak/UnPak TAG Date functions) courtesy of Paul Williams and
Victor Capton.
Example:
S := UnPakTagDate(UserSt.LastDate);
CStrLn(S);
08/11/93
===============================================================================
FUNCTION UnPakTagTime(TagTime : Wrod): String;
The exact same as the above function, except that it it used to un-pack a
T.A.G. compressed time format in a 00:00:00 (24 hour format) string.
Example:
S := UnPakTagTime(UserSt.LastTime);
CStrLn(S);
00:01:34
===============================================================================
FUNCTION PakTagDate(S : String): Word;
This function is the exact opposite of the UnPakTagDate() function. It takes
a 00/00/00-format string and converts it directly into a T.A.G. BBS semi
MS-DOS 1900 format date stamp.
Example:
UserSt.LastDate := PakTagDate('08/11/93');
===============================================================================
FUNCTION PakTagTime(S : String): Word;
Exact same as the above function, but for T.A.G. time stamps. Uses a 24-hour
00:00:00 format string.
Example:
UserSt.LastTime := PakTagTime('00:01:34');
===============================================================================
FUNCTION GetWord(S : String; W : Integer): String;
This functions displays word "W" of string "S". See below.
Example:
S := 'This is a cool string.';
Temp := GetWord(S,2);
CStrLn(Temp);
is
===============================================================================
FUNCTION CoolDate : String;
This function returns the current system date in a 00/00/00 string.
Example:
WriteLn(CoolDate);
05/09/94
===============================================================================
FUNCTION CoolTime : String;
This function returns the current system time in a 00:00:00 (24-hour)
string.
Example:
20:28:01
===============================================================================
FUNCTION OutDate(KMonth, KDate, KYear : Word): String;
This function is the exact same as "CoolDate()", but it returns the date
from the values specified in the function's paramters. See below.
Example:
WriteLn(OutDate(5,9,1994));
05/09/94
===============================================================================
FUNCTION OutTime(KHour, KMin, KSec : Word): String;
This function is the same as "CoolTime()", but it returns the time from the
function's parameters that you specify. See below.
Example:
WriteLn(OutTime(0,0,34));
00:00:34
===============================================================================
FUNCTION ExtendedDate : String;
This function returns the current system time and date stamp in the same
way that T.A.G. does for it's ^S! SDR code to display the time and date.
Example:
WriteLn(ExtendedDate);
12:00:00 pm Mon May 09 1994
===============================================================================
FUNCTION SeeWords(St: String): Integer;
This functions reports the number of words in any given string.
Example:
S := 'This string is five words';
I := SeeWords(S);
WriteLn(I);
5
===============================================================================
FUNCTION PadRight(St : String; Ch : Char; L : Integer): String;
This function "pads" characters on the end of a string until L length.
See the example for more details.
Example:
Temp := 'Hi';
S := PadRight(Temp,'ƒ',5);
WriteLn(S);
Hiƒƒƒ
===============================================================================
FUNCTION PadLeft(St : String; Ch : Char; L : Integer): String;
This function "pads" characters onto the beginning of a string to make it
a length of L.
Example:
Temp := 'Hi';
S := PadLeft(Temp,'ƒ',5);
WriteLn(S);
ƒƒƒHi
===============================================================================
PROCEDURE Exec(Path, CmdLine : String);
This is a replacement for the DOS.Exec procedure that supports pipe-ins and
redirects. See below examples.
This routine courtesy of the Pascal snippets for 05/93, I believe.
Examples:
Exec('C:\UTILS\MISC\','PKZIP COMMAND C:\COMMAND.COM > NUL');
[Output would be muted]
Exec('C:\UTILS\MISC\','PKZIP COMMAND C:\COMMAND.COM > OUTPUT.TXT');
[Output would be re-directed to a text file "OUTPUT.TXT"]
Exec('C:\UTILS\MISC\','PKZIP -z COMMAND < COMMENT.TXT');
[Pipes in the text filename "COMMENT.TXT" for a ZIP comment]
===============================================================================
FUNCTION DayNum(Dt : String): Word;
This function takes a T.A.G. date string (00/00/00) and reports the number
of days since January 1st, 1985. This comes in VERY handy for FILES.DIR
operations.
This routine courtesy of Victor Capton.
Example:
FileDays := DayNum(Ul.Date);
===============================================================================
FUNCTION WordToHex(W : Word): String;
This function can convert any integer value up to 65,535 to a hexadecimal
value.
S := WordToHex(255);
CStrLn(S);
FF
===============================================================================
Support
═══════
I am open to suggestions, code submissions, bug reports, and documentation
corrections. Once I get the actual release out (v1.00 Standard), I may actually
release the entire source code. It's nothing big, really. It's only meant for
a kit for the lazy or a kit for beginners that don't have to "re-invent the
wheel". If you think any of the functions/procedures that are included are
useless or bad, LET ME KNOW and I will fix it!
You can get in contact with me via the FidoNet TAG and TAGBETA echos, and via
NetMail to 1:2410/480.
-Joe McElmeel