
  Programming Notes                                A WindoWatch feature

                    Window Aspect: A Scripting Language
                   A Tutorial: Part Seven Ghost BBS v3.20
                      Copyright 1995 by Gregg Hommel



 We digressed last time so let's get back to... the INI format file....

 Two columns ago, we began discussing INI format files, and using them
 under Wasp. This time, we are going to get into more specific ways to
 use an INI file to control a script or scripts, and look at some other
 examples of how they can be valuable in script writing.

 There is one aspect, no pun intended, of INI format file use that I
 have fallen back on time and again which can be very helpful during the
 writing stage of a script.  I began using it because A) compile time on
 my old, now upgraded,  386SX20 machine were dead long, and B) my wife
 is far from a computer expert. Although this example of using an INI
 format file is derived from GHOST, it can be applied to any script in
 the experimentation stage of new coding.....

 As I said, my wife is not a computer expert... she knows the programmes
 she needs to know for work, and so on, but certainly doesn't use GHOST
 frequently, since that is my baby.  She knows how to start and stop
 GHOST, how to change certain settings using the GHOST utilities, and
 even how to edit a text file.  I wouldn't want to walk her through
 locating source code, editing it, compiling the result, and then moving
 that compiled file to the directory where GHOST expects to find it.
 Even talking her through locating where, in some 8,000 lines of code or
 more, a particular section is located, would be a real challenge. In
 truth,  I sometimes can't remember where important lines of code are
 located and must go searching too.

 I decided to use my INI format files to help out. I created a temporary
 entry in the [DOS Comm] section of GHOST.INI where other parameters
 controlling the operations of GHOST under DOS are stored -  like this
 DOS_Pause=2

 I then modify the code in GHOST from a simple PAUSE 2 that I
 needed to recompile before testing, into this...

   profilerd S0 "DOS Comm" "DOS_Pause" pauseval
   if pauseval > 0
      pause pauseval
   endif

 I recompiled the code with this code in it, and went off to the other
 location to test things. It still didn't work, so I had my wife edit
 GHOST.INI to change DOS_Pause= from 2 to 5. She saved the changes, and
 I tried to open a DOS door again, knowing that now GHOST would pause
 for five seconds before actually opening the door.

 In this way, I was able to use the INI format file to allow me to
 perform multiple tests of the same code with a minor change done,
 without having to recompile the code in between tests.

 This same concept can be used if you want to test multiple code
 routines to handle the same thing, i.e. a conditional running of
 certain code that can be easily changed to test different code without
 the need to recompile between tests.

 Suppose that you have an INI format section named [Testing], with a
 line

   use_code= which is set to an integer value, to start with, a 1.

 In your source script, you have something along the lines of this...

   profilerd inifile "Testing" "use_code" testval
   switch testval
      case 1
         ;use this code to handle the situation
      endcase
      case 2
         ;use this code to handle the situation
      endcase
      case 3
         ;use this code to handle the situation
      endcase
      case 4
         ;use this code to handle the situation
      endcase
      case 5
         ;use this code to handle the situation
      endcase
   endswitch

 Simply by changing the value of use_code= in your INI format file, you
 could test five different methods of handling a certain situation. One
 can determine from that, which of the differing code ideas best handles
 specified procedures without having to re-code and re- compile between
 each test.

 In the end, you might even decide to leave some of that code in the
 script, to allow you to easily customize the operation of it at any
 point in time, or if you distribute it for others to use.

 But there are a multitude of other ways you can use an INI format file,
 in place of a text file. GHOST uses INI format files for a lot of
 things, so let's look at those files under GHOST to see how else you
 might use an INI format file.

 1) The main GHOST IN format file is GHOST.INI and it is used to store a
 whole host of settings that control the actual operation of GHOST.
 However, there is much more here than meets the eye..

 When you first start GHOST, you actually don't. What you really are
 starting is the GHOST launcher script, called GHOST.WAX, in your
 \ASPECT subdirectory.  In the interests of keeping that subdirectory as
 clean as possible, I really didn't want to put everything to do with
 GHOST BBS there. GHOST uses a fair number of support files, and putting
 them all in \ASPECT could really clutter things up.

 So, GHOST allows you to store everything but three files (GHOST.INI,
 GHOST.WAX, and GHSTUTIL.WAX, the utility launcher) in directories of
 your own choosing.

 This is great, except that the GHOST launcher script has to know where
 to find them, so that they can be used.  The GHOST.INI file contains
 all of that information. Many of the entries in GHOST.INI are pointers
 to tell the various scripts which make up GHOST in it's entirety, where
 to find other scripts or support files that might be needed.

 There is a side effect to this.  When I release an updated version of
 GHOST, I can include an install utility to do the update for the end
 user. I don't have to know where on their system, they have put the
 various GHOST files. All that the GHOST install utility has to do is
 read their GHOST.INI file, and the install script knows exactly where
 to put the new file.

 2) One of the biggest complaints I heard about the old PCP/Win 1.0x
 Host script, and to a lesser degree, about the newer PCP/Win 2.xx Host
 script, is that it would make changes to your PCP/Win set up in order
 to run properly, and then would leave those changes in effect after it
 shut down.  These changes would make the use of PCP/Win afterwards, a
 nightmare for the user.

 GHOST BBS makes every effort to avoid this. And to do so, it uses
 the GHOST.INI file.

 When you first launch GHOST, one of the first things that the launcher
 script does, before actually launching the runtime script for GHOST, is
 that it reads various settings from your current set up. These settings
 are for settings that GHOST is going to change in order to function as
 a host, and are therefore, the very same settings  to be reset when
 GHOST is shut down. The GHOST launcher script writes these settings it
 has read, into a special section of the GHOST.INI file. When the
 runtime script begins, it can freely change these settings to whatever
 is appropriate for GHOST operations and without concern.  When you exit
 GHOST by shutting it down, control is returned to the launcher script,
 which reads all of the original settings, and then restores them to
 their original condition.

 However, there is one other feature to this.  When GHOST changes the
 settings, it also sets a "flag" entry in that same section of
 GHOST.INI. If, for some reason, GHOST is terminated abnormally, and
 your system is NOT restored as you would expect, there are two
 remedies.

 When you re-start GHOST, and let's assume it is in your StartUp Group,
 and a power failure is the cause of the abnormal termination of GHOST.
 Once power is restored, your system starts back up, and because GHOST
 is in the StartUp Group, it also re-starts the GHOST launcher. It will
 be able to tell, by that flag entry in GHOST.INI, that your set up
 under PCP/Win was changed, and was not restored to "normal".
 Therefore, the  launcher, this time, doesn't read your system settings,
 but instead, just re-starts GHOST. When GHOST is finally terminated
 normally, the original settings remain to be restored.

 The second remedy  is when you don't restart GHOST, but know or suspect
 that it was terminated abnormally the last time you ran it. There is
 one other script which GHOST installs in your \ASPECT subdirectory,
 called GHOSTFIX.WAX. All you have to do is to run this script, and
 GHOST will check that INI file flag. If it is set wrong, GHOST will
 offer to restore your original system settings, in the event that any
 remain behind and were not properly reset with the abnormal termination
 of GHOST.

 3) Here's one use for an INI file that GHOST 3.20 doesn't use, but
 GHOST 3.10 for PCP/Win does. It might prove useful to you in your
 script writing because an INI file setting can be used to pass
 information from one script, to another.

 GHOST BBS 3.10 is written as a series of modules to get around the
 PCP/Win 1.0x limits on memory. However, most of those module scripts
 need information being held in the main script, in order to run. This
 information can indeed, be passed by setting a system global variable
 such as I0 or S0,  even though at times, it can be difficult to track
 those variables with the possibility that you might pass the wrong data
 to another script.

 However, if you write the data to an INI file entry, and then, when the
 secondary script begins running, it checks that INI file entry for the
 data it needs, you have passed the data without worrying about keeping
 track of what the system global variables are holding.

 4) When a user logs on to GHOST, certain information about that user
 needs to be used regularly throughout their log on. This is suited to
 storage in global variables. However, other information on that user is
 needed only at certain points in the script, and it seems silly to
 waste good global variable memory space on something like that. As
 example, when you open a DOS door in GHOST, certain information on the
 user opening the door, along with various system settings, such as baud
 rate, parity, etc. have to be included in what is called a drop
 file-DOOR.SYS for the DOS BBS door to read and use. But they are only
 needed then, and not elsewhere in GHOST. Other information in the drop
 file never changes, such as the BBS name.

 The drop file (DOOR.SYS) is a text file, and as we all know, trying to
 locate and change one or several lines in a text file can be done in
 Wasp, but it involves a fair bit of code to accomplish. GHOST does it
 the easy way... it stores all of the information needed in the drop
 file, in a special section of the GHOST.INI, listed as Line#=, where #
 is the line in the drop file where that information must be recorded.

 GHOST uses what is called a 32 line, GAP standard drop file, called
 DOOR.SYS for DOS door information. When you log on to GHOST, the
 personal information about that user required in the DOOR.SYS file is
 written to GHOST.INI. When a door is opened, the specific system
 information existing at the time (baud rate, parity, stop bits, etc.)
 is read and written to the appropriate places in that same INI section.
 To change the appropriate lines in the DOOR.SYS file is now a simple
 task, because we don't actually change those lines. Instead, we create
 an entirely new DOOR.SYS file, with the appropriate information in the
 correct spots.  To do so is a simple for/next loop, like so....

 fopen 1 door_file CREATE TEXT
 for i = 1 upto 31
    strfmt _line "Line%d" i
    profilerd IniFile "DoorSys" _line TempVar
    fputs 1 TempVar
 endfor
 fclose 1

 which should, by now, be a fairly simple code segment to follow. All it
 does is create a new DOOR.SYS file, read the lines from the INI file,
 starting at Line1= and finishing at Line31=, putting the results of that
 INI file read into the DOOR.SYS file after it has been read.  Voila! A
 new DOOR.SYS file, with all the current, and correct, information is
 created in a flash.

 We've only just scratched the surface in using INI format files, but
 heaven forbid that our esteemed Editor-in-Chief, Lois, the ogre, should
 accuse me of being too long-winded in a single column, so we'll stop
 here for this month, with a summary of the uses noted above for INI
 format files. Please study this carefully, as questions on it may be on
 next month's oral examination <g>...

 The "Summary" so far...

 1) INI format files can be used, when writing a script, to test various
 optional code segments, and determine which one does the best job,
 without requiring that you edit the source code, and recompile for each
 test.

 2) An INI format file can allow you to use support files for a
 given script, and to store those support files in locations other than
 the main \ASPECT directory.

 3) An INI format file can be used to store certain settings not necessarily
 needed by the current script, but perhaps needed to restore the system to
 its original state when the current script is done.

 4) INI format files can be used to pass data from one script to another,
 even if the two scripts are run in different PCP/Win sessions.

 5) Sometimes, only a text file will suit.

 But an INI format file can be used to store the information required in
 that text file, even if set at scattered locations throughout the
 script, and then used to create the text file when needed.

 Next month, we'll look at other INI format files used by GHOST, how
 they are used, and some ways that GHOST uses information stored in
 multiple INI format files to personalize various aspects of a GHOST
 logon....

 One last thing... If any of you are interested in pursuing the topics
 discussed in this column, or any other Wasp related topics, on a more
 personal basis, you are welcome to contact me to initiate a one-on-one
 discussion. I can be reached several ways. Email on the Internet is
 often the fastest, and most reliable.

 My email address is gregg.hommel@canrem.com or if you have Compuserve
 access, my CIS ID is 72537,552. If neither of those suits, I can also be
 reached in the Windows and Procomm conferences of RIME, NANet and ILink,
 and the EchoNet and FIDO Windows conferences. For R/RO mail on RIME, my
 node is ->118, and for FIDO netmail, my FIDO node is (1:229/15).


 Gregg Hommel is a much respected Aspect script writer and programmer. He
 is well known on the various nets hosting any number of conferences.
 Gregg sits on our Editorial Board. Comments concerning this or earlier
 tutorials can be directed to him as gregg.hommel@canrem.com

                         ww


