Offline Utilities
This section covers routines that are used in the offline utilities and nowhere else. The offline utilities also make use of several routines that are used for the online operator interface, starting on page 265.
Most offline utilities have a basic background screen design which stays in view whenever the Operator is using that utility. These screens can be designed using TheDraw, and saved as 4000 byte .BIN files. For a utility to read a screen into memory at run-time, it uses iniscn():
iniscn(filspc,where); Read an 80x25 character color screen from a .BIN file
char *filspc; DOS path for the file
void *where; buffer or video memory
The where parameter can be either an in-memory buffer (allocated by alcmem(SCNSIZ), where SCNSIZ is defined as 4000 in GCOMM.H), or the actual video RAM address (see page 265 about frzseg()).
Applies to: WG3.x
Header check:
SCNSIZ(WG2GCOMM.H:231) is not defined inWGDEV/INC.setatr()is still declared (VIDAPI.H:147).
See page 299 for what iniscn() does on monochrome screens.
Window Output: explode()
To make a window pop up on the screen, we use explode():
explode(sctptr,wulx,wuly,wlrx,wlry);
Pop up a window on the CRT
char *sctptr; screen image (from iniscn())
int wulx,wuly; window upper left corner
int wlrx,wlry; window lower right corner (inclusive)
You can use TheDraw to design a pop-up window background in a .BIN file, then read it in with iniscn(), possibly modify it with setwin() and printf(), and display it with explode().
The four windowing parameters in the explode() function define both where to read the image (relative to sctptr) and where to display it (on the CRT). So you really design where to put the pop-up window in the .BIN file with TheDraw, and just tell explode() what you came up with.
Or, you can pack many window backgrounds on a single .BIN screen and use explodeto() to put them anywhere on the CRT:
explodeto(sctptr,fux,fuy,flx,fly,tux,tuy);
Pop up a window on the CRT
char *sctptr; screen image (from iniscn())
int fux,fuy; source window upper left corner
int flx,fly; source window lower right corner (inclusive)
int tux,tuy; destination window upper left corner
If you don’t like shadows, use nsexploto() instead of explodeto(), with the same parameters.
A call to any of the explode() family of routines automatically calls proff() with the tux,tuy parameters, so that you can use calls to prat() relative to where you put the window on the screen (see page 269 about proff() and prat()). This affects future operation of the choose() and edtval() routines (see below).
All X coordinates range from 0 to 79, left to right, and Y coordinates range from 0 to 24, top to bottom.
The global variable explodem defaults to 1 for an animated exploding effect, but may be set to 0 to make the windows pop up instantly.
int explodem; animate the exploding window?
1=animate, 0=instant
A shadow of one cell vertically and two cells horizontally is automatically applied to the bottom and right edges of each pop-up window.
When you’re ready to pop up a window, first save the current screen image so you can restore it when you make the window disappear. For example:
char *scnsav;
:
movmem(frzseg(),scnsav=alcmem(SCNSIZ),SCNSIZ);This allocates 4000 bytes and moves the current screen image to it. When done with the window, just restore the saved image back, as in:
movmem(scnsav,frzseg(),SCNSIZ);
free(scnsav);Pop-up windows can be popped on top of one another. This means you’ll need to have a series of saves and restores nested in one another, like this:
save background
pop-up #1
save window #1
pop-up #2
save window #2
pop-up #3
restore window #2
restore window #1
restore background
Monochrome Compatibility
To be compatible with both monochrome and color screens, you can call monorcol():
monorcol() Determine monochrome versus color, based on the Hardware Setup CNF option CRT (which is set to COLOR, MONO or AUTO)
imonorcol() Determine monochrome versus color based on BIOS settings only. This is equivalent to monorcol() when CRT is set to AUTO. We use this routine in cases where we don’t want to be depending on the BBSMAJOR.MCV file.
int color; 1=operator’s screen is color, 0=monochrome
If you don’t want to depend on the CRT offline option, you could compute color automatically by some other method as in:
color=(FP_SEG(frzseg()) != 0xB000);Don’t define your own color variable — use the global variable from GCOMM.LIB.
The color variable has a global effect on iniscn() and setatr() — if color is set to zero, those routines will translate color values into reasonable monochrome values:
Any attribute with a white background becomes black on white (inverse video). Otherwise, the attribute becomes white on black, preserving blinking and/or brightness if they are present.Window Input: edtval(), choose()
If you want the operator to enter something, you can use explode() to pop up a window (see the previous section), and then edtval() to handle his entry session.
save=edtval(sx,sy,maxlen,sval,valrou,flags);
edit a string field on the screen
int save; 0 means esc was pressed, 1 means enter, tab, shift+tab, up, or down was pressed
int sx,sy; starting point for the field on the screen
(sx is 0-79, sy 0-24)
int maxlen; maximum size of string (including nul — maxlen-1 is field width)
char *sval; default value / return value
int (*valrou)(); validation routine
int flags; options
The sx,sy coordinates are relative to the tux,tuy coordinates of the most recent call to the explode() family of routines (page 297). This is done via the proff() and prat() routines (page 269).
Put a default value in the sval buffer if you want one (the cursor will start at the right end of the value), or fill sval with a zero-length string to start from scratch. Either way, you have to have maxlen bytes available at sval. Here are the bit flag options for the last parameter of edtval():
#define MCHOICE 1 /* multiple choice question, hide cursor */
#define ALLCAPS 2 /* convert all chars to capital letters */
#define USEPOFF 4 /* use proff() x,y base coord offsets */
#define MULTIEX 8 /* allow multiple field-exit conditions */The operator can type in a new value, move the cursor right or left, ins or del characters, hit home or end, and when finally done, press enter, tab, shift+tab, up, or down to save or esc to abort. Actually it’s up to you how you handle the difference between all these exit methods. You can tell whether it was esc or not by edtval()’s return value. You can distinguish among the other cases using the edtvalc global variable:
int edtvalc; Keystroke that ended edtval()
After edtval() returns, you can get the entry results in the buffer that the sval parameter pointed to.
While edtval() is running, the entry field will use setatr() attribute of 0x0F (bright white on black). For this reason, your pop-up window should probably have a background color other than black. When edtval() completes normally it restores the original attribute. If it completes with the esc keystroke, the entry field stays visible.
The valrou parameter is the address of a keystroke validation function. It will be called each time the operator presses a key other than one of the exit keys (see the return value save above). The function is passed the code for the key pressed (see about key codes on page 274) and the buffer contents so far (nul-terminated, without that keystroke). Your function should return a 1 to accept the keystroke or a 0 to reject it. Here are a few validation functions from ??GCOMM.LIB that you can use:
isok=validig(c,sval); digit validation routine
int isok; 1=it’s a digit, 0=reject
int c; key code (as in getchc())
char *sval; string entered so far
isok=validyn(c,sval); yes/no validation routine
int isok; 1=it’s a digit, 0=reject
int c; key code (a la getchc())
char *sval; string entered so far
Here’s the source code for these routines:
int
validig(c,sval); /* is c a valid decimal digit? */
int c;
char *sval;
{
return(c >= '0' && c <= '9');
}Editor's note (not part of Fountain's text): This sample
validig(c,sval)is illustrative only. The name collides with the real engine routinevalidig(int c)declared in GCOMM.H (one parameter, not two); do not present this sample as the engine API, and do not compile it into a module alongside GCOMM.H. (Source: analysis/wg1/FINDINGS.md.)
int
validyn(c,stg) /* validate c as yes/no (for edtval()) */
int c;
char *stg;
{
if (tolower(c) == 'y') {
strcpy(stg,"Yes");
}
else if (tolower(c) == 'n') {
strcpy(stg,"No");
}
return(0);
}Notice how you can allow a single character to change the entire entry string — just write to the buffer pointed to by the sval parameter.
The routine calling your validation routine adds the character to the buffer if your routine accepts it, and doesn’t otherwise. Either way, the entire string is redisplayed after each keystroke.
When using validyn(), maxlen must be at least 4.
Multiple Choice
The following routine allows an offline operator to make a multiple-choice selection using a scrolling window, with up and down arrow keys highlighting the different choices, and enter making the final choice:
choice=choose(nchoices,choices,upx,upy,lox,loy,escok);
Pop up a window of choices
int choice; index of choice 0..nchoices-1 or -esc if operator escaped
int nchoices; number of choices
char *choices[]; array of choices
int upx,upy; upper left corner of window
int lox,loy; lower right corner of window
int escok; allow esc? 1=yes 0=no
The upx,upy coordinates are relative to the tux,tuy coordinates of the most recent call to the explode() family of routines (page 297). This is done via the proff() and prat() routines (page 269).
The window boundaries are inclusive. The window does not have to be big enough to hold all your choices, and if it isn’t, choose() will show (more) at the bottom and scroll when the operator moves the cursor down. A few global variables are controlling the display attributes:
int selatr; Attribute for scrolling choice bar
int nslatr; Attribute for the other choices
There are some alternatives and variations to choose(). The first is choowd():
choice=choowd(choices,first,upx,upy,lox,loy,escok);
Pop up a window of choices
int choice; index of choice 0..nchoices-1 or -esc if operator escaped
char *choices[]; array of choices, after the last of which is a NULL
int first; index of the default choice
int upx,upy; upper left corner of window
int lox,loy; lower right corner of window
int escok; allow esc? 1=yes 0=no
Here too, upx,upy are relative to the window established by explode().
The two differences between choowd() and choose() are: choowd() uses a NULL to terminate the choices[] array while choose() passes the quantity nchoices; and choowd() allows you to specify a default starting point in the choice array, while choose() always starts you at index 0.
The third alternative is to break the choosing up into two pieces:
supchc(nchoices,choices,upx,upy,lox,loy,escok);
choice=choout();
This does exactly what choose() does, with the same parameters and return value, but you get the chance to sneak some processing in between the startup and the choosing session. You would only do this if you had knowledge of some of global variables in CHOOSE.C from the Extended C Source Developer’s Kit.
The fourth alternative is to break the choosing up into many pieces. You’d need to do this in a multitasking environment so that you could be working on other tasks while waiting for keystrokes from the operator. Or you’d need this if you wanted to take some special action on certain keystrokes.
Here you get the best of choose() and choowd() in kit form, with some assembly required. Here’s the equivalent of choose() (with an optional starting point like choowd()):
supchc(nchoices,choices,upx,upy,lox,loy,escok);
jmp2chc(first); <- this line is optional
dspchc();
cursiz(NOCURS);
do {
choice=hdlchc(getchc());
while (choice == nchoices);
rstcur();The jmp2chc() routine establishes the default or starting point, as does the first parameter in choowd(). The new routine dspchc() displays the background of the choice window after startup. Notice it’s polite to turn the cursor off for the choosing session. The hdlchc() routine handles operator keystrokes. Of course, you could set things up to be doing other things while kbhit() is false, and only call getchc() when kbhit() is true. The hdlchc() routine has the same return value as choose() and choout(), except it may return nchoices to indicate that the choosing session isn’t over yet.
Large Model Programming
Most offline utilities from Galacticomm use the Large memory model of Borland C++ and do not make use of the Phar Lap DOS-Extender. This is a less complicated development environment than what we use to make MAJORBBS.EXE and all the .DLL files. These .MAK files come with Worldgroup’s Client/Server Developer’s Kit:
BBSRPT.MAK Offline Reports (choice 9 on the Introductory Menu, includes all eight reports)
GALP&QR.MAK Offline Polls & Questionnaires analysis (choice 7 on the Introductory Menu, GALP&QR)
BBSRPT.MAK uses protected mode due to its use of the messaging engine, but GALP&Q.MAK is in large model, as are most offline utilities. Many more .MAK files come with the Extended C Source Developer’s Kit.
Here are the most important differences in large model programming versus protected mode programming:
Smaller memory limits on the program (640K or so total, up to 64K static data)Object files reside in \WGSERV\LOBJ instead of \WGSERV\PHOBJ.To do the compiling and linking steps piece by piece:
Compile a <filename>.C source file that contributes to an .EXE offline utility program:
CD \WGSERV\SRC or CD \WGSERV\DDD (as appropriate)
CTL <filename> CTL <filename>
It’s not a good idea to do CTL * because different source files need to be compiled with different CTXXX.BAT files.
Relink a <utility name>.EXE file:
CD \WGSERV\LOBJ
LNK <utility name> <other file 1> <other file 2>
or, as appropriate
CD \WGSERV\DDD
LNK <utility name> <other file 1> <other file 2>
Look in the corresponding .MAK file for the utility for the exact way to link it.
Language Editor .DLLs
When you define a language, you can also define a custom editor program for editing text or other information in that language. Usually a custom editor will be associated with the protocol portion of the language, for example WGSDRAW for all languages that end in /ANSI, or RIPaint for all /RIP languages.
Language Editors are used by CNF to edit text blocks and by Menu Tree to create and edit custom menus. Language Editor .DLLs will run in protected mode, and they must behave appropriately. See page 333 for more on running in protected mode.
To create your own language editor .DLL:
1. In your language .MDF file (page 32), use the name of your .DLL file in the language editor command line, as in:
Language Editor: TESTIT.DLL %s
This one directive can do up to three different things. First it declares that this editor is a .DLL editor (as opposed to an editor that’s an .EXE file or a .BAT file). Second, it specifies TESTIT.DLL as the .DLL that should be loaded in order to run the editor. And third, your language editor handler routine may be able to use it to recognize when text should be edited in your language. When it comes time to edit something, the language editor command will be passed to all editor handler routines, and your editor handler routine will need to decide between “I’m supposed to edit the text,” or “No, some other editor is supposed to edit the text, not me.” More on this later.
By the way, for consistent selection of the proper editor under Menu Tree, a unique language editor should be associated with a unique language file extension. For example, the language editor command line RIPAINT.DLL %s should be associated with, and only with, the language file extension .RIP. This comes up when you’re trying to define multiple RIP languages (English/RIP, Spanish/RIP, German/RIP, etc.).
- Create an editor handler routine. A simple example:
int
tstedt(
char *command,
char *txtbuf,
unsigned sizbuf)
{
If (!sameto("TESTIT.DLL",command)) {
return(EONOTME);
}
return(edit(txtbuf,sizbuf) ? EOSAVE : EONOCHG);
}In this example, edit() is your function for editing the text, and it returns 1 if it wants to change the text or 0 if it doesn’t.
As mentioned, whenever the Sysop wants to edit some text (when he presses F2 to edit in CNF, or he chooses to Edit the way this menu looks in Menu Tree), the language editor command line from the appropriate language .MDF file is formatted and passed to all registered editor handler routines. Each editor handler has the responsibility to look at the command and either get to work (in the above example, to call edit(), and return either EOSAVE or EONOCHG) or pass the buck to return EONOTME — effectively saying “it’s not my job”.
Here are the meanings of the parameters that will be passed to your editor handler routine:
command This is the formatted language editor command line from the appropriate language .MDF file. You would typically look at the first word of this command to find out if your editor should be working on this text. If not, you need to return EONOTME. See below for all possible return values.
The %s from the language editor command line has been replaced by a filename by the time it gets to you in the form of this command parameter. You probably don’t care about that filename unless txtbuf is NULL.
txtbuf If non-NULL, this is the address of the text in memory, and also where you should put the text after it has been edited. This is how CNF will call your language editor.
If NULL, you should get the text from the file identified in the command, and write the edited text back there too. This is how Menu Tree will call your language editor.
sizbuf This is the maximum size the text should attain. In no event should your editor handler write outside of the inclusive memory range txtbuf[0] to txtbuf[sizbuf-1]. sizbuf does include the room for the terminating nul.
The possible return values of your editor handler routine are:
EONOTME This command is for another editor
EOERROR Error occurred (details in edterr[])
EOABORT Operator aborted, recover old data
EONOCHG No change to data, don’t update
EOTRUNC Data truncated (ibsize=original size)
EOSAVE Done editing, save data
EOSAVE+EOPGUP Save data, skip to option above
EOSAVE+EOPGDN Save data, skip to option below
EONOCHG+EOPGUP No change to data, skip to option above
EONOCHG+EOPGDN No change to data, skip to option below
These constants are defined in EDTOFF.H. If you can’t decide which return value to use among EOSAVE, EOTRUNC, and EONOCHG, use EOSAVE.
Here are some global variables associated with editors:
char edterr[]; where to put an error message
(used only when you return EOERROR)
long ibsize; size of original text before it was truncated (used only when you return EOTRUNC)
The wording of the edterr[] message should be such that it fits well into a message like This CNF Editor command <edterr>: <editor command from .MDF file>.
For example, some appropriate wordings of edterr[] might be cannot create CNF00000.FRC, or requires more real-mode memory, or erased the SAVE.TXT file. We suggest you test each of your error messages with CNF to make sure they look right.
Your editor handler routine and associated code will need to be in a C source file that includes:
#include "gcomm.h"
#include "edtoff.h"- Register your editor handler routine. Make a function whose name starts with init__. It gets passed the address of the routine to register editor handler routines, and should be declared EXPORT. The function doesn’t return anything.
For example:
void EXPORT
init__testit(regrou)
void (*regrou)(EDTHANDLER *edthdl);
{
(*regrou)(tstedt);
}This function will get called the first time someone tries to use your editor, so you may want to include some more initialization code here.
A key strategy with each language editor .DLL is not to load any .DLL until and unless it’s actually needed. So the first time the Sysop edits some text that’s associated with a given language editor .DLL is when that .DLL is loaded and initialized.
You may be thinking there’s a paradox here (How can the Sysop pick my editor before I’ve even registered it?). The resolution is in the multiple purposes of the language editor command line in the .MDF file. The first time the Sysop tries to edit something associated with your language editor .DLL, your editor handler routine has not even been registered. But a special editor handler routine (dlload() in EDTOFF.C) will (1) recognize this condition, (2) notice that your command TESTIT.DLL <temp file> calls out a .DLL, (3) load and initialize your .DLL, and (4) allow you to get to work editing the text. From then on, your registered editor handler will respond to all text edit sessions where your language is in effect.
4. Compile your program using CTPH.BAT, for example:
CTPH TESTIT
- Make a linker response file. For example, TESTIT.LNK:
%PHARLAP%\bc4\lib\c0phdll +
%MBBS%\phobj\testit
%MBBS%\testit
nul
plhide phapi cnfimp /Twd /s /n
%MBBS%\dlib\nodef
And use it to make your .DLL file:
LTDLL TESTIT
If you get undefined symbols for Borland Library routines, you may have to find alternatives to using those routines. See page 23 about the perils of linking BCH286.LIB in a .DLL.
6. Install your .DLL file, and the language .MDF file, on the Worldgroup server computer where you want the editor to be available.
.MSG File Reading and Writing
If your offline utility needs to examine the value of a CNF option direct from the .MSG file, as opposed to the compiled .MCV file, you can use msgscan().
value=msgscan(filnam,name);
Read a CNF option from an .MSG file
char *value; value of option (or NULL=can’t find)
char *filnam; file (include .MSG extension)
char *name; name of option (not including types **S** or **T**)To read the option from the .MCV file, use the getmsg() and xxxopt() routines, described starting on page 89. It’s usually more convenient to use getmsg() or the xxxopt() routines if you are reading a .MSG file that’s part of the same product release. That is, if your .MSG file and your offline utility are sold and updated as a package.
Applies to: WG3.x
Header check:
getmsg()is a compatibility macro forgetMsgBlk()in WG3.2 (GCOMM.H:195).
On the other hand, if your product’s utility is reading another product’s .MSG file, msgscan() should be used. An example would be any offline Add-on utility that needs to know the values in BBSMAJOR.MSG. Using msgscan() allows your utility to continue to work even after the .MSG file is updated to a new version (as long as the option you’re changing has not been obsoleted of course).
If you’re writing an offline utility and you need to change the value of CNF options, you could use the setcnf() and applyem() functions.
setcnf(name,value); Specify a CNF option change
char *name; name of the option
char *value; new value for the option
applyem(filnam); Set the CNF options in this file
char *filnam; file (include .MSG extension)
Here’s an example of using these routines to set the values of several CNF options in different .MSG files.
setcnf("GROUP3","MODEM");
setcnf("BAUD3","19200");
setcnf("LOCK3","YES");
setcnf("INIT3","AT&FE0S0=0S2=255X6&R0B1");
setcnf("SUPCLS","PROSPECT");
applyem("BBSMAJOR.MSG");
applyem("BBSSUP.MSG");When you bring the Worldgroup server up again, new .MCV files will automatically be generated by WGSMSX.
Up to 100 setcnf() changes can be accumulated before you call applyem(). If you want to change more than 100 options, you can specify them in lots of 100 or fewer. Calling applyem() sets things up so that the next call to setcnf() starts with a clean slate of specified changes.
As you can see, you can specify changes to several different options in several different files. Then you can call applyem() on the file(s) where the options are stored. If you accumulate option changes for multiple files, beware of options with the same names in two different .MSG files. applyem() would change them both to the same value.
You can change the value of any type of CNF option with setcnf() and applyem(). But if you change the value of a type T text option, only the language 0 version will be affected.