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():
...
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:
...
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.
...
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.
...
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!...
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
...
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.
...
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
...
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)
...
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:
...
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.
...
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.
...
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:
...
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.txtsection 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.
...
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.
...