home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PCPTK10.ZIP / PCPLUSTK.DOC < prev    next >
Encoding:
Text File  |  1989-04-03  |  18.4 KB  |  530 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                          PCPlus Directory Toolkit
  25.                                 Version 1.0 
  26.                                 
  27.                                 
  28.                                 
  29.                                 
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.                                 
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                                 
  50.                                 
  51. (c) 1989 Metro Consulting Group, Inc.
  52.  
  53. Authored By:  Todd A. Scalzott
  54.               Metro Consulting Group, Inc.
  55.               10605 Lakeside Oak Court
  56.               Burke, VA  22015
  57.               (703) 250-9271
  58.  
  59.  
  60.  
  61. What is it?
  62.  
  63.    The PCPlus Directory Toolkit is a Turbo Pascal unit consisting of routines
  64.    for working with a ProComm Plus directory file. 
  65.  
  66.    Procedures and functions include routines for opening, copying, reading,
  67.    sorting, and writing ProComm Plus directories.  Each routine returns an
  68.    error code if an error is detected.
  69.  
  70.  
  71.  
  72. SHAREWARE
  73.  
  74.    The PCPlus Directory Toolkit is SHAREWARE.  Please support it.  The 
  75.    shareware policy employed for this product is very simple.  If you use
  76.    this product for YOUR OWN PERSONAL USE, take it.  Enjoy it.  Remember our
  77.    name.  If you use this product in a commercial environment, or in a 
  78.    shareware product that you intend to distribute, please follow these:
  79.  
  80.            1)  Place a message somewhere (visible) in your product (e.g. at
  81.                start-up time or on a help screen) stating:
  82.                 
  83.                This product uses Metro Consulting Group's
  84.                ProComm Plus Directory Toolkit
  85.  
  86.                Please also place this in your documentation.
  87.  
  88.            2)  Send a $15 donation with your name, address, phone number, 
  89.                and ProComm Plus Directory Toolkit version number to:
  90.  
  91.                Metro Consulting Group, Inc.
  92.                10605 Lakeside Oak Court
  93.                Burke, VA  22015
  94.  
  95.  
  96.  
  97.  
  98. Disclaimer
  99.  
  100.    It seems that these are necessary.
  101.  
  102.    Metro Consulting Group disclaims all warranties of any kind, implied or
  103.    otherwise, pertaining to this software.  MCG will not be liable for damages
  104.    of any kind incurred during the use of the ProComm Plus Directory Toolkit.
  105.    This includes instances in which MCG is aware of possible damages occuring.
  106.    
  107.  
  108.  
  109. Technical Support
  110.  
  111.    If you have a problem or question, please call us.  If you find a bug or
  112.    have a suggestion that you think would lead to a better product, please
  113.    call us.  
  114.  
  115.    Metro Consulting Group, Inc.
  116.    (703) 250-9271
  117.  
  118.  
  119.  
  120. Component Summary
  121.  
  122.    The following is a list of all procedures, functions, constants, and
  123.    types available in the ProComm Plus Directory Toolkit and their use.  
  124.  
  125.  
  126. CONSTANTS
  127.  
  128.       Max_ProComm_Entry = 200;
  129.                                 The maximum number of entries allowed in a
  130.                                 PCPlus directory file.
  131.  
  132.       Raw_Data_Size     = 74;
  133.                                 The size of each field of raw data read from
  134.                                 a PCPlus directory entry.  Each entry can be
  135.                                 expressed as an ARRAY[1..74] OF BYTE. 
  136.  
  137.  
  138.  
  139. TYPES
  140.  
  141.       ProComm_File  = FILE; 
  142.                                 Pointer to PCPlus dir file.  This pointer is
  143.                                 used by all routines for reading and writing
  144.                                 of information to or from a PCPlus directory.
  145.  
  146.       Sort_Field_Names = ( PCP_Name, PCP_Number, PCP_Area_Code, PCP_Exchange,
  147.                            PCP_Baud, PCP_Last_Called, PCP_Total_Calls );
  148.  
  149.                                 Tag names of each field which can be sorted
  150.                                 upon by the procedure Sort_Block.
  151.  
  152.  
  153.  
  154.             The following is for the logical representation of each PCPlus
  155.             directory entry.  This is the main data type that is used.
  156.  
  157.       ProComm_Entry = RECORD                   
  158.          Physical     : ARRAY[1..Raw_Data_Size] OF CHAR;
  159.                         The physical or "raw" representation of the entire
  160.                         directory entry including name, number, etc.
  161.  
  162.          Entry_Name   : STRING[24];
  163.                         The name given for the directory entry.
  164.                         Example:  Ultimate Connection BBS
  165.  
  166.          Phone_Number : STRING[20];
  167.                         The phone number for the directory entry.
  168.  
  169.          Baud_Rate    : INTEGER;
  170.                         The baud rate for the directory entry.
  171.  
  172.          Parity       : STRING[5];
  173.                         The parity for the directory entry.
  174.                         Either 'NONE', 'ODD', 'EVEN', 'MARK', or 'SPACE'.
  175.  
  176.          Data_Bits    : INTEGER;
  177.                         The number of data bits for the directory entry.
  178.  
  179.          Stop_Bits    : INTEGER;
  180.                         The number of stop bits for the directory entry.
  181.  
  182.          Duplex       : STRING[4];
  183.                         The duplex for the directory entry.
  184.                         Either 'HALF' or 'FULL'.
  185.  
  186.          Script_Name  : STRING[8];
  187.                         The name of the ASPECT script to be executed when
  188.                         connection is established.  
  189.  
  190.          Last_Called  : STRING[8];
  191.                         The date the entry was last called in MM/DD/YY form.
  192.  
  193.          Total_Calls  : INTEGER;
  194.                         The total number of calls (connections) placed to
  195.                         the directory entry.
  196.  
  197.          Def_Protocol : STRING[10];
  198.                         The default xmit/rcv protocol.  Either 'NONE',
  199.                         'MODEM-7','YMODEM','TELINK','XMODEM','YMDM BAT',
  200.                         'KERMIT','ASCII','CIS B','WXMODEM','YMDM-G',
  201.                         'YMDM-G BAT','IMODEM','SEALINK','EXT 1','EXT 2',
  202.                         or 'EXT 3'.
  203.  
  204.          Term_Type    : STRING[8];
  205.                         The default terminal type.  Either 'VT52','VT102',
  206.                         'ANSI','HEATH 19','IBM 3101','ADDS VP','ADM 5',
  207.                         'TVI 950','TVI 955','WYSE 50','WYSE 100','3270/950',
  208.                         OR 'TTY'. 
  209.       END;
  210.  
  211.  
  212.  
  213.       ProComm_Header = ARRAY [1..250] OF CHAR; 
  214.                                 The physical file header which preceeds all
  215.                                 entries in the PCPlus directory file.   In 
  216.                                 all cases that I have observed, this is all
  217.                                 null.  You shouldn't have to use it, other 
  218.                                 than when copying or creating a whole dir.
  219.  
  220.       Whole_ProComm_Dir = ARRAY [1..Max_ProComm_Entry] OF ProComm_Entry;
  221.                                 Type for an entire directory of 200 entries.
  222.                                 Already defined if you wish to work with the
  223.                                 entire directory at one time.
  224.  
  225.  
  226.    PROCEDURE Close_Dir_File ( Dir_File : ProComm_File; Result : INTEGER );
  227.  
  228.    Closes the directory file pointed to by Dir_File.  Result codes follow the
  229.    Turbo Pascal I/O error codes.  A successful operation returns the result
  230.    code of 0.
  231.  
  232.    Example:   .
  233.               .
  234.               .
  235.  
  236.               var my_dir   : procomm_file;
  237.                   close_res : integer;
  238.  
  239.               begin
  240.                  .
  241.                  .
  242.                  .
  243.                  close_dir_file(my_dir,close_res);
  244.                  if (close_res <> 0) then
  245.                     writeln('Error closing the directory.')
  246.                  else begin
  247.                     . 
  248.                     . 
  249.                     .
  250.               end;
  251.               .
  252.               .
  253.               .
  254.  
  255.  
  256.    PROCEDURE Create_Dir_File ( Dir_Name : STRING; Dir_File : ProComm_File;
  257.                                Result   : INTEGER );
  258.  
  259.    Creates an empty directory file with the name given by Dir_Name and opens
  260.    it with the the file pointer Dir_File associated with the newly created 
  261.    directory file.   Result codes follow the Turbo Pascal I/O error codes.  A
  262.    successful operation returns the code of 0.
  263.  
  264.    Example:   .
  265.               .
  266.               .
  267.  
  268.               var my_dir : procomm_file;
  269.                   res    : integer;
  270.  
  271.               begin
  272.                  create_dir_file('C:\PCPLUS\NEWDIR.DIR',my_dir,res);
  273.                  if (res <> 0) then
  274.                     writeln('Error creating the directory.')
  275.                  else begin
  276.                     . 
  277.                     . 
  278.                     .
  279.               end;
  280.               .
  281.               .
  282.               .
  283.  
  284.  
  285.    PROCEDURE Get_Entry ( Dir_File   : ProComm_File;  Entry_Num : INTEGER;
  286.                          Entry_Data : ProComm_Entry; Result    : INTEGER );
  287.  
  288.    Get the value of entry number Entry_Num from the PCPlus directory file 
  289.    pointed to by Dir_File and return the results in the variable Entry_Data.
  290.    Result codes follow Turbo Pascal I/O error codes.  An additional result
  291.    code of -1 indicates that Entry_Num is out of range.  A successful 
  292.    operation returns a code of 0.
  293.  
  294.    Example:   .
  295.               .
  296.               .
  297.  
  298.               var my_dir    : procomm_file;
  299.                   my_entry  : procomm_entry;
  300.                   res,count : integer;
  301.  
  302.               begin
  303.                  open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
  304.                  if (res <> 0) then
  305.                     writeln('Error opening the directory.')
  306.                  else
  307.                     for count := 1 to 10 do begin
  308.                        get_entry(my_dir,count,my_entry,res);
  309.                        if (res = 0) then
  310.                           writeln(count:3,'. ',my_entry.entry_name);
  311.                     end;
  312.               .
  313.               .
  314.               .
  315.  
  316.  
  317.    PROCEDURE Get_Header ( Dir_File : ProComm_File; Header : ProComm_Header;
  318.                           Result   : INTEGER );
  319.  
  320.    Get the header from the PCPlus directory file pointed to by Dir_File.  The
  321.    header will be returned in the variable Header.  This routine will most
  322.    likely be rarely used, but is available for those who whish to work with
  323.    the header directly.  Result codes follow Turbo Pascal I/O error codes.  
  324.    A successful operation returns a code of 0.
  325.  
  326.  
  327.    PROCEDURE New_Entry  ( Entry_Data : ProComm_Entry );
  328.  
  329.    Creates an empty directory entry.  Used for filling data in for a new entry
  330.    within the directory or erasing a previous entry.  To erase an entry, pass
  331.    its entry data into New_Entry and then use the procedure Write_Entry to 
  332.    write it back to the directory file.
  333.  
  334.  
  335.    PROCEDURE New_Header ( Header : ProComm_Header );
  336.  
  337.    Creates a new (null) PCPlus directory file header.  This routine will most
  338.    likely be rarely used, but is available for those who whish to work with
  339.    the header directly.
  340.  
  341.  
  342.    PROCEDURE Open_Dir_File ( Dir_Name : STRING; Dir_File : ProComm_File;
  343.                              Result   : INTEGER );
  344.  
  345.    Opens the PCPlus directory file designated by Dir_Name for access.  The
  346.    opened file will be assigned to the file pointer Dir_File.  Result codes
  347.    follow the Turbo Pascal I/O error codes.  A successful operation returns
  348.    the result code of 0.
  349.  
  350.    Example:   .
  351.               .
  352.               .
  353.  
  354.               var my_dir   : procomm_file;
  355.                   open_res : integer;
  356.  
  357.               begin
  358.                  open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,open_res);
  359.                  if (open_res <> 0) then
  360.                     writeln('Error opening the directory.')
  361.                  else begin
  362.                     . 
  363.                     . 
  364.                     .
  365.               end;
  366.               .
  367.               .
  368.               .
  369.  
  370.  
  371.  
  372.  
  373.    PROCEDURE Read_ProComm_Dir_Block ( Dir_File : ProComm_File; 
  374.                                       First, Count : INTEGER;
  375.                                       Entry_Data_Array;
  376.                                       Array_Size, Array_Start : INTEGER;
  377.                                       Result : INTEGER );
  378.  
  379.    Reads an entire block of entries from the PCPlus directory file pointed to
  380.    by Dir_File, starting with entry number First and proceeding for Count
  381.    entries.  The read block will be loaded into Entry_Data_Array, whose upper
  382.    bound (dimension) is Array_Size, starting at location Array_Start.  Result
  383.    codes follow Turbo Pascal I/O error codes.  An additional result code of
  384.    -1 indicates an illegal First.  A successful operation returns the result
  385.    code of 0.
  386.  
  387.    Example:   .
  388.               .
  389.               .
  390.  
  391.               var my_dir    : procomm_file;
  392.                   my_entry  : procomm_entry;
  393.                   res,count : integer;
  394.                   my_block  : array[1..20] of procomm_entry;
  395.  
  396.               begin
  397.                  open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
  398.                  if (res <> 0) then
  399.                     writeln('Error opening the directory.')
  400.                  else 
  401.                     { read 10 entries starting at #3 into my_block 10 thru 20 }
  402.                     read_procomm_dir_block(my_dir,3,10,my_block,20,10,res);
  403.               .
  404.               .
  405.               .
  406.  
  407.  
  408.    PROCEDURE Sort_Block ( Entry_Data_Array; Array_Size,First,Last : INTEGER;
  409.                           Field_Name : Sort_Field_Names; Order : CHAR );
  410.  
  411.    Sort the block of entries in the array Entry_Data_Array whose upper bound
  412.    (dimension) is Array_Size.  The block will be sorted on Field_Name (one of
  413.    those specified by the type Sort_Field_Names) in the order 'A' or 'D' 
  414.    (Ascending or Descending), starting with the array entry First and ending
  415.    with the array entry Last.  
  416.    
  417.    NOTE:  This is not a physical sort.  No disk writes will be performed.  
  418.           First and Last pertain to the array entries, not the PCPlus 
  419.           directory entries.
  420.  
  421.    A recursive Quick Sort is performed.  
  422.  
  423.    Example:   .
  424.               .
  425.               .
  426.  
  427.               var my_dir    : procomm_file;
  428.                   my_entry  : procomm_entry;
  429.                   res,count : integer;
  430.                   my_block  : array[1..20] of procomm_entry;
  431.  
  432.               begin
  433.                  open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
  434.                  if (res <> 0) then
  435.                     writeln('Error opening the directory.')
  436.                  else begin
  437.                     { read the first 10 entries into the block starting
  438.                       at block entry 20 and then sort.}
  439.                     read_procomm_dir_block(my_dir,1,10,my_block,20,10,res);
  440.                     { sort the entire block in 'A' order on the entry's name }
  441.                     sort_block(my_block,20,1,20,PCP_Entry_Name,'A');
  442.                  end;
  443.               .
  444.               .
  445.               .
  446.  
  447.               
  448.    PROCEDURE Update_Physical ( Entry_Data : ProComm_Entry );
  449.  
  450.    Updates the Physical field of Entry_Data according to each field within.
  451.    When an entry is read from a PCPlus directory file or created with the 
  452.    procedure New_Entry, the Physical field is intact.  Any modifications to
  453.    any of the fields within Entry_Data render this to not be true.  A call to
  454.    Update_Physical is NOT necessary, but may be desirable for a speed savings
  455.    by allowing writes in raw_mode.
  456.  
  457.  
  458.    PROCEDURE Write_Entry ( Dir_File   : ProComm_File;  Entry_Num : INTEGER;
  459.                            Entry_Data : ProComm_Entry; Raw_Mode  : BOOLEAN;
  460.                            Result     : INTEGER);
  461.  
  462.    Writes the data in Entry_Data to the PCPlus directory file pointed to by
  463.    Dir_File as entry number Entry_Num.  Entry_Num is physically overwritten
  464.    by Entry_Data.  Raw_Mode pertains to the Physical field in a variable of
  465.    type ProComm_Entry.  If you have NOT MODIFIED the contents of any fields
  466.    within the entry, a Raw_Mode of TRUE will cause the Physical field to be
  467.    written, rather than all other elements of the structure.  This provides
  468.    a faster method of writing data which is useful for moving blocks of 
  469.    entries from one place (or directory) to another.  
  470.    Result codes follow Turbo Pascal I/O error codes.  An additional result
  471.    code of -1 indicates that Entry_Num is out of range.  A successful 
  472.    operation returns the result code of 0.  
  473.  
  474.    See Also:  PROCEDURE Update_Physical
  475.  
  476.    Example:   .
  477.               .
  478.               .
  479.  
  480.               var my_dir    : procomm_file;
  481.                   my_entry  : procomm_entry;
  482.                   res,count : integer;
  483.  
  484.               begin
  485.                  open_dir_file('C:\PCPLUS\PCPLUS.DIR',my_dir,res);
  486.                  if (res <> 0) then
  487.                     writeln('Error opening the directory.')
  488.                  else
  489.                     { Erase the first 10 entries, not in raw_mode, although
  490.                       it is possible after a call to new_entry }
  491.                     for count := 1 to 10 do begin
  492.                        new_entry(my_entry);
  493.                        write_entry(my_dir,count,my_entry,FALSE,res);
  494.                     end;
  495.               .
  496.               .
  497.               .
  498.    
  499.  
  500.    PROCEDURE Write_Header ( Dir_File : ProComm_File; Header: ProComm_Header;
  501.                             Result   : INTEGER );
  502.  
  503.    Write the header given by the variable Header to the PCPlus directory file
  504.    pointed to by Dir_File.  This routine will most likely be rarely used, but
  505.    is available for those who whish to work with the header directly.  Result
  506.    codes follow Turbo Pascal I/O error codes.  A successful operation returns
  507.    a code of 0.
  508.  
  509.  
  510.    PROCEDURE Write_ProComm_Dir_Block ( Dir_File : ProComm_File;
  511.                                        First, Count : INTEGER;
  512.                                        Entry_Data_Array;
  513.                                        Array_Size, Array_Start : INTEGER;
  514.                                        Raw_Mode : BOOLEAN; Result : INTEGER );
  515.  
  516.    Writes an entire block of entries to the PCPlus directory file pointed to
  517.    by Dir_File, starting with entry number First and proceeding for Count
  518.    entries.  The Block will be written from Entry_Data_Array, whose upper
  519.    bound (dimension) is Array_Size, starting at location Array_Start.  
  520.    Raw_Mode may be set to TRUE if the entry has not been updated in any way
  521.    since it's initial creation or reading.  Result codes follow Turbo Pascal
  522.    I/O error codes.  An additional result code of -1 indicates an illegal
  523.    First.  A successful operation returns the result code of 0.
  524.  
  525.    See Also:  PROCEDURE Write_Entry
  526.               PROCEDURE Update_Physical
  527.  
  528.  
  529.  
  530.