You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Operating Environment

Worldgroup is designed as a central hub (MAJORBBS.EXE) which governs free-standing (and therefore easily interchangeable) modules.

Each module has a module definition file (.MDF). Most modules also have their own .MSG files, and program modules have their own .DLL files which themselves may govern various data files.

Once installed, modules can be set to be Available or Disabled via the Basic Utility WGSDMOD (under choice 7 on the Introductory Menu). An Expressly Disabled module will not be allowed to operate until made Available again via WGSDMOD.

Once Available, modules can be further described as Active or Inactive.

A module is Inactive when, although Available, nothing calls it.

A module becomes Active when it is named in a module page in either Menu Tree (as configured by the Sysop in Design Menu Tree, choice 2 on the Introductory Menu).

A module can also become Active when it is named as a requirement in another module’s .MDF file. When the other module becomes Active, the first module becomes Active. E-mail, for example, Requires the messaging engine in order to function.

Finally, a module can be set unconditionally Active. Language modules, for example, are set to become active as soon as the Worldgroup 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, .CVT and .DMD files 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 .VIR files can be built from the .MAK file (chapter 21, "Creating .VIR files from within .MAK files").

Module Definition Files are how Worldgroup recognizes many aspects of your Add-on Option. They provide information on:

Special installation programs to be run once then erasedOnce installed, what .DLL files to load, if anyWhat .MSG files (CNF options) to include, if anyWhether the module can be used in Menu Tree module pagesWhether the module requires that other modules be activeWhether the module replaces other modulesWhether the module should be loaded regardless of other circumstancesDocument files to be integrated into WGSUSER.DOC, if anyBtrieve database requirementsSpecial processing at auto-cleanup, or at timed eventsAdd-on utilities, if anyLanguage information, if appropriateCustom editors for CNF text blocks and Menu Tree custom menusWhether other modules should be involved when downshifting from C/S mode to terminal modeVersion Control for both client app and server agent files.EXE and support files involved in the client appThe default icon file to use if the Sysop doesn’t specify one in Menu TreeFor purposes of this book, we’ll concentrate on the terminal-mode items. Client App Developer’s Guide and Agent Developer’s Guide cover the C/S-mode items.

For example, here is the .MDF file for the Registry of Users:

; GALREG.MDF

Module name: Registry of Users


Developer: Galacticomm

Requires:
Replaces:

Install:

Online user manual: GALREGTM.DOC

DLLs: GALREG
MSGs: GALREGIS

Btrieve page size: 1024
Btrieve files:     1

Cleanup:

Event-1:
Event-2:
Event-3:
Event-4:

Add-On Utility:

I need:

Agent version: 1.01
Client app version: 1.00
Client app EXE: GALRG100.EXE
Client app support files: GALRG100.HLP
Default Icon: GALREG.ICO

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 Worldgroup. 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.

It will be automatically combined with others to form WGSUSER.DOC. That file is (by default) attached to the welcoming e-mail message sent to new users. WGSUSER.DOC is also available through one of the default file pages in the Information Center menu page.

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 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.

If your module makes use of dynamic Btrieve files, it should police itself when online, making sure it doesn’t use up more Btrieve file handles than it’s entitled to. Call gnumdb() to get your .MDF file’s current number of dynamic Btrieve files:

nbfalw=gnumdb("DDDXXX.MDF");

You’ll need to supply an offline utility to update this line when adding or removing data files used by your module. You can use snumdb() to set this number:

snumdb("DDDXXX.MDF",nbfalw);

The server will pick up changes in the .MDF file, and rewrite BBSBTR.BAT as appropriate (combining the count of your module’s core data files with its dynamic ones).

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 server shuts down for auto-cleanup. You can have multiple Cleanup: lines with multiple DOS commands. These commands are executed before Worldgroup runs the Sysop-configurable BBSCLEAN.BAT file.

Event-1 through Event-4

Name an .EXE or .BAT file to run when the Worldgroup server shuts down for any of the timed events. These commands are executed before Worldgroup 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:

Add-On Utility:  DDDANLYZ (analyze color reciprocity)

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:

Client app EXE: GALXX100.EXE
Client app support files: GALXX100.HLP
Shared support files: GCSPCLI.DLL VBRUN300.DLL GALCBK.VBX SS3D2.VBX
Shared support files: THREED.VBX

Applies to: WG3.x

Header check: the OLDSSFLS list of shared support files lives in GALNSSF.H, which exists only in WG2 (not in WGDEV/INC). The VBX/DLL list printed here is client-side material.

In this example of a basic VB3 app, all required files are listed. The .exe and .hlp file will go into the app’s directory on the client. The .dlls and .vbxs will go into the \windows\system directory on the client. Your VB3 app should look largely the same, except you may have additional support files and a different list of shared support files. Be sure to list all required files whether shared or not. Try to share standard .dlls and .vbxs when possible. It will reduce the overall size of the client and save users download time (as well as disk space).

The Client App Developer’s Guide describes certain support files that are guaranteed to be present for your app to make use of. This is no longer the case. If your app’s .mdf file has no Shared support files line, it will be treated as a v1.x app and be assumed to require all of the files previously guaranteed to be present. Include a Shared support files line in your app and specify all required files.

When your app is installed on the server, it should put its shared support files in its app directory, just like standard support files. Your shared support files will be automatically removed from your app directory and possibly put into the server’s galssf directory. If a newer version of a support file already exists in galssf, your app’s version will be deleted. Otherwise, it will be moved into galssf. Never install a shared support file directly into the galssf directory. If there’s some reason not to install them into the app directory, install them to the galnssf directory on the server, and they will be automatically handled from there.

When deciding which version of a shared support file should go into the galssf directory, the server uses the same logic that the client does when determining whether the client needs to receive a shared support file into \windows\system. For the purpose of the following explanation of that procedure, consider the file already in galssf or \windows\system the “existing file” and consider the one that is being considered to go there (over the existing file, if present) the “new file.”

If the existing file does not exist, the new file is used. If the existing file has no built-in version information (as .dlls and .vbxs can), but the new file does, the new file is considered newer and is used. If both files have version information, whichever one has the higher version number is used. Otherwise, the time/date stamps on the files are compared and whichever is the newer one is used.

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.

To provide such a function, your agent must be declared in the same .mdf file as the start-up app. Add a line to the .mdf file:

Startup function: MYFUNC

In this example, myfunc() should be defined in the first (usually the only) .dll referenced in the .mdf file’s DLLs line:

BOOL EXPORT
myfunc(void)
{
}

Applies to: v10

v10: EXPORT is __declspec(dllexport) (or empty under USE_DEF_FILE; chapter 29, section 29.5). BOOL comes from the Windows headers under MSVC (v10 headers themselves use it, for example BOOL IsWow64();, OPRLOW.H:147), but the engine's own type is GBOOL, a short (GCTYPDEF.H:135): use GBOOL in anything stored or exchanged with the engine.

Applies to: WG3.x

Header check: BOOL is not defined in WG3.2; write GBOOL (chapter 2 note, GCTYPDEF.H:105). 3.2 module entry points are written VOID EXPORT init__galfil(VOID); (GALFILH.H:614); EXPORT is defined per platform in GCTYPDEF.H:30-58.

Of course, the function name is up to you, as long as the name in the .mdf and .c files match.

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 itself handles such clean-up. Whenever a version of Worldgroup is installed, a utility runs to clean up old revisions of client apps from the server app directories.

The utility deletes all files in each app directory if not named in the corresponding .mdf file.

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:

; GERMRIP.MDF (language file created by WGSLANG.EXE)
Module Name: German/RIP language
Developer: Sysop
Internal
Unconditional
Language: German/RIP
Language Description: Die deutsche Version von RIPscrip graphics
Language File Extension: .RIP
Language Editor: RIPAINT.DLL %s
Language Yes/No: Ja/Nein

Notice that it does not declare a .DLL file. Most of a language module’s purpose in life is to tell the text-block handling system that each T type CNF option may have a version in this 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 custom menus under the /ANSI languages, three file extensions apply:

.ASC Standard ASCII

.ANS ANSI colors and cursor control with standard ASCII

.IBM ANSI colors and cursor control with IBM extended ASCII

When it comes time to use one of these files, here’s the decision process that occurs in opnans() in MENUING.C:

If the user’s terminal has ANSI capability
If the user’s terminal is an IBM PC
Use the .IBM file (or .ANS or .ASC as required)
else
Use the .ANS file (or .IBM or .ASC as required)
else
Use the .ASC file (or .ANS or .IBM as required)

For other editors, you’ll probably want to specify a single file extension, such as .RIP for RIPaint.

When it comes time to custom design the way a menu looks, Menu Tree will present a list of filenames with all of the extensions for all user languages that are defined, as in:

