Technical manual
******************************************************************************* * * * chat - an EMAS utility to allow users to chat to each other using the 2900.* * * * Copyright (c) 1982 by James Darby at UKC. * * Assembler routines by R.D.Eager at UKC. * * * * Version 2.35 * * * * * *******************************************************************************
Introduction
This is the source code of the EMAS chat utility. It allows users to hold an interactive conference on several terminals on an EMAS 2900 system. Its main features are :- 1) Low OCP overhead. The utility uses any a small amount of OCP time. This is obtained by use of the d delay call in Director when the program is waiting for input. 2) max chatters (see below) people max in one chat. Up to max chatters (see below) people can be chatting away at once. 3) Ease of use. Chatters may be as passive or active as they please. 4) Fun for all the family. Great for annoying operators and operations supervisors. 5) "Available in easy to swallow capsules" .........
Constants used
Max message descriptors is the number of message descriptors in the chat file. After this is reached most of the routines cycle round to the first. Max chatters is the maximun number of chatters allowed at once. Max commands is the number of the commands the program has. Chat file size is the size of the chatting file created. Decline is a pseudo type used for the tell user routines. Invite is the same as decline, but performs a different function Number of system processes is what it says it is. %constant %integer max message descriptors = 50, max chatters = 10, max commands = 8, chat file size = 8192, decline = 1, invite = 2, number of system processes = 4 This %constant %long %integer is the mask for the normal interrupts. i.e. A, C, Q, W, X, Y and a, c, q, w, x, y. Note that this includes the operator ST log off command, this is perhaps a bit naughty to trap, but we must if we are to stop the program from crashing if someone is forced off the system. It does not stop the XST however (nothing can). %constant %long %integer interrupt mask = X'0382000A0382000A' These constants are used to help psuedo boolean variable values %constant %integer true = 1, false= 0 This constant string holds the list of commands. Note that they are in lower case, but we convert upper into them. %constant %string(max commands) command string ="cdiruvw?" This %constant %string %array holds the error messages from cheak name. %constant %string(25) %array fail reason (1:4) = %c "Talking to yourself ?????", "Invalid user name.", "User not known.", "User not logged in."
Record formats used.
Connect report format
This is the format of the %record returned by connect to indicate various information about how the file was connected (assuming it was). %record %format connect report format(%integer conad, file type, data start, data end)
Descriptor format
This is the format of a single entry in the message area. The integer contains the number of the chatter who transmited the message, and the string the message itself. %record %format descriptor format (%integer from, %string(123) text)
Head format
This is the format of the heading record in the message area. The first four integers are numbers that must be common to all the chatters and are locked by the fourth which is the semaphore. %record %format head format (%integer current top, users, close, semaphore, %string(31) %array names (0:max chatters), %string(6) %array real names (0:max chatters))
Message area format
This is the format of the entire message area. It consists of the header record followed by the array of message descriptors. %record %format message area format (%record (head format) head, %record (descriptor format) %array %c descriptor(1:max message descriptors) )
it f
This highly YUCH format is that used by the communications software to control the console of the user. %record %format it f (%integer in base, in length, in pointer, out base, out length, out pointer, out busy, om waiting, intt waiting, jn base, jn cur, last free, spare 5, spare 6, spare 7)
io stat f
Again this is a format concerned with the i/o system. This is simpler in that it just contains the current position of read data in T#IT and any multi-character interrupts that have occured. %record %format io stat f (%integer in pos, %string(15) int mess)
procs format
This is the format of the information returned by the system call d procs. It has tonnes on gumf on whats happening to a process. %record %format procs format ( %string(6) user, %byte incarnation, catagory, snzt, run q, %integer actw0, lstad, lamtx, stack, status)
comf
This is the format of the common data area in EMAS. This table is stored at location X'80C00000' (ie in the public segment). %record %format comf (%integer ocptype, ipldev, sblks, sepgs, ndiscs, dlvnaddr, gpctabsize, gpca, sfctabsize, sfca, sfck, dirsite, dcodeda, suplvn, tojday, date0, date1, date2, time0, time1, time2, epagesize, users, cattad, servaad, %byteinteger nsacs, resv1, sacport1, sacport0, nocps, resv2, ocpport1, ocpport0, %integer itint, contypea, gpcconfa, fpcconfa, sfcconfa, blkaddr, ration, smacs, trans, %longinteger kmon, %integer ditaddr, smacpos, supvsn, pstva, secsfrmn, secstocd, sync1dest, sync2dest, asyncdest, maxprocs, inspersec, elaphead, commsreca, storeaad, procaad, sfcctad, drumtad, tslice, feps, maxcbt, performad, sp1, sp2, sp3, sp4, sp5, sp6, lstl, lstb, pstl, pstb, hkeys, hoot, sim, clkx, clky, clkz, hbit, slaveoff, inhssr, sdr1, sdr2, sdr3, sdr4, sesr, hoffbit, blockzbit, blkshift, blksize, end)
References in Subsystem
Connect
This is the Subsystem call to connect a file. %system %routine %spec connect (%string(31) file, %integer mode, hole, protection, %record (connect report format) %name report, %integer %name flag)
set ss inhibit
This subsystem call disables interrupts for a short while..... %system %routine %spec set ss inhibit
allow interrupts
This system call allows interrupts again %system %routine %spec allow interrupts
out file
This Subsystem call sets up a file for output. If the file exists then that is used, else as in this program it is created. %system %routine %spec out file (%string(31) file name, %integer size, hole, protection, %integer %name conaddr, flag)
destroy
This is the %system version of destroy. It is used by the chat leader to destroy the file SS#CHAT at the end of a chatting session. %system %routine %spec destroy(%string(31) file, %integer %name flag)
reroute contingency
This is the reroute contingency specification. Look in the Subsystem documentation to find out compleate details. In short it allows us to trap interrupts and to act on them. %system %routine %spec reroute contingency (%integer ep, class, %long %integer mask, %routine on trap, %integer %name flag)
signal
This is the signal routine in the Subsystem. See Subsystem documentation for further details. In short it allows us to signal an event to the error handler in the Subsystem. %system %routine %spec signal (%integer ep, p1, p2, %integer %name flag)
console
This is a highly PUTRON routine that performs about 10000000000 different functions. We use it to find the address of it and io stat. %system %routine %spec console(%integer ep, %integer %name start, length)
disconnect
This call is used to disconnect a connected file. We use it to disconnect the leader SS#CHAT file when non-leaders leave the chat. %system %routine %spec disconnect (%string(255) file, %integer %name flag)
permit
This call is used by the chat leader to permit the SS#CHAT file to everyone so that they can chat into it. %system %routine %spec permit (%string(31) file, %string(6) user, %integer mode, %integer %name flag)
uc translate
This call simply translates from lower to upper case all the bytes from address for length bytes. %system %routine %spec uc translate (%integer address, length)
failure message
This string function allows us to pick up the appropriate failure message from the subsystem. %system %string(255) %function %spec failure message(%integer failure code)
terminate
This call flushes the output buffer to the console. %external %routine %spec terminate
Prompt
This just sets up the prompt for the user. %external %routine %spec prompt(%string(255) p)
set return code
This sets the return code in the subsystem for the chat program. %external %routine %spec set return code (%integer code)
d delay
Good ol' d delay !!! This delays its arguments number of seconds before returning. N.B. No OCP time is used. %external %integer %function %spec ddelay(%integer n)
uinfi
This is the general purpose information function. %external %integer %function %spec uinfi(%integer n)
call
This revolting routine is supposed to allow user program to call other subsystem commands. It is so fragile that I have had to de-impliment the subsystem escape!!! %external %integer %function %spec d fsys(%string(6) user, %integer %name fsys)
d fsys
This rather natty director call allows us to find out what disc pack a user is on. Speeds up d message and connect a lot!!! %external %routine %spec call (%string(31) command, %string(255) param)
d message
This is the routine called by TELL. It sends the bytes from address of length bytes to user on fsys. The action is the sort of action wanted. %external %integer %function %spec d message(%string(255) user, %integer %name length, %integer action, fsys, address)
unifi
This is the string general info function. %external %string(255) %function %spec uinfs(%integer n)
d procs
This supervisor call allows us to access the names of all processes on the system. It also gives lotsa uvver gunk. %external %integer %function %spec d procs (%integer %name max processes, %integer address)
Global variables used.
The global variables used are:- %integers: flag : General purpose flag, often return by system calls. conaddr : Connecting address of files. last look : Last message looked at. our semaphore : Have we got the semaphore ? my top : Top message looked at. me : My number on the chat. fsys : File system of someone (usually chat leader). input since - last print : Any input since we last did some output? %strings: my message(255) : The line the user last typed. last from(31) : Name of person from whom last mesage came.
%records: message area : Used to hold messages. Defined as %name and mapped. io stat : I/O status in communications package. Very complex. it : Interactive terminal. Used to hold pointers for user. connect report : Return by connect to give connecting information.
Plebian service routines
These routines are just simple routines called by the main body of the program.
in string
%routine in string(%string(255) %name input) In this routine we read in a string into the %name passed as parameter. Local variables. %integer: ch : used to hold the ascii value of the character just read. %integer ch
This %on %event block picks up any end-of-input and forces the routine to exit with "*" as the result. (This is the string used to indicate the end of chat.) Note however that if we are the chat leader then we force the ~c command. This closes down the chat. %on %event 9 %start %if me = 1 %then input = "~c" %else input ="*" %return %finish
First clear the input line to an empty one. input = "" Now loop round inputting characters and adding them to the end of the line being input. The loop is ended when the new line is found. Note that the new line is NOT added onto the end of the string. %cycle read symbol(ch) input = input.to string(ch) %unless ch = nl %repeat %until ch = nl And thats all there is .......... %end
print line
%routine print line (%string(255) line) This routine is really very simple, all it does it to print out the string followed by a new line. print string(line) new line %end
get name
%string(32) %function get name This routine gets the name of the user. It first calls uinfs(7) which is the systems idea of what the users name is. If this returns with the blanket name "Course" then the job number is used instead. This is found by calling uinfs(1). This is very boring so the ~r command has been included. Local variables:- %string(32) system name : Holds the name as its thought out. %string(32) system name system name = uinfs(7) %if system name = "Course" %then system name = uinfs(1) %result = system name %end
fail
%routine fail(%integer fail no) This routine is called when there is some failure in the chat program. It prints out the apppropiate error message and the halts the program. Note: This is liable to be a very serious fault, but hasn't happened yet. The code at this point attempts to tidy up as best as possible. This is not allways going to work, but one can but try. Local variables:- %integer users address : Is used to hold the address of the users field in the message area. %integer users address
General service routines
send to user
%routine send to user (%string(255) %name chatter, %integer what message) This routine sends an invitation to another user to join into the chat. It call a straight forward version of d message. Note: It requires fsys to have been found and the name validated. Both of these can be done by calling check name before. If fsys and name are not Ok then the d message call is likely to complain in very strong terms. In this case we print out the system error mesage (using failure message). Local variables: %integer: len : Used to hold the length of the message. mesg addr : Used to hold the address of the message. %string(80): intro : Holds the message.
test for logged on
This function tests for a user being logged on forground on the system. It does this by calling the highly obnoxious director call d procs. One of the many "features" of this routine is that it insists on providing a result for process 0. This can NEVER exist!!!!
check name
%integer %function check name (%string(255) %name name) This routine checks a users name and fills in fsys. It will give a non-zero %result if there is an error. These %results are :- 1) Attempt to talk to self. 2) Invalid user name. 3) User not known. 4) User not logged in. Local variables. %integer: max processes : Holds systems max number of processes.
%string(255) first part : Tempary string storage. second part : " " " %record(comf) com : Common data area in EMAS.
end chat
Here is the routine called when a user trys to end his connection to chat.
print messages
This routine prints out any new messages that may have occured. It also removes the user from the chat system if the close flag has been set. Local variables: %integer: from : Used to hold the number from whom the message came.
User command routines
subsystem
This has been removed in the current version due to yucky bits in the subsystem. It just prints an error message.
close chat
This routine is used by the chat leader to close down the chat if he wants to go away and do something less boring. First check if we are in fact the chat leader as otherwise this is not a very fair thing to do. Local variables: %integer time : Holds the time left (in seconds) for the chatters to leave.
rename
This is the rename routine (much abused by operators and others). It's function is to allow us to change out name. This is, to put it mildly, open to abuse. Local variables: %integer: new length : Holds length of new name user attempts to enter. %string(255): new name : Holds actual attempt at new name.
who is on
This routine prints out the names of those currently in the chat. Note that when someone leaves the system the name is prefixed with a star and so we should not print these out. Local variables: %integer: counter : Holds current pointer in name area. user count : Holds current total of users. %string(255): name : Holds name of current user being looked at.
tell user
This routine is for sending messages to a user who is not currently using the chat program. It can either be used to invite a new person into the chat decline an offer to chat while he is not a leader. In the latter case we provide the name of our leader so that the person can enter into a chat with them. Local variable: %string(255) who to : Job number of the person to whom we want to send our message.
twiddle commands
This is the command interpreter. All we do is to resolve the command into a string containing all the command letters. We then take the length of the string remaining on the left to give us a value of the command we have just been asked to run. Local variables: %string(255) remaining part : Holds the remaining part of the string after resolution.
Master control routines
on trap
This is the ultra hairy interrupt routine. Local variables: %integer: time : Holds limit on delay time.
set up
In this routine we set up the chat file and inform the other user of our wish for a chat if we are initiating the chat. Local variables: %integer: a io stat : Address of io status recored. a it buffer : Address of io file (T#IT). counter : Used by leader to point to entries to be cleared.
main loop
This is the main loop of the program. In it we test for input and act accordinly. We also test to see if any new messages have arrived and if so we print them.
User's comments
If you have any comments about chat or its documentation then please let me know by typing them below. If you don't know how to use EMAS mail then if you could say so I will TELL the answer back. MAIL mal101, Chat tech users comments Thank you.