Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

User Interface

This chapter deals primarily with the terminal-mode side of Worldgroup the Major BBS modules. Terminal mode by definition means that all processing occurs on the server PC, none on the user’s PC. In C/S mode, user I/O issues are handled by client apps written in Visual Basic. A C/S agent merely offers an API to the client app. In terminal mode, however, there is no client app, so the code running on the server PC is expected to provide a UI, a user’s interface, as well.

Even if you never intend to write terminal-mode access for your projects, it is worthwhile to at least skim this chapter, and to carefully read the final section beginning on page 124.

User Output: prf(), prfmsg()

prf(ctlstg,p1,p2,...,pn);
prfbuf-directed printf()-lookalike

...

See also page 89 about prfmsg(), the variation of prf() that reads text from an .MCV file. prfmsg() is used far more often in Worldgroup’s the Major BBS’s code.

outprf(unum); send prfbuf to a channel & clear

...

This pointer is updated by prf() and prfmsg() to point to the end of the formatted string in prfbuf. Both clrprf() and outprf() reset prfptr to the beginning of prfbuf.

Multilingual User Output

To review, if you want to format text for the current user, you use the prfmsg() and outprf() routines, remembering to call setmbk():

Code Block
        setmbk(appmb);
        prfmsg(HOWAYA,usaptr-
>userid
>userid);
        outprf(usrnum);

This code prepares to read from a specific .MCV file, reads the HOWAYA message from it and formats it with the current user’s User-ID, and then sends the formatted message to the current user. If there are multiple versions of the HOWAYA text block for multiple languages, then the version corresponding to the current user’s language will be read (or the most appropriate fallback alternative — see Dialects in Sysop’s Guide for more details on language subsets).

Things get a little tricky when you need to send a message to another user who is also online. Let’s say your module had some scheme for pairing users, and when both partners logged on you wanted to notify them. To tell the first partner that the second partner had logged on you could code this:

Code Block
        if (onsys(partner(usaptr-
>userid
>userid))) {
             prfmsg(PNRHERE,usaptr-
>userid
>userid);
             outprf(othusn);
        }

PNRHERE says something like, Your partner, %s, just logged on. The problem is that the other user will get the message in the language of the current user. To avoid this:

Code Block
        if (onsys(partner(usaptr-
>userid
>userid))) {
             prfmlt(PNRHERE,usaptr-
>userid
>userid);
             outmlt(othusn);
        }

There are four routines that have multilingual cousins:

...

There is some work wasted here in formatting text for languages that will never be sent to a user but, if you code multiple outmlt()’s, all those languages will come in handy. To save that unnecessary processing, you might try this:

Code Block
        if (onsys(partner(usaptr-
>userid
>userid))) {
             clingo=extoff(othusn)-
>lingo
>lingo;
             prfmsg(PNRHERE,usaptr-
>userid
>userid);
             outprf(othusn);
             clingo=extptr-
>lingo
>lingo;
        }

Here we’ve just changed the global variable clingo to the other user’s language temporarily. If you’re formatting text for only one other user, you can always set clingo like this.

...

This routine is used to transmit an asynchronous message to a user. By asynchronous, we mean a message that does not follow from the question/answer question/answer banter that normally goes on between each user and Worldgroupthe Major BBS. This message is an interruption. injoth() is used, for example, for:

...

Now here’s what we could do to tell both partners that the other is online:

Code Block
        if (onsys(partner(usaptr-
>userid
>userid))) {
             prfmlt(PNRHERE,usaptr-
>userid
>userid);
             if (injoth()) {
                  prfmsg(PNRTOO,othuap-
>userid
>userid);
                  outprf(usrnum);
             }
        }

PNRTOO says something like, Your partner, %s, is already online. The injoth() routine is compatible with both monolingual and multilingual formatting methods. It does the equivalent of an outprf() or outmlt() as appropriate to the othusn user.

...

By the way, notice how we can get away with prfmsg()/outprf() to the current user after using prfmlt()/injoth() on the other user? This does not violate the rules of mixing monolingual and multilingual user output routines.

...

Changing usrnum

...

One last point: if you ever change the value of usrnum, it’s important to call curusr(). Suppose you’re temporarily changing the user number to userno for some reason:

...

int newunum; new user number, 0 to nterms-1

Defining Text Variables

See the Editing Text Blocks chapter in Sysop’s Guide about using text variables. Here we’ll tell you how to program your own text variables. From a programming standpoint, a text variable is simply a function that has a name and returns a string of arbitrary length. The length and justification issues arise when using the variable — see WGSDRAW.