Edit INFOMENU.IBM using WGSDRAW

Edit INFOMENU.ANS using WGSDRAW

Edit INFOMENU.ASC using WGSDRAW

Edit INFOMENU.RIP using RIPaint

Edit INFOMENU.ZAP using ZAPDRAW

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:

Language Editor:  WGSDRAW %s

Let’s say you want to use an editor named ZOGEDIT that expects the filename as its parameter and needs the /A switch for ANSI capabilities, you’d specify:

Language Editor:  ZOGEDIT %s /A

When it comes time to edit an option or a menu, the %s is replaced with a filename and the above command is executed as a DOS command. We use a system() call on this command line, so DOS will look for ZOGEDIT.COM, ZOGEDIT.EXE, or ZOGEDIT.BAT throughout the path.

The first word of the language editor command line should be the name of the editor. An optional extension could have special meanings:

<name> to specify a DOS command line

<name>.EXE to specify a DOS .EXE file that can be spawned as a daughter process (the daughter EXE file must have a very large capacity for file handles — this is not usually the best approach)

<name>.DLL to specify an editor in a .DLL file (see page 306 about custom editors in .DLLs that register themselves)

In all cases the <name> part is advertised as the name of the editor, both in CNF and in Menu Tree.

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:

Language Yes/No: Affirmative/Negative

In this case the letters A or N will be expected in response to a yes-or-no question. Clearly the first letter of each word must be different.

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 (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.

The Language Yes/No directive also affects the operation of cncyesno(). If a user enters A, then cncyesno() returns Y. This way, your code can always check cncyesno() for Y or N return values. See page 107.

Users can also type in the entire yes or no string. cncyesno() will take it all, and still return Y or N.

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 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 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 while online. There are other ways to run online code, like text variables or global commands, but modules are by far the most powerful.

By registering a module, you complete one of the links necessary to make your service available to users online. The other link is completed by the Sysop when he designs his Menu Trees. Remember that the Sysop ultimately decides who uses each service and how the menus leading to it are structured.

Note: modules service terminal-mode users. Agent Developer’s Guide describes how to create agents to service C/S-mode users (actually, to service client apps running on users’ PCs). Before you get into that, though, you need to understand the concepts in this guide first.

Here are the items to remember when making a module for Worldgroup:

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:

statecode=register_module(ptrmodule);   Register a module
int statecode;                          Value of usrptr->state
                                                whenever user will be "in" this module
struct module *ptrmodule;                       Pointer to your module structure

You might use the statecode in some circumstance to determine if the user is “in” your module (by comparing usrptr->state == statecode, for example). Each time you call register_module() you must pass a pointer to a unique module structure.

Here is the data structure for each module, consisting of a description and nine entry points (this comes from MAJORBBS.H):

extern
struct module {                       /* module interface block               */
     char descrp[MNMSIZ];             /*    description for main menu         */
     int (*lonrou)();                 /*    user logon supplemental routine   */
     int (*sttrou)();                 /*    input routine if selected         */
     void (*stsrou)();                /*    status-input routine if selected  */
     int (*injrou)();                 /*    "injoth" routine for this module  */
     int (*lofrou)();                 /*    user logoff supplemental routine  */
     void (*huprou)();                /*    hangup (lost carrier) routine     */
     void (*mcurou)();                /*    midnight cleanup routine          */
     void (*dlarou)();                /*    delete-account routine            */
     void (*finrou)();                /*    finish-up (sys shutdown) routine  */
} **module;

Here are some sample pieces of code for initializing a simple module:

int colorinp(void);
void clscol(void);

struct module colormod={   /* module interface block            */
     "",                   /* name used to refer to this module */
     NULL,                 /* user logon supplemental routine   */
     colorinp,             /* input routine if selected         */
     dfsthn,               /* status-input routine if selected  */
     NULL,                 /* "injoth" routine for this module  */
     NULL,                 /* user logoff supplemental routine  */
     NULL,                 /* hangup (lost carrier) routine     */
     NULL,                 /* midnight cleanup routine          */
     NULL,                 /* delete-account routine            */
     clscol                /* finish-up (sys shutdown) routine  */
};

static
int colstt;                /* ANSI color diagnostics, state no. */

void EXPORT
init__colormod()           /* the module initialization routine */
{
     stzcpy(colormod.descrp,gmdnam("DDDCOLOR.MDF"),MNMSIZ);
     colstt=register_module(&colormod);
}

As this example shows, you should leave the description blank (a zero-length string) and read it in from your .MDF file during initialization. This example reads in the module description from the DDDCOLOR.MDF file, such as:

Module Name: ANSI color diagnostics

This way, your module name is only in one spot: the .MDF file. If the description in the descrp field disagrees with the one in the .MDF file, then the module won’t be accessible: Menu Tree will call out one name, but the other will be registered online.

Note: if the Module name field in one .MDF file matches the Module name field in another .MDF file, Worldgroup 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 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 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():

int usrnum; user number for the communications channel.

struct user *usrptr; points to that channel’s user struct (see MAJORBBS.H). For example, usrptr->baud is his baud rate, usrptr->substt is his substate, etc.

struct extusr *extptr; points to extendible in-memory data for the channel. For upward compatibility, new in-memory fields will be added here, and not to the user[] array.

struct usracc *usaptr; points to that channel’s usracc struct (see page 293). For example, usaptr->userid is his User-ID, usaptr->usrpho is his phone number. This data is stored in a database.

Each user’s session on the Worldgroup 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”.

The usrptr structure contains this state information, represented by three variables (see MAJORBBS.H). These represent the “context” of the user:

usrptr->class Channel condition:

Applies to: WG3.x

Header check: in WG3.2 struct user (MAJORBBS.H:105) the member class is named usrcls (WG2 MAJORBBS.H:75: int class). Wherever this guide writes usrptr->class (here, chapters 4, 5 and 12) write usrptr->usrcls. The class codes are listed under "user usrcls codes" (MAJORBBS.H:220-226: VACANT 0, ONLINE 1, BBSPRV 2, SUPIPG 3, SUPLON 4, SUPLOF 5, ACTUSR 6). Compatibility: 2030.H:5 defines CLSNAM as usrcls under #ifdef IS30; nothing defines class as an alias, so the old spelling is a compile error (class is also a C++ keyword).

VACANT = 0 channel is not in use

ONLINE = 1 call has been answered
(getting User-ID and password)

BBSPRV = 2 acts similar to ACTUSR, except credit
deduction and time limits don’t apply
(a service might take advantage of this)

SUPIPG = 3 sign-up in progress (brand new user)

SUPLON = 4 supplemental logon activity in progress
(using the lonrou() entry point)

SUPLOF = 5 supplemental logoff activity in progress
(using the lofrou() entry point)

ACTUSR = 6 logged on using entry point sttrou()

Don’t confuse usrptr->class with the user classes that Sysops define from the Remote Sysop ACCOUNT menu CLASS command - the concepts are not related.

usrptr->state Module number in use, corresponding to the return value of register_module(). This makes sense only when usrptr->class is BBSPRV, SUPLON, SUPLOF, or ACTUSR.

usrptr->substt Substate number within the module selected, if any. This is usually some number indicating the question last asked of the user. It’s zero at the beginning of a series of calls to sttrou() when entering a module page or lonrou() when logging on or lofrou() when logging off. If those entry points return 1, then they should also set usrptr->substt to a nonzero value so that they can recognize the context when they are called again with a line of input from the user.

The following global variables are available for any entry point where user input is expected. This includes sttrou() for lines of text when the user is “in” the module, and lonrou() and lofrou() when you’ve set up some supplemental interaction during logon or logoff (more on that below).

int margc; the number of separate arguments (words) in the user’s input line (see page 103)

char *margv[]; table of pointers to the “words” of the user’s input line

char *margn[]; table of pointers to the ends of the input words

int inplen; total length of the input line in bytes

int pfnlvl; profanity level of the input (0 to 3, mild to severe)

The Volatile Data Area is maintained during any protracted interactive session, as with sttrou(), lonrou(), and lofrou(). So you can use the VDA for storing information to track that session. You can also use the VDA in your huprou() entry point, with restrictions (see page 69).

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.

The difference (one logon message versus a series of logon prompts and responses) lies in the lonrou() return value:

lonrou() returns 0 you’re done with logging this user on

lonrou() returns 1 you’re expecting the user to respond to a prompt that you just sent to him

To send one logon message, just make lonrou() always return 0. To go through a series of prompts and responses, return 1 whenever you’re expecting more input from the user. Then lonrou() will be called again when he types the next line of input. When your lonrou() returns 0, the user will resume his logon process. Perhaps there are other modules with lonrou()’s of their own. Otherwise he’s ready to get the Top menu.

You can tell the first lonrou() from subsequent lonrou() calls by the user’s substate:

usrptr->substt == 0 on the first call to lonrou(). Your lonrou() routine should change it to something nonzero, and return 1.

usrptr->substt == nonzero on subsequent calls. Keep changing this substate between lonrou() calls. When done, return 0.

While you’re lonrou() routine is “in effect” (until it returns 0), any status codes on the channel trigger a call to your stsrou() entry point.

Note: to intercept the moment when a user first connects to the Worldgroup 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.

You can keep track of the user’s context with the usrptr->substt variable. This is always zero when the user first enters a module. You can set it to a different value for each prompt you send him, so that when you get his reply, you can interpret it in the proper context.

We use the CNF option number codes for double duty: identifying the prompt text block, and remembering the context (substate) of a reply:

####### Identifying the prompt text block

As you’ll see on page 89, text blocks are identified first by their .MCV file (specified by setmbk()), and second by an integer sequence number defined in the .H file. That integer can be used in calls to prfmsg() to output the text block. For example:

        setmbk(colmb);
        prfmsg(PROMPT);

colmb is returned by opnmsg().
PROMPT is from a WGSMSX-generated .H file.

####### Remembering the context (substate) of a reply

We often use the integer sequence number defined in the .H file to remember the last prompt sent to the user:

        usrptr->substt=PROMPT;

So his reply can be handled in the proper context:

        switch (usrptr->substt) {
             :
        case PROMPT:
             handleit(margc,margv[0]);
             break;
             :
        }

We recommend that, whenever the user types the single letter X followed by enter, that he exit out of whatever he’s doing and return to a previous menu. If your module has its own local menu (many do), then he returns to that menu. If he’s already there, he should return to the parent menu page which originally brought him to your module.

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 select character that got the user into this module (that’s the single-character menu selection that the user typed, as defined in Menu Tree Design for the parent menu page)The command string for the corresponding module page, if any (the Sysop specified this in offline Menu Tree Design)What the user typed after the select character, if anything Also the substate (usrptr->substt) always starts at zero. The state (usrptr->state) is the value returned to you by register_module() when you registered your module.

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 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):

