PCPlus Directory Toolkit
Version 1.0

























(c) 1989 Metro Consulting Group, Inc.

Authored By: Todd A. Scalzott
Metro Consulting Group, Inc.
10605 Lakeside Oak Court
Burke, VA 22015
(703) 250-9271



What is it?

The PCPlus Directory Toolkit is a Turbo Pascal unit consisting of routines
for working with a ProComm Plus directory file.

Procedures and functions include routines for opening, copying, reading,
sorting, and writing ProComm Plus directories. Each routine returns an
error code if an error is detected.



SHAREWARE

The PCPlus Directory Toolkit is SHAREWARE. Please support it. The
shareware policy employed for this product is very simple. If you use
this product for YOUR OWN PERSONAL USE, take it. Enjoy it. Remember our
name. If you use this product in a commercial environment, or in a
shareware product that you intend to distribute, please follow these:

1) Place a message somewhere (visible) in your product (e.g. at
start-up time or on a help screen) stating:

This product uses Metro Consulting Group's
ProComm Plus Directory Toolkit

Please also place this in your documentation.

2) Send a $15 donation with your name, address, phone number,
and ProComm Plus Directory Toolkit version number to:

Metro Consulting Group, Inc.
10605 Lakeside Oak Court
Burke, VA 22015




Disclaimer

It seems that these are necessary.

Metro Consulting Group disclaims all warranties of any kind, implied or
otherwise, pertaining to this software. MCG will not be liable for damages
of any kind incurred during the use of the ProComm Plus Directory Toolkit.
This includes instances in which MCG is aware of possible damages occuring.



Technical Support

If you have a problem or question, please call us. If you find a bug or
have a suggestion that you think would lead to a better product, please
call us.

Metro Consulting Group, Inc.
(703) 250-9271



Component Summary

The following is a list of all procedures, functions, constants, and
types available in the ProComm Plus Directory Toolkit and their use.


CONSTANTS

Max_ProComm_Entry = 200;
The maximum number of entries allowed in a
PCPlus directory file.

Raw_Data_Size = 74;
The size of each field of raw data read from
a PCPlus directory entry. Each entry can be
expressed as an ARRAY[1..74] OF BYTE.



TYPES

ProComm_File = FILE;
Pointer to PCPlus dir file. This pointer is
used by all routines for reading and writing
of information to or from a PCPlus directory.

Sort_Field_Names = ( PCP_Name, PCP_Number, PCP_Area_Code, PCP_Exchange,
PCP_Baud, PCP_Last_Called, PCP_Total_Calls );

Tag names of each field which can be sorted
upon by the procedure Sort_Block.



The following is for the logical representation of each PCPlus
directory entry. This is the main data type that is used.

ProComm_Entry = RECORD
Physical : ARRAY[1..Raw_Data_Size] OF CHAR;
The physical or "raw" representation of the entire
directory entry including name, number, etc.

Entry_Name : STRING[24];
The name given for the directory entry.
Example: Ultimate Connection BBS

Phone_Number : STRING[20];
The phone number for the directory entry.

Baud_Rate : INTEGER;
The baud rate for the directory entry.

Parity : STRING[5];
The parity for the directory entry.
Either 'NONE', 'ODD', 'EVEN', 'MARK', or 'SPACE'.

Data_Bits : INTEGER;
The number of data bits for the directory entry.

Stop_Bits : INTEGER;
The number of stop bits for the directory entry.

Duplex : STRING[4];
The duplex for the directory entry.
Either 'HALF' or 'FULL'.

Script_Name : STRING[8];
The name of the ASPECT script to be executed when
connection is established.

Last_Called : STRING[8];
The date the entry was last called in MM/DD/YY form.

Total_Calls : INTEGER;
The total number of calls (connections) placed to
the directory entry.

Def_Protocol : STRING[10];
The default xmit/rcv protocol. Either 'NONE',
'MODEM-7','YMODEM','TELINK','XMODEM','YMDM BAT',
'KERMIT','ASCII','CIS B','WXMODEM','YMDM-G',
'YMDM-G BAT','IMODEM','SEALINK','EXT 1','EXT 2',
or 'EXT 3'.

Term_Type : STRING[8];
The default terminal type. Either 'VT52','VT102',
'ANSI','HEATH 19','IBM 3101','ADDS VP','ADM 5',
'TVI 950','TVI 955','WYSE 50','WYSE 100','3270/950',
OR 'TTY'.
END;



