Versions Compared

Key

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

...

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.

...

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.

...

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.

...

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:

...

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

...

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.

...

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:

...

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.

...

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.

...

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.

...

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

...

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.

...

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:

...

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.

...

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