5 Output to user has completed — this status is intercepted by the executive when it results from an injoth() (an asynchronous message). In some cases however, an injoth() or other system operation will let a status 5 slip through to your stsrou() entry point. If you use status 5’s yourself, turn them on with btuoes(usrnum,1) and then send your output. When you get the status 5, be sure to check context (such as a flag or substate code) before processing it (spurious status 5’s should be ignored or passed to dfsthn()). After processing, turn off status 5’s with btuoes(usrnum,0). If you don’t turn them off, you’ll get a status 5 after every prompt from then on.

2,12,22 The GSBL routine btucmd() has been passed a command and that command has completed normally

240 Used by convention in Worldgroup 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.

251 Data input overflow (mostly harmless)

252 Echo buffer overflow

253 Data output overflow

254 Status input overflow (rather serious)

255 Command output overflow (rare)

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 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.

The injoth() function (page 100) is used to send asynchronous messages to a user’s terminal, such as SYSTEM GOING DOWN or YOUR FAX WAS SUCESSFULLY SENT. There are two ways your module could handle this.

####### Asynchronous message handling method 1

If the injrou field of your module structure is NULL, the executive just simulates a cr from the user’s terminal to get the user’s prompt back. If you need to use the condition of an empty input line for some purpose other than for reprompting (such as for default answers) then you can detect the use of injoth() with a test similar to this (this could be an excerpt of your sttrou() routine):

        if ((usrptr->flags&INJOIP) == 0) {
             handlecommand();
        }
        else {
             reprompt();
        }

####### Asynchronous message handling method 2

The injrou() entry point, if one exists in your module, is called when an asynchronous message needs to get through to the user. The message is already formatted in the prfbuf buffer and can be transmitted with btuxmn(). You should also resend the latest prompt. For example, here’s an excerpt of a possible injrou() routine:

        btuxmn(othusn,prfbuf);
        btuoes(othusn,1);
        user[othusn].flags¦=INJOIP;
        return(1);

In fact, this is exactly the code in dftinj() that gets executed when there is no injrou() entry point, except that dftinj() has no return value — don’t use it as your injrou() routine. There’s little point to having an injrou() routine that’s exactly the above, but you could make little modifications to it. The btuxmn() is used in place of an outprf(othusn), specifically so that a user’s ctrl+O abort of text output doesn’t clobber the message. You may have some other way of displaying the message (e.g. transmitting an ANSI sequence to pop up a window or something). Setting btuoes(othusn,1), and setting the INJOIP flag prepares for a future call to the sttrou() entry point with the INJOIP flag set, asking for a reprompt.

Your injrou() entry point must not modify the prfbuf buffer contents. Those contents may be needed for output to other channels.

So to reprompt after displaying the asynchronous message, use btuoes() and INJOIP, as shown above.

Note the use of othusn instead of usrnum. Whatever instigated this asynchronous message, it probably didn’t happen due to a process on the recipient’s channel. It may be in response to a /p global page command from another user’s channel, or to a Send-message softkey command from the Sysop’s console. So the familiar usrptr is not defined at this point.

int othusn; User number of the channel that is to receive the asynchronous message.

Remember that in your injrou() routine:

Don’t use usrnum, use othusnDon’t use usrptr->substt, use user[othusn].substtDon’t use usaptr->userid, use uacoff(othusn)->useridDon’t use extptr->lingo, use extoff(othusn)->lingoYour injrou() routine needs to return a value indicating whether the user got the message or not:

return 0 if the user could not be interrupted at the moment

return 1 if the message was sent to the user’s terminal

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.

The difference (one logoff message versus a series of logoff prompts and responses) lies in the lofrou() return value.

lofrou() returns 0 you’re done with this user, he can log off

lofrou() returns 1 you’re expecting the user to respond to a prompt that you just sent to him

lofrou() returns -1 user does not want to log off after all, return him to his most recent menu

To send one logoff message, just make lofrou() always return 0. To go through a series of prompts and responses, return 1 whenever you’re expecting more input from the user. Then lofrou() will be called again when he types the next line of input.

When your lofrou() returns 0, the user will resume his logoff process. Perhaps there are other modules with lofrou()’s of their own. Otherwise he’s ready to confirm that he really wants to get disconnected.

You can tell the first lofrou() from subsequent lofrou() calls by the user’s substate:

usrptr->substt == 0 on the first call to lofrou(). Change usrptr->substt to something else and return 1.

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.

The absdtdy() function exists to determine whether or not there’s been an abnormal shutdown (non-catastro() crash) today:

        if (absdtdy()) {
            longcup();
        }

If the server locks up, GPs, or otherwise crashes without the system shutdown routines being called, the absdtdy() routine will return TRUE for the remainder of the day. After a successful cleanup, it will begin returning FALSE again.

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 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:

        if ((localfp=fopen("SOMEFILE.TXT",FOPWA)) == NULL) {
             catastro("Cannot create SOMEFILE.TXT!");
        }

Then your finrou() entry point could do this:

        if (localfp != NULL) {
             fclose(localfp);
             localfp=NULL;
        }

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 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 Worldgroup. Channel numbers need not be assigned sequentially. For example, a Worldgroup 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.

Channel numbers control where an online user is indicated on the Summary and Online User Information screens. Channel numbers are also recorded in most audit trail messages.

Channel numbers are used to identify channels for the Sysop.

The total quantity of channels that are defined adds up to an important value, called nterms. Many data structures in Worldgroup are multiplied by this value.

int nterms; total number of channels defined

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 numbers are used internally to identify each channel.

usrnum has the following additional values for special occasions:

User number -1 Channel FFFF (hex) Operator Console operations

User number -2 Channel FFFE (hex) Auto-Cleanup operations

User number -3 Channel FFFD (hex) Timed shutdown event

User numbers are used to index the arrays that are dimensioned by the value nterms. Almost all of the low-level hardware interface routines in the Galacticomm Software Breakthrough Library deal directly with a specific communications channel, and this channel is specified by this user number, not by the channel number that the Sysop assigns.

If you want to change the value of the usrnum variable, even temporarily, it’s a good idea to use curusr() to do it. See page 102.

The array channel[] in MAJORBBS.C translates from user number to channel number:

        channel[<user number>] == <channel number>

The function usridx(), also in MAJORBBS.C, does the reverse translation (or returns -1 for unassigned channel numbers):

        usridx(<channel number>) == <user number>

User number nterms-1 is channel number 00 and is reserved for local Sysop emulation.

Group Numbers

Worldgroup can have up to 16 channel groups, nominally and internally numbered 1 to 16. Use the constant NGROUPS for the number of groups.

