THEORY OF OPERATION MANUAL for Pascal Integrated Communications System (PICS) Version 1.0 August 1,1986 Les Archambault PICS.PAS and the associated support files (including this documentation file) are Copyright (c) 1986 by Les Archambault. Non-commercial, public distribution and use of this system is permitted. All commercial rights are reserved. Distribution of PICS should include this documentation. --------------------------------------------------------------- In this section I shall do my best to provide the details of how PICS operates. The first thing I'll go through is a complete tour through the sequence of operations from entry into PICS to the CP/M prompt. Then some detailed explanations of the more complex routines used throughout the program. ================================================================ COLD START (Entering PICS from CP/M) ---------- The first operation upon entering the PICS program is the COLD START routine. This is performed only once. The operations are: * The System_init procedure in the PICS.MCH file is called to perform any machine initialization that the sysop has programmed into this procedure. (usually this is just a dummy routine). * All of the internal variables are set to the values in the PICSDEF.INC file as constants. * The system is set: Audit file =OFF, Non-library mode, and Sysop wants the system=OFF. * The pointers for all of the dynamic variable storage areas are set to their initial values (NIL). * The Output driver for sending characters to the modem and local console is installed. (Putchar routine). * The current drive/user is set as the location for system files and the drive is reset (just in case of a disk change by the sysop). * An attempt is made to open and read the SYSMSG.BB# file and assign pointers to the record numbers of the individual messages and menus. If the file is not found, PICS will try to create it from the file SYSMSG.TXT file. If this can't be done the system will notify the console and abort to CP/M. * The system organization file created with the Setup program is read and the entries transfered to dynamic memory storage. If the required message areas and file sections can't be found, the system notifies the local console that it can't continue, and the program aborts to CP/M. SETUP ---- This routine is called when PICS is entered from CP/M and between callers. It's jobs are: * All of the initial conditions for operation are set, such as printer OFF, chat OFF, initial mode Messages, etc. Variables are set to answer the phone with 2 nulls, upper case only, bell OFF, and default width and lines/screen until a user is recognized or tells us differently. * The timeout (while waiting for remote input at a prompt) is set at 60 seconds. * Each of the system files is now opened and prepared for reading and/or writing. Any files that are not found are created and the local sysop console notified. * An entry is made in the log file: PICS UP. NOTE: The files opened at this time remain open until a caller signs off the system. They are then closed and re-opened (to assure that all of the data is written to disk) for the next caller. If the system crashes for any reason, the information on the current caller may be lost. WAIT FOR USER ------------- This is the routine that is running while the cursor is bouncing around the screen. It is basically a counter loop. Inside the loop PICS responds as follows: * Commands from Sysop's console. Control L - Sysop wants to use system locally. Control J - Display system settings and other commands available, remain in wait_for_user loop. Control C - Exit PICS system and return to CP/M. If the Sysop enters a Control C, he will then be asked if he wants to busy the phone before returning to CP/M. * If the Sysop has requested delay-down while there is a caller on the system (he wants to use the system when the caller finishes) the wait-for-user routine will busy the phone line, start the console bell ringing, and start another timer loop that will reset the delay-down flag and return to waiting for a caller if the Sysop doesn't take control of the system within about 10 minutes. If the Sysop does take control of the system, the local_online flag is set to True and the phone line is made busy. When the local_online flag is set True, the input timeout and time on system routines will not operate. * If a condition has developed where the amount of free disk space is less than the default settings, PICS will display a message to the sysop explaining the problem. This will occur about every 5th time the cursor moves and stay on the screen for about 10 seconds. This is a warning only and not a condition that will end the wait_for_user loop. * Calls the modem Mdring routine each time through the loop to determine if a ring has been detected. If so, calls the MdAns answer phone routine. The flags remote_online and remote_copy (flag that allows characters to be sent to the remote screen) are set True if there is a carrier present. * If the Auto Macro execution switch is turned on, the clock is read to determine if it is time to start execution of the Macro. If it is time, the routine sets the local_online flag just like it would be if the sysop had requested local use. then the modem busys the phone line, enters the system and feeds the macro into the multiple command buffer. Note: There is another flag that prevents the auto macro from working more than once in a 24 hour period. Initially when entering PICS from CP/M this flag is set so that the first auto macro operation can't happen for 24 hours. The wait_for _user loop will continue until one of the above conditions exist that allow the system to exit wait_for_user. CHECK_300_RESTRICT ------------------ If the flag for checking 300 baud callers restrictions is ON, the clock is read to determine the time and whether the restriction is in effect. If so the caller is asked to call back at a differ- ent time and the phone is hung up. The remote_online flag is set to False so that PICS will re-enter the wait_for_user routine. If no action is taken by this routine the program then enters the Logon routine. LOGON ----- This routine starts by asking separately for the first and last names of the caller. (If there is an automatic macro in progress the name is automatically set to 'SYSOP' and the password check is bypassed.) Both the first and last names are compared with a list of reserved names in the BADNAMES.LST file. This file can be either a list of names strung together or a separate name on each line. All punctuation is removed from both the first and last names and then a search is performed to see if either name is a sub-string in each of the lines of the BADNAMES.LST file. If either name is found to be a sub-string of one of the lines in the reserved names file the caller is notified and asked to try again. Otherwise, a key string is prepared from the names (if not reserved) and passed to the Turbo Access system for identification (see if there is a record for this name). If there is a record PICS then calls the routine get_old_password. The caller is given the max_tries number of tries to enter his password (dots echo). If no match is found with the record in the User file after max_tries, the message entry routine is automatically entered and a message to sysop started with the subject 'Password Problem'. The caller is now able to complete the message describing his problem for the Sysop. After completing the password problem message the system disconnects the caller. If everything is ok the input timeout time limit is now increased to the current setting of sleepy_time. If there was no User record for the caller, he is asked if he is a new user (this is so he can get back to the names questions if he made a mistake and entered the names incorrectly). If the answer is yes, the caller will be asked questions about nulls, lower case etc. and asked for a password. If all of these are entered corectly, the system will make a log entry for the caller, assign him the default un-validated user access and time on system and proceed. INIT_USER --------- After the Logon the clock is read and a log entry made for the caller. If the callers access level is less than 10, the phone is hung up without notice, (twit) and PICS recycles back to the Wait_for_user routine. The callers last message read is placed into a temporary variable so that it will remain constant throughout the session. It is updated when the caller signs off. If everything is OK, the Users Stats screen is displayed. SET INITIAL AREA AND SECTION ---------------------------- At this time if the user access level is >=250, the initial Message Area is set to SYSTEM and the initial File Section set to NEWIN. If less than 250 the initail Message Area is POST and the initial File Section is LOGIN. Since the initial Mode flag was set to Messages in the Set_Up routine. The message summary file for the initial Area is now read and the dynamic variables set up for it. (There will be a further explanation of the dynamic variables later.) At this point the system Bulletin in the SYSMSGS.BB# file are shown. THE COMMAND LOOP ---------------- At this point, we are in the main command loop. There are four Modes of operation, one for each of the subsystems. Each command is processed and then returns the main command prompt. A G command in any of the Modes is the exit from this loop. EXIT SYSTEM ----------- If the access level of the caller is less than 250, he is asked if he wishes to leave a comment to the Sysop before leaving the system. This is really just a message automatically marked to the Sysop. A check is now made to be sure that if there is an open LIbrary or Audit file, the appropriate file is closed. WRAPUP ----- Pics displays the 'Thanks, call again' message and hangs up the phone. Then if the caller was a valid one (with a valid password), the system updates the Last Message Read, times on system and writes this new information to the caller's user record. A log entry is written to show the user logged off. The Stats file is updated to include this caller, then all of the system data files are closed. At this point, the Setup procedure is once again called and it falls through (remember we're in a loop) to the wait_for_user routine. This completes a sequence through the system for a single caller. ================================================================== PROMPT PROCESSING ----------------- Several procedures are used for processing prompts and returning the desired character, string or number. In most cases (other than when a Y/N answer is needed), the PROMPT function is called. The following parameters are sent to the function: 1. A string of up to 50 characters for PROMPT to print. 2. The maximum number of characters for PROMPT to accept. 3. One or more special characters that set the way PROMPT operates. The PROMPT function then displays the prompt string and then calls the GETSTR procedure which actually gets and processes the string that will be returned. The special characters and maximum length are passed to GETSTR. The special characters work as follows: A Automatic completion of the input line when the maximum number of characters requested is met. (means that no carriage return will be required from the user.) If the A speecial character is not specified the display of characters typed will stop when the maximum charac- ters parameter is reached. The user will then have to enter a carriage return or further edit the line (more later on editing the line.) E Echo the characters typed to the local console and modem. Display dots if no E special character is specified. S Shiftlock. All characters input are converted to upper case. W Wordwrap. Allows continuous entry and performs word wrap to the next line. (Forces Auto line completion). M Displays 'Press "?" for Menu' after the prompt string has been displayed. L Literal. Accepts characters only from the local console or modem. Multiple commands are not accepted. If tried, only the first command will be returned. If L special character is not specified the multiple command buffer will be checked for commands every time GETSTR is called. If one is found it will be returned without displaying the prompt string, until there are no more commands in the buffer. The multiple command string buffer is 80 characters long. During entry of characters from the local console or modem the following editing is possible: TAB will add 5 spaces to the line. Delete or Backspace will backspace over 1 character and erase it. Control X will erase the line to the left of cursor. Control A will move cursor to beginning of the line if Echo ON Control S moves cursor one character left if Echo ON. Control D moves cursor one character right if Echo ON. Control F Redisplays line and moves cursor to end. Control G deletes the character under the cursor. In addition to the above, the following commands are available only from the local (Sysop) console: Control W Sysop initiated chat request. Chat will start the next time system gets to a subsystem command prompt. Control E Remote screen is blanked out (no characters sent to modem until this command toggled again.) Control R Delay-Down request. After current caller logs off, Sysop wants to use system. Control T Twit. Hangs up with no notification and re-cycles. Control J (Linefeed) The status line displays these commands. At the completion of all of this, the string prepared is returned to the calling routine. ================================================================= THE AUDIT COMMAND ----------------- Most of the PICS data files are stored on the disk as random access files. This serves two purposes: The speed of reading and writing is increased, and the amount of space used is kept to a minimum. However, they are not readable with text editors or the Type program. The Audit command is a method by which you can create a text file from some of the random access files. This is the only purpose of this command. It is explaned thoroughly in the Sysops Commands Manual.