home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / PBAPI10.ZIP / FAREA.BAS < prev    next >
BASIC Source File  |  1998-02-21  |  11KB  |  237 lines
  1. ' ─────────────────────────────────────────────────────────────────────────
  2. ' Program Title: Sample Program for TriBBS's FAREA.DAT API UNIT
  3. '     Copyright: 1997-98 by Freejack's Software
  4. '        Author: Gary Price
  5. ' Last Modified: 02/21/98
  6. ' ─────────────────────────────────────────────────────────────────────────
  7. '         Notes:
  8. ' ─────────────────────────────────────────────────────────────────────────
  9. '       History:
  10. ' ─────────────────────────────────────────────────────────────────────────
  11. '
  12. ' In this sample.bas file, you will see servals different examples on how
  13. ' to use the Pointer "fa" to make calls to the TriBBS API FAREA.PBU Unit.
  14. ' Also there are some examples showing how to use the FAREA.PBU Unit
  15. ' without using pointers.  To use any of the current examples, go to the
  16. ' section and you will see a "$IF 0" statment at the head of the example, all
  17. ' you need to do to make that section of code run is change the '0' to any
  18. ' non-zero number.
  19. '
  20. ' A pointer is a varible that holds 32-bit (4 byte) address of data located
  21. ' elsewhere in memory. It is called a pointer because it literally points
  22. ' to data. The data at which it points is known as the target.
  23. '
  24. ' Pointers are Powerfull! The address is defined at run-time, so any target
  25. ' in memory can be referenced by your program just as if it were a standard
  26. ' PowerBASIC varible. This type of indirection is much faster and more
  27. ' efficient than PEEKing and POKEing at the target data.
  28. '
  29. ' All String Pointer calls will grab the data from memory, and strip any
  30. ' spaces and null terminator characters from the end of the string which
  31. ' will allow you to print with better screen output control.
  32. '
  33. ' When writting back to memory with a pointer string, this FAREA API will
  34. ' set the length back to proper size and add the null terminator, CHR$(0)
  35. ' to the end of the string. This again, will save time in writting back
  36. ' to the original record FAREA.DAT.
  37. '
  38. ' For non-pointer calls, you will have to adjust the string yourself for
  39. ' proper printing to the screen. Also, when writting back to the FAREA.DAT
  40. ' file, you must add a num terminator to the end of the string. More on this
  41. ' in the Non-Pointer example.
  42. ' ─────────────────────────────────────────────────────────────────────────
  43.  
  44. $CPU 80386                    ' Requires a 386 system or faster
  45.  
  46. $OPTIMIZE SPEED             ' make fastest possible executable
  47.  
  48. '$COMPILE EXE "FAREA.EXE"   ' compile to an EXE
  49.  
  50. $DEBUG MAP OFF              ' turn off map file generation
  51. $DEBUG PBDEBUG OFF          ' don't include pbdebug support in our executable
  52.  
  53. $LIB COM        OFF         ' turn off PowerBASIC's communications library.
  54. $LIB CGA        OFF         ' turn off PowerBASIC's CGA graphics library.
  55. $LIB EGA        OFF         ' turn off PowerBASIC's EGA graphics library.
  56. $LIB VGA        OFF         ' turn off PowerBASIC's VGA graphics library.
  57. $LIB LPT        OFF         ' turn off PowerBASIC's printer support library.
  58. $LIB IPRINT     OFF         ' turn off PowerBASIC's interpreted print library.
  59. $LIB FULLFLOAT  OFF         ' turn off PowerBASIC's floating point support.
  60.  
  61. $ERROR BOUNDS   ON          ' turn on bounds checking for pointer debugging
  62. $ERROR NUMERIC  OFF         ' turn off numeric checking
  63. $ERROR OVERFLOW OFF         ' turn off overflow checking
  64. $ERROR STACK    OFF         ' turn off stack checking
  65.  
  66. $COM    0                   ' set communications buffer to nothing
  67. $STRING 16                  ' set largest string size at 16k
  68. $STACK  2048                ' let's use a 2k stack
  69. $SOUND  1                   ' smallest music buffer possible
  70.  
  71. $DIM ALL                    ' forces all Varibles and Arrays to be
  72.                             ' pre-dementioned before use.
  73.  
  74. $DYNAMIC                    ' all arrays will be dynamic by default
  75.  
  76. $OPTION CNTLBREAK OFF       ' don't allow Ctrl-Break to exit program
  77.  
  78. DEFINT A-Z                  ' default all variables to integers for maximum
  79.                             ' speed and minimum size
  80. '============================================================================
  81.  
  82.  
  83. '============================================================================
  84. '                          DECLARATIONS SECTION
  85. '============================================================================
  86. ' ** THIS SECTION IS FOR LINKS AND INCLUDES STATMENTS **
  87.  
  88. $LINK "G:\PB35\TBAPI10\PBAPI10.PBL"     ' ** SET THIS LINE TO YOUR PATH **
  89. $INCLUDE "G:\PB35\TBAPI10\PBAPI10.INC"  ' ** SET THIS LINE TO YOUR PATH **
  90. '---------------------------------------------------------------------------
  91. ' ** DECLARE SUB's BELOW THAT WILL BE USED IN THIS PROGRAM **
  92. '
  93. ' Use this section for any declarations needed to be made other than the
  94. ' FAREA.DAT API which are located in the FAREA.INC file.
  95.  
  96. '---------------------------------------------------------------------------
  97. '* DECLARE ALL LOCAL AND SHARED VARIABLES USED IN MAIN PROGRAM BETWEEN SUBS *
  98.  
  99. DIM FAN  AS STRING     ' Local Varible to hold the File Area Name
  100.  
  101. '---------------------------------------------------------------------------
  102. ' ** SET THIS LINE BELOW TO YOUR TRIBBS MAIN NODE's DIRECTORY **
  103.  
  104. TBNode1sMainDirectory = "E:\TRIBBS"
  105. '============================================================================
  106.  
  107. '============================================================================
  108. '                         ** MAIN PROGRAM BODY **
  109. '============================================================================
  110.  
  111. CLS     ' Clears screen prepares it for printing
  112.  
  113. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  114. '                ** EXAMPLE 1 for FAREA.DAT Pointer Calls **
  115. '----------------------------------------------------------------------------
  116. $IF 0  ' Change the '0' to '1' to run this example
  117.  
  118.   FAREA_DAT_OpenRead 1         ' Will Open and Read in FAREA.DAT
  119.                                ' record #1
  120.  
  121.     PRINT "Total Records:" FAREA_DAT_Length  ' Returns and Prints Total
  122.                                              ' Records in FAREA.DAT
  123.  
  124.     FAN = FAREA_DAT_GetFAN     ' Returns a 32-bit pointer to the File Area's
  125.                                ' Name string
  126.  
  127.     PRINT FAN                  ' Prints the File Area Name
  128.  
  129.     FAREA_DAT_PutFAN "New File Area Name"  ' Let's put a new File Area Name
  130.                                            ' in for this file area
  131.  
  132.     PRINT FAREA_DAT_GetFAN     ' Returns a 32-bit pointer to the File Area's
  133.                                ' Name string with the new File Area Name.
  134.  
  135.   FAREA_DAT_Close              ' Closes Farea.dat file
  136.  
  137.  ' In the example below, we can open, read, close the Farea.dat file, also
  138.  ' get and print the File Area Name from record #(1) all in a single line of
  139.  ' code. :)
  140.  
  141.    PRINT    ' Print a blank line
  142.    FAREA_DAT_OpenReadClose 1 : PRINT FAREA_DAT_GetFAN
  143.  
  144. $ENDIF
  145. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  146.  
  147. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  148. '                ** EXAMPLE 2 for FAREA.DAT Pointer Calls **
  149. '----------------------------------------------------------------------------
  150. $IF 0  ' Change the '0' to '1' to run this example
  151.  
  152.  
  153.  FAREA_DAT_OpenReadClose 1     ' Will Open and Read in FAREA.DAT
  154.                                ' record #1 and close the file
  155.  
  156.   ' Grab File Area's data from memory using the a 32-bit pointer
  157.  
  158.     PRINT FAREA_DAT_GetFAN     ' File Area Name
  159.     PRINT FAREA_DAT_GetFAP     ' File Area Path
  160.     PRINT FAREA_DAT_GetFAUP    ' File Area Upload Path
  161.     PRINT FAREA_DAT_GetFAFL    ' File Area Files List
  162.     PRINT FAREA_DAT_GetFAUL    ' File Area Upload Files Llist
  163.     PRINT FAREA_DAT_GetFAIF    ' File Area Index file
  164.     PRINT FAREA_DAT_GetSL      ' File Area Security Level (0 to 9999)
  165.     PRINT FAREA_DAT_GetVSL     ' File Area View Security Level (0 to 9999)
  166.     PRINT FAREA_DAT_GetODN     ' File Offline CDROM Disk Number (0 to 9999)
  167.     PRINT FAREA_DAT_GetFST     ' File Area Sort Type (0=By Date, 1=By Name)
  168.  
  169.      PRINT FAREA_DAT_GetAFAP(1) ' Additional File Area Paths
  170.                                 ' (1) represents the first add. file area
  171.                                 ' path, selection is (1 to 10)
  172.  
  173.      FAREA_DAT_PutAFAP 1, "C:\Newfiles" ' Change the Additional Farea Area
  174.                                         ' Path Name number (1) to something
  175.      PRINT FAREA_DAT_GetAFAP(1)         ' Grab the Additional Farea Area Path
  176.                                         ' and print it for number (1)
  177.  
  178.    ' ** These are Bit Fields converted to integers below **
  179.  
  180.     PRINT                        ' Prints a blank line
  181.     PRINT FAREA_DAT_GetPFAF     ' Private File Area Flag (0=No,1=Yes)
  182.     PRINT FAREA_DAT_GetCDFAF    ' CDROM File Area Flag (0=No,1=Yes)
  183.     PRINT FAREA_DAT_GetAFAF     ' Alias File Area Flag (0=No,1=Yes)
  184.     PRINT FAREA_DAT_GetOFAF     ' Offline File Area Flag (0=No,1=Yes)
  185.     PRINT FAREA_DAT_GetMIFAF    ' Master Index File Area Flag (0=No,1=Yes)
  186.  
  187. $ENDIF
  188.  
  189. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  190. '                ** EXAMPLE for FAREA.DAT Non-Pointer Calls **
  191. '----------------------------------------------------------------------------
  192. '
  193. ' This sample section will show how to use the FAREA.PBU Unit in it's basic
  194. ' form. This will require more string operations than the pointer section
  195. ' since you will be grabing just basic data straight from the FAREA.DAT
  196. ' file. Trimming, and removing and adding null terminators will have to be
  197. ' performed in this manner. If is very important when writting any data
  198. ' back to the FAREA.DAT file in this manner, you add the null terminator
  199. ' CHR$(0) to the end of all normal predefined strings based on the FAREA.DAT
  200. ' type structure located in the FAREA.INC file. Follow the example below.
  201. '
  202. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  203.  
  204. $IF 0  ' Change the '0' to '1' to run this example
  205.  
  206.  FAREA_DAT_OpenRead 1        ' Open FAREA.DAT File, and Read in record #1
  207.  
  208.  
  209.   PRINT FAREA.FareaName      ' Prints File Area Name as is from Farea.dat
  210.   PRINT LEN(FAREA.FareaName) ' Prints Len of File Area Name
  211.                              ' This shows a string length of 41 characters,
  212.                              ' which is 40 charcaters that you may use for
  213.                              ' data, and the last 41 contains the null
  214.                              ' terminator, CHR$(0)
  215.  FAREA_DAT_Close             ' Close FAREA.DAT File.
  216.  
  217.  
  218.   ' Now, lets trim off the excess spaces and the null terminator.
  219.   ' First I will create a new variable to hold the new data.
  220.  
  221.   DIM Temp AS STRING         ' Dimention a new variable
  222.  
  223.  FAREA_DAT_Open              ' Open FAREA.DAT File
  224.  FAREA_DAT_Read 1            ' Read in Record #1
  225.  
  226.   Temp = RTRIM$(FAREA.FareaName, ANY " " + CHR$(0)) ' This preforms the trim
  227.                                                        ' operation
  228.   PRINT Temp                 ' Prints the new string without the extra spaces
  229.                              ' and CHR$(0)
  230.   PRINT LEN(Temp)            ' Prints the True Length of the File Area Name
  231.  
  232.  FAREA_DAT_Close             ' Closes FAREA.DAT File
  233.  
  234. $ENDIF
  235. '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  236.  
  237. END                          ' Ends the Program