Applies to: WG3.x

Header check: NGROUPS was removed in WG3.2; the constant is NUMGRPS (#define NUMGRPS 17, MAJORBBS.H:62; WG2 MAJORBBS.H:45: 17 channel groups from WGSMAJOR.MSG).

        grpnum[<user number>] == <group number>

You can use this to determine the channel type of a group using the grtype[] array:

        grtype[<group number>] == <group type code>

Group Type Codes (from MAJORBBS.H)

#define GTMODEM  1       /* group type code:  Modem channels              */
#define GTMLOCK  2       /* group type code:  Locked modem channels       */
#define GTSERIAL 3       /* group type code:  Serial channels             */
#define GTX25    4       /* group type code:  X.25 channels               */
#define GTLAN    5       /* group type code:  LAN channels                */
#define GTOTHER  6       /* group type code:  GCDI channels               */
#define GTNONE   0       /* group type code:  No channels defined         */

Here is an example of testing a channel’s type:

        if (grtype[grpnum[usrnum]] == GTLAN) {
             ... LAN channel type ...
        }
        else if (usrptr->flags&ISX25) {
             ... X.25 channel type ...
        }
        else {
             ... other channel type ...
        }

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) MAXPARSZ is (MAXBLK/sizeof(VOID *)) (GME.H:61), MAXBLK is 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 pack in v10 inc/); beware sizes and member offsets of structs ported from DOS (MBBS10.txt section 3); (4) disk records must not contain pointers, HANDLE, size_t or unsigned __int64. See chapter 29, section 29.3. Ignore the segment/far text of this guide: there are no 64K segments.

Worldgroup 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.

####### Data Structures Available To All Modules

Structure Lifetime Access See page
CNF options Unlimited Disk (direct) 79
Online User status and session info (usrptr) User session Memory 112
Online user detail (usaptr) Unlimited Memory 293
Offline user detail (BBSUSR.DAT) Unlimited Disk (indexed) 293
System variables (sv,sv2,sv3) Unlimited Memory 292

####### Data Structures For Use By A Specific Module

Structure Lifetime Access See page
Volatile Data Area Module active Memory 68
alcmem() memory From server up to server down Memory 60
File opened using fopen() Unlimited Disk (sequential) 73
File opened using opnbtv() Unlimited Disk (indexed) 280

####### Examples Of Data Used By A Specific Module

Structure Lifetime Access
Electronic Mail message 21 days (default) Disk (indexed)
Uploaded attachment to an e-mail message 14 days (default) Disk (sequential)
Online user’s Forum quickscan configuration Unlimited Memory
User logoff record From server up to server down Memory
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 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)

You must take careful consideration of the scope of a variable before you use it. For example, some mistakes to watch out for:

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 use of memory from getting out of hand. region=alcmem(nbytes); Dynamically allocate some memory

char *region; pointer to the region

unsigned nbytes; size of the region, in bytes (up to 65530)

This routine differs from the standard C malloc() allocation function, in that alcmem() never returns the value NULL. Any memory allocation errors are handled by the shutdown routine memcata() (see page 76).

Since memory allocation is relatively time consuming, we recommend that you avoid using alcmem() for short-term solutions. The Volatile Data Area is better for data that is only needed while a user is in a specific module (see below).

Memory allocated using alcmem() is automatically deallocated when Worldgroup shuts down and returns to DOS. To deallocate yourself, you may use the standard Borland library routine free().

To move an already-allocated block of memory into bigger (or smaller) living quarters:

newspace=alcrsz(oldspace,oldsize,newsize);
Reallocate space to a different size

char *newspace; new space

char *oldspace; old space

unsigned oldsize; old size

unsigned newsize; new size

The new space will have the same contents as the old space, up to the size of the smaller space. If oldspace is NULL, or oldsize is zero, then alcrsz() will act exactly like alcmem(newsize). Otherwise, the oldspace parameter should be the return value of an earlier call to alcmem(), or an equivalent routine such as alcrsz() itself. Like alcmem(), alcrsz() will never return NULL. It will catastro() if it runs into trouble.

To allocate new space for an existing NUL-terminated string:

newspace=alcdup(string); Allocate new space for a string

char *newspace; new space

char *string; old space

You might do this if the old space is volatile and about to be used for some other purpose. The alcdup() routine is similar to the Borland library function strdup(), except that alcdup() will never return NULL.

zregion=alczer(nbytes); Allocate new memory and zero it out

char *zregion; address of new memory

unsigned nbytes; size in bytes

This routine is just like alcmem() except that the new memory is filled with zero bytes.

If you’re allocating an array of blocks, one per channel (that is, nterms of them), then you should only use alcmem() or alczer() if each block is smaller than 256 bytes. If the block is 256 bytes or larger, you should use alcblok() or alctile().

To allocate more than 64K worth of memory at a time, you’ll need a way to break it down into smaller parts. There are two schemes for doing this that differ in how the memory is allocated, but are almost identical functionally. alctile() gives you a different selector for each of these smaller parts, and alcblok() crams as many parts into each selector as possible.

Applies to: WG3.x

Header check: alctile() and ptrtile() (WG2 PLSTUFF.H:32,34) are not declared in WGDEV/INC; there is no PLSTUFF.H. They served the 16-bit protected-mode 64K segment limit of the DOS server and have no WG3.2 header equivalent.

If you’re allocating an nterms array (an array of structures, one per online user), and that structure is 256 bytes or larger, then the array could be 256 x 256 = 65,536 bytes or larger, and you need to use one of these schemes. The prime recommended method for allocating a region that is N x M bytes long is to use alcblok():

bigregion=alcblok(qty,sizblock);
Allocate a very large memory region,
qty by sizblock bytes

void *bigregion; return value, for ptrblok() only

unsigned qty; number of blocks

unsigned sizblock; size of each block

The alcblok() routine never returns NULL (it calls catastro() in case of insufficient available memory). If qty times sizblock is less than about 64K, alcblok() only allocates one region. Otherwise it will allocate multiple regions of up to 64K each.

When you want to use one of the individual blocks, you have to pass the bigregion return value to ptrblok():

block=ptrblok(bigregion,unum); Dereference an alcblok()’d region

void *block; pointer to an individual block

void *bigregion; return value from original alcblok()

unsigned unum; index, 0 to qty-1

The alcblok() return value can only be passed to ptrblok() and not dereferenced in any other way. You should store it in a variable declared to be type void *. The ptrblok() return value on the other hand can be assigned or cast to the native type of your blocks (whatever it is you’re allocating that has sizblock bytes). Typically you would cast it to a variable of type struct something *.

This is roughly how we allocate memory in MAJORBBS.C for the Volatile Data Area, and in FILEXFER.C for the file transfer session control blocks.

The unum parameter is an index between 0 and qty-1 (qty was passed to the original alcblok()). ptrblok() returns a pointer to the block of memory sizblock bytes long corresponding to this index. Each value from 0 to qty-1 will give you a different block. You shouldn’t count on any other aspect of the ptrblok() return values. For example, different values of unum might or might not produce pointers with different selectors.

In general you can count on ptrblok() never returning NULL. The only exception might be if you abusively call it with a NULL bigregion, or an out-of-range unum.

The other method for large memory allocation is alctile(). There is a corresponding ptrtile() routine, which is the only legal way for dereferencing alctile()’s return value, just like the alcblok()/ptrblok() cousins. In fact the calling parameters are identical too:

bigregion=alctile(qty,sizblock);
Allocate a very large memory region,
qty by sizblock bytes

void *bigregion; return value, for ptrtile() only

unsigned qty; number of tiles

unsigned sizblock; size of each tile

block=ptrtile(bigregion,unum);
Dereference an alctile() region

void *block; pointer to a tile (offset always 0)

void *bigregion; return value from original alctile()

unsigned unum; index, 0 to qty-1

What’s happening under Phar Lap is that the region is tiled into a series of regions that are each smaller than 64K. Each region gets a different selector, and its base offset is guaranteed to be zero.

You might need this special feature of alctile()/ptrtile(), but it is usually much better to use alcblok()/ptrblok() if at all possible, because of the latter routine’s economy with selectors. Every computer has a rock-solid limit of 8192 selectors, no matter how much memory it has. That limit is imposed by the number of possible 16-bit values with the three low order bits set to 111. So selector economy is a very desirable thing.

By the way, there is no way to free the memory allocated by alcblok() or alctile() before the program terminates (at which time the memory is automatically freed, of course). It’s assumed that you’ll be keeping these very large regions of memory in use for the duration of the program.

If you want to create an array that will dynamically increase in size, consider using the dynamic array API. It can manage arrays up to 64K in size, expanding them as needed. To create a dynamic array, just call newarr():