1. Code a routine that returns a pointer to a string. You’re responsible for storing the string somewhere where it will be available for immediate use. Just about any buffer except an “automatic” (stack) array will do. Example:

Code Block
        char *
        tvar_nikei(void)
        {
             return(l2as(nikeiaverage()));
        }
  1. Register the routine, along with the text variable’s name, using the register_textvar() routine, as in:

Applies to: WG3.x

Header check: INT register_textvar(CHAR *name,CHAR *(*varrou)()) (MAJORBBS.H:767): the variable name is not const, and the callback must return a writable CHAR *. A text-variable routine that returns ncdate(), nctime(), getfnm() and the like returns a const CHAR * in WG3.2 and must either cast or copy the result into a static buffer (stlcpy, GCOMM.H:409). See the const CHAR * hazard note in chapter 28.

Code Block
        register_textvar("NIKEI",tvar_nikei);

You can do this in your init__xxx() initialization routine. Now you can use the text variable NIKEI when creating menus or text blocks.

Be careful about the context of using a text variable. Either you must code the routine so that it will produce valid results no matter when it’s called, or you must be sure that when the Sysop uses the text variable in a particular text block or menu that the routine will work. See the context limitations on using some of the standard text variables in the Sysop’s Guide.

User Input

On Worldgroupthe Major BBS, each time a user types a string of characters and presses enter, a status 3 condition occurs on his channel. Whatever module is in effect for that channel processes the input through the sttrou() entry point for the module (see page 48).

...

margv[2] now points to SPAIN

Profanity

int pfnlvl; profanity level of the input
0 means no profanity, 1 means mild,
3 means very profane

This global variable is based on the user input line in input[]. It is saturated at (it’s never more than) the value of CNF option PFCEIL located in Configuration Options (level 4 on the Introductory Menu).

Echo

echon(); Turn echo on for this channel

...

Then call echon() to make things normal again. The convention is to use secchr as the first parameter to echsec(). This is the setting of CNF option SECCHR located in Configuration Options (level 4 on the Introductory Menu). SECCHR defaults to * (asterisk).

Command Concatenation

This feature has two purposes on Worldgroupthe Major BBS.

1. It allows the Sysop to define detailed subcommands within his online service. This comes up during Menu Tree design when the Sysop types in command strings for module pages that give users access to your module. Sysop’s Guide has examples of these strings for Worldgroup’s the Major BBS’s baseline modules.

2. Command concatenation allows an experienced user to type several commands at once. For example, ERF from a menu that offers E for E-mail means: E-mail / Read messages / starting at the first message number.

...

This routine translates the user’s keystrokes from their selected language into 'Y' and 'N'. Suppose this line were in the French language .MDF file:

Code Block
        Language Yes/No:  OUI/NON

Then cncyesno() would work like this:

...

cncall(); expect a variable-length word sequence (consume all remaining input)

...

Example of Command Concatenation

...

User session:

Code Block
<...menu...> Q

QUIZ!

What is the first letter of the alphabet? A

How many fingers do you see? 0

END OF QUIZ!  You won!
Code Block
<...menu...> QA0

END OF QUIZ!  You won!

<...menu...>

Source code of user input handler entry point:

Code Block
      int
      sttqiz(void)
      {
           int retcode=1;
           do {
                bgncnc();
                switch (usrptr-
>substt
>substt) {
                case 0:
                     cncchr();          /* gobble the module select character */
                     prf("\
nQUIZ
nQUIZ!\n");
                     prf("What is the first letter of the alphabet? ");
                     usrptr-
>substt
>substt=1;
                     break;
                case 1:
                     if (cncchr() == 'A') {
                          prf("How many fingers do you see?\n");
                          usrptr-
>substt
>substt=2;
                     }
                     else {
                          prf("\
nThat
nThat's wrong!  You lose!\n");
                          cncall();
                          retcode=0;
                     }
                     break;
                case 2:
                     if (morcnc() && cncint() == 0) {
                          prf("\
nEND
nEND OF QUIZ!  You won!\n\n");
                          cncall();
                          retcode=0;
                     }
                     else {
                          prf("\
nThat
nThat's wrong!  You lose!\n");
                          cncall();
                          retcode=0;
                     }
                     break;
                }
           } while (!endcnc());
           outprf(usrnum);
           return(retcode);
      }

We’ve used prf() here instead of prfmsg() for simplicity. In practice we’d use prfmsg()s and put all text into a .MSG file (see page 79).

...

Exiting to the Parent Menu, or to your Module's Menu

...

condex(); conditional exit to parent menu for after handling concatenated commands

...

For example, you could code:

Code Block
        if (usrptr-
>flags
>flags&CONCEX) {
             prfmsg(X2MAIN);
             condex();
        }

Now, the result (if any) of condex() is identical to the result of exiting from your module’s sttrou() entry point while returning zero. The big difference is that you can call condex() anywhere, perhaps deep from some routine in your code, and the exit is taken immediately — you will never return from condex() if it takes any action at all. This feature is implemented using the setjmp() / longjmp() feature in the compiler library.

User-ID Cross Referencing

When writing an Electronic Mail message, users can type in part of a User-ID and the server will present them with all User-IDs that resemble it. The user can type in a more exact User-ID, or just pick one of the alternatives by number.

...

int rc; return Code (see below)

char *string;

...

Return Codes

...

UIDFND User-ID found, by exact match (case is unimportant), or picked by number. You should get the User-ID from uidxrf.userid, not from the string you passed to hdluid(). That string, even if it is an exact match, probably doesn’t have the right case. And it could always be a number if the user ended up picking the User-ID from a list.

...

The text output of hdluid() is in the prfbuf — your calling program must do an outprf() eventually.

Default Selection Character

You can allow Sysops to configure the default response to your prompts by (1) putting the default character at the end of the prompt, (2) using getdft() just before you output the prompt, and (3) using chkdft() when you get the reply.

Here’s an example of a text block with the default answer at the end:

Code Block
ASKVOW {Pick a vowel: A} T Prompt asking for a vowel

This is a little misleading to Sysops in that we aren’t going to send the A when we send the prompt. You could also do this:

Code Block
ASKVOW {Pick a vowel (press ENTER for "A"): A} T Prompt asking for a vowel

Here, if Sysops wanted to change the default to E, they would need to change two things:

Code Block
ASKVOW {Pick a vowel (press ENTER for "E"): E} T Prompt asking for a vowel

You want your code to use that final character before the } curly brace to fill in for a user who doesn’t pick any character and just presses enter. Here are the tools:

...

Then after the reply comes in, chkdft() checks to see if the user pressed just enter and, if so, makes the input variables look as if he had typed the character. Then your code can go about its business and parse the input.

User Status and Handling

ison=uinsys(usrid); determine if a user is online

...

int othusn; the user number of the other user

Code Block
 struct user *othusp; pointer to structure for that user in the user[] array (see MAJORBBS.H)
 struct extusr *othexp; pointer to extendible in-memory structure for that user (see extoff() below)
 struct usracc *othuap; pointer to structure for that user in the usracc structure (see uacoff() below)

These variables are analogous to usrnum, usrptr, and usaptr, see page 45. To get the other user’s language index, use extoff(othusn)->lingo.

...

Be careful not to use isripu() unless you know the clingo variable is available. For example, in an interrupt routine such as hpkrou() in MAJORBBS.C, only isripo() should be used.

Hanging up on a User

If you’ve decided, for whatever reason, to boot a user off of the Worldgroup Major BBS server, call byenow():

byenow(msgnum,p1,p2,...,pn);
say goodbye to a user and disconnect (implicit input: usrnum, channel to hang up)

...

If you need to do this for a user other than the one you’re servicing (other than usrnum, that is), then you need to temporarily save usrnum and restore it, as in:

Code Block
        usnsave=usrnum;
        curusr(othusn);
        byenow(LASERCEPT);
        curusr(usnsave);

This would do the dirty work for the othusn user. Note that usrptr and usaptr are not involved at this stage at all.

Intercepting User-Connect

You can intercept the moment that a user first connects to the Worldgroup Major BBS server using the (*hdlcon)() handle-connect vector:

...

The (*hdlcon)() vector starts out pointing to the gtansi() routine which is an internal (static) function in MAJORBBS.C. Use (*hdlcon)() just like the parasitic way in which you would use an interrupt vector: save its value (the pointer to some old function), put a pointer to your own function in its place, and then when your own function gets called, make sure to call that function whose pointer you saved (unless you think of something better to do).

Here’s a simple example:

Code Block
        void (*hcsave)();  /* save location for old handle-connect vector */

        void
        brblast(void);      /* blast low-baud rate users on high channels */
        {
             if (usrnum >= 32 && usrptr-
>baud
>baud < 9600) {
                  setmbk(dddmbk);
                  byenow(OTHERBAUD);
                  rstmbk();
             }
             else {
                  (*hcsave)();
             }
        }

        void
        install_brblast(void);              /* install baud-rate blaster */
        {
             hcsave=hdlcon;
             hdlcon=brblast;
        }

The brblast() routine hangs up on slow-modem callers on channels with user number 32 and higher. The install_brblast() routine should be called from your init__xxx() routine (exactly once, of course). It saves the current pointer in the handle-connect vector, and puts a pointer to brblast() in its place.

Now when anyone connects to the Worldgroup Major BBS server, brblast() is called. If their user number is 32 or greater and their baud rate is less than 9600, it sends some goodbye message (politely saving and restoring the current .MCV file handle) and prepares to hang up on the user. Otherwise, the user gets online like normal.

...

If you want to take over connect-time processing for multiple status conditions, then you’ll need to set up your own class, state and substate (remember the three context variables described on page 45?):

Code Block
        :
        usrptr-
>class
>class=BBSPRV;
        usrptr-
>state
>state=mystate;
        usrptr-
>substt
>substt=CONTSTEP1;
        usrptr-
>flags¦
>flags¦=NOGLOBS;
        :

Applies to: WG3.x

Header check: write usrptr->usrcls (MAJORBBS.H:105); see the note in chapter 3 at "usrptr->class".

If you do this, then your sttrou() and stsrou() vectors will get called for future events (such as the user entering a line of text or a status condition on that channel). BBSPRV is a special class that allows your module entry points to get called without deducting credits or limiting inactivity, etc. — you’re on your own. The mystate variable is the handle for your module (the return value of register_module()). The substt value CONSTEP1 is a local constant so you can distinguish this type of event in your entry point routines.

...

When done, you can return control to the powers-that-be and continue with the standard connect process by restoring usrptr->class and calling the saved vector value:

Code Block
        :
        usrptr-
>class
>class=VACANT;
        (*hcsave)();
        :

Notice that it’s important to restore usrptr->class (and remember that this use of the word class is in no way related to user security Classes).

...

margv[3] Callee’s network address (that of your WorldgroupMajor BBS)

margv[4] (optionally) User data field (nul-terminated string)

...

Looking through MAJORBBS.C, you may find that some of these vectors default to pointing to a routine that does nothing at all. If you change the value of one of these vectors, it is still good programming practice to call the routine it originally pointed to from inside of your new routine.

Autosensor Routines

Add-on Options may hook into the autosensing phase of the Worldgroup Major BBS server session — the very start when we probe the user’s terminal for signs of intelligent life. If there are any autosensors active, the Auto-sensing... message appears and then all autosensing routines are run in parallel on that channel.

...

For another example, say that to automatically detect compatibility with the ZEBRATerm terminal software you want to send out a Z immediately upon connection, and then wait for a ! reply. If the Worldgroup Major BBS server gets the reply within 1 second, it knows it’s talking to ZEBRATerm. But if it gets nothing for 1 second, it assumes not.

Here’s how such a ZEBRATerm autosensor might be coded:

Code Block
        int
        zebratest(
        unsigned snccon,
        char *incbuf,
        int nbytes)
        {
             if (snccon == 0) {
                  btuxmt(usrnum,"Z");
             }
             else {
                  while (nbytes--) {
                       if (*incbuf++ == '!') {
                            zebra[usrnum]=1;
                            setbyprot("/ZEBRA",2);
                            return(1);
                       }
                  }
                  if (snccon >= 16) {
                       zebra[usrnum]=0;
                       return(1);
                  }
             }
             return(0);
        }

To register your autosensor routine, you need to call regautsns() in your initialization code, for example:

Code Block
        :
        regautsns(zebratest);
        :

The code for regautsns() and related routines can be found in AUTSNS.C.

When a user first connects to a Worldgroup Major BBS server, all autosensor routines are called repeatedly. Each autosensor eventually returns 1 to indicate it is done, and from that point is no longer called for that session. When all autosensors are done, or 10 seconds elapse, whichever comes first, the autosensing phase is over.

...

This is a subtle but important point: autosensor routines should check for incoming data before checking for a timeout. This way, if the Worldgroup Major BBS server happens to get tied up with the other channels for an unusually long period, then when it finally does get around to servicing the autosensing channel, it properly handles any data received in the interim.

...

Just setting auswait=240 (15 seconds) might cause a problem for another autosensor that needed the master timeout to be at least 320 (20 seconds).

...

Voting Confidence Factors

...

All languages start out with a confidence factor of 1. Any autosensor can change the confidence factor of any language to any number between 0 and 100. The voting confidence factors for all languages and users is stored in this 2D array:

...

To set the voting confidence factor for the current user (usrnum) for the language ilingo to 5, you would code:

Code Block
        poslng[usrnum*nlingo+ilingo]=5;

You could vote on all languages with the same terminal protocol suffix with:

...

int fstcand; the winner, or the first language (lowest index) that is tied for first place

Client/Server User Support

Applies to: v10

Not in v10. The Client/Server (Visual Basic client app) mode was removed in v10 (MBBS10.txt section 2; the v10 history has the commit "Initial port of GALTELE including removal of AHTML and CS related code"). Read this passage as WG1-3.x history only.

...

If the server knows exactly what modules’ logon/hangup routines need to be called in order to drop straight to a specific terminal-mode module, it can skip calling unnecessary logon/hangup routines, providing the user with a much smoother journey into the module. You can specify which other modules need to be initialized in order to go straight into a module with an I need line in its .MDF file:

Code Block
I need: BBSFTF BBSFSD BBSFSE

This tells the server exactly which other modules to call logon/hangup routines for when dropping straight into your module. To specify that it doesn’t need any other modules, specify a blank I need line:

Code Block
I need:

As long as your module has no I need line, the server will be forced to assume it needs everyone, and treat your module as described above. You can also explicitly claim to need everyone with the following line:

Code Block
I need: Everyone

To force your module to be needed by someone else (they don’t know it, but they really do need you), use the Needs me line:

Code Block
Needs me: GALTLC

You can also force yourself to be needed by everyone with the following line:

Code Block
Needs me: Everyone

By default, your module should start out with a blank I need line. But, as you call upon services in other modules, you will need to include those other modules. The most popular modules to need are:

...

You can always tell a C/S-mode user in disguise as a terminal-mode user by the WSGCSU flag:

Code Block
if (!(usrptr-
>flags
>flags&WSGCSU)) {
    prfmsg(ANNOUN);
    outprf(usrnum);
}

You might want to make use of that knowledge in your logon routine to not output unnecessary announcements to C/S users dropping into terminal mode. To go even further, you might want to check the entstt field for such C/S users to see if they’re dropping straight into a module or not:

Code Block
if (!(usrptr-
>flags
>flags&WSGCSU) || usrptr-
>entstt
>entstt == 0) {
    prfmsg(ANNOUN);
    outprf(usrnum);
}

With the above code, the logon message won’t be output to C/S-mode users dropping straight into a module. Depending on the importance of your particular announcement message, this might be a very friendly thing for your module to do.

Although it’s ok to use the entstt in your logon routine to consider whether or not to display a logon message, it’s not ok to use it to decide whether or not to initialize your module for terminal-mode use. If entstt isn’t 0 and it’s not your module, it means that the user is going straight into another module. But, your module’s logon routine is still being called for a reason. It’s still fair game to be entered by the user or otherwise called upon. Otherwise, your logon routine wouldn’t have been called at all.

Virtual Terminal Mode (Agent Side)

Applies to: WG2+

The Virtual Terminal Mode (VTM) API is the Worldgroup Major BBS equivalent of Windows NT’s console mode API. Some Worldgroup Major BBS apps will need to make use of a standard ANSI terminal window to allow the user to interact. Doors is one of those apps in Worldgroup’s the Major BBS’s baseline package. Without dropping into terminal mode and running a terminal mode module, users in apps that use VTM (like Doors) can make use of a terminal window alongside other client/server apps.

...

Text sent from the server to the client is handled by unsolicited dynapaks. An API routine exists for an agent to send text to the client:

Code Block
vtmsend(instid,len,value);
// (can't be called until after vtmsendok(), below)

This routine requires the VTM instance id (communicated to the agent through the dynapak name in the initial read) in order to send the value to the client. The length of the value can be up to MAXDPKV. If given a choice, call vtmsend() fewer times with larger chunks of data rather than more times with smaller chunks. Each vtmsend() call translates into an unsolicited dynapak to the client. It would be very inefficient use of bandwidth to send one character per unsolicited dynapak. If you can help it, avoid this.

...

Applies to: WG1-3.x (client side: C/S, WGM)

Client side of VTM (vtmwin()): see 20-client-side-addendum.md.

...

Previous: Major BBS v10: 03 Operating Environment  |  Contents  |  Next: Major BBS v10: 05 User Services