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

char *ctlstg; printf()-like control string

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

Function prf() has the same syntax as printf(). However, the formatted output of prf() goes into a global buffer pointed to by prfbuf. An internal variable prfptr keeps track of where prf() should write into prfbuf: prf() starts writing text at prfptr, terminates the text with a nul (\0), and leaves prfptr pointing to the nul when done. This means that the output of several prf()’s in sequence are concatenated together. outprf() is commonly used to transmit the results of one or more prf()’s to a specific user.

As with printf(), there is no limit to the number of parameters (p1, p2,..., pn) that you may pass to prf(). They should correspond one-for-one with the % directives in the control string, and you must be careful not to overflow the prfbuf. Use PFBSIZ for the size of prfbuf, but it’s not a constant. PFBSIZ is computed to be the same as CNF option OUTBSZ in Configuration Options (Level 4) and is set by iniprf() at initialization time.

See page 270 for the coding of ANSI directives that you can transmit to user screens. For example, you could use:

prf("\33[37;44;0mFiberlink 92 to Munich is condition \33[32;1mGREEN!");

This sends a message that starts out white on blue and ends up flashing bright green on blue.

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

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

int unum; user number

This function transmits the contents of the prfbuf buffer to a specific user. When unum is anything other than usrnum, you should probably use outmlt() (page 98). The prfptr variable mentioned above is reset to the beginning of prfbuf. This means that several outprf()’s can be used to transmit the same text to different users, as long as no prf()’s intervene. But the next prf() will start at the beginning of prfbuf again.

clrprf(); clear the prf buffer independent of outprf

This function resets the prfptr mentioned above to point to the beginning of prfbuf and stores a \0 there.

char *prfbuf; output buffer of prf() and prfmsg()

This is the variable mentioned above that points to the buffer where user output is formatted. The contents of that buffer are transmitted by outprf() using the GSBL routine btuxmt().