ProComm_Header = ARRAY [1..250] OF CHAR;
The physical file header which preceeds all
entries in the PCPlus directory file. In
all cases that I have observed, this is all
null. You shouldn't have to use it, other
than when copying or creating a whole dir.

Whole_ProComm_Dir = ARRAY [1..Max_ProComm_Entry] OF ProComm_Entry;
Type for an entire directory of 200 entries.
Already defined if you wish to work with the
entire directory at one time.


PROCEDURE Close_Dir_File ( Dir_File : ProComm_File; Result : INTEGER );

Closes the directory file pointed to by Dir_File. Result codes follow the
Turbo Pascal I/O error codes. A successful operation returns the result
code of 0.

Example: .
.
.

var my_dir : procomm_file;
close_res : integer;

begin
.
.
.
close_dir_file(my_dir,close_res);
if (close_res <> 0) then
writeln('Error closing the directory.')
else begin
.
.
.
end;
.
.
.


PROCEDURE Create_Dir_File ( Dir_Name : STRING; Dir_File : ProComm_File;
Result : INTEGER );

Creates an empty directory file with the name given by Dir_Name and opens
it with the the file pointer Dir_File associated with the newly created
directory file. Result codes follow the Turbo Pascal I/O error codes. A
successful operation returns the code of 0.

Example: .
.
.

var my_dir : procomm_file;
res : integer;

begin
create_dir_file('C:\PCPLUS\NEWDIR.DIR',my_dir,res);
if (res <> 0) then
writeln('Error creating the directory.')
else begin
.
.
.
end;
.
.
.


PROCEDURE Get_Entry ( Dir_File : ProComm_File; Entry_Num : INTEGER;
Entry_Data : ProComm_Entry; Result : INTEGER );

Get the value of entry number Entry_Num from the PCPlus directory file
pointed to by Dir_File and return the results in the variable Entry_Data.
Result codes follow Turbo Pascal I/O error codes. An additional result
code of -1 indicates that Entry_Num is out of range. A successful
operation returns a code of 0.

Example: .
.
.

var my_dir : procomm_file;
my_entry : procomm_entry;
res,count : integer;

begin
open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
if (res <> 0) then
writeln('Error opening the directory.')
else
for count := 1 to 10 do begin
get_entry(my_dir,count,my_entry,res);
if (res = 0) then
writeln(count:3,'. ',my_entry.entry_name);
end;
.
.
.


PROCEDURE Get_Header ( Dir_File : ProComm_File; Header : ProComm_Header;
Result : INTEGER );

Get the header from the PCPlus directory file pointed to by Dir_File. The
header will be returned in the variable Header. This routine will most
likely be rarely used, but is available for those who whish to work with
the header directly. Result codes follow Turbo Pascal I/O error codes.
A successful operation returns a code of 0.


PROCEDURE New_Entry ( Entry_Data : ProComm_Entry );

Creates an empty directory entry. Used for filling data in for a new entry
within the directory or erasing a previous entry. To erase an entry, pass
its entry data into New_Entry and then use the procedure Write_Entry to
write it back to the directory file.


PROCEDURE New_Header ( Header : ProComm_Header );

Creates a new (null) PCPlus directory file header. This routine will most
likely be rarely used, but is available for those who whish to work with
the header directly.


PROCEDURE Open_Dir_File ( Dir_Name : STRING; Dir_File : ProComm_File;
Result : INTEGER );

Opens the PCPlus directory file designated by Dir_Name for access. The
opened file will be assigned to the file pointer Dir_File. Result codes
follow the Turbo Pascal I/O error codes. A successful operation returns
the result code of 0.

Example: .
.
.

var my_dir : procomm_file;
open_res : integer;

begin
open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,open_res);
if (open_res <> 0) then
writeln('Error opening the directory.')
else begin
.
.
.
end;
.
.
.




PROCEDURE Read_ProComm_Dir_Block ( Dir_File : ProComm_File;
First, Count : INTEGER;
Entry_Data_Array;
Array_Size, Array_Start : INTEGER;
Result : INTEGER );

Reads an entire block of entries from the PCPlus directory file pointed to
by Dir_File, starting with entry number First and proceeding for Count
entries. The read block will be loaded into Entry_Data_Array, whose upper
bound (dimension) is Array_Size, starting at location Array_Start. Result
codes follow Turbo Pascal I/O error codes. An additional result code of
-1 indicates an illegal First. A successful operation returns the result
code of 0.

Example: .
.
.