arrhdl=newarr(incsiz,elemsiz);
create new dynamic array

int arrhdl; handle to new dynamic array

int incsiz; number of elements to grow by at a time

unsigned elemsiz; size of each array element

To minimize memory fragmentation, the incsiz parameter specifies the number of elements to grow by each time the array needs to be resized. To add a new element to an array, call add2arr():

elemptr=add2arr(arrhdl,newelem);
add element to dynamic array

void *elemptr; pointer to the new element

int arrhdl; dynamic array handle returned by newarr()

void *newelem; data for new element (or NULL to init to 0’s)

To get a pointer to an array element, call arrelem():

elemptr=arrelem(arrhdl,index);
get pointer to element in array

void *elemptr; pointer to the requested element

int arrhdl; dynamic array handle returned by newarr()

int index; index of requested element

After calling add2arr(), an element may relocate in memory. So, you can’t get a pointer to an element once and refer to it forever. Instead, call arrelem() to get the latest pointer whenever an add2arr() might have taken place.

To find out the number of elements currently in an array, call ninarr():

nelems=ninarr(arrhdl); get # of elements in array

int nelems; number of elements in the array

int arrhdl; dynamic array handle returned by newarr()

Another API exists for dealing with pools of memory areas. Each pool contains a variable number of memory areas, each up to about 64K in size. To conserve memory, the pool API allows x total memory areas and y memory areas in memory at once. The API will handle swapping memory areas in and out of memory as needed. The Sysop can set the location of the swap file used with the ASFILE CNF option.

You can create a memory pool by calling newpool() at initialization time:

poolhdl=newpool(areasiz,nareas,ninmem);
create a new memory pool

int poolhdl; handle to new memory pool

unsigned areasiz; size of memory areas within memory pool

int nareas; total number of memory areas within memory pool

int ninmem; number of memory areas to be in memory at once

The messaging engine (GME) uses the pool API for buffers to handle the writing of messages. By default, there’s one per channel but only one for every eight channels can be in memory at once. That ratio is editable by the Sysop with the CHNPBUF CNF option.

The number of areas in memory relative to the total number is something that you will want to default differently based on the nature of what’s stored in the areas and how often they’ll be used. You should make the ratio configurable by the Sysop since every system makes use of software in a different way.

When you want to make use of a memory area, you need to reserve it. As long as it’s reserved, its data is secure. You maintain the actual data, and the API handles swapping it in and out of memory as needed. When you’re done with an area, you need to unreserve it so that it can be used again.

To reserve an area, call rsvarea():

areahdl=rsvarea(poolhdl);
reserve a memory area

int areahdl; handle to the area (or -1 if none available)

int poolhdl; pool handle returned by newpool()

To get the pointer to a memory area you’ve previously reserved, call areaptr():

area=areaptr(poolhdl,areahdl);
get pointer to memory area

int poolhdl; pool handle returned by newpool()

int areahdl; area handle returned by rsvarea()

The areaptr() routine will swap areas in and out of memory as necessary. Every time you call areaptr(), it invalidates anything previously returned by areaptr(). That’s because, in getting the pointer to one area, it may very well have been necessary to swap out another area. So, you can’t rely on pointers to areas remaining valid very long: just until the next areaptr() call. So, call areaptr() each time you need to get the pointer to an area.

To unreserve a memory area, call unrarea():

unrarea(poolhdl,areahdl);
unreserve memory area

int poolhdl; pool handle returned by newpool()

int areahdl; area handle returned by rsvarea()

Once you unreserve a memory area, the data in it is lost as it becomes free to be reserved again. The ability to reserve and unreserve memory areas allows a pool of memory areas to be used in a very dynamic fashion. If your needs are more static, like one area per channel, then you can reserve all nterms areas at initialization time and never unreserve them.

We use the following routines for general purpose handling of memory regions:

movmem(source,destination,nbytes);
Move a block of memory

char *source; source block

char *destination; where to put it

unsigned nbytes; number of bytes, 1 to 65535

setmem(destination,nbytes,value);
Set a block of memory to a value

char *destination; pointer to the block

unsigned nbytes; number of bytes, 1 to 65535

char value; 1-byte value or character

repmem(destination,pattern,nbyt);
Replicate a pattern in memory

void *destination; where to put it

char *pattern; nul-terminated string

int nbyt; total number of bytes at destination

The repmem() function will replicate [nbyt/strlen(pattern)] copies of the pattern at the destination. The \0 terminator of pattern is not replicated. If that quotient is not an integer, the last copy of the pattern will be truncated, but exactly nbyt bytes will be written. No nul is ever written to destination.

chimove(source,destination,nbytes);
Reentrant version of movmem()

Applies to: WG3.x

Header check: chimove() and chiset() (WG2 GCOMM.H:353-354) were removed from GCOMM.H. movmem(s,d,n) is now a macro for galmovmem(s,d,n) (GCOMM.H:164-166; memmove(d,s,n) on the other platform branch, :173). sizmem() is still declared (GCOMM.H:707).

char *source; source block

char *destination; where to put it

unsigned nbytes; number of bytes, 1 to 65535

The chimove() function can be called by interrupt routines as well as mainline routines without conflict.

memavl=sizmem(); Find out how much memory is available

long memavl; number of bytes

Volatile Data Area

dclvda(nbytes); Declare size of the Volatile Data Area

int nbytes; size in bytes

This function should only be called by your init__xxx() routines (see page 42). The function declares the maximum size that the module will require of the Volatile Data Area. Each user online will be given a separate region of this size. When the user selects a module page from a menu option, the corresponding module may use that region until the user exits back to the parent menu again. For example, if the Electronic Mail module requires 1000 bytes and the Registry module requires 500 bytes of the Volatile Data Area, they should both declare these amounts in their init__xxx() routines. 1000 bytes will be allocated (the larger of the two).

char *vdaptr; Points to the Volatile Data Area

This global variable points to a memory region that is allocated for each user who is online, and is used by the module that is in effect at the time. The variable vdaptr is set to point to the appropriate region upon each call to these entry points for the module:

sttrou() character line input after user selects the module page

lonrou() logon message / line input during logon

lofrou() logoff message / line input during logoff

stsrou() status input

Continuing the above example for dclvda(), each time that a user in E-mail types in a line, the sttrou() entry point for E-mail is invoked (see page 48) and the global variable vdaptr points to that user’s Volatile Data Area. The E-mail software is free to store whatever it likes there for the duration of the user’s stay in E-mail.

int vdasiz; The actual size of the Volatile Data Area

Of course, vdasiz is only valid when all the voting is done — that is, at any point other than your init__xxx() routine.

The entry point:

huprou() hang up

may also use the Volatile Data Area under the condition that:

usrptr->state == <module number>

where <module number> is the return value of register_module() (page 43) of the module whose huprou() entry point has been called. That is, huprou() may work with the VDA if the user hung up while that module was active (while the corresponding menu option was selected). Remember that whenever a user logs off or hangs up, the server calls the huprou() entry point of every module, not just that of the module he was using. So if your huprou() entry point detects that the user who is logging off was in your module (using the above test), then huprou() may take appropriate steps to clean up any unfinished business in the VDA. Otherwise, it must leave the VDA alone.

char *vdatmp; Points to the ad hoc Volatile Data Area

This additional area is available after the initialization entry points have been called for all modules and the Volatile Data Areas (page 68) have been allocated for each channel. vdatmp is to be used for brief ad hoc purposes. You can’t depend on the contents of the buffer it points to being preserved through any cycle. You can only use vdatmp within a single call to any of the other entry points, or within a single rtkick() invocation, or within other routines for short-term purposes (but not within your init__xxx() routine).

For one example of vdatmp usage, see the implementation of the global /R registry lookup command in REGISTRY.C (function gloreg()).

char *vdaoff(unum); Compute volatile data pointer for

int unum; some other user

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 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 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.

As a simple example, suppose a module, when selected by a user, simply displayed four narrative lines on the user’s screen and then, after the user pressed enter, returned to the parent menu as follows:

line 1
line 2
line 3
line 4
Press ENTER (wait until user presses enter)

back to menu...

In practice, you would never split up such a small task, but it serves well as an example.

The task is divided into four sub-tasks using the cycle-mediated method. The following functions would be used for the sttrou() and stsrou() entry points:

      STATIC int
      sttexm(void)
      {
           switch (usrptr->substt) {
           case 0:
                prf("line 1\n");
                outprf(usrnum);
                btuinj(usrnum,CYCLE);
                usrptr->substt=1;
                return(1);
           case 4:
                prf("back to menu...\n");
                outprf(usrnum);
                return(0);
           }
           return(1);
      }

      STATIC void
      stsexm(void)
      {
           if (status == CYCLE) {
                switch (usrptr->substt) {
                case 1:
                     prf("line 2\n");
                     usrptr->substt=2;
                     btuinj(usrnum,CYCLE);
                     break;
                case 2:
                     prf("line 3\n");
                     usrptr->substt=3;
                     btuinj(usrnum,CYCLE);
                     break;
                case 3:
                     prf("line 4\n\nPress ENTER ");
                     usrptr->substt=4;
                     break;
                default:
                     dfsthn();
                     return;
                }
                outprf(usrnum);
           }
           else {
                dfsthn();
           }
      }

Applies to: WG3.x

Header check: STATIC is not defined in WG3.2 (WG2 GCOMM.H:257); write static (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.

begin_polling(unum,rouptr);
Turn on polling for this channel

int unum; User number for the channel

void (*rouptr)(void)); Polling routine (no parameters, no return value)

stop_polling(unum); Turn off polling for this channel

int unum; User number for the channel

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 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 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:

FOPRA Read in ASCII mode

FOPRB Read in Binary mode

FOPWA Write in ASCII mode

FOPWB Write in Binary mode

FOPRWA Read & Write in ASCII mode

FOPRWB Read & Write in Binary mode

FOPAA Append in ASCII mode

FOPAB Append in Binary mode

Exception Handling: catastro()

catastro(ctlstg,p1,p2,...,pn)
catastrophic error, exit to DOS

char *ctlstg; control string for error message

TYPE p1,p2,...pn; parameters for error message (maximum 16 bytes of parameters)

This module is called under numerous failure mode conditions. You should remember that catastro() failure conditions are severe cases, such as missing databases, DOS errors, or illegal formatting of CNF options (see page 76 about insufficient memory errors).

So, when to use catastro()? Most often, it’s to give a bumbling Sysop a soft place to fall. There are many cases when not to. If it’s a likely Sysop mistake, then the Sysop procedures need reworking. If it’s a programming mistake, then you may need more safeguards. If it’s the result of something bizarre that a non-Sysop user has done, you absolutely must keep the system up and not penalize innocent bystander users.

Typical catastro() events are things that should “never happen” under normal conditions. But when Murphy’s Law prevails and they do happen, it should be orderly. It’s good to use a catastro() when the alternative would be a chaotic hard-to-trace result that nobody in their right mind would want.

Say you’re using two databases and you just know that if you pull a certain name from the A database, that the same name will appear in the B database one or more times. Well, the Sysop could trip you up by failing to properly restore both database files from a backup in tandem. The result should not be that the program destroys both databases.

When choosing the wording of your catastro() message, try to keep in mind honest mistakes the Sysop could make and use plain English to lead him toward a solution. A Sysop is more likely to be able to handle Cannot find file XXXX.ZOO than fopen() is NULL on XXXX.ZOO. Phrase Sysop-causable errors in terms comprehensible to Sysops and phrase errors that only a programming error could cause in terms most useful for programmers.

Often, rather than calling catastro(), you can just allow something unpleasant but isolated to happen, like the user who triggered the unhappy event could get an empty list with no explanation (but not trash — sending trash to the screen might have unpredictable consequences). For example, you should apply extra caution when processing strings that they don’t overflow the destination buffer — use stzcpy(), or brutally chop off the source string if you have to.

Now, to make every function that deals with a pointer check for NULL is pretty silly, so a balance is needed. For example, whenever you use fopen() to open a file, always check for NULL, so that if a Sysop messes up his installation or runs out of disk space he gets something predictable and not a wild memory write followed by a computer lock-up. Nothing is worse than an intermittent lock-up.

A non-Sysop user should never be able to trigger a catastro() — your customers’ Worldgroup servers would be vulnerable to hackers bent on sabotaging a system rather than in pillaging it.

Here is an example of how you would use catastro() to handle the case of a missing file:

if ((fp=fopen("NEEDTHIS.FIL",FOPRA)) == NULL){
catastro("Cannot find the file \NEEDTHIS.FIL\!");
}

Note that the function for opening Btrieve databases, opnbtv() (page 281), has a built-in catastro() to handle the file-not-found condition (BTRIEVE OPEN ERROR 12).

The parameters are identical to those of the standard printf(), but no more than 16 bytes of parameters (that’s not including the control string) can be passed. For example, each of the following would exhaust the parameter list p1,p2,...,pn, but they would work:

4 pointers to character strings

8 integers

8 characters (remember, a character parameter takes up 2 bytes)

Note: no long integer or floating point values can be used as parameters (i.e. your control string cannot contain %ld or %f directives). If you need to make such conversions, see the l2as() and spr() functions in the section beginning on page 312.

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():

memcata(); Generate a catastro() with a polite message about insufficient memory: There is not enough memory to continue. Please either reduce your memory requirements or install more memory, and try again.

The routines alcmem() and alczer() have their own internal calls to memcata(). They never return NULL.

Languages

Worldgroup 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:

English/ANSI Spanish/RIP Expert/ANSI

English/RIP German/ANSI Staff/ANSI

Spanish/ANSI German/RIP Tutorial/RIP

The multilingual feature primarily allows different versions of user output to be defined for different languages. Worldgroup won’t translate user input (e.g. menu selections and commands), however.

For example, if a user has to type R for read or W for write, he’ll have to do the same thing in all languages. The best way to handle this is in the way the prompts are worded, for example:

RDOWRT {(R)ead or (W)rite? },{(L)eer or (E)scribir?} ...is wrong

RDOWRT {(R)ead or (W)rite? },{R=Leer, W=Escribir?} ...is right

One exception: YES and NO responses can be translated. Different languages can mean that Worldgroup 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 server comes up, it builds a list of the user languages that are defined and sets a few global variables:

nlingo number of languages defined,
always at least 1

clingo language index, 0 to nlingo-1, for the current user

extptr->lingo usually the same as clingo

extoff(n)->lingo language index of user number n (where n is 0 to nterms-1)

languages[clingo]->name name of the current user’s language

languages[clingo]->desc description of the current user’s language

See LINGO.H for more fields in the languages[] array of language information structures.

The main function of clingo occurs when reading in the type T (text block) CNF options from disk. There can be a different version of each type T option for each language, and the value of clingo determines which version to read in. We’ll get into this more on page 89.

To look up the index of a language by its name:

ilingo=lngfnd(lngnam); look up a language by its name

char *lngnam; name of language, 1 to 15 characters long

int ilingo; language index,
0 to nlingo-1, or -1=unknown

To show users a list of all languages for them to pick:

prf("\rWhich language/protocol would you prefer to use?");
lnglist(1);
1ngfoot(1);

You’d be better to use prfmsg() (page 89) than prf() of course, but using prf() is a better way to show you what’s going on in this example. The 1 parameter to lnglist() and lngfoot() means offer all languages as options for the user to pick. Use a 0 instead to only offer those languages with the top voting confidence factors (more about that on page 122). Here’s how you might put the user’s choice into effect:

        int ilingo;
        :
        :
        if ((ilingo=cnclng()) != -1) {
             clingo=extptr->lingo=ilingo;
        }

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 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:

language limit = 32767 / number of options in the .MSG file

There’s actually a different language limit for each individual .MSG file. For example, BBSMAJOR.MSG has about 300 options in it, so it should be able to support over 100 languages. That means that each text block in BBSMAJOR.MSG could have 100 different versions. But if one Sysop’s BBSMAJOR.MSG had 100 languages, then problems could occur if a future release of BBSMAJOR.MSG had more than 327 options. Hence the official limit of 50 languages.

If a Sysop exceeds the limit on the number of languages, then WGSMSX would report:

        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 Worldgroup. 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 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 at run-time — the .MCV files. These sections will help you create new CNF options and use them in Worldgroup.

Worldgroup’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.

CNF type TEXT options (text blocks) can be specified in different languages. The first line of an .MSG file defines the languages that may appear throughout the file, in this format:

        LANGUAGE {<language 0>},{<language 1>},{<language 2>} ...

For example:

        LANGUAGE {English/ANSI},{Spanish/ANSI},{French/ANSI}

Language 0 is always English/ANSI. Omitting the LANGUAGE{} pseudo-option is equivalent to including the line:

        LANGUAGE {English/ANSI}

CNF options can be specified at different levels:

LEVEL1 Hardware Setup

LEVEL3 Security & Accounting

LEVEL4 Configuration Options

LEVEL6 Edit Text Blocks

The levels are numbered to correspond with the numeric selections from the Introductory Menu.

Other special-purpose levels:

LEVEL8 Full Screen Editor help messages

LEVEL10 Internet Connectivity Option (ICO)

LEVEL30 Reserved for configuring

: } the 16 databases of

LEVEL45 The Major Database

LEVEL95 Debugging Options

