home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / progmisc / pbc22a.zip / LIB_BI.DOC < prev    next >
Text File  |  1992-06-24  |  25KB  |  547 lines

  1.      LIB_BI.DOC  Copyright (c) 1992  Daniel M. Smith, Jr.
  2.  
  3.               TOWARD LIBRARIES AND INCLUDE FILES
  4.  
  5.  
  6.  
  7. This document consists of a basic tutorial on BASIC include
  8. files and libraries. It is included with my libraries by the
  9. kind permission of the author. The text has been edited for
  10. consistency with my existing documentation and includes minor
  11. alterations where I considered them helpful.
  12.    -- Thomas G. Hanlin III
  13.  
  14. While the following might be considered mundane by experienced
  15. programmers, it's always nice to have a good foundation to
  16. begin building on.  With that in mind, the examples and
  17. discussion of topics will be in relatively layman terminology.
  18. To give you an excellent grasp of each idea presented, examples
  19. and step-by-step procedures will be given.  If you are using
  20. any version of QuickBASIC including QBX Professional
  21. Development System, the information presented here is
  22. applicable to all, although some versions may present specific
  23. problems regarding arguments and syntax. In fact, it is
  24. germaine to all higher level languages but specifically to the
  25. many forms of BASIC which is the language we are concerned
  26. about.
  27.  
  28. Many routines have been developed by programmers to accomplish
  29. tasks within the BASIC environment. Some are simple, yet others
  30. are extremely complex, possibly requiring memory allocation,
  31. etc. Since these routines are already available why waste time
  32. trying to re-invent the wheel so to speak; include the ones you
  33. require into your program with the $INCLUDE Metacommand (hardly
  34. layman language, so let's take time right now to find out about
  35. this special terminology).
  36.  
  37. Metacommands are special commands that are used to make your
  38. programs perform in a specific fashion. BASIC has three such
  39. commands; two ($DYNAMIC and $STATIC) which deal with allocation
  40. of dimensioned arrays and the $INCLUDE command which provides a
  41. means of incorporating external programs or routines into your
  42. programs. It specifically tells the compiler to stop processing
  43. the current program in favor of the program directed by the
  44. $INCLUDE Metacommand. When the included program ends, execution
  45. returns to the next line of the main program following the
  46. included routine.
  47.  
  48. We are only concerned here with $INCLUDE since it is the means
  49. by which all external routines are usually made a part of the
  50. main program. There is a specific syntax required with all
  51. metacommands that needs to be emphasized; most curious is that
  52. these commands are always preceded by REM or the apostrophe
  53. character. The following is the correct syntax for $INCLUDE:
  54.  
  55.    REM $INCLUDE: 'MyFile.BI'
  56.       or
  57.    ' $INCLUDE: 'MyFile.BI'
  58.  
  59. More than one metacommand can be placed on the same line as
  60. long as they are separated by white space. The other two
  61. metacommands don't require an argument, so no colon (delimiter)
  62. is required when using them. Note that the above argument is
  63. enclosed by single quotation marks (apostrophes).
  64.  
  65. What is a ".BI" file?  Nothing can be more frustrating than
  66. trying to figure out what constitutes an include file when you
  67. have never been near one before.  Forget trying to track it
  68. down in reference books!! Here it is in a nutshell and will
  69. save you a lot of time.
  70.  
  71. First, it doesn't have to have the ".BI" extension at all, but
  72. that's the common extension used for BASIC Include files.
  73. Second, no SUB or FUNCTION programming statements are permitted
  74. in the file; and Third, include files must be in ASCII format.
  75. A ".BI" file then is simply the declaration statements
  76. identifying the external subroutine or function that you want
  77. to be included into the main program. The following syntax is
  78. what you could expect to find in a typical ".BI" file. Let's
  79. call it 'WINDO.BI'.
  80.  
  81. The metacommand is:
  82.    REM $INCLUDE: 'WINDO.BI'
  83.  
  84. The contents of the file might be:
  85.  
  86.    DECLARE SUB Windo (TRow%, LCol%, BRow%, RCol%)
  87.    DECLARE SUB Colour (ForeGrd%, BackGrd%, Scrn%)
  88.    DECLARE SUB Border (Style%, Title$)
  89.    DECLARE SUB WritWin (FC%, BG%, Text$)
  90.    ' (etc)
  91.  
  92. The list could go on to include other windowing capabilities
  93. such as saving the screen the window pops up on, restoring the
  94. screen when the window is closed, etc.  Whatever the routine or
  95. function you wish to include in your program requires a
  96. definition statement similar to the above in the ".BI" file.
  97. The actual program defined is, of course, located in a library
  98. of subroutines; you are only telling the program to expect
  99. these particular subroutines to be called elsewhere in the
  100. program. If it were not for the ".BI" file and the declarations
  101. contained therein, when the program reached the call to the
  102. subroutine a "SUBPROGRAM NOT DEFINED" error message would be
  103. encountered. Every subroutine and function must be defined
  104. either at the beginning of the main module or in the ".BI" file
  105. if it is to be called during program execution.  I should also
  106. point out here that all arguments (ie., those within the
  107. parentheses in the examples above) must be established in your
  108. program before you make the call to the external subroutine.
  109. The % arguments require integers and $ arguments require
  110. strings.
  111.  
  112. Let's assume you have a key trapped that directs your program
  113. to a label called WIN. We would expect to find something like
  114. the following:
  115.  
  116.    WIN:
  117.       TRow% = 8: LCol% = 20: BRow% = 18: RCol% = 60
  118.       BackGrd% = 2: ForeGrd% = 15: Scrn% = 0
  119.       Style% = 1: Title$ = "TEST WINDOW"
  120.  
  121. Now that the parameters are established:
  122.  
  123.    Border Style%, Title$
  124.    Colour ForeGrd%, BackGrd%, Scrn%
  125.    Windo TRow%, LCol%, BRow%, RCol%
  126.  
  127. The parameters can be set when the function is used, for
  128. example:
  129.  
  130.    LOCATE 10, 25
  131.    WritWin 14, 4, "This is only a test!"
  132.  
  133. By the way, why use Colour instead of Color, or Windo instead
  134. of Window? Because COLOR and WINDOW are BASIC keywords! We
  135. can't use them, since they are already defined to mean
  136. something else. Sometimes you have to be careful with names.
  137.  
  138. Declaration is not required for GOSUB, since you never have to
  139. pass any arguments explicitly.  The GOSUB statement is kind of
  140. a specialized version of GOTO, not a subroutine in the sense
  141. that a SUB or FUNCTION is.
  142.  
  143. Hopefully, this will help you to a proper perspective of ".BI"
  144. files.
  145.  
  146. NOW!! Here comes the big one. We will step through this very
  147. slowly because libraries are the backbone of programming. Each
  148. time a programmer prepares a method to accomplish a certain
  149. job, it becomes candidate for retention, since the same routine
  150. might be required again (either by himself or other persons who
  151. program in the same language).  These routines are normally
  152. placed in libraries. It could be a small library, or, if many
  153. routines have been created, it could be quite large. The term
  154. "library" is very appropriate, because (like books) routines
  155. can be removed from programming libraries and used when you
  156. need them, but do not need to be kept in your program when you
  157. don't. Much work and research go into solving specific tasks or
  158. coming up with better and more efficient ways of doing a
  159. particular job. Making these great routines available to others
  160. makes programming so much easier because you won't have to
  161. waste time trying to come up with the same routine again. Just
  162. extract it from the provided library and place in a new library
  163. you are going to use. Very easily said, but it takes
  164. considerable doing. This is exactly what we are going to
  165. examine now.
  166.  
  167. We will step through the entire procedure for creating a new
  168. library exactly in the same order as you should every time you
  169. decide to use someone else's library routines. Please keep in
  170. mind that these instructions are given from a QuickBASIC
  171. viewpoint. With other versions of BASIC you will have to make
  172. substitutions or modifications in the syntax where required.
  173.  
  174. First you must decide which routines you are going to need from
  175. the library. Make a list of the names of each routine on paper
  176. leaving room on the right for additional information.  You will
  177. realize the advantage of doing this shortly.
  178.  
  179. Next, you must have a listing (.LST) file of the library to
  180. find out the specific module file the routine is located in.
  181. When .OBJ files are placed in libraries they no longer have an
  182. extension associated with them; they are merely modules within
  183. the library. However, when they are extracted (as we will see
  184. later) they are given the .OBJ extension once again by LIB.EXE
  185. which is the default. Programmers often place related routines
  186. in one module file within the library. If a routine exists in
  187. its own module file then extracting that module file will
  188. provide you with that particular routine; however if several
  189. routines exist in one module file you can't extract a specific
  190. routine you must extract the entire module file.  Therefore,
  191. just because we know the name of a routine does not necessarily
  192. give us access to that routine because it could be in a module
  193. file with an entirely different name. When you see your first
  194. listing file you will more readily discern what I mean. If the
  195. routines are contained in one library and the programmer has
  196. provided both ".QLB" and ".LIB" files you will not need a list
  197. file if you use the programmers libraries. Otherwise, if no
  198. listing (.LST) file exists for the library it will be necessary
  199. to create one.
  200.  
  201. That brings us to our next step, creating a .LST file.
  202.  
  203. LIB.EXE is the library management tool that comes with most of
  204. the versions of BASIC that include a compiler.  Some
  205. programmer's huge libraries may be too large for some older
  206. versions of LIB.EXE and if so the programmer will make you
  207. aware of that in his readme file or other documentation.
  208. QuickBASIC 4.5 and PDS/QBX 7.x seem quite up to tackling all
  209. library tasks. To create the .LST file enter:
  210.  
  211.    LIB LIBRARY.LIB
  212.  
  213. where LIBRARY.LIB is the name of the library requiring the
  214. listing file. The .LIB extension is not really required, since
  215. LIB.EXE knows it will be working with a .LIB file. NOTE:
  216. LIBRARY.LIB is always replaced with the actual name of a
  217. library in the following examples; xx in a QB .LIB file name is
  218. replaced with the actual number of your version.
  219.  
  220. LIB.EXE and the library must be in the same directory. To make
  221. everything simple I usually create a special subdirectory for
  222. the library and copy LIB.EXE to it along with the library files
  223. I intend to use. Also copy LINK.EXE to the same subdirectory
  224. for future use. There will be quite a bit of activity in this
  225. directory; this will keep everything a little organized. If
  226. something goes wrong it's easy to identify the erroneous files
  227. and start over again without having to search for the files we
  228. created and maybe erase something inadvertantly.
  229.  
  230. After pressing enter in example above you will see the following:
  231.  
  232.    Operations:        press Enter to continue
  233.       Since we did not define any operation on the command line
  234.       LIB is prompting for direction; none is required at this
  235.       time.
  236.  
  237. Next you see:
  238.  
  239.    List file:         type LIBRARY.LST and press Enter
  240.       You can name the list file anything you wish but it would
  241.       be advisable to name it the same as the library to avoid
  242.       confusion.
  243.  
  244. The .LST file will be created in the current subdirectory. You
  245. can use any text editor to view the file. It may be quite long
  246. so I would not use the DOS TYPE command except to redirect it
  247. to the printer. Make sure you have sufficient paper and that
  248. the printer is on and ready. To redirect the list file to
  249. printer, type the following:
  250.  
  251.    TYPE LIBRARY.LST >PRN
  252.  
  253. List files are in two columns. Each column has two text entries
  254. divided by dots. The left entry is the subroutine name; the
  255. right is the module file to which it belongs. Some module file
  256. names are really quite cryptic; also as mentioned before some
  257. have the same name as the subroutine. Related routines will
  258. probably be in a single module file.
  259.  
  260. Using the example .BI file we looked at before, you might see
  261. this in the listing file of the library containing those
  262. subroutines.
  263.  
  264.    WINDO...............wnd
  265.    COLOR...............wnd
  266.    BORDER..............wnd
  267.    WRITWIN..........writwn
  268.  
  269. Please note that all of the above could have been in the same
  270. module or in all different modules. Notice also that the module
  271. file "writwn" is not spelled the same as the subroutine.
  272. Programmers may change the name of .OBJ files, sometimes just
  273. by abbreviating the name of the routine.
  274.  
  275. Now that we have the .LST file we can really get down to work.
  276. First we must select the routines that will be needed for
  277. inclusion into the main program and identify the module(s) to
  278. which they belong. We will continue to use the WINDO example
  279. throughout this instruction.
  280.  
  281. The next step is to copy the module files from the Library. The
  282. .LST file has shown us the names of the module files we need to
  283. make our imaginary window. We need to extract WND and WRITWN.
  284. Recall that when they are extracted they will be given the .OBJ
  285. extension by default.
  286.  
  287. LIB.EXE can do this. Just type the following:
  288.  
  289.    LIB LIBRARY.LIB  *WND.OBJ *WRITWN.OBJ
  290.  
  291. The "*" tells LIB to copy the module files only.  The original
  292. modules will remain in the library.
  293.  
  294. There are several operators that tell LIB what to do and I will
  295. briefly describe some here:
  296.  
  297.    +   preceding the .OBJ file means add to library
  298.    -   preceding a module name removes it
  299.    -+  preceding a module removes original and replaces it with
  300.        the updated version. Be sure the new version is
  301.        available to LIB because removal action is always first
  302.        in order.
  303.  
  304. There are more but the above gives ample ability to manipulate
  305. libraries. Consult your manual on others.
  306.  
  307. After doing the above example, you would have all of the
  308. required .OBJ files in the current subdirectory.  You could
  309. verify their existence by typing DIR at the DOS prompt.  When
  310. there are more than a few .OBJ files, it may help to keep a
  311. notepad handy to keep track of them.
  312.  
  313. If we needed .OBJ files from a second library we would again
  314. use LIB.EXE to extract those files from that particular
  315. library. There would then be .OBJ files from two different
  316. libraries; these can be easily combined into a new library
  317. specific to the needs of the main program.
  318.  
  319. As mentioned before, QuickBASIC uses two types of Library
  320. files: the normal .LIB files at linking time and .QLB
  321. (QuickLibrary) files when programming in the QuickBASIC
  322. environment. Certainly you want to see your program run, if
  323. possible, prior to compiling an .EXE file so all bugs can be
  324. removed.  Notice I said "if possible". There may be occasions
  325. when running a program is not possible because of conflict with
  326. the environment.  If this should happen, you will have to
  327. create the .EXE file from the DOS command line or determine the
  328. cause of the conflict and correct it.  Refer to your QuickBASIC
  329. guide book for the proper syntax for BC and LINK. I will also
  330. describe them briefly after we create these new libraries.  If
  331. you do run into this type situation I suggest you get the rest
  332. of your program functioning the way it should; then make the
  333. .EXE file to check the end result. Then you can work with the
  334. sticky subroutine; any error subsequent to that would
  335. definitely suggest the problem is with that subroutine.
  336.  
  337. So, a .QLB library is the first one we need to see how the
  338. program will function.  LINK.EXE will provide the means to do
  339. this job. LINK.EXE has a special switch (/Q) which tells the
  340. program to make the .QLB library. If the switch is omitted
  341. QuickBASIC will not be able to load the library when instructed
  342. to do so with the /L switch because of improper format.
  343.  
  344. The following syntax for LINK will provide a .QLB library:
  345.  
  346.    LINK /Q WND.OBJ WRITWN.OBJ, MYNEW.QLB,,BQLBxx.LIB;
  347.  
  348. LINK.EXE will combine the .OBJ files into the new .QLB library
  349. using QuickBASICs provided library for support routines.
  350. Naturally if you were using some other version of BASIC you
  351. would use the library provided to support the specific
  352. environmental library. NOTE: When using the /L swith to load
  353. QuickBASIC only one .QLB file can be specified. This means one
  354. thing, ALL external routines must be in the same .QLB library.
  355. Also, .QLB libraries are not manageable as .LIB libraries are,
  356. therefore it is important to have identified all routines
  357. required prior to creating the .QLB library. If you forget one
  358. you will have to LINK all .OBJ files again to include the
  359. one(s) you forgot.  I should mention that it is possible to do
  360. these tasks within the QuickBASIC environment in which case
  361. .QLB libraries can be manipulated but only by changing the
  362. resulting library to a different name which basically means you
  363. are redoing everything again anyway. An advantage of this
  364. method is that the parallel .LIB file will be created at the
  365. same time. Consult your manual if you opt for this method.
  366. It is desirable to know how to do it from the command line.
  367.  
  368. You should copy the .BI and .QLB file now to your program
  369. directory. The following syntax will make your new library
  370. available to the main program when you are ready to try the
  371. external routines.  It is assumed of course that you have
  372. entered the $INCLUDE metacommand into your program (preferably
  373. ahead of other DECLARE statements) and that subroutine arguments
  374. have been entered or will be entered before the call is made to
  375. a particular routine:
  376.  
  377.    QB /L MYNEW.QLB
  378.  
  379. or, if you wish to load the program at the same time:
  380.  
  381.    QB YOURPROG /L MYNEW.QLB
  382.  
  383.  
  384. Your program is up and running now and you have presumably
  385. ironed out all the bugs and are ready to create the .EXE file.
  386. Whether it is a standalone executable or one requiring the run
  387. library your external routines must be supported by parallel
  388. .LIB files. These parallel files contain the same object code
  389. as the .QLB files but in entirely different format. If, when
  390. creating the .EXE file, these files are not found they will be
  391. omitted from the .EXE program. Hence a certain function may not
  392. work at all even though the rest of the program is perfect. For
  393. this reason it is always a very good idea to create the .LIB
  394. file at the same time you create the .QLB file. For purposes of
  395. illustration I will repeat the syntax for creating the .QLB
  396. file so that you may see both of these commands together and
  397. their relationship to each other:
  398.  
  399.    LINK /Q WND.OBJ WRITWN.OBJ, MYNEW.QLB,,BQLBxx.LIB;
  400.  
  401. and here is the command to create the parallel .LIB file:
  402.  
  403.    LIB MYNEW.LIB+WND.OBJ+WRITWN.OBJ;
  404.  
  405. LIB will create MYNEW.LIB in the current directory as the
  406. parallel file of MYNEW.QLB. It should be copied also to your
  407. program directory when it is created along with the .BI and
  408. .QLB files.
  409.  
  410. The semicolon at the end of these commands tells LIB that no
  411. other directions are necessary. Omitting the semicolon will
  412. cause LIB to prompt you for additional information. Try it if
  413. you're curious. If you type LIB alone on the command line the
  414. program will prompt you for each entry. You are allowed 127
  415. characters on the command line, so if you have a considerable
  416. number of .OBJ files to list, using LIB alone on the command
  417. line is advisable, since you are not limited to the number of
  418. .OBJ files you can list. When you run out of space on the first
  419. line, just type an ampersand (&) at the end of the line and
  420. press Enter. The Operations prompt will be repeated and you can
  421. continue entering information.
  422.  
  423. You can now create the .EXE version of your program. From
  424. within the QuickBASIC environment you determine the type of
  425. executable program you desire. BC will compile your program
  426. using defaults based on it's analysis of the program and
  427. automatically enter the LINK phase. If you choose an executable
  428. requiring the run time library LINK will use BRUNxx.LIB in
  429. conjunction with your .LIB file(s) to create the .EXE file.
  430. Advantages are smaller code which may be desirable with larger
  431. programs; disadvantages are slower execution and BRUNxx.LIB
  432. must be in the same directory or available to the program to
  433. provide support routines. If you choose the standalone
  434. executable version LINK will use BCOMxx.LIB and your .LIB
  435. file(s) to create the .EXE file.  Standalone executables are
  436. larger but run faster and are self- supporting. Additionally,
  437. using command line compiling and linking, certain options can
  438. be used to decrease program size depending on the requirements
  439. of your program. You must consult your manual for this
  440. information; they are usually .OBJ files that can be linked
  441. with your program to curtail specific unnecessary functions. To
  442. use these you MUST link from the command line.
  443.  
  444. As I mentioned above, sometimes it may be necessary to create
  445. the .EXE file from the command line. In earlier versions of
  446. QuickBASIC it was advisable to do so since smaller .EXE files
  447. could be obtained. Version 4.5 seems to do fine; QBX 7.x is
  448. even better.
  449.  
  450. First you must invoke the QuickBASIC Compiler (BC) to compile
  451. the program. The default syntax for QuickBASIC 4.x follows:
  452.  
  453. For .EXE requiring run time support:
  454.  
  455.    BC YOURPROG.BAS;
  456.  
  457. For .EXE as a standalone program:
  458.  
  459.    BC YOURPROG.BAS/O;
  460.  
  461. You will need to add /E or /V if you use ON ERROR in your
  462. program-- BC will tell you if you forget.  Add /C:512 if you
  463. use communications, to set the comm buffer size.
  464.  
  465. There are alternative methods which may be used and they are:
  466.  
  467.    BC     (and answer the following prompts:
  468.  
  469.       Source Filename: [.BAS]: YOURPROG.BAS
  470.       Object Filename: [YOURPROG.OBJ]:   press Enter
  471.       Source Listing: [NUL.LST]:    press Enter
  472.  
  473. Result: all error messages will be printed on screen and may
  474. scroll out of sight.
  475.  
  476. You may have many object files.  If you run out of space on a
  477. line, just type a plus (+) at the end and the prompt will be
  478. repeated on the next line.
  479.  
  480.    BC YOURPROG.BAS;
  481.  
  482. Result: all errors will be printed on screen and may scroll out
  483. of sight.
  484.  
  485.    BC YOURPROG.BAS; >YOURPROG.ERR
  486.  
  487. Result: all errors will be printed to a file in the current
  488. directory with name following ">". Redirection to the printer
  489. would be more functional and would not clutter up the directory
  490. as follows:
  491.  
  492.    BC YOURPROG.BAS; >PRN
  493.  
  494. Result: a printout of the errors which you can refer to while
  495. entering the proper operations which really means in the end
  496. you will be using one of the first two examples to tell the
  497. compiler what to do.
  498.  
  499. It is possible to use the same switches as the compiler. When
  500. you reach your final compilation from within the environment,
  501. use the "MAKE EXE AND EXIT" function. The options used by the
  502. QB environment will remain on the screen.  Write them down and
  503. use those options (except the /T) when you must compile from
  504. the command line.  This method is not recommended, since QB
  505. uses a lot more options than is usually necessary, which
  506. results in your programs being larger and slower than need be.
  507. Still, it's an easy way to get running in a hurry.
  508.  
  509. NOTE: Do not use /T since it turns off error messages and is
  510. only used by default within the QB environment because all
  511. possible errors have, presumably, been eliminated.
  512.  
  513. When you have successfully created YOURPROG.OBJ you are ready
  514. to use the linker (LINK.EXE). Linking is pretty straightforward
  515. as you will see. The syntax is:
  516.  
  517.    LINK YOURPROG.OBJ/EX;
  518.  
  519. If you have multiple object files and libraries:
  520.  
  521.    LINK YOURPROG.OBJ+ANY.OBJ/EX, YOURPROG.EXE, NUL, MYNEW.LIB;
  522.  
  523. Again you are limited to 127 characters on the command line. It
  524. might be more convenient to just type:
  525.  
  526.    LINK /EX   (the /EX option is desirable for optimization)
  527.  
  528. and answer the following prompts:
  529.  
  530.    Object Modules [.OBJ]: YOURPROG.OBJ+ANY.OBJ+NEXT.OBJ
  531.    Run File [YOURPROG.EXE]:        press Enter if no change
  532.    List File [NUL.MAP]:            press Enter for no map
  533.    Libraries [.LIB]: MYNEW.LIB+ANY.LIB
  534.  
  535. If you run out of room on a line just type "+" at the end of
  536. the line and the specific prompt will be repeated.
  537.  
  538. This was not intended to be a complete documentation of the
  539. special features of LIB.EXE, BC,EXE and LINK.EXE, but rather
  540. specific knowledge about common application of the programs
  541. with regards to BASIC programming and the use of third party
  542. subroutines therein.  Knowing how to manipulate libraries is an
  543. important investment of time for anyone considering creating
  544. programs no matter what particular language is used.  The
  545. knowledge gained is applicable to all.
  546.  
  547.