var my_dir : procomm_file;
my_entry : procomm_entry;
res,count : integer;
my_block : array[1..20] of procomm_entry;

begin
open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
if (res <> 0) then
writeln('Error opening the directory.')
else
{ read 10 entries starting at #3 into my_block 10 thru 20 }
read_procomm_dir_block(my_dir,3,10,my_block,20,10,res);
.

.
.


PROCEDURE Sort_Block ( Entry_Data_Array; Array_Size,First,Last : INTEGER;
Field_Name : Sort_Field_Names; Order : CHAR );

Sort the block of entries in the array Entry_Data_Array whose upper bound
(dimension) is Array_Size. The block will be sorted on Field_Name (one of
those specified by the type Sort_Field_Names) in the order 'A' or 'D'
(Ascending or Descending), starting with the array entry First and ending
with the array entry Last.

NOTE: This is not a physical sort. No disk writes will be performed.
First and Last pertain to the array entries, not the PCPlus
directory entries.

A recursive Quick Sort is performed.

Example: .
.
.

var my_dir : procomm_file;
my_entry : procomm_entry;
res,count : integer;
my_block : array[1..20] of procomm_entry;

begin
open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
if (res <> 0) then
writeln('Error opening the directory.')
else begin
{ read the first 10 entries into the block starting
at block entry 20 and then sort.}
read_procomm_dir_block(my_dir,1,10,my_block,20,10,res);
{ sort the entire block in 'A' order on the entry's name }
sort_block(my_block,20,1,20,PCP_Entry_Name,'A');
end;
.
.
.


PROCEDURE Update_Physical ( Entry_Data : ProComm_Entry );

Updates the Physical field of Entry_Data according to each field within.
When an entry is read from a PCPlus directory file or created with the
procedure New_Entry, the Physical field is intact. Any modifications to
any of the fields within Entry_Data render this to not be true. A call to
Update_Physical is NOT necessary, but may be desirable for a speed savings
by allowing writes in raw_mode.


PROCEDURE Write_Entry ( Dir_File : ProComm_File; Entry_Num : INTEGER;
Entry_Data : ProComm_Entry; Raw_Mode : BOOLEAN;
Result : INTEGER);

Writes the data in Entry_Data to the PCPlus directory file pointed to by
Dir_File as entry number Entry_Num. Entry_Num is physically overwritten
by Entry_Data. Raw_Mode pertains to the Physical field in a variable of
type ProComm_Entry. If you have NOT MODIFIED the contents of any fields
within the entry, a Raw_Mode of TRUE will cause the Physical field to be
written, rather than all other elements of the structure. This provides
a faster method of writing data which is useful for moving blocks of
entries from one place (or directory) to another.
Result codes follow Turbo Pascal I/O error codes. An additional result
code of -1 indicates that Entry_Num is out of range. A successful
operation returns the result code of 0.

See Also: PROCEDURE Update_Physical

Example: .
.
.

var my_dir : procomm_file;
my_entry : procomm_entry;
res,count : integer;

begin
open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
if (res <> 0) then
writeln('Error opening the directory.')
else
{ Erase the first 10 entries, not in raw_mode, although
it is possible after a call to new_entry }
for count := 1 to 10 do begin
new_entry(my_entry);
write_entry(my_dir,count,my_entry,FALSE,res);
end;
.
.
.


PROCEDURE Write_Header ( Dir_File : ProComm_File; Header: ProComm_Header;
Result : INTEGER );

Write the header given by the variable Header to the PCPlus directory file
pointed to by Dir_File. This routine will most likely be rarely used, but
is available for those who whish to work with the header directly. Result
codes follow Turbo Pascal I/O error codes. A successful operation returns
a code of 0.


PROCEDURE Write_ProComm_Dir_Block ( Dir_File : ProComm_File;
First, Count : INTEGER;
Entry_Data_Array;
Array_Size, Array_Start : INTEGER;
Raw_Mode : BOOLEAN; Result : INTEGER );

Writes an entire block of entries to the PCPlus directory file pointed to
by Dir_File, starting with entry number First and proceeding for Count
entries. The Block will be written from Entry_Data_Array, whose upper
bound (dimension) is Array_Size, starting at location Array_Start.
Raw_Mode may be set to TRUE if the entry has not been updated in any way
since it's initial creation or reading. Result codes follow Turbo Pascal
I/O error codes. An additional result code of -1 indicates an illegal
First. A successful operation returns the result code of 0.

See Also: PROCEDURE Write_Entry
PROCEDURE Update_Physical