LEVEL96 Reserved for configuration options of the Major Gateway/ Internet Add-on Option

LEVEL97 Reserved for options in the Entertainment Teleconference that cannot be edited by CNF

LEVEL98 Reserved for text that Sysops are not expected to want to view or modify using CNF

LEVEL99 Reserved for Full Screen Data Entry templates (which are not editable by CNF)

The .MSG files have the following format:

        LANGUAGE {<language 0>},{<language 1>},{<language 2>} ...
        LEVEL1 {}
        <option specifier>
        <option specifier>
        :
        LEVEL3 {}
        <option specifier>
        <option specifier>
        :
        LEVEL4 {}
        <option specifier>
        <option specifier>
        :
        LEVEL6 {}
        <option specifier>
        <option specifier>
        :

Each section at any level may contain from zero up to any number of option specifiers. The LEVELn {} may be omitted for any section that contains no option specifiers.

Each <option specifier> has the following format:

<help paragraph> <option name> <version list> <hinge> <coding>

<help paragraph> Up to 12 lines of text describing the CNF option. This message appears on the CNF screen when the operator is in HELP mode. You should only use columns 2 through 60 of these 12 lines to give the paragraph the proper appearance on the CNF screen. For best appearance if you use less than 12 lines, add a blank line before the line with the option name. If you use all 12 lines, use no blank line. The <help paragraph> may be omitted. In that case, leave two blank lines in its place.

<option name> One to eight characters (capital letters or numbers). This same symbol will be used in the C language source code to refer to this CNF option. This is done with the .H file that WGSMSX generates.

<version list> The text of the option, perhaps with versions in multiple languages (for type T options only). There is always a version for language 0. All other languages may or may not have versions. Of course, there can’t be more versions than there are languages, as defined by the LANGUAGE{} line at the start of the file.

In a 4-language file, here are the possibilities for encoding the 4 different versions:

                {<version 0>}
                {<version 0>},{<version 1>}
                {<version 0>},{<version 1>},{<version 2>}
                {<version 0>},,{<version 2>}
                {<version 0>},{<version 1>},{<version 2>},{<version 3>}
                {<version 0>},,{<version 2>},{<version 3>}
                {<version 0>},{<version 1>},,{<version 3>}
                {<version 0>},,,{<version 3>}

Notice that empty and missing are not the same thing. An empty option has nothing between the curly braces, but a missing option has no curly braces. See about Dialects (language subsets) in Sysop’s Guide.

Only type T options can have multiple versions in multiple languages. Other types of options always have exactly one version.

<version n> This is a string of characters that are available to Worldgroup 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:

} is represented as ~}

~ is represented as ~~

The number of characters in each version is limited by CNF option OUTBSZ (located in Configuration Options, choice 4 on the Introductory Menu). OUTBSZ may be set to 4096, 8192 or 16384.

<contents> The <version 0> text for options of all types except type T is the <contents> of the option: what’s between the curly braces.

<hinge> The hinge is an optional field that implies that a particular option “hinges” on another option.

This mechanism is used to avoid contradictory combinations of options from appearing on the CNF screen. You can use it to hide one option based upon the value of a preceding option. See page 87 for more details.

<coding> This information is used by the CNF utility to control the format and limitations on the option contents.

There are examples of CNF options on page 88. Also look in the .MSG files.

Option Coding Syntax

C Character, ' ' through '~'

B Binary (YES or NO)

E <v1> <v2> ... <vn> Enumerated (multiple choice)

N <min> <max> Decimal numeric (%d)

L <min> <max> Large decimal numeric (%ld)

H <min> <max> Hexadecimal numeric (%x)

S <length> <descript> String of characters (%s)

T <description> Text (up to OUTBSZ-1 characters)

Type C: Character Configuration Options

The format of the <contents> for this type of option is:

        <description> <character>

Where <character> is a single character, as for a menu selection, and <description> is a short description, for example:

        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:

<description> YES or <description> NO

Where <description> is a short description, for example:

        Answer YES to this question if you want new users
        to be able to play in the games.  Answer NO to allow
        them to watch, but not play.

        NEWGAM {Allow new users to play games? NO} B

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:

        <description> <choice>

Where <choice> is a one-word selection among a small set of possible answers. <description> is a short description. The set of possible answers is enumerated in the <coding>, for example:

        How rough do you want users to be able to play?

                EASY -- nobody loses too much
                NORMAL -- can lose your shirt
                ROUGH -- users can cheat
                BRAWL -- cheaters can be shot

        PLALVL {Play difficulty: ROUGH} E EASY NORMAL ROUGH BRAWL

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:

        <description> <number>

Where <number> is a 16-bit integer between -32768 and 32767. A smaller set of limits may be specified in the <coding>, for example:

        How many seconds should we
        wait for a user's bet before
        skipping him for the round?

        PLWAIT {Wait for how many seconds? 30} N 5 3600

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:

        <description> <number>

just like for type N options, except that this <number> will be stored as a 32-bit integer. Limits are specified in the <coding>, for example:

        How much should we allow a user
        to bet during one round?

        MAXBET {Maximum bet: 1000000} L 0 100000000

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:

        <description> <hexadecimal number>

The <hexadecimal number> is unsigned, and may be between 0 and FFFF. Smaller limitations may be encoded in the <coding>. For example:

        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:

        This string is the sign-on message for initiating
        uplink using the 227.85-228.05 MHz "APLINK" band,
        including your FCC registration number

        UPSIGN {U905 Westar 7::88A,5932-051} S 30 Uplink sign-on command

This would appear on the CNF screen something like this:

        UPSIGN     Uplink sign-on command ........ U905 Westar 7::88A,5932-051

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.

WGSDRAW, the default editor for all /ANSI languages, can edit an image of up to 25 lines of 79 characters each. If you use all 25 lines, then the last line cannot end with a line terminator (i.e. no more than 24 line terminators may be in the <version n>). The <coding> field specifies a short description for the option, for example:

        UPCOMP {
        Uplink established, at %s on %s

        *** BEGINNING UPLINK TRANSMISSION ***
        } T Uplink established notification

Type T options are the most numerous. Almost all user prompts and messages are located in Edit Text Blocks (choice 6 on the Introductory Menu), and are type T options.

If Sysops change the sequence of %-symbols in a type-T option, CNF will warn them about the consequences. Even so, Worldgroup 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:

<null pointer> The pointer is NULL (all 4 bytes are zero)

<invalid pointer> The pointer does not contain a valid selector, or the offset is too big for the selector

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:

        NEWGAM {Allow new users to play? NO} B
        CHGGAM {Charge new users how much to play? 1000} N 0 32767

This combination of option settings does not make sense. How can you charge new users for playing if you never allow them to play? If these options were coded like this:

        NEWGAM {Allow new users to play? NO} B
        CHGGAM {Charge new users how much to play? 1000} (NEWGAM=YES) N 0 32767

then the second option would not even appear on the CNF screen, at least not as long as the value of the NEWGAM option was NO. Change NEWGAM to YES and CHGGAM appears.

CAUTION: The hinge feature has no effect on the contents of the .MCV file, and thus no effect on the execution of Worldgroup. Your programming on Worldgroup 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 can also use the hinge specification to test for a set of values, for example:

        (SATLINK=KBAND,QBAND,ZBAND)

This hinge will activate an option when the SATLINK option is either KBAND, QBAND, or ZBAND. On the other hand:

        (GEOSYNC#90,105,120)

will activate an option when option GEOSYNC is neither 90, 105, nor 120.

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:

        If you want users to be able to change their date of birth,
        answer this question with a YES.  If only you, as the
        Sysop, want to have the option of changing a user's date
        of birth after he or she signs up, answer this question
        with a NO.  You can always change the date of birth from
        the User Account Detail screen.

        CHGBDY {Allow users to change their date of birth? NO} (ASKBDY=YES) B

This option is named CHGBDY. It has six lines to its help message. These appear while CNF is in help mode, per the F1 key. This is a B-type option, which is a YES or NO option. Its current value is NO. It is hinged on the option named ASKBDY. CHGBDY appears only if ASKBDY is set to YES.

Here’s another example of an option specifier in an .MSG file:

        GREET {Hello},{Hola},{Bonjour} T Greetings for a user

This GREET{} option has no help text. It has three versions for languages 0, 1 and 2. Here are more examples, with other languages missing:

language 0 language 1 language2

GREET {Hello} Hello Hello Hello

GREET {Hello},{Hola} Hello Hola Hello

GREET {Hello},{Hola},{Bonjour} Hello Hola Bonjour

GREET {Hello},,{Bonjour} Hello Hello Bonjour

The first and last examples omit the Spanish (language 1) versions of GREET{}, so Spanish language callers will revert to the English version Hello (which is language 0). The second example omits the French (language 2) version of GREET{}.

A friendly reminder:

GREET ,{Hola},{Bonjour} Not allowed!
It’s never legal to omit language 0.

Compiling CNF Options

Worldgroup 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).