char *prfptr; pointer to the current position in prfbuf

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

        setmbk(appmb);
        prfmsg(HOWAYA,usaptr->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:

        if (onsys(partner(usaptr->userid))) {
             prfmsg(PNRHERE,usaptr->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:

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

There are four routines that have multilingual cousins:

MonolingualMultilingual
prfmsg()prfmlt()
prf()pmlt()
clrprf()clrmlt()
outprf()outmlt()

Each routine has the same parameters as its cousin. The critical routine is outmlt(). It transmits formatted information to one user. That information must have been formatted by prfmlt() or pmlt(), and not prfmsg() or prf(). By the same token, outprf() should not be outputting information formatted by prfmlt() or pmlt(). If you combine prfmsg() and outmlt() then English/ANSI users will get text in the native language of the usrnum user, and all other users will get nothing at all. If you combine prfmlt() and outprf(), then all users will get the English/ANSI version.

When clearing the formatted information, it would be nice to use clrprf() or clrmlt() as appropriate, but you can always use clrmlt() if you’re in doubt (it does everything clrprf() does and more). clrmlt() is already called before every sttrou(), stsrou(), lonrou(), or lofrou() entry point, and also before every polling routine (page 72).

The monolingual routines are more efficient than the multilingual routines, so you should always use monolingual if you know you are outputting to the current user only. In most of Galacticomm’s software the vast majority of text blocks go to the current user.

Whenever output goes to a user other than usrnum, the most convenient thing to do is to use the multilingual suite of routines. In the above case, when prfmlt() formats PNRHERE, it first checks what languages are represented online (including that of the current user) and then for each one, formats a version of PNRHERE for that language. There’s actually a separate prfbuf-type buffer allocated for each language. Here’s how to get each buffer’s address and pointer:

ptrtile(prfbuffers,ilingo);
the address of the prfbuf for language ilingo

Applies to: WG3.x

Header check: ptrtile() is not declared in WGDEV/INC (WG2 PLSTUFF.H:34). prfbuffers is declared EXPWGSV(VOID*) prfbuffers; (GCOMM.H:832, "tiled array of prf() output buffers"); use the multilingual calls (pmlt(), GCOMM.H:858) rather than indexing the buffers.

prfpointers[ilingo] the address within the ilingo’th prfbuf where we’re currently formatting text.

The language 0 version goes in the first of the prfbufs, which is prfbuf itself. If anyone is online with language 1 selected, then the language 1 version goes in the prfbuf buffer number 1, and so forth, from 0 to nlingo-1. When formatting is done, then outmlt(othusn) sends the appropriate version of the text to user number othusn.

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:

        if (onsys(partner(usaptr->userid))) {
             clingo=extoff(othusn)->lingo;
             prfmsg(PNRHERE,usaptr->userid);
             outprf(othusn);
             clingo=extptr->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.

But both of these methods (prfmlt/outmlt and changing clingo) have an important drawback — they don’t reprompt the other user. The other user was probably sitting at some prompt and it would be polite to show him that prompt again, after your interrupting message.

Here’s the best way to send a message to another user who is online and may be using any service at all on the server:

got=injoth(); inject a message to another user
implicit inputs:
othusn ... channel # to inject to
prfbuf ... message to be injected

int got; 1=user got it 0=user was busy

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 the Major BBS. This message is an interruption. injoth() is used, for example, for:

    the Teleconference page feature and the global /P commandthe Sysop send-message function (F2)notifying online users that they have received Electronic Mailnotifying users that credits have been posted to their accountThe message will not be injected if the recipient’s NOINJO flag (in user[othusn]->flags) is set, as it is when he is downloading, in Sysop Chat mode, or is otherwise unavailable. The value returned by injoth() indicates whether or not this happened: 1=user got the message; 0=user did not get the message.

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

            if (onsys(partner(usaptr->userid))) {
                 prfmlt(PNRHERE,usaptr->userid);
                 if (injoth()) {
                      prfmsg(PNRTOO,othuap->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.

    You should probably always use prfmlt() or pmlt() to format the text for injoth(), not prfmsg() or prf().

    In the above example, prfmlt() generates the text for injoth(), but if prfmsg() had been used it would inject the text in the clingo language only.

    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:

    Right wayWrong way
    int unsave;int unsave;
    ::
    unsave=usrnum;unsave=usrnum;
    curusr(userno);usrnum=userno;
    ::
    curusr(unsave);usrnum=unsave;

    The curusr() routine sets up many global variables in tandem with the new user number, like usrptr, usaptr, and extptr. It also sets clingo to the new user’s language index.

    curusr(newunum); Change to a different user number

    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:

            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.

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

    The variables in this section are implicit inputs to the sttrou(), lonrou(), and lofrou() entry point routines for a module.

    int margc; number of words in user input line

    char *margv[]; array of pointers to the words in user’s input line (there are margc of these pointers)

    char *margn[]; array of pointers to the ends of the words (to the terminating nuls)

    These variables are initialized by the function parsin():

    parsin(); parse input line (insert \0 after each word, compute margc and margv[])

    The parsin() routine is always called before control is passed to your module through the sttrou() entry point. The user’s input line is “parsed” into individual words, with the intervening spaces removed and \0 terminators placed on each word. The global variable margc is the number of words, and margv[] is an array of pointers to those words. Each word contains no spaces and is terminated by nul (\0). margc and margv[] work very much like the C language argc and argv[] work for command line parameters passed to the main() routine.

    char input[]; user input line

    int inplen; total length of the input line in bytes

    rstrin(); restore parsed input line (undo effects of parsin())

    The rstrin() function restores the user’s input to its original form (the nuls are removed and the spaces restored), undoing the effects of parsin(). After calling rstrin(), you use the global variable input[] to refer to the user’s entire input line.

    For example, if a user types in the line RAIN IN SPAIN followed by enter, then the sttrou() entry point of the current module is invoked with:

    margc is 3

    margv[0] points to RAIN

    margv[1] points to IN

    margv[2] points to SPAIN

    If you call rstrin(), then:

    input[] points to RAIN IN SPAIN

    You can still use margv[] pointers after rstrin(), but don’t expect the same results as before. Although each margv[] still points to the same initial character in each word, the terminating nul has been removed from all but the last. For example,

    margv[0] now points to RAIN IN SPAIN

    margv[1] now points to IN SPAIN

    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

    To turn echo off for a channel, use:

    btuech(usrnum,0) Turn echo off for this channel

    Then use echon() to turn it on again. Don’t use btuech(usrnum,1) to turn echo on. To echo secret characters, such as **** during password entry, use this routine:

    echsec(c,width); Echo secretly

    char c; character to echo with every keystroke

    int width; maximum number of characters expected

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

    From a programming perspective, the idea is to loop through the characters and parameters of the user’s command. The global variable nxtcmd in CNCUTL.C keeps track of what has already been interpreted from the user’s command — it points to the rest of the command.

    bgncnc(); begin command concatenation

    After calling bgncnc(), the command is unparsed (has spaces again, not separate words), and prepared for interpretation using the command concatenation utilities.

    done=endcnc(); are we done with the user’s command?

    int done; 1=yes, done 0=no, there’s more

    After calling endcnc(), the rest of the command is put back into input[] and re-parsed (margc and margv[] are recomputed), just as if the user had typed in the rest of the command starting from this point. If anything is left from the command, this function returns false.

    ch=morcnc(); is there any more command?

    char ch; next character (‘\0’ if none)

    The morcnc() routine tells you if there are any more characters left in the command. It first skips any leading blanks and returns the next nonblank character. The character that is returned is not skipped. If you want to use this character, then call cncchr().

    The remaining utilities read a single parameter (character, number, etc.) from the user’s command string.

    ch=cncchr(); expect a character from the user

    char ch; the next character (‘\0’ if none)
    (converted to upper case)

    n=cncint(); expect an integer from the user

    int n; the integer (0 if none)

    ln=cnclon(); expect a long integer from the user

    long ln; the long integer (0L if none)

    n=cnchex(); expect a hexadecimal number

    int n; the number (0 if none)

    ptr=cncnum(); expect a decimal number

    char *ptr; optional ‘-‘ followed by decimal digits (no conversion — returns ASCII string)

    wrd=cncwrd(); expect a space-delimited word

    char *wrd; truncated if over 29 characters

    uid=cncuid(); expect a User-ID or Forum name

    char *uid; the User-ID or Forum name

    signam=cncsig(); expect Forum name, with or without /

    char *signam; always returns name with /

    yesno=cncyesno(); expect yes or no from the user

    int yesno; 'Y'=yes, 'N'=no

    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:

            Language Yes/No:  OUI/NON

    Then cncyesno() would work like this:

    user inputs:cncyesno() returns
    oY
    ouiY
    nN
    nonN
    QUE?Q
    yY

    The cncyesno() routine returns the next character from the command and removes it from nxtcmd. This is also what cncchr() does. One difference: the translation described above. Another difference: if the user enters the entire word for yes or for no, then all of those characters are removed from nxtcmd too. But cncyesno() still only returns Y or N in those cases.

    For cases when yes/no decisions are not made through cncyesno(), you could use lingyn():

    yesno=lingyn(firstc); translate user’s yes/no into 'Y'/'N'

    char yesno; ‘Y’ if yes, ‘N’ if no, otherwise toupper(firstc)

    char firstc; first character of user’s response, should be the first character of the yes or no words in that user’s language.

    ilingo=cnclng(); expect a language name or language pick from numbered list (1 to nlingo)

    int ilingo; returns language index, 0 to nlingo-1, or -1=invalid name or number

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

    Example of Command Concatenation

    User session:

    <...menu...> Q
    
    QUIZ!
    
    What is the first letter of the alphabet? A
    
    How many fingers do you see? 0
    
    END OF QUIZ!  You won!
    <...menu...> QA0
    
    END OF QUIZ!  You won!
    
    <...menu...>

    Source code of user input handler entry point:

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

    This routine can be used to return the user to the parent menu after the servicing of a string of concatenated commands that either came from the module’s command string or from what the user typed.

    To help handle these kind of situations, you may be able to make use of the CONCEX flag to give you fair warning of what condex() will do. Whenever a user enters a module from a Menu Tree menu, the (usrptr->flags&CONCEX) flag is:

      Set if the EXICNC CNF option is set to YES and the user concatenated two or more command characters together; orCleared if EXICNC is NO or if he typed a single character. It remains set (or cleared) throughout the user’s activities in the module.

      How you should use condex(): When your code would normally return the user to your module’s internal menu (but not normally to the parent Menu Tree menu), then you can call condex() to conditionally exit to the Menu Tree menu at that point. By the way, condex() tests the CONCEX flag and does nothing if it is not set.

      For example, you could code:

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

      To use this feature in your own program when you need the user to type in a User-ID, use the hdluid() routine:

      rc=hdluid(string); find User-IDs that resemble a string

      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.

      UIDPMT More than one possible match, or no matches at all. You need to reprompt a short prompt asking for a User-ID. You should be able to use the same prompt you did just before you first called hdluid(). Then pass the string received from the user to hdluid() again. If there were multiple possibilities, they’ve just been listed out. It should be obvious to the user in that case that he can just type in a number.

      UIDCAL Continue calling hdluid(), no prompting is necessary. The user has just specified an incomplete User-ID, there’s only one possible match, and now we’re asking the user to confirm yes-or-no.

      Before you pass the string to hdluid() (which is usually the return value of cncall()) you should check it for special values like X for exit or ? for help. You may be accommodating other possible entries. Then as a last resort, try hdluid().

      If you get the return value UIDPMT or UIDCAL, then hdluid() expects to get called again. If that doesn’t happen for some reason (the user typed X to exit and you intercepted it), then be sure to call clrxrf():

      clrxrf(); Abandon User-ID cross-referencing

      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:

      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:

      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:

      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:

      dftchr=getdft(); Get the default character and remove it from prfbuf

      char dftchr;

      chkdft(dftchr); Put the default character in the input buffer, if user just pressed enter

      You call getdft() after you have prfmsg()’d the prompt and you’re about to use outprf(usrnum) to send it to the user’s terminal. getdft() strips the character out of the prfbuf buffer (so it never gets to the user’s terminal) and returns it for you to hold onto. You can also use the final cursor position feature of WGSDRAW and getdft() will work properly.

      The tricky part is that you need to save this default character between cycles somehow. You get the character from getdft() when you send the prompt, but you need to use it when the user gets around to typing in a reply.

      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 ison; true if user anywhere online

      char *usrid; User-ID to be tested for

      int uisusn; global variable, set to user number when uinsys() returns 1

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

      int ison; true if user online & logged on

      char *usrid; User-ID to be tested for

      The differences between uinsys() and onsys() are:

        onsys() only returns true if the user has already logged on.
        uinsys() also catches that space of time between typing in User-ID and password when we think the user is about to log on.uinsys() sets the global variable uisusn.
        onsys() sets othusn, othusp, and othuap (see below). isin=instat(usrid,qstate);
        see if a user is using a specific module

        int isin; true if user is in the module

        char *usrid; User-ID to be tested for

        int qstate; state (module number returned by register_module())

        If either instat() or onsys() return true, then the following global variables are also set:

        int othusn; the user number of the other user

         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.

        All of the above routines will return false, by the way, for a user with Sysop privileges when he has selected /invis to become invisible. If you need to penetrate the Sysop invisibility veil for some reason you could use the following routines instead:

        use onbbs(usrid,1) instead of uinsys(usrid) anywhere online

        use onsysn(usrid,1) instead of onsys(usrid) logged on

        This might be necessary if you were trying to decide whether to modify a user’s account record in memory or on disk for example. There are several examples of this in ACCOUNT.C and ACCSCN.C.

        To reference the user account information of someone who is online, don’t use the usracc[] array directly. Since that array might be larger than 64K, you must use uacoff():

        uaptr=uacoff(unum); Get online user account info

        struct usracc *uaptr; pointer to in-memory account info

        int unum; user number

        And similarly with the extended in-memory array, use extoff():

        exptr=extoff(unum); Get more online user info

        struct extusr *exptr; pointer to extendible in-memory info

        int unum; user number

        For dealing with RIP support, the following exist:

        int ripdfd; 1=at least one /RIP language is defined, or 0=none

        int ripidx; Index of the first /RIP language, 0 to nlingo-1, or nlingo if there are no /RIP languages

        hasrip=isripu(); Is this a /RIP user?

        int hasrip; 1=yes, 0=no

        hasrip=isripo(unum); Is that a /RIP user?

        int hasrip; 1=yes, 0=no

        int unum; user number, 0 to nterms-1

        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 Major BBS server, call byenow():

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

        int msgnum; message number in current .MCV file (don’t forget setmbk(), page 91)

        TYPE p1,p2,...,pn; parameters if any (max 12 bytes)

        This routine will make reasonably sure that your goodbye message gets transmitted to his screen, and then his session will be terminated. You may still get status codes after calling byenow(), but you can check the usrptr->flags&BYEBYE flag to detect that situation. You will definitely get a call to your huprou() entry point.

        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:

                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 Major BBS server using the (*hdlcon)() handle-connect vector:

        void (*hdlcon)(); Handle-connect vector

        When any channel — modem, serial, X.25 or LAN — establishes a connection with the user’s terminal, then the function pointed to by this vector gets called. Here are the final events on the different types of channels that occur before the (*hdlcon)() vector gets called:

        Modem channel CONNECT received

        Serial channel Any cr-terminated string received

        X.25 channel X.3 programming complete (X.29 string sent)

        IPX Direct channel Any cr-terminated string received

        IPX Virtual channel Any packet received

        SPX channel Connection established

        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:

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

        The connect handler that you install by this method is limited in what it can do. Keep in mind that other modules might be intercepting the vector too, and you really shouldn’t be depending on one to execute before the other. And if you want a user to log on, you should relinquish complete control and let the normal connect sequence proceed. In other words, call the function whose pointer you saved.

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

                :
                usrptr->class=BBSPRV;
                usrptr->state=mystate;
                usrptr->substt=CONTSTEP1;
                usrptr->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 a channel is in the BBSPRV class, it has the equivalent of MASTER status (also known as carrying the MASTER key), the ability to pass through any lock. It is absolutely mandatory to set the NOGLOBS flag, else the user can execute privileged global commands (/L SYSOP, for example) while you handle connect-time processing.

        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:

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

        Whatever another handle-connect routine does, you should be able to rely on it to either set the usrptr->state code or call byenow(). gtansi() does assume you’re still in the VACANT class in some cases.

        There are other moments in the connection process with vectors you can intercept:

        void (*hdlrng)(); Handle-RING-string vector

        This routine can be used for auxiliary handling of the RING that comes in on modem channels. The routine would get called on every RING before the CONNECT message. The RING and any text that might follow it are available by consulting margc and margv[].

        void (*hdlnrg)(); Handle-non-RING-string vector

        This vector is called when a string other than RING is received on a modem channel that is awaiting an incoming call. The string is available by consulting margc and margv[]. You might use this to handle strings other than RING in some special manner.

        int (*hdlcnc)(); Handle-CONNECT-string vector

        This vector gets called on a modem channel when the first non-RING string is received following the RING string. The string is available by consulting margc and margv[]. Return values are:

        -1 Ignore the string

        0 Reset the channel and get ready to receive another incoming call

        1 Connection complete, the (*hdlcon)() vector will get called after a short pause

        You might intercept (*hdlcnc)() if you wanted to handle the parameters of the CONNECT string in some special way, or if you were expecting legitimate messages other than RING or CONNECT to come in.

        int (*hdlc25)(); Handle-X.25-connection vector

        This vector gets called at the beginning of every X.25 call. You could intercept it to process the parameters of the incoming X.25 call:

        margv[0] RING

        margv[1] Caller’s network address

        margv[2] CALLING

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

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

        margv[4] will only be available if margc >= 5 and if you have set the x25udt flag in advance (see GSBL Guide).

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

        Add-on Options can register autosensing routines to test for particular features in each user’s terminal and vote on which languages or protocols he should use. See the ansisns() routine in MAJORBBS.C for an example.

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

                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:

                :
                regautsns(zebratest);
                :

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

        When a user first connects to a 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.

        Each autosensor routine will be called with the same three parameters as in the above zebratest() example:

        unsigned snccon; count of 1/16 seconds since connection was established with this channel — the first call is always zero and each call after that is steadily increasing (and nonzero)

        char *incbuf; buffer of incoming binary bytes on this channel — this same data is shared by all autosensor routines

        int nbytes; number of bytes in incbuf

        As you can see in the example, usrnum is an implicit input to the autosensor, as well as usrptr and usaptr and other global session variables.

        Your autosensor routine will need to return an int indicating whether the autosensing is done for that channel.

        autosensor return value 1=done autosensing
        0=still working on autosensing

        You can count on the fact that the snccon parameter will be zero the very first time your autosensor is called for a session, and always nonzero after that for the same session. So use the (snccon == 0) case to initialize things if you need to. In every call after that, snccon will be at least one, even if it’s 0.000001 second later. In the above example, we transmit the Z right off the bat and return 0 (zero because we know we’re not done autosensing yet). Otherwise we check for incoming data.

        This is a subtle but important point: autosensor routines should check for incoming data before checking for a timeout. This way, if the 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.

        Suppose in the above example that within such a delay of a second or more, a ! reply did come in. Then zebratest() gets called with both a timeout condition and data available. Clearly the data available condition should take precedence (as it does in this example).

        After checking for incoming data, we take a glance at the watch. If our one second’s up, we give up and assume that we’re not connected to ZEBRATerm. Remember that other autosensor routines might be at work here so if we don’t understand the incoming data we have to ignore it.

        This autosensor’s ultimate job, when it detects ZEBRATerm, will be to set the zebra[] array element for each user to indicate 1=ZEBRATerm, 0=not. It will also vote for the languages that end in /ZEBRA with a confidence factor of 3. We’ll take a closer look at what this voting business is all about in the next section.

        All autosensing is subjected to a 10-second master timeout, so if any autosensor takes more than 10 seconds for any reason, the autosensing period will end anyway. You can change this master timeout if you like by changing the value of the global auswait variable:

        unsigned auswait; master autosensing timeout, in 1/16 of a second (e.g. 160 = 10 seconds)

        The healthiest way to change this is probably to be sure you only increase it, as in:

        auswait=max(auswait,240);

        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:

        char *poslng; pointer to a 2D array of voting confidence factors (varies fastest by language, then by user number, has nlingo*nterms total number of elements)

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

                poslng[usrnum*nlingo+ilingo]=5;

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

        setbyprot(suffix,value);
        set voting confidence factor by protocol

        char *suffix; language name suffix

        char value; voting confidence factor

        This routine will find all languages with names that end in suffix and set their voting confidence factor to value. See the example call to setbyprot() in the zebratest() example above.

        At the end of the autosensing period, the language with the highest confidence factor automatically becomes the language for that channel. If there’s a tie, as is often the case, then what happens next depends on the LANGOP CNF option located in Configuration Options:

        LANGOP=ASK Display a numbered list of the languages that have the highest confidence factor, and ask the user which one he wants to use.

        LANGOP=AUTO Just go ahead and select one of the languages with the highest confidence factor (it picks the language with the lowest numbered index, but the Sysop can’t count on which language that is, unless it’s English/ANSI).

        The voting confidence factors are available throughout a user’s session. To determine the top factor, call

        numcand=cntcand(); determine the maximum voting confidence factor, among all the languages, and how many languages have it

        Here are the implicit return values of cntcand():

        int maxcand; maximum voting confidence factor among the languages

        int numcand; =1, one language is clearly the winner
        >1, more than one language is tied for first place (numcand is a global variable and it’s also the return value of cntcand())

        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.

        *Terminal mode module logon routines are otherwise not called for C/S users.

        Client/server users are allowed to drop into terminal mode in order to use terminal-mode modules. When a user drops down to the terminal-mode main menu, all terminal-mode modules’ logon routines are invoked as if an ordinary terminal-mode user had just logged on.*

        The user then uses terminal mode as if he had made contact with the server through any other ASCII/ANSI terminal program. When he returns to C/S mode, all terminal-mode modules’ hangup routines are called, as if an ordinary terminal-mode user had hung up.

        The Sysop can specify that a C/S menu option should lead directly to a specific terminal mode module. Assuming the terminal mode module hasn’t had its .MDF file updated for C/S support, all terminal mode logon routines (and eventually hangup routines) are called, as with the main menu above. After all of the logon routines are finished, the user is automatically put into the specific module.

        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:

        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:

        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:

        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:

        Needs me: GALTLC

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

        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:

          BBSFSE for the FSE (full screen editor) services;BBSFTF for the FTF (file transfer facility) services; andBBSFSD for the FSD (full screen data entry) services.Note: Of course, all of the standard Replaces logic is figured into arriving at what modules are really needed by what other ones.

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

          if (!(usrptr->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:

          if (!(usrptr->flags&WSGCSU) || usrptr->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 Major BBS equivalent of Windows NT’s console mode API. Some 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 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.

          Implementing a VTM interface involves work in both the app and corresponding agent. The app’s role is simple: fire up the VTM window. If you haven’t read about it already, see the Virtual Terminal Mode section on page 22 for how the client initiates a VTM session. Following are details on implementing the agent side of a VTM session.

          Worldgroup Manager takes the dynapak name passed by the app to vtmwin() and appends a unique instance id (an integer turned into a string) to it. It then reads that dynapak. The agent should be on the lookout for such reads. When one comes in, it should take note of the instance id on the end of the dynapak name (to keep multiple VTM sessions with the same user distinct). It should leave the read outstanding (not respond right away). Whenever the read is terminated (responded to, aborted, etc.), whether by the client or the server, the VTM session is considered over. While the VTM session is ongoing, the read will be outstanding, so the agent can feel free to use the read request’s per-request memory to keep track of information about the session.

          When the user types in the VTM window, dynapaks will be sent to the agent. The dynapaks will be writes of the same dynapak name as the initial, outstanding read. The value of these writes will be the text typed by the user. Actually, the text sent in these dynapaks isn’t necessarily typed by the user. It could be file transfer data (since the user does have file transfer options available to him).

          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:

          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.

          An agent is only allowed to call vtmsend() immediately after a successful call to vtmsendok(). Call vtmsendok() with the channel you would like to send VTM data to. If it returns FALSE, you’ll have to wait (data needs to be throttled) and try again later. If it returns TRUE, you can immediately call vtmsend(), but only once. You need to call vtmsendok() again if you want to call vtmsend() again.

          Applies to: WG2+

          Header check (GCSPSRV.H): the routines are declared as BOOL vtmsndok(int tochan) (tochan is the C/S user’s usrnum) and void vtmsend(int srcid,int length,void *value) (srcid is the source identifier, i.e. the VTM instance id). The addendum’s "vtmsendok()" is the header’s vtmsndok(). MAXDPKV is 16384 (GCSP.H).

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

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