
Programming Notes                                         A WindoWatch feature

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


You've written the ultimate script for PCP/Win!  But you face a
dilemma:  If you release the source code to the public, with the WAX
file,  people will try modifying that source code, and when it doesn't
work, will be contacting you for help in fixing their altered code. Depending upon how complicated the source code might be and let's assume, very, such user modifications and the resulting problems might result in taking more of your time to handle than legitimate support of your own original code.

Nonetheless, you want people to be able to customize the operations of your script and to change the operation into something more suited to their needs.  Whether it is to display an alternative set of information, or dialog boxes, or whatever, how can you satisfy both their needs and still support your original code?

If you haven't already guessed that the answer is via an INI format
file, then you haven't been reading the previous columns! 

I hate to keep using GHOST BBS as an example for this column, but it is something I am intimately familiar with, and it provides convenient examples of some of the issues I want to discuss here.

GHOST BBS uses a basic INI format file (GHOST.INI) for a variety of system information. We've already discussed that file to a fair degree, not only in terms of the more standard things contained in the file, but also with respect to some of the less normal items.

However, there are still obviously more ways that GHOST uses INI format files, or I wouldn't be writing this.  I think perhaps, the best way to see how GHOST uses various INI format files is to follow what happens when GHOST is running, and a remote user calls. We'll begin after the two modems have negotiated a connection, since that procedure has nothing to do with our discussion here....

When you call a GHOST BBS system, the first thing GHOST has to know, is which of the multiple languages it supports and which one you, the user, wants displayed. If there is only one language set up, than, obviously, this is not necessary.  The first thing GHOST does is checks the GHOST.INI file for a setting which tells it how many languages the system is set up for. If it is just one, then we simply continue on.  However, if it is configured for multiple languages, GHOST then checks the GHOST.INI file to get a description of those languages in order to display a numbered list for the user,  -you- , to opt for.

GHOST takes the language number requested, reads the GHOST.INI file for a base prompt file path and name, adds the language number and the extension .PMT to it, and now knows which file it needs to read for the various prompts it will be displaying. The fact is, that the .PMT file, in spite of the extension, is nothing more than another INI format file which is used immediately by GHOST. The next item required from the user is whether or not they wish to have ANSI graphics displayed.  Note. This should be displayed in the language
which the remote user has just chosen. Therefore, GHOST accesses the PMT (prompt) file which it has just determined should be used, and locates the prompt asking the user which graphics mode he wishes, using standard INI format file read commands i.e. profilerd.

The user response to that prompt tells GHOST to use ANSI  where an integer value of 1 is set  or not  where an integer value of 0 is set. This is important, as a large number of GHOST entries in all INI files depend upon that integer value to tell GHOST where to look for something, or what to display. For that matter, GHOST uses it immediately to determine the next prompt to display. The PMT file actually has two main sections, [Prompt0] and [Prompt1] . I will leave it up to you to determine what each section is for (Hint: remember the value of the integer used to indicate whether or not to use ANSI displays?)

GHOST now goes to the appropriate [Prompt#] section, of the already
determined PMT file, and gets the prompt to be displayed asking for the remote user's name.  It is here where we come across two other INI format files used by GHOST to store data.....

1. The first one, GHOST.USR, contains quite simple entries. Because
GHOST can use multiple user record files, and has to, to over come  the 64K size limit on INI format files imposed by Windows, GHOST needs to know where a particular user's information is located. This is where GHOST.USR comes in with each entry in the format of...


[USER NAME]
UserData=x:\path\filename.ext

When a user types his/her name upon entering GHOST, it is checked here to determine the name of the single file which contains the data for that user. And this brings us to the second INI format file used here...

2.  USER#.REC  (where the # is a number from 1 to ?) which is still another INI format file which contains all data for a given user.

What if the user is not listed in the GHOST.USR file, you ask?

The answer to that query is simple, yet, at the same time, not quite as simple as it first looks!  If the user name entered is not in the GHOST.USR file, GHOST assumes that it is a new user, and confirms this with the individual, using another prompt pulled from the previously mentioned PMT file. When the user confirms that they are new, GHOST has to go through some hoops to determine what to do then.

As mentioned above, Windows imposes a size limit of around 64K on any INI format file.  GHOST takes a slightly more conservative view of INI format file sizes, at least, when it comes to the user record database. There are two reasons for this...

1.   Although the theoretical limit is 64K, in practical terms, problems
begin developing with INI files that are slightly smaller than that limit. 

2.   Each upgrade version of GHOST has, until recently, added more data to the user record information stored. The upgrade scripts in GHOST have taken care of this by writing the new user information to the REC files if and when necessary. Theoretically, it is possible for a GHOST BBS upgrade to push a user record database file over the 64K limit, unless there is some leeway available to update the records without reaching that limit.

As a result, when it comes to GHOST user records, an internal file size
limit of 55,000 bytes is imposed by GHOST. As a result, the first thing done by GHOST is to read the GHOST.INI file to determine the name of the REC file currently in use, locate that REC file, and check the size of it. If it is less than 55,000 bytes, a new record can easily be added without approaching that Windows imposed INI format file size limit of 64K.

However, if the file in question already is greater than 55,000 bytes,
GHOST won't use it.  We can't/won't  tell the user he can't log on, so back we go to GHOST.INI, to check two things.. the name of the base file to read for user records, and the number of the file currently in use, both of which are stored there.

Using that information, GHOST increments the index number it got by 1, adds that to the base file name it read in GHOST.INI, and then adds the REC extension. As example, let's assume the current user file is  M:\GHOST\USERS\USER4.REC

The GHOST.INI file will tell GHOST that the base name is M:\GHOST\USERS\USER, and the current index is 4.  GHOST increments that current index to 5, adds it to the base file name, and then adds the extension which results in a new user record file of

M:\GHOST\USERS\USER5.REC

Once the new user has entered a password, and verified it, GHOST
uses a PROFILEWR command to record the basic information for the new user, and that PROFILEWR command automatically creates the new USER5.REC file. We discussed this automatic creation of an INI format file earlier, as it is one of the nice features of the PROFILEWR command.

From here on, the inner workings of GHOST are not at issue in this
column, so we'll drop our imaginary GHOST user at this point, and review what we have discussed so far.

1.   INI format files can be used to store all kinds of information needed by a script while it is in operation.

2.   INI format files do not need to use the INI extension. They can    have any extension which you like.  It is the format of the file content
which is the critical issue.

3.   INI format files need not be stored in C:\WINDOWS. They can be stored wherever they are most appropriate.  I prefer to keep them, as much as possible, with the files they apply to.

4.  Reading from or writing to an INI format file is much simpler than doing the same thing in a non-INI format file. It involves one 

command to read, and one command to write -  with the write command resulting in the creation of the file if it doesn't already exist before the write command is invoked.

But how does this relate to  your ultimate Wasp application?

An INI format file can be one of the most useful tools you have at your
disposal.  It is not only useful for the storing of configuration inform-ation, but for the storage of  any application data that you may need. This includes information which may be optional to the application, or cause the application to branch to a different path if set. Additionally,  the information in the INI format file can be set on the fly, which makes it useful for modifying application operations also, and on the fly.

There is also another way that an INI format file can be most useful.
Using it can help eliminate one of the few drawbacks to the Wasp
language and that is the inability to pass a start up argument, singular
or multiple, to a script.

If you have done any Wasp programming at all, you may have run across this. One thing which cannot be done in Wasp and which should be fixed as soon as possible,  is to start a script with arguments on the command line.

When a script starts running under PCP/Win, it begins...period!  You can't modify how it begins through the use of command line arguments, a normal procedure in most programming languages. This kind of a procedure can be extremely useful in modifying how a script operates when it is run.

Fortunately,  in Wasp, there are three ways to work around this
limitation...

1.   If you spawn one script from another, you can use the Wasp internal global system variables (S0-9, I0-9, etc.) to pass start up arguments to the spawned script.

The drawback when doing this is that you are limited to 10 arguments of each type.  Additionally, the global system variable can be inadvertently modified by a script run before starting the one you want the argument passed to.

2.   You can store start up arguments in a text file to be read by the
script.

The drawback here is that, in order to use the file, you have to locate
it, open it, read it line by line, and locate the line that you need
within the file using STRCMP and other commands. In other words, this can be a lot of work.

3.   You can use an INI format file to store the arguments.

This eliminates the drawbacks of the system variables, since you can
store as many arguments as you like, within the 64K file size limitation.  The script has to explicitly change the entries in
the file making an inadvertent change to the value much more
difficult.

It also, eliminates the drawbacks of using a text file, because an INI format file never has to be explicitly opened as  the PROFILERD command does that automatically.  Additionally, you don't have to read in the file line by line using string manipulation commands to locate what you want.  Again, the PROFILERD command finds the exact line you ask it for, quickly, and without error or string manipulations.

The next column will be in the New Year. For us, this isn't going to
mean something completely new, as we are going to go back to our old
friend, George, whom we have left hanging for the past couple of
columns. The poor guy has been sitting there, logged on, and staring at a blank screen, for all this time, while went exploring elsewhere. So we are going to drop back in on him, and get him past the blank screen, and help him write a script that goes beyond a simple log in.

One last thing... I have found an ISP, and thus, now have a new email
address, and even a Home Page of my own. Should you have any reason to contact me, my new email address is

gregghom@ophelia.waterloo.net or, you could browse to my Home Page, where you can download a copy of either GHOST BBS or PCB Freedom, and by the time you read this,  even download my original Wasp 1.0 Tutorial, or my columns from WindoWatch.
The URL for my homepage is http://www.waterloo.net/~gregghom/

Gregg Hommel is a much respected Aspect script writer and programmer. He is well known on the various nets hosting any number of conferences. He is applying his considerable programming talents to the construct of  his own homepage and ours. Gregg sits on our Editorial Board and is a regular WindoWatch contributor. 

                         ww


