Operating Environment
Worldgroup The Major BBS is designed as a central hub (MAJORBBS.EXE) which governs free-standing (and therefore easily interchangeable) modules.
...
Finally, a module can be set unconditionally Active. Language modules, for example, are set to become active as soon as the Worldgroup Major BBS server comes online, without need of outside prompting from either the Menu Trees or from other modules. Unconditional activation is set within the module’s own .MDF file.
Module Definition Files: .MDF
Applies to: WG3.x
Editor's note: in WG3.x the
.MDF,.MSG,.HTM,.CVTand.DMDfiles of a project may be#ifdef'd on any define passed to the build (chapter 21, "#ifdef'ing files"); an install script for an add-on is described in chapter 23 (InstallShield). Btrieve.VIRfiles can be built from the.MAKfile (chapter 21, "Creating .VIR files from within .MAK files").
Module Definition Files are how Worldgroup the Major BBS recognizes many aspects of your Add-on Option. They provide information on:
...
Here are some details about what to put in your .MDF file.
Comment Header
This is the name of the .MDF file. Note that a semicolon ; at the beginning of any line labels that line as a comment.
Module name
This description of the module appears when designing module pages in the Menu Tree. It will also appear on the miscellaneous statistics screen and in Basic Utility WGSDMOD. Use gmdnam() to read in this description — see page 44. The name may be up to 24 characters long.
Developer
Your name or company name.
Requires
If your module will require that any other modules be active, name them here. You might use this if that module exports symbols that you use. When several modules all require each other, use a circular definition. For example, GALFOR.MDF requires GALTLC.MDF, which in turn requires GALEML.MDF, which itself requires GALFOR.MDF again. You can list up to five .MDF files.
Replaces
If your module replaces another, name the other module here. For example, Galacticomm’s Entertainment Collection has an Entertainment Teleconference that replaces the Teleconference that comes with the standard version of Worldgroupthe Major BBS. Note: the Requires and Replaces logic work well together, such that if module A requires module B, and module C replaces module B, then module A’s requirement is satisfied by module C being present.
Note: be sure not to Replace a module that has exported symbols, even if your module exports the same symbols.
Install
If any special installation procedures are required, call out the .EXE, .COM or .BAT file here (just the root of the filename, not the extension, like you’d type in a DOS command). This file will be run only when the module is first installed on a Sysop’s computer, and then is automatically deleted. The presence of this file acts as a flag to find out whether installation is needed or not.
Online user manual
You should write a brief but thorough help topic in a normal text file, aimed at the audience of terminal-mode users, and name this file here. The convention is to use the same name as the .MDF file with a .DOC extension.
...
To provide help text geared to the C/S-mode side of your application, you’ll create a Windows .HLP file referenced by the client app (the Windows .EXE file) you create. See Client App Guide for more details.
DLLs
Name the .DLL Dynamic Link Library (or Libraries, up to five of them) for your module. See page 23.
MSGs
Name the .MSG files that contain CNF options (for the Sysop to manage in Hardware Setup, Security & Accounting, Configuration Options, and Edit Text Blocks). More about CNF options starting on page 79.
Btrieve page size
If your Add-on Option uses any Btrieve databases of its own, you must name the maximum page size in bytes. This is also specified in the .BCR files for creating the databases. If you have purchased Btrieve in order to create your own databases, see the Btrieve documentation for more on page sizes.
Btrieve files
This is the number of .DAT Btrieve database files that your Add-on Option will have open at a time. We keep all .DAT files open for the entire time the Worldgroup Major BBS server is up.
Dynamic Btrieve Files
The Btrieve files line in your module’s .MDF file is intended for the “core” (fixed) Btrieve files required by your module. If your module needs a variable number of additional Btrieve files, you can count them in the Dynamic Btrieve files line in your .MDF file.
...
As it does with module names, INSTALL will maintain the current Dynamic Btrieve files lines when installing updates to .MDF files, while updating the standard Btrieve files line.
Cleanup
Name an .EXE or .BAT file to run when the Worldgroup Major BBS server shuts down for auto-cleanup. You can have multiple Cleanup: lines with multiple DOS commands. These commands are executed before Worldgroup the Major BBS runs the Sysop-configurable BBSCLEAN.BAT file.
Event-1 through Event-4
Name an .EXE or .BAT file to run when the Worldgroup Major BBS server shuts down for any of the timed events. These commands are executed before Worldgroup the Major BBS runs the Sysop-configurable BBSEVT?.BAT files.
Add-On Utility
If you want an offline utility to appear in the menu from option 8 of the introductory menu, specify the .EXE, .COM or .BAT file and description of the option. For example:
...
The file DDDANLYZ.BAT (or DDDANLYZ.EXE, etc.) will be run if the operator picks that option. For aesthetics, we recommend that you fit the name within an 8-character left-justified field, capitalize the entire name, follow it with one space, and append a lower-case description in parentheses. The description can be up to 40 characters long.
UNCONDITIONAL
If this word appears on a line by itself anywhere in the .MDF file, then your module is loaded unconditionally (whether something in the operator’s Menu Tree calls for it or not).
INTERNAL
If this word appears on a line by itself anywhere in the .MDF file, then your module won’t appear in the list of choices for module pages. If your module is an INTERNAL module, you’ll usually want to make it also an UNCONDITIONAL module. If you don’t, the only way this module can become active is if another (active) module Requires it.
I need, Needs me
If a system has terminal-mode module pages in its C/S-mode Menu Tree, C/S-mode users who select these pages will temporarily suspend C/S activities and drop into terminal mode. Common uses of this include the Menuing System (terminal mode’s Top page), the Remote Operator Menu, and Doors.
The I need field in .MDF files lists which other modules are required in order to properly operate in this circumstance. The Needs me field activates this module whenever any of the modules named in this field are accessed in terminal mode by a user dropping down from C/S mode. See page 124 for more details.
Agent version, Client app..., and Default Icon
These C/S constructs are covered in Agent Developer’s Guide and Client App Developer’s Guide. They have nothing to do with terminal mode.
Shared support files
Applies to: WG2+
In addition to the standard Client app support files line you use in your app’s .mdf file, there is now an additional Shared support files line. Unlike the standard support files line where the files are transferred to your app’s directory on the client, shared support files are transferred to the \windows\system directory on the client. This allows certain support files to be shared between apps. Given this, most VB3 apps have something like the following in their .mdf files:
...
Applies to: WG2+
Header check (GALNSSF.H, new in WG2): the list of Shared Support Files that were automatically included in Worldgroup 1.x (and are not in 2.x+) is the space-delimited macro OLDSSFLS: BC30RTL.DLL GCSPCLI.DLL GALCBK.VBX GSWDLL.DLL SS3D2.VBX MSAFINX.DLL VBRUN300.DLL GSW.EXE ANIBUTON.VBX GRAPH.VBX KEYSTAT.VBX MSMASKED.VBX MSOUTLIN.VBX PICCLIP.VBX SPIN.VBX THREED.VBX. A .MDF with no Shared support files line is treated as a v1.x app and is assumed to need these.
Startup function
Applies to: WG2+
Start-up apps continue to work as described in the Client App Developer’s Guide. Additionally, an agent can control whether or not a start-up app is automatically run for a particular user. When the server is thinking about telling the client to run a start-up app, it can call a particular function in an agent (with the current user in context with things like usrnum and usrptr). This function can return TRUE to allow the start-up app to be run or FALSE to not.
...
Applies to: WG2+
Header check (INTEGROU.H): struct moddat gains the member
char *stfunc("startup app permission function name"), which holds the name from this line. In the shipped source (BBSMAINM.C) it is resolved with DosGetProcAddr() and, when non-NULL, called as(*cur->stfunc)()before the start-up app is run for the user.
Server clean-up
Applies to: WG2+
No one expects an updated app to, when installed on the server, clean up any old revisions of itself. To keep from filling up a Sysop’s hard drive with old client files, Worldgroup the Major BBS itself handles such clean-up. Whenever a version of Worldgroup the Major BBS is installed, a utility runs to clean up old revisions of client apps from the server app directories.
...
Don’t put files in your app’s server directory unless they’re named in the app’s .mdf file (as client app EXE or support file). You can create subdirectories off of your app’s server directory for such files.
Language .MDF Files
Here is an example of an .MDF file for the German/RIP Language:
...
Language module .MDF files have a few additional constructs:
Language
The language name has a 1-8 character spoken language followed by a slash (/) and a 1-6 character terminal protocol. That’s a total of up to 15 characters.
Language Description
This description can be up to 40 characters long. It shows up when picking a language out of a list, as in the CNF F3 CHOOSE LANG softkey, or online when users pick a language.
Language File Extension
A file extension may be needed to store text for this language on disk. This comes up when customizing menus under Menu Tree or editing CNF options with certain custom editors.
...
For CNF options, a temporary file is created for external editors when they specify a DOS command line. The Language File Extension will be used on that file.
Language Editor
There are two cases where an editor is needed: CNF text blocks and Menu Tree customized menus. WGSDRAW is the standard in-memory editor and is specified like this:
...
Any %s in the language editor command line gets replaced with the name of the file to be edited.
Language Yes/No
This line of the language .MDF file tells you what words to use for Yes and No in that language. For example:
...
There may be conflicts when certain prompts expect Y=yes, N=no or other special characters. First, you should avoid words that start with either ? or X, as those characters have other universal meanings within Worldgroup the Major BBS (Help and Exit). Also, a yes-or-no word that starts with R will conflict with the highly visible situation where users can choose (Y)es=logoff, (N)o=stay online, or (R)elog on.
...
You can see that BBSMAI.MDF has the standard .MDF information combined with language information for the English/ANSI language.
Initialization Routine: init__xxx()
Worldgroup The Major BBS will recognize any routine in your .DLL whose name starts with init__ (that’s two under_scores) as an initialization routine, and call that routine when the Worldgroup Major BBS server comes up. In your initialization routine, be sure to:
There must be exactly one init__ routine in every .DLL. The one routine will initialize the module for both terminal mode and C/S mode as necessary. See Agent Developer’s Guide for more information on C/S-mode aspects of the initialization routine.
Declare it as EXPORT (page 21). Register your module with register_module() (page 43). Open the CNF options file (.MCV in run-time) using opnmsg() (page 91). You can read in options using routines like numopt() and ynopt(). Open any Btrieve databases you’re using with opnbtv() (page 280).Declare how much if any of the Volatile Data Area that you’ll need to service users, using dclvda() (page 68).Allocate memory if needed. Use the Volatile Data Area if at all possible. Register global commands with globalcmd() (page 135).Prepare enough VDA memory for any Full Screen Data Entry sessions using fsdroom() (page 143) and dclvda().Register text variables with register_textvar() (page 102).Kick off any rtkick() routines (page 316).Modules
A module is the main mechanism for making your code run on Worldgroup the Major BBS while online. There are other ways to run online code, like text variables or global commands, but modules are by far the most powerful.
...
Here are the items to remember when making a module for Worldgroupthe Major BBS:
Put your initialization code in a routine whose name starts with init__ (see above).In that initialization code, register your module using the register_module() function and a unique module structure. Compile and link your module code into a .DLL file (page 23). Identify the .DLL file in your .MDF file (page 32). For example:
...
Note: if the Module name field in one .MDF file matches the Module name field in another .MDF file, Worldgroup the Major BBS will complain to the Sysop at startup, asking which module to delete or rename.
Naturally, DOS will not allow two identical filename.exts to reside in the same directory, so there will never be two .MDFs with the same filename installed on the same Worldgroup Major BBS server. The INSTALL program will overwrite the existing file with the new file of the same name. If this is an update, this is desirable. Strict adherence to Developer-ID naming conventions will prevent accidental sharing of a single name between products of different developers.
Any of the entry points can be NULL if you don’t need them, except: stsrou() (make it dfsthn if you don’t need special status handling, like in the above example); and sttrou() (make it point to a function that returns zero if your module has no menu-selectable interactive services). The above example sets up to call the colorinp() for text input and clscol() when the Worldgroup Major BBS server shuts down.
Variables Available to Many of the Entry Points
These global variables are set up by the executive before calling any of the entry points lonrou(), sttrou(), stsrou(), lofrou(), or huprou():
...
Each user’s session on the Worldgroup Major BBS server is a procession through a series of states. The states distinguish conditions like “waiting for him to type in his User-ID”, “waiting for him to type in his password”, or “waiting for him to decide whether to thread forward or backward from this forum message”.
...
char *vdaptr; points to the Volatile Data Area. This is memory allocated for a channel, and used by the routines of a module — but used only while the module is selected for that channel.
...
Logon Input Service Routine: lonrou()
...
You can use this entry point to give a user some kind of notice when he is logging on, such as “Our stock price rose 4 points yesterday”. You can also use lonrou() for a protracted interactive session with the user — a series of questions and answers, or prompts and commands that he goes through right after logging on, such as “would you like to purchase more shares now?”, “Ok, how many?”, etc. This all happens before the user has a chance to make a selection from the Top menu.
...
Note: to intercept the moment when a user first connects to the Worldgroup Major BBS server, use the handle-connect vector (*hdlcon)() as described further on page 115.
For special handling of new users who have just signed up, you could maintain your own separate database of User-ID-tagged information and, during lonrou(), look for the case when usaptr->userid isn’t in your database yet... and then insert it of course.
...
Module Input Service Routine: sttrou()
...
sttrou() is the most heavily used entry point for most modules. It is first called when a user selects your module (selects a module page that refers to your module from a parent menu). After that, sttrou() is called each time a user enters a cr-terminated input line while “in” the module. He gets “out” of the module (returning to the parent menu) when the sttrou() routine returns 0.
...
We also recommend that whenever the user just presses enter (so that margc == 0), that you re-transmit the last prompt. See page 51 about handling asynchronous messages such as user-to-user paging, Sysop-to-user messages, etc., in the injrou() entry point or by checking the INJOIP flag.
...
Entering and Exiting a Module
...
Special things happen when a user first enters a module. The input string that’s parsed into words in margv[] (see page 103) is a combination of three things:
...
The sttrou() entry point for your module keeps getting called with each new input line until your sttrou() routine returns a zero. That’s your way to signify (to the Worldgroup Major BBS server executive) that the user is exiting your module back to the parent menu. See page 109 for more on whether to exit to a module’s local menu or to the parent menu page.
...
Status Handler Routine: stsrou()
...
The stsrou() entry point is invoked when the user is “in” the module (has selected a module page that’s based on your module from some menu, or is in the module’s logon or logoff supplemental entry point), and the channel detects a status condition. Here are some of those status conditions (for more details, see GSBL Guide):
...
240 Used by convention in Worldgroup the Major BBS for “cycle-mediated” tasks. This value is represented by the constant CYCLE in MAJORBBS.H. You can generate status 240’s artificially with btuinj(usrnum,CYCLE). See page 70.
...
Call dfsthn() (the default status handler) for status conditions your module is not specifically expecting. If there is no User-ID logged onto the current channel, dfsthn() may call you back, resulting in an infinite loop. See the status handling in FILEXFER.C for an example of the proper way to test against this condition.
...
Reprompting Routine: injrou()
...
In many cases, the Worldgroup Major BBS server needs to immediately send a user a brief message. An asynchronous message is one that interrupts the user’s normal banter of prompts and commands. After the message is displayed, the user needs to see his current prompt over again.
...
This, quite logically is also the return value of injoth() (see page 100).
...
Logoff Input Service Routine: lofrou()
...
You can use this entry point to give a user some kind of notice when he logs off, such as “Thank you for your purchase order of 12 items”. You can also use lofrou() for a protracted interactive session with the user — a series of questions and answers, or prompts and commands that he goes through just before logging off, such as “Would you like your order shipped to you within six hours by Lazer Express for an extra $29?”, “Then we’ll need your complete 9-digit ZIP+4 code:”, etc. This all happens before the final Are you sure you want to log off (Y/N)? prompt.
...
usrptr->substt == nonzero on subsequent calls to lofrou(), until lofrou() returns 0.
...
User Disconnect Routine: huprou()
...
Every module’s huprou() entry point is invoked whenever a fully-logged-on user loses carrier. You can use this to de-allocate any resources you might have allocated for the user (be careful with the Volatile Data Area, see page 68). If NULL, no action is taken. This applies to all modules, not just the current one.
...
Auto-Cleanup Routine: mcurou()
...
The mcurou() entry point of each module is invoked once per day, (default time: 3:00 AM). This entry point may be NULL if the module has no need for auto-cleanup processing. You can also use the Auto Utility: line of the .MDF file to specify offline processing during the auto-cleanup. See page 36.
...
You may want to make use of absdtdy() in order to do certain crash recovery in your cleanup code. This should be of particular interest to any modules that keep important data in memory and only save it at shutdown time. If things get out of sync due to crashes (message counts, for example), cleanup can get them back in sync again.
...
Delete User Account Routine: dlarou()
...
This entry point is called for all modules when a user account is deleted. A pointer to the User-ID of the account to be deleted is passed as an explicit parameter to this routine.
The dlarou() entry point exists so that if any special, module-specific actions are necessary when an account is deleted, they will get done. For example, the Registry module maintains a separate database, keyed by User-ID, containing all of the information the user had entered in response to the Registry questionnaire. When a user’s account on the Worldgroup Major BBS server is deleted, the corresponding Registry entry should be deleted from the Registry database as well so as not to waste disk space and create account-confusion problems. Therefore, the Registry’s dlarou() entry point routine deletes the record for the user, if it exists, from the Registry database.
...
System Shutdown Routine: finrou()
...
Finally, the finrou() entry point is invoked as the system is shutting down and returning to DOS — this is the place to flush buffers, close files, and so on. In general, you will be undoing whatever was fired up by the corresponding init__xxx() routine that registered your module. This entry point will be called when a catastro() fatal error occurs (see page 73), in an attempt to save whatever can be saved before returning to DOS. This routine should be designed to safely execute in this kind of hostile situation. For example, say your init__xxx() had some code that did this:
...
That way, the fclose() is guaranteed to execute no more than once, and then only if the file had been opened in the first place.
Channel Numbering and Grouping
Worldgroup The Major BBS can handle up to 256 communication channels simultaneously, which for ease of management are grouped into up to 16 groups. Channels are numbered in hexadecimal from 00 to FF, while groups are numbered in decimal from 1 to 16.
Groups are defined in Hardware Setup through CNF options GROUP1 to GROUP16. The first channel number in each group is assigned under each GROUPn with the STARTn CNF option, and the number of channels in each group is assigned by the NUMBRn CNF option. See Sysop’s Guide for Worldgroupthe Major BBS. Channel numbers need not be assigned sequentially. For example, a Worldgroup Major BBS server can have a GalactiBox on channels 10 to 1F, a PC Xnet card on channels E0 to FF, and a COM3 modem on channel 03.
...
The total quantity of channels that are defined adds up to an important value, called nterms. Many data structures in Worldgroup the Major BBS are multiplied by this value.
...
Channel 00 is reserved for local Sysop emulation and counts as one of the defined channels that add up to nterms.
User Numbers
Independent of channel numbering, there is an internal index called a user number. User numbers are assigned sequentially to each channel that is defined, so user numbers always run from 0 to nterms-1. The global variable usrnum is set to the user number of the user currently being serviced.
...
User number nterms-1 is channel number 00 and is reserved for local Sysop emulation.
Group Numbers
Worldgroup The Major BBS can have up to 16 channel groups, nominally and internally numbered 1 to 16. Use the constant NGROUPS for the number of groups.
...
Note that there are two ways to check for an X.25 channel. The flag check (when done by itself) takes less code.
Data Structures and Memory Allocation
Applies to: v10
v10 memory rules: (1) the engine's allocators
alcmem/alczer(GCOMM.H:287) and the C runtime heap are not interchangeable; (2)MAXPARSZis(MAXBLK/sizeof(VOID *))(GME.H:61),MAXBLKis 65530U (GME.H:57), so a pointer array holds 8191 pointers on x64; (3) structure packing is set by the project, not the headers (no#pragma packin v10inc/); beware sizes and member offsets of structs ported from DOS (MBBS10.txtsection 3); (4) disk records must not contain pointers,HANDLE,size_torunsigned __int64. See chapter 29, section 29.3. Ignore the segment/fartext of this guide: there are no 64K segments.
Worldgroup The Major BBS has numerous ways of handling data, based upon how long the data must last (its lifetime) and upon how often, or in what manner, the data must be accessed.
...
| Lifetime | Explanation |
|---|---|
| Unlimited | For the life of your hard disk (or until someone explicitly changes the information) |
| From server up to server down | While the Worldgroup Major BBS server is on-the-air: from 5 Go to Kill System |
| User Session | While a user is online |
| Module active | Between the time a user selects a module from the Menu Tree, and exits that module |
| Access | Explanation |
| Memory | Access is fastest |
| Disk (direct) | Access requires reading only a sector or two |
| Disk (sequential) | Access as a serial stream of bytes |
| Disk (indexed) | Access records by their content (using Btrieve) |
...
Referencing BBSUSR.DAT for account detail on a user who is online. If your application must deal with the accounting detail of a user, be sure to use uacoff() (page 114) for online users, or the BBSUSR.DAT database record for offline users (these have the same structure, see page 293). You can see how the module addcrd() in ACCOUNT.C makes this distinction when it adds credits to a user’s account. Unconditional use of the Volatile Data Area in the huprou() entry point. If your module requests temporary use of the Volatile Data Area, your module can freely use the area in its sttrou() (line input) and stsrou() (status) entry points. But your module should not use the Volatile Data Area in the huprou() entry point unless the usrptr->state code is equal to the module’s handle (return value of register_module()), i.e. unless the user hung up when he was “in” your module. See page 68 for more details. If you are developing a global command handler (page 135), be careful not to use the vdaptr memory area. This might conflict with the use of vdaptr by whatever module the user is working in, such as Electronic Mail. Use the vdatmp buffer only for one-shot ad hoc purposes (see page 69). Heeding all of these cautions, use the Volatile Data Area whenever you can, rather than alcmem()’ing your own memory region. This will keep Worldgroup’s the Major BBS’s use of memory from getting out of hand. region=alcmem(nbytes); Dynamically allocate some memory
...
Memory allocated using alcmem() is automatically deallocated when Worldgroup the Major BBS shuts down and returns to DOS. To deallocate yourself, you may use the standard Borland library routine free().
...
long memavl; number of bytes
Volatile Data Area
dclvda(nbytes); Declare size of the Volatile Data Area
...
This routine is used whenever you need to access the volatile data area of some user other than the one that you are directly servicing (the one referred to by the global variable usrnum). You might use this to check before a user deletes an item, to make sure that no other users are using it at the same time. Remember that any module other than your module can make any use of the VDA that it pleases. You’ll probably only want to use vdaoff() on users who are also in your module.
Ways to Split up a Long Task
Since Worldgroup the Major BBS is a multi-user system, it cannot work on any one task for too long at a time. If it did, then some users would experience an annoying delay in the response time. By the way, this delay would not show up between character transmissions to the user through the modems — those are interrupt driven. Echoes of user keystrokes are also interrupt driven. Rather, this kind of delay might show up in the time between a user typing in a line and receiving his next prompt. A certain amount of delay cannot be avoided, particularly with disk I/O.
If you have a time-consuming task to perform, and if you can break that task down into chewable computation bites, then you can improve response time in two ways:
...
Cycle Mediating Simulating CYCLE status codesPolling Routine begin_polling() and stop_polling()Cycle Mediating
...
The trick here is to perform a little bit of the task and then generate a status 240 condition. Channel status conditions are managed internally by the GSBL (Galacticomm Software Breakthrough Library). Then when that status 240 is reported back to you, do a little more work on the task, generate another status condition, and so on. This allows Worldgroup the Major BBS to service all other channels that are online, plus perform other housekeeping chores, while it’s also working for the user in your module. You will see in GSBL Guide that the status code we use for cycle mediating, status 240, is reserved for application program use. In the source file MAJORBBS.H, the constant CYCLE is defined as 240.
...
Applies to: WG3.x
Header check:
STATICis not defined in WG3.2 (WG2GCOMM.H:257); writestatic(chapter 2 note).
Notes:
...
usrptr->substt is used to keep track of the progress of each user that selects this module from a menu. It is always set to zero when a user first selects the module. prf() is like printf(), except that the converted text goes into a buffer. outprf() transmits the contents of that buffer to a specific user. stsexm() calls dfsthn() (the default status handler, in MAJORBBS.C) when stsexm() encounters a status code that it is not expressly designed to deal with. Polling Routine
...
The other way to break a long task down into parts is by registering a polling routine. Each channel can have a polling routine which is called regularly. The actual polling rate depends on system loading, but it can be very rapid.
...
To start, register the polling routine with begin_polling(). The stop_polling() function is often called by the polling routine itself when it decides polling is over.
File Handles: fopen()
Worldgroup The Major BBS supports up to 256 users simultaneously, so it needs to have numerous files open simultaneously. Unfortunately, DOS .EXE programs and most compilers support only 20 file handles. To get around that limitation, we’ve included code in the PHGCOMM.LIB library that increases the file handling capacity. It’s important that linker response files list PHGCOMM.LIB before the patched Borland library BCH286.LIB (as is done in LTBBS.LNK) for this to work.
This allows up to 254 total files to be open simultaneously, using either the standard fopen() or open() routines (we use fopen()).
Worldgroup The Major BBS as shipped from the factory was compiled and linked with these modified routines installed, so the MAJORBBS.EXE file can handle more file handles. If you’re developing your own Add-on Option, your .DLL code will use the fopen() that’s in MAJORBBS.EXE.
The Second Parameter of fopen()
Use the following constants for the second parameter of fopen(), depending on how you will use the file:
...
FOPAB Append in Binary mode
Exception Handling: catastro()
catastro(ctlstg,p1,p2,...,pn)
catastrophic error, exit to DOS
...
A non-Sysop user should never be able to trigger a catastro() — your customers’ Worldgroup the Major BBS servers would be vulnerable to hackers bent on sabotaging a system rather than in pillaging it.
...
All catastro() messages are written to the text file CATASTRO.TXT with a time and date stamp... assuming, of course, that the system is still capable of writing to disk rationally.
Insufficient Memory: memcata()
All errors that result from a quantitative lack of memory should not call catastro(), but instead should call memcata():
...
The routines alcmem() and alczer() have their own internal calls to memcata(). They never return NULL.
Languages
Worldgroup The Major BBS can support multiple spoken languages (English, French, German), multiple dialects (Expert, Tutorial), and multiple terminal protocols (ANSI, RIP) for multiple users simultaneously. Language names consist of a 1-8 character spoken language, a slash, and a 1-6 character terminal protocol. That’s a total of up to 15 characters. Some examples:
...
The multilingual feature primarily allows different versions of user output to be defined for different languages. Worldgroup The Major BBS won’t translate user input (e.g. menu selections and commands), however.
...
One exception: YES and NO responses can be translated. Different languages can mean that Worldgroup Major BBS expects different strings for YES and NO. This affects the operation of the cncyesno() routine, and some other special cases. You can use lingyn() for those special cases: it translates a user’s single-character response into Y or N depending on their language (see page 107).
When the Worldgroup Major BBS server comes up, it builds a list of the user languages that are defined and sets a few global variables:
...
Either a number or a language name will satisfy cnclng(). After this, all future prfmsg() output on this channel will be in the new language.
Maximum Number of Languages
We claim that Worldgroup Major BBS can support up to 50 simultaneous languages, but the practical limit is probably higher. The tightest constraint comes from the needs of a certain structure in each .MCV file. You can compute that limit like this:
...
Too many options (starting at "XXXXXX")
or too many languages in XXXXXXXX.MSG.Creating CNF Options
CNF options affect many aspects of the operation of Worldgroupthe Major BBS. See Sysop’s Guide. CNF options are stored in .MSG files, converted to .MCV files, and read in as needed using a very quick direct indexed scheme. CNF options help in these ways:
...
A non-programmer Sysop can change numerous values, names, options, prompts, and messages that affect the operation of his Worldgroup Major BBS system.A large volume of text is stored on disk, saving memory. As a developer, you can specify your own CNF options in .MSG files. These are converted into a special form for use by Worldgroup the Major BBS at run-time — the .MCV files. These sections will help you create new CNF options and use them in Worldgroupthe Major BBS.
Worldgroup’s The Major BBS’s Configuration Facility, CNF, requires special formatting information about each CNF option in the .MSG files. When the Sysop uses CNF to change the value of a CNF option, then this information is used to make his job easier.
...
<version n> This is a string of characters that are available to Worldgroup the Major BBS at run-time. This, and the option name is the only information that WGSMSX takes from the .MSG file to create the run-time .MCV file. In the .MSG files:
...
There are examples of CNF options on page 88. Also look in the .MSG files.
Option Coding Syntax
C Character, ' ' through '~'
...
T <description> Text (up to OUTBSZ-1 characters)
...
Type C: Character Configuration Options
...
The format of the <contents> for this type of option is:
...
This is the activation code letter for calibrating uplink #3
UPSEL3 {Select character for uplink 3: G} C...
Type B: Binary Configuration Options
...
The format of the <contents> for this type of option is:
...
The YES or NO choices show up as softkey selections under CNF.
...
Type E: Enumerated Configuration Options
...
The format of the <contents> for this type of option is:
...
These four enumerated <choice>s show up as softkey options under CNF.
...
Type N: Numeric Configuration Options
...
The format of the <contents> for this type of option is:
...
In this case, 5 and 3600 are the permanent inclusive limits on the value of the <number>. The operator, using CNF, can change the value of this option to something other than 30, but not to something outside of the range 5 to 3600. If you don’t want any particular limits on a option, then you may specify N -32768 32767
...
Type L: Large Numeric Configuration Options
...
The format of the <contents> for this type of option is:
...
In this case, the value of the option is one million. The operator, using CNF, will not be able to make it larger than a hundred million. If you wish to have no particular limit on the option, you may code L -2147483648 2147483647
...
Type H: Hexadecimal Numeric Configuration Options
...
The format of the <contents> for this type of option is:
...
What channel would you like to reserve
for your satellite uplink?
SATCHN {Channel for satellite uplink: 3F} H 0 3F...
Type S: String Configuration Options
...
The <contents> for this type of option are the value of the string. The maximum length and description of the string are encoded in the <coding>. For example:
...
If you use 0 as the length of the string, the maximum length will end up being used, as limited by the width of the CNF screen. Note: A longer <description> means a shorter <contents> length.
...
Type T: Text Configuration Options
...
The <version n> text for this type of CNF option may consist of up to OUTBSZ-1 characters.
...
If Sysops change the sequence of %-symbols in a type-T option, CNF will warn them about the consequences. Even so, Worldgroup the Major BBS tends to be tolerant of %s symbols that show up where they don’t belong. In case of emergency, the server will try to convert the %s symbols into one of these strings:
...
This may not always work, and it is possible that a misplaced %s will cause messy characters to show up on the user’s terminal, or worse, the server could crash with a GP (general protection fault) when prfmsg() tries to use the pointer.
Hinge Specification
This feature keeps CNF from showing one option based upon the value of a preceding option. For example:
...
CAUTION: The hinge feature has no effect on the contents of the .MCV file, and thus no effect on the execution of Worldgroupthe Major BBS. Your programming on Worldgroup the Major BBS must specially handle a situation such as the above to be sure that new users aren’t charged for a game that they aren’t allowed to play, or anything similar, where server operation would be out of sync with the CNF option settings.
...
You probably will not want to hinge on the value of a T option. Any option that does so will always be inactive.
...
Examples
...
Here’s an example of an option specifier:
...
GREET ,{Hola},{Bonjour} Not allowed!
It’s never legal to omit language 0.
Compiling CNF Options
Worldgroup The Major BBS makes sure it has all the .MCV files it needs to run by running WGSMSX with no arguments (this happens in WG.BAT). That checks all .MSG files and makes .MCV files out of them if their time and date disagree. (After WGSMSX makes an .MCV file, its time and date are identical to that of the corresponding .MSG file.) That’s fine, but if you insert or delete CNF options, you need a new .H file in the source directory. That should be taken care of with your .MAK file, or by specific steps in your development process (page 27).
...
The last syntax gives you complete control over what the files are named and where they go.
Using CNF Options
Files with .MCV extension contain the values of the CNF option for use at run-time. Worldgroup The Major BBS reads from these files at run-time to get the values of the options. Your source code can refer to the options by the <option name> that you used in your .MSG file, as specified on page 81. To do this, your source file will need to include the header file in your source file using the C language #include directive.
...
You’ll only have to use inimsg() if you’re writing an offline utility that reads .MCV files. Set maxsiz to 16384 if you need to be sure you’re compatible with any .MCV file used on Worldgroupthe Major BBS.
mbkptr=opnmsg(mcvfil); open a new .MCV file
...
This routine opens a file of CNF options for reading. An array of pointers is read in at this time so that when it comes time to read the actual value of an option from disk, access time is minimal.
.MCV File Identifiers
The return value of opnmsg() is a pointer to type FILE. The value identifies a specific .MCV file — a file containing CNF options. You should only need to use this value when you call the routines setmbk() and clsmsg(). The same type of value is also stored in the global variable curmbk (see below).
...
The following routines are used for reading in the values of CNF options other than of type T (text). To save time, these routines are usually called during initialization and their values are stored in memory. This means that Worldgroup Major BBS need not do a disk read every time it needs the value of the CNF option.
...
This function gets the value of a type N CNF option. If the value read from the file does not conform to the inclusive limits specified by floor and ceil, then Worldgroup the Major BBS reports a catastro() error message.
...
This function gets the value of a type L CNF option. If the value read from the file does not conform to the inclusive limits specified by floor and ceil, then Worldgroup the Major BBS reports a catastro() error message.
...
This function gets the value of a type H CNF option. If the value read from the file does not conform to the inclusive limits specified by floor and ceil, then Worldgroup the Major BBS reports a catastro() error message.
...
Don’t forget to terminate the token list with a NULL parameter.
Changing Configuration Variables
If you understand the various roles of the .MSG, .MCV, and .H files you will see that changing the contents of an option without changing the order of the options has no effect on the .H file. This means that you do not need to recompile Worldgroup the Major BBS every time you change a CNF option. The CNF utility never changes option order. If you change the order of CNF options, either by adding, deleting, or just rearranging them, you must remember to regenerate the .H file (CNF does not do this — use your .MAK file or the WGSMSX utility, page 89), and recompile all the source code that #includes this header file.