UserBase v2.50
User Manual
Table of Contents
UserBase License Agreement:
Distribution of this software: UserBase is freeware. You are hereby licensed to make any number of backup copies of this free software and documentation. You can give the copy of the software to anyone or distribute the freeware version of the software providing that no additional fee is charged and the package files are not modified in any way.
The supplied source code may be modified and reproduced freely, within the following restrictions:
- any new application produced in part or whole from the UserBase source code can not be named soley Userbase.
- New applications developed in part or whole from the UserBase source code may only include the word UserBase in the application name and title where the new application is backwards compatable at a functionality level with the existing UserBase application.
- New applications developed in part or whole from the UserBase source code must acknowledge UserBase in its documentation, and provide a reference link to the Userbase home page (http:\\www.myaddons.com\userbase).
- Exceptions and clarifications to the above restrictions may be granted, but must be requested in writing
Disclaimer of Warranty: This software and the accompanying files are supplied as is and without warranties as to performance or merchantability or any other warranties whether expressed or implied. Because of the various configuration options and purposes for which this tool may be used, no warranty of fitness for a particular purpose is offered. Any liability of the seller will be limited exclusively to product replacement.
Acceptance of Terms: Installing and using UserBase means the acceptance of these terms and conditions of the license. If you do not agree with the terms of this license you must remove UserBase files from your storage devices and cease to use the product.
July 2003
What Is UserBase?
UserBase is a server RAD application. There is no user interaction with the application directly, although the various features and options can be configured using the UserBase Monitor tool, which is installed in the Monitors folder (FirstClass Services folder on pre-FC7.0 servers).
What Does It Do?
Every time a user account is created or changed, every piece of information contained on the user profile form is extracted out and recorded in an Access database.
When a user logs in, a check is made to see if they already have a record in the database; if not they are added. When a user is deleted, they are removed from the database.
How Does It Work?
Every time a user account modification occurs, a statistics event is generated by the FirstClass Server. The RAD app is triggered, and the user is added to the queue.
Each action is assigned a different priority – the higher the priority, the more important the action e.g. a user login is assigned a priority of 1, while a user being deleted is assigned 4. If a user is already in the queue, but an event occurs with a higher priority, the queue entry is replaced with the higher priority.
The queue is processed (how often and how many records at a time is user configurable through the Monitor) and the user information extracted into the database.
Requirements
UserBase requires RAD 2.0 Build 1035 or higher to be installed on your FirstClass Server. UserBase will work on any FirstClass Server version 5.5 or above. UserBase needs Statistics logging to be turned on, with a minimum of Session (login/logout) and Add/Del/Change user being logged:
Installing UserBase
Follow the steps outlined below to install UserBase:
1. Check the above requirements section to ensure you met them.
2. Stop your FirstClass Server
3. Run (double-click) on the UserBase Setup.exe application program and follow the on-screen prompts.
4. When prompted for the location to install the application, select the root of the volume containing the primary FirstClass Post Office folder (FCPO). \FCPO\ will automatically be appended to the installation path by the installer.
5. When the installation process has completed, restart your FirstClass Server. Several batch files will be processed and you should see the following message on your FirstClass Server console, indicating the application has installed and loaded correctly:
Using the UserBase Database
UserBase doesn’t do much in itself. The idea behind UserBase is to extract the user information, and make it available for other RAD applications.
The UserBase database is called UserBasedb.mdb, and can be found in the FCPO\FCRAD\DATA Folder. The Table that contains all the user information is called Userdetails.
Each Column of the table corresponds to a field on the form. The columns are named using the format <D/M><server version><field number><data type> e.g.
The users last name information is stored in column D62120400, where 62 refers to FirstClass Server version 6.2, 1204 is the field Id on the User Profile form that contains the users last name, and 00 corresponds to the text field type. If the field begins with M instead of D, it is a mailbox field. The only exception to the above is the two date fields - Last Login and Date Created. If the server version number for these two fields is 00, then the value returned from the server is stored in human readable date format. both columns can coexist in the same table e.g. D00123514 would store the value in date format, and D55123514 would store the value as a signed integer.
A description of each field in the database is also available when the table is viewed in Design mode within Access.
UserBase Monitor
The UserBase Monitor is added to the Monitors folder (post FC6 servers) or the FirstClass Services folder (pre FC7 Servers) during the install process, and allows you to monitor the progress of the UserBase application, as well as configure the various options.
Status Indicator
The Lamp indicator shows the status of the UserBase application. It will be one of three states:
Colour Message Meaning
Green Running UserBase is running correctly
Yellow Stalled UserBase is loaded, but not capturing user details
Red Not Running UserBase is not loaded
Clicking on the lamp will allow you to load/unload the UserBase application as needed.
Reliability
By default, UserBase doesn’t extract every users details into the database the minute it is run (although this can be configured – see “Synch Now” below). Instead, each time a user logs in, a check is made to see if their details exist in the database; if not, they are added. So the UserBase database will not contain every FirstClass users details i.e. be 100% reliable, until every user has logged in at least once since the UserBase application was started.
The Record breakdown shows the number of users, by type, both on the server, and stored so far in the database. The resulting percentage does not take into account users or groups listed in the Skip List so may never reach 100%.
Pending Records
Indicates the number of user records sitting in the queue, waiting to be processed.
Activity Settings
The following group of options/values control how often the user information is extracted, and how much information is extracted.
Poll Interval How often (in seconds) the pending records queue is processed. If the Poll Interval is set to 0, records are processed in real-time i.e. the queue is by-passed.
Process Number How many pending records to process on each poll of the queue. If there are more records queued than the number specified to process, then the balance of queued items will carry over into the next process cycle. The Process Number default setting is to process them all. If the Poll Interval is set to 0, this setting is ignored.
Refresh Interval How often to refresh the UserBase Monitor while it is running.
Log State The level of detail to log (1 being the least detailed, 5 being as much detail as you can handle). Where the log is output to is specified by the Log To setting, described below.
Force On Login Forces the users record to be extracted to the database each time they log in, regardless of whether it exists already. See explanation below of why you would want to set this.
Log To Can either log details to the server console, or, to the server console and the FirstClass log files.
Version Indicates the version number of the UserBase application, and the database that is being used.
Online If Force On Login is set to anything other than No, the Online indicator will show the number of users currently online.
Forcing update on Login
Normally you would only want the database updated when a change occurs to user information within the FirstClass Server. Extracting out all the user information each time a user logs in would normally be an unnecessary overhead.
However, if you run other RAD applications on your server that make changes to a users information, this change won’t be captured in UserBase unless you are running FirstClass 6.0 or higher, but excluding FirstClass 7.0 (where this feature was brocken again), or the RAD app is UserBase aware i.e. the RAD app adds the user to the process queue itself. The reason for this is that UserBase is driven by statistic events, triggered by the FirstClass Server. At present, a RAD application making changes within the FirstClass environment on a pre-version 6.0 FirstClass Server, or a 7.0 FirstClass Server doesn’t trigger a statistic event, and is therefore missed by UserBase.
Refresh Now
Updates the UserBase Monitor screen immediately
Purge Now
Deletes all the records in the UserBase database, starting afresh. Purge Now can be used to clear any combination of the Pending Queue, the Online Status value or completely delete all user records in the database.
Synch Now
You can force UserBase to record all your existing user details in one go. Note: this is dependant on the last Trash Collection having completed successfully as the \FCPO\STATS.DIR\diskuse.txt file is used to read in the user detals.
Skip List
Every piece of user information is extracted by UserBase, including passwords. There are going to be accounts you don’t want extracted out e.g. the Admin account.
Any userid added to the Skip List won’t be added to the UserBase database.
If you add a Privilege Group to the list, all members of that group will be excluded from the UserBase.
Settings
Buffer Size
Newer versions of RAD supported the ability to retrieve large amounts of information back from the server. In earlier versions of UserBase, the routine that pulled the information out of lists on the user form (e.g. the list of privilege groups the user is a member of) had to request the information a line at a time. When RAD 2.1 was released, the whole list could be retrieved in one request - making it a much more efficient process.
The Buffer Size setting refers to the size of memory to reserve for retrieving these lists. The default setting is usually more than enough to accomodate the user with the most information.
Developing Applications for UserBase
UserBase was designed with the developer/administrator in mind. Having every piece of user related information in a searchable database can be very useful.
Extracted information is stored in the UserDetails table in the UserBasedb.mdb file.
Each column in the table (with the exception of the Record column which is used as a unique reference) relates to one of the fields of information on the User Information form in FirstClass.
With the exception of the Userid column (which is just called UserId) the fields all use the following naming convention:
Position Possible Values Description
1 D, M, P or Z M means the field relates to the POP account mailbox form for the user (a sub-form of the User Information form).
P means the field relates to the users Preferences settings.
D means the field relates to any of the fields on the main User Info form
Z is a user defined field and will be skipped
2-3 0-9 A 2 digit number referring to the version of FirstClass Server that this field is first supported in (so that an attempt to extract newer user information from an older version server doesn’t occur)
If the value of this field is 00, and the field is a date field on the main User Info form, then the date will be stored in the database in human readable format.
4 - 7 0-9999 The actual Field Id as used in FirstClass of the information field being extracted. This will vary in length between 1 and 4 characters long.
Last 2 0-14 The data type as assigned by FirstClass of the field being extracted.
e.g. D55120400 refers to data (D) field 1204 (users last name) of type 00 (text) on FirstClass Server version 5.5 (55) or higher.
D00123514 refers to data (D) field 1235 (Time and Date The Account Was Created) of type 14 (number) on any server version. The 00 indicates that it should be stored in Date format.
P55110306 refers to field 1103 (Enable sounds during chat ) on the Preferences form (P) of type 06 (checkbox) on FirstClass Server version 5.5 (55) or higher.
M62200100 refers to field 2001 (Users POP Account 1 Username ) on the POP Mailbox form (M) of type 00 (text) on FirstClass Server version 6.2 (62) or higher.
Accessing Information in a Project
The UserBase database can be accessed like any other database from a RAD project. When establishing the connection to the database, it is recommended you use a static, ReadOnly cursor type e.g.
stmtDetails.OpenStatement(cnctDBase, dbStatic, dbReadOnly)
If you want exclusive access, or need a more powerful (e.g. dynamic etc) connection type, you should lock the database by incrementing the Lock Column in the Settings table by 1.
Your application should respect the lock status; if the lock value is less than 0, then the UserBase server application is updating the table at that point in time, and your application should wait for this process to finish before trying to lock the table e.g.
If SerVer < 61 Then
' Lock down the userbase polling sequence
stmtUBSettings.Refresh
Do While stmtUBSettings.Column("Lock") < 0
frmMain.txtCount = "Waiting for UserBase to Free Queue..."
Sleep(5)
frmMain.txtCount = "Repolling Queue..."
stmtUBSettings.Refresh
Loop
stmtUBSettings.Column("Lock") = stmtUBSettings.Column("Lock") + 1
stmtUBSettings.Update
End If
The above code snippet checks to see if the table is currently in use by UserBase (Do While stmtUBSettings.Column("Lock") < 0). Once the table is freed up, the table is locked (stmtUBSettings.Column("Lock") = stmtUBSettings.Column("Lock") + 1), preventing UserBase from updating the table while you are using it.
The lock is really only needed if you are updating the queue, and are running on a pre-6.1 version of FirstClass Server (If SerVer < 61 Then).
Updating the Queue
If your application is running on a pre-6.1 server, and you make changes to a Users Information form, you will need to add the entry to the Queue table
To add a user to the queue so that their account is processed by UserBase, add the appropriate userid to the UserId column, and the appropriate action in the Action column.
Action is a numerical value representing what has occurred:
-1 The user has logged in. Only update their online status.
1 The user has logged in. If Force on Login is set to Yes (in the UserBase Monitor), the record will be updated; otherwise the entry will be ignored.
2 The User Information form has been edited and the record will be updated
3 The User Account has been created, and a recorded will be added
4 The User Account has been deleted, and the UserBase record will be removed.
As mentioned above, you only need to manually manipulate the queue is you are using a pre-6.1 version FirstClass Server. If this is the case, remember to lock down the table first (as described above) and (very important!) don’t forget to unlock the table once you have finished e.g.
If SerVer < 61 Then
stmtUBSettings.Column("Lock") = stmtUBSettings.Column("Lock") - 1
stmtUBSettings.Update
End If
Data Shorthand
The ‘ character can not be directly stored in a database. Hence, UserBase converts it to a /+
So, when retrieving data remember to convert the sequence back to the appropriate character e.g.
' Convert any embedded ' characters back from the Userbase /+ format
frmContact.txtName = Replace(frmContact.txtName,"/+","'")
Also note that multi-line fields on the FirstClass User Information form have the End of Line symbol converted to a \r when extracted, so these will also need to be converted e.g.
frmContact.txtNotes = Replace(stmtDetails.Column("D55122400"),"\r",Chr(13))
| 