If you’re ever in doubt, here’s how to run WGSMSX in a development environment:

        CD \WGSERV
        WGSMSX <filename> -OSRC

where <filename>.MSG is the name of your editable .MSG file. This puts the .MCV file into \WGSERV and the .H file in \WGSERV\SRC where it can be used to compile the software that uses the options. Of course, if you’re putting your source code in a separate directory, you’ll need -ODDD or something.

WGSMSX has these alternative command syntaxes:

        WGSMSX [-O<source directory prefix>]
        WGSMSX @<list file> [-O<source directory prefix>]
        WGSMSX <root filename> [-O<source directory prefix>]
        WGSMSX <MSG file path> <MCV file path> <H file path>

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 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.

The symbols defined in this header file are often used for more than just referring to CNF options — they also keep track of user substate. See page 47 for more on this.

prfmsg(msgnum,p1,p2,...,pn);
like prf, but the control string comes from an .MCV file

int msgnum; message number within current .MCV file

p1,p2,...,pn; just like printf()’s parameters (except no longs or floats)

This function is just like prf() (page 96), in that the formatted text output goes into the prfbuf. However, with prfmsg(), the control string comes from a CNF text block. Be sure to call setmbk() to identify the appropriate .MCV file that the text block should come from before calling prfmsg() (more on setmbk() below). The global variable clingo defines the language that prfmsg() will read (page 76).

prfmsg() is used far more often than prf() for two reasons: (1) memory is saved by storing the text on disk, and (2) the Sysop can change the control string using CNF in Edit Text Blocks. Like prf(), there is no limit to the number of parameters (p1,p2,...,pn).

It’s fine to use prfmsg() in cases where you’re formatting text for the current user. When you’re formatting text for another online user however, you need to consider what language that user has selected. Remember clingo is the language of the current user, and all prfmsg() calls depend on clingo. See page 98 for more about prfmsg()’s multilingual cousin, prfmlt().

The library PHGCOMM.LIB (and the source file MSGUTL.C, which is available with the Extended C Source Suite) has several utility routines for reading and processing CNF options from these .MCV files.

inimsg(maxsiz) initialize the message buffer

unsigned maxsiz; maximum number of bytes in any option

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 Worldgroup.

mbkptr=opnmsg(mcvfil); open a new .MCV file

FILE *mbkptr; .MCV file identifier

char *mcvfil; filespec of .MCV file (xxxx.MCV)

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).

Applies to: WG3.x

Header check: in WG3.2 opnmsg() returns an opaque HMCVFILE, not a FILE *: HMCVFILE opnmsg(CHAR *mcvfil) (MCVAPI.H:54); clsmsg(HMCVFILE) (MCVAPI.H:66), setmbk(HMCVFILE) (MCVAPI.H:70) and the global curmbk (EXPWGSV(HMCVFILE) curmbk, MCVAPI.H:43) use the same handle type. Declare message-file variables as HMCVFILE (the porting shim LAYER.H:4 has #define MSGFILE HMCVFILE); do not call fopen-family routines on it. The file-name parameter is not const.

setmbk(mbkptr); set current .MCV file block pointer

FILE *mbkptr; .MCV file identifier (from opnmsg())

This important routine identifies the .MCV file to be used in subsequent calls to getmsg() or to prfmsg() (see above). When a file is opened, an implicit setmbk() takes place.

Applies to: WG3.x

Header check: getmsg() is not a function in WG3.2 but is kept as a compatibility macro: #define getmsg getMsgBlk (GCOMM.H:195, "avoid Unix name space collision"); the function is CHAR *getMsgBlk(INT msgnum) (MAJORBBS.H:865). Existing calls compile unchanged.

A common programming mistake is to forget to use setmbk() at the beginning of a series of prfmsg()’s. This can lead to a program that appears to work when you test it with one user, but fails with multiple users. The symptoms are usually quite obvious: messages are total nonsense, or you get a fatal error like RAWMSG: MSG NO. <nn> OUT OF RANGE IN <filename>.

rstmbk(); restore previous .MCV file block pointer from before last setmbk() call

A typical usage of rstmbk():

setmbk(fbkmb);
prfmsg(AUXBEEP);
rstmbk();

Calls to setmbk() and rstmbk() can be nested up to 10 levels deep.

extern FILE *curmbk; get the current .MCV file identifier

This global variable contains the current .MCV file identifier (see above) that was last set by opnmsg() or setmbk().

There is an alias for curmbk, called lclmbk, that allows you to get at the internal .MCV structure. It’s the identical variable as curmbk, but recast to struct msgblk *. For example, lclmbk->filnam is the name of the .MCV file. See \WGSERV\SRC\MSGUTL.H for details. To use lclmbk, include MSGUTL.H in your C source file.

bufadr=getmsg(msgnum); read value of CNF option

char *bufadr; address of buffer with retrieved text

int msgnum; message number (use option name from the .H file)

This routine retrieves a CNF option into a buffer, and returns a pointer to the buffer. The same buffer is always used for option contents (and hence the same pointer is always returned by getmsg()), so you must finish using these contents before you execute another getmsg(), prfmsg(), rawmsg(), or getasc() call.

The msgnum parameter is the sequential number of the option within the .MCV file. In your source code, you can use the name of the option here.

Your source file should include the appropriate header file using the #include directive. The .H header file was generated from the .MSG file by the WGSMSX utility.

getmsg() is called indirectly by prfmsg() (see page 89) for the most common usage of CNF options: user prompts and messages. These CNF options are type T. getmsg() does translate embedded text variables (page 102).

bufadr=getasc(msgnum); read value of CNF option

Applies to: WG3.x

Header check: getasc() is CHAR *getasc(INT msgnum) (GCOMM.H:515) and returns a writable pointer into the message buffer; treat the string as read-only (see the const CHAR * hazard note in chapter 28).

char *bufadr; address of buffer with retrieved text

int msgnum; message number (use option name)

This variation on getmsg() returns text blocks with ASCII compatible line terminators (both cr and lf are on every line — getmsg() uses an internal line terminator format where cr is a hard return, and lf is a soft return). getasc() does not interpret text variables (page 102).

bufadr=rawmsg(msgnum); read value of CNF option

char *bufadr; address of buffer with retrieved text

int msgnum; message number (use option name)

This variation of getmsg() reads in the raw text from the .MCV file. Text variables, if any, are not translated, and the internal line termination scheme is used (cr = hard carriage return or paragraph boundary, and lf = soft carriage return).

clsmsg(mbkptr); close an .MCV file

FILE *mbkptr; file identifier (from opnmsg())

This routine closes a CNF option file and deallocates the special structures allocated by opnmsg(). There’s no absolute need to call this: the shutdown will close it if it has not already been explicitly closed.

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 need not do a disk read every time it needs the value of the CNF option.

val=numopt(msgnum,floor,ceil);
get numeric option from .MCV file

int val; value of option

int msgnum; message number (use option name)

int floor,ceil; inclusive limits on the value

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 reports a catastro() error message.

lval=lngopt(msgnum,floor,ceil);
get large numeric option from .MCV

long lval; value of option

int msgnum; message number (use option name)

long floor,ceil; inclusive limits on the value

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 reports a catastro() error message.

hval=hexopt(msgnum,floor,ceil);
get hex option from .MCV file

unsigned hval; value of option

int msgnum; message number (use option name)

unsigned floor,ceil; inclusive limits on the value

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 reports a catastro() error message.

flag=ynopt(msgnum); get yes/no option from .MCV file

int flag; 1 if value started with Y, 0 if not

int msgnum; message number (use option name)

This function gets the value of a type B CNF option (YES or NO).

ch=chropt(msgnum); get single-character from .MCV file

char ch; the character

int msgnum; message number (use option name)

This function reads in a type C CNF option.

string=stgopt(msgnum); get a string from .MCV file

char *string; pointer to newly allocated string

int msgnum; message number (use option name)

This function puts the contents of a type S CNF option into a newly allocated string that is just big enough to hold it. You could use free() if you ever needed to deallocate the string.

index=tokopt(msgnum,token1,token2,....,NULL);
multiple choice option

int index; 1=token1, 2=token2, 0=none

int msgnum; message number (use option name)
char *token1;
char *token2;

:

This function checks a type E CNF option for one of several possible values. If the last word in the option specified by msgnum matches token1, then tokopt() returns 1, if token2, it returns 2, and so on. If the word matches none in the token list, tokopt() returns 0.

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 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.

  • No labels