System Installation 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. CONTENTS I. System and other Requirements II. Installation of a New System Step 1. Modifying the machine dependent routines Step 2. Editing the Toolbox routines Step 3. Compiling PICS Step 4. Editing the System Message File Step 5. Establishing System Organization Step 6. First run of program to create new data files and login Sysop I. SYSTEM AND OTHER REQUIREMENTS In order for you to be able to put together a PICS system, you need to be familiar with CP/M and the basics of Turbo Pascal. There are a few machine dependent routines here that you may have to edit before compiling the program (more on that later). If you don't have the knowledge, perhaps you could get a friend to help you with the initial installation. After that no special knowledge is required. As designed, PICS operates on a systems with 80 column screens. Most terminals that use other widths will automatically wrap around on lines longer than their maximum. Some, the Comodore 64 for example, don't have auto wrap around and will not work properly with PICS. If you wish to operate a PICS system on a system with less than an 80 column screen and not have the lines wrap around, you will have to make extensive changes to the source code. PICS is designed to operate on a Z-80 computer with at least 54K of TPA (Transient Program Area) operating under CP/M 2.2. Borland's Turbo Pascal ver. 2.0 or later and the Turbo Toolbox are required for compiling. The Toolbox routines are used to provide the Btree support for the user file. None of the additional features beyond those of version 2.0 is used, so it is recommended that 2.0 be used, because the runtime library (and thus the size of the compiled program) will be about 900 bytes longer when using ver. 3.0. A real time clock is strongly recommended, but not absolutely necessary. Due to the screen format commands of Turbo and the differing sizes of each users Transient Program Area inside of CP/M, each system needs to be compiled on the machine where it will be used. Two 360K drives are the minimum that can be used to obtain satisfactory operation. Of course more is better, and a hard disk is ideal. If you do not have at least two 360K drives, it will be impossible to compile the source code. Since PICS makes use of numerous overlays, it is disk intensive (reads the disk frequently) and may run slowly if your drives have a slow access time. Sorry 'bout that, but the number of features offered by the program and the limits of CP/M force this upon us. II. INSTALLING A NEW SYSTEM As distributed, the PICS source code is ready to be compiled on your machine except for the machine dependent routines described below. There are many defaults that can be changed to make the system operate as you desire, but I recommend that you follow the instructions as is and compile a working system using the default settings that are already in the source code. This will minimize the chance for initial errors. The following discussion is for getting a system up and running with the minimum of effort. After you have an operating PICS system, it will be easy to go back and customize the source defaults and recompile. =============================================================== Here are six steps that are required to get a system running on your machine. STEP 1. MODIFYING THE MACHINE DEPENDENT ROUTINES ----------------------------------------- There are three groups of required files which PICS utilizes to match the hardware in your particular system. These files will be read and included by the compiler during generation of PICS. 1. Files with the suffix .MCH contain the routines that match your hardware. 2. Files with the suffix .MDM contain the modem routines. 3. Files with the suffix .CLK contain clock routines (one has been included for users without a clock). The names of these files reflect the hardware that they support. Several sample files are provided for different machines, modems and clocks. Select from the PICSSUP.LBR the set of routines which most closely match your system. You may have to change some of the code to match your hardware if the sample isn't correct. NOTE: There are two dummy files named DUMMY.MCH and DUMMY.MDM that have no machine dependent or modem dependent code in them. Along with the NORTC.CLK file, these three will allow you to compile a PICS system that will run locally for your evaluation. No modem input/output is performed. After evalustion you will still have to re-compile with the proper files to enable remote calls. After you have finished modifying the routines, or determined that they will work as-is, the three sample files will have to be renamed: PICS.MCH PICS.MDM PICS.CLK These three files are REQUIRED and must be present to compile an operating system. Below is a complete description of the routines and their purpose. The names of the procedures and functions are constant throughout the examples and may not be changed. the code between the Begin and End statements may be changed to fit your hardware. THE *.MCH FILE -------------- ROUTINE NAME OPERATION ---------------------------------------------------------------- system_init This procedure is called only once during the initial start-up of PICS. It may be used to set any necessary system parameters (or none at all). Examples of useful things to be done here: Set VT-180 scrolling region to enable a status-line. Send one-time commands to modem Set function keys system_de_init This procedure is called once just before PICS is terminated. The procedure may be used to reset any parameters desired. For example, commands performed during the previous routine (system_init) may be 'un-done' here. putstat This procedure is used to write 'st' to the status line of the local console. If such a line is not readily available, the top or bottom line of the console may be used instead. This proce- dure may freely use any of the screen commands of Turbo Pascal such as LowVideo, HighVideo, ClrEOL, etc. ch_init This routine should initialize the serial port of the computer if it requires it (use mdinit in the .MDM file to initialize the modem itself). ch_on Turns on the communication channel for use by PICS. Usually this is done by enabling DTR (Data Terminal Ready), but you may also need to do such things as enabling the transmitter of the UART. ch_off Turns off the communication channel. Usually this will simply consist of lowering DTR. ch_carck This function is called frequently to determine that the user is still logged in. Usually this is done by requesting the data carrier detect (DCD) status of the UART, but other methods are possible. ch_inprdy This function returns TRUE when a byte is avail- able to be read, a FALSE is returned when none is available. Only the test is performed, the system does not read the byte. ch_inp This function returns the byte read from the input port. The system assumes that one is available. (A call to ch_inprdy should have been performed first) All eight bits should be returned to the system. ch_out The system will wait in this routine until the modem is ready to accept data. Notice that the value sent is a BYTE, not a CHARACTER. All eight bits should be sent to the port. ch_set Set the bps rate of the communication channel to the value determined by rate. Rate is an ordinary integer such as 300, 1200, etc. Hint: If you are having trouble making modifications to the sample routines, try and find an insert for the IMP communications program, BYE or anything else that contains the i/o code for your machine. In these routines you will find the ports and value numbers to use. THE *.MDM FILE --------------- ROUTINE NAME OPERATION ---------------------------------------------------------------- mdresult This function returns the result code from the modem. PICS does not directly access this function, but other routines in .MDM file may. mdsend Sends a command string to the modem. As in mdresult, PICS does not use this routine, but other routines in the .MDM file may. mdhangup Hangs up the modem immediately. This can be accomplished by dropping DTR on some modems or by sending a command such as 'ATH' on the Hayes. mdbusy This routine is called when local console use is requested and when delayed shutdown is used. Its purpose is to take the modem off-hook so callers will be presented a busy signal. If the modem cannot perform this operation, call mdhangup from here so that the modem will not answer. mdring Monitors the modem port to see if a call has been received. This can be done by looking at the ring indicator (if available), looking for an answer signal from a smart modem, or by simply looking for a carrier detect. This function returns a TRUE or FALSE to indicate the call status. mdans Once a call has been received, this routine is called to answer the phone. This can be done by raising DTR on some modems, or by sending a command to a smart modem such as 'ATA'. mdinit Get the modem ready to talk to PICS. For "intelligent" modems, this is usually done by sending some sort of initialization string. For "dumb" modems, no action may be necessary. NOTE: mdresult and mdsend are only used by other routines in the .MDM file and may not be required in all systems. THE *.CLK FILE --------------- ROUTINE NAME OPERATION ---------------------------------------------------------------- GetTAD Returns six values in the tad_array which are the binary representation of seconds, hours, minutes, day, month, and year (in that order). If your machine does not have a real time clock, these values will be set to zero and you can set the date once a day from the sysop menu. SetTAD Complementary procedure to GetTAD which is used to set the time and date. Note: Systems without real time clocks will not have to modify the GetTAD and SetTAD routines. They are intended to remain as they are. Tick_a_min Used when there is no real time clock to simulate ticking off a minute, a dummy routine when a clock is being used. Tick_a_sec Same as above, but for seconds. Note: When not using a real time clock, PICS uses the two routines above to simulate a clock when the caller is at any prompt. This is the only time that the clock is being simulated. The amount of time for uploads/downloads is also added/subtracted from the time allowed on the system, but that doesn't depend on these routines. There is one other simulated clock routine in effect during the time that PICS is waiting for a caller. It is used to advance the date and also does not depend on the above routines. ============================================================== STEP 2. EDIT TOOLBOX FILES ------------------ PICS makes extensive use of overlays to increase the amount of memory available for dynamic allocation. The two Turbo Toolbox files ADDKEY.BOX and DELKEY.BOX can be safely and simply conver- ted into overlays which will increase the amount of usable memory by approximately 2k. Since each file consists of exactly one procedure, insert the word 'overlay' before the word 'procedure' at the beginning of each file (be sure there is a space after 'overlay') and save the edited file. While this step is optional, it is strongly recommended. Neither of the two procedures is called frequently, so the disk overhead is minimal and the memory increase is significant. ================================================================= STEP 3. Compile PICS ------------ Before compiling PICS be sure that your Turbo Pascal program has been installed for the terminal that you will use on the system. This is described in the Turbo Pascal documentation. If your disk drives are small (360K) you will not be able to keep all of the PICS source files (around 330K) on the same drive that will be used automatically by the Turbo Compiler to generate the .COM and overlay files. In addition, after compilation you may not have room on your system drive for all of the required files. Here are sample solutions: In a two 360K drive system, have the Turbo Pascal programs and the PICS source files on drive A. Move the file PICS.PAS to drive B. (which has at least 200K free space). The Turbo Compiler should then be run from the A drive. The following solution will allow you to locate the PICS overlay files (PICS.000-PICS.003) on a different drive that that used for the PICS.COM file and the rest of the data files used by PICS: If you wish to have the overlay files located on a different drive, edit the PICS.PAS file with the Turbo Editor mode. Just after the {$C-} statement at the beginning of the file: If you are using Turbo Pascal version 2. then add a new line with the statement {$OA} which will tell PICS to look for the overlays on drive A. The second letter represents the drive..{$OC} means use the C drive. Remember, you must locate the overlay files in the same user area on both drives. If you are using Turbo Pascal version 3. then add a new line with the statement OvrDrive(1); where 1= the A drive, 2= the B drive etc. The same user area restriction still applies. If possible, keep the overlay files on the same drive/user as the rest of the files. The following is a list of the source files for PICS that you will need to have present to compile the program. PICS.PAS PICSDEF.INC ACCESS.BOX (From the Turbo Toolbox) GETKEY.BOX (From the Turbo Toolbox) PICSVAR.INC PICS.MCH (Hardware dependent routines) PICS.MDM (Modem routines) PICS.CLK (Clock routines) PICSKIO.INC (Resident I/O routines) PICSKMS.INC (Misc. resident routines) The following files will be used to generate the PICS.000 overlay file. PICSOV0A.INC PICSOV0B.INC PICSOV0C.INC PICSOV0D.INC PICSOV0E.INC PICSOV0F.INC PICSOV0G.INC ADDKEY.BOX (From the Toolbox, modified to DELKEY.BOX be an overlay file, see above) The next two files will be used to create the PICS.001 overlay in addition to being part of the PICS.000 overlay. (This is an overlay within an overlay, or a nested overlay.) PICSOV0H.INC PICSOV0I.INC The following files will be used to generate the PICS.002 overlay file. PICSOV2A.INC PICSOV2B.INC PICSOV2C.INC PICSOV2D.INC PICSOV2E.INC PICSOV2F.INC PICSOV2G.INC PICSOV2H.INC PICSOV2I.INC PICSOV2J.INC PICSOV2K.INC PICSOV2L.INC The following file will be used to generate the PICS.003 overlay file. PICSOV3A.INC The final file is the main procedure for the program. PICSMAIN.INC The above 35 files represent about 340K of code, or about 9500 lines. The reason for so many files is that the Turbo Pascal editor must be able to load each file into memory in order to edit it. The compiler doesn't care how many files there are, because it just reads one line at a time. It is VERY IMPORTANT that you compile the PICS source files using the operating system (CP/M) version that you will use to run the PICS program. Turbo Pascal measures the amount of free memory at compile time. If the program is run in an operating environment with less free memory space, you will get a message like 'insufficient memory' when running PICS. PICS does not require any special handling for Turbo Pascal's static (compile time) allocation of stack space. The following steps (in Turbo Pascal Editor) will create a compiled version of PICS ready for use. These commands will create PICS.COM and four overlay files: PICS.000- PICS.003 which are the overlay files. The steps below are to be performed inside the Turbo Compiler program: 1) O - Options 2) C - COM file 3) Q - Quit 4) C - Compile 5) PICS [in small system example above use B:PICS] 6) Q - Quit and return to operating system Upon completion of the compilation you will have the following files: PICS.COM 32K PICS.000 42K PICS.001 4K PICS.002 60K PICS.003 4K The Turbo Compiler should tell you that it has compiled about 9595 lines of code, producing a code area of 23891 bytes, a data area of 9500 bytes and depending on your TPA size, about 14000 bytes of free space. If you have less than 5000-6000 bytes of free space you will have to be careful about setting up too many Message Areas and File Sections because the names and descriptions are stored in memory while PICS is operating (see Setup below). The above files will have to reside on the drive/user you set up as the System File Section for your system. ================================================================== STEP 4. EDIT THE SYSTEM MESSAGES FILE ----------------------------- The system message file SYSMSG.TXT (included in the distribution package) should be edited for your particular system. This file contains the System Welcome Message and Bulletins as well as other messages and the menus for PICS. PICS can processes SYSMSG.TXT files which have been created by text editors - such as WordStar - which use the high bit. When PICS is started, it attempts to open SYSMSG.BB# which is a random access file. If PICS finds this file, it will be used. If not, PICS will create it from SYSMSG.TXT. This is what will happen the first time you run PICS. Whenever the file SYSMSG.TXT is updated, delete the file SYSMSG.BB# so PICS will automatically update the random access file (which PICS reads for the system explanatory messages). Caution: When used with certain text editors, SYSMSG.TXT will not contain a terminating End-Of-File marker (^Z) if the number of characters in the file is a multiple of 128. Should this happen, PICS will not properly terminate the creation of SYSMSG.BB# and a disk full error will eventually occur. As a work-around, add or delete one or more characters from SYSMSG.TXT, delete SYSMSG.BB#, and restart PICS. This extreme situation obviously does not occur often. You should also be careful that your editor expands all tabs to the proper number of spaces and not as just one character (Control I). ================================================================ STEP 5. ESTABLISHING THE SYSTEM ORGANIZATION AND SET UP ----------------------------------------------- A program named SETUP.PAS has been included in the PICS distribution package. Compile this program into a .COM program and run it. It will create the System Organization file named SECTION.BB#. In this new file will be minimum required message areas and file sections as discussed above. Later, the same program can be used to edit and add entries as desired. Initially there are no conferences or Articles provided, nor are they needed to get the system running. I recommend that you use the minimum organization provided by the setup program until the system is up and running. The security of a computer system is of paramount importance when that system is readily available through the telephone system. To make PICS robust enough to withstand both incorrect entries and malicious attacks against the system, a simple but effective method is used: an access level, ranging from 0 to 255, is assigned to each user. The Message Areas and File Areas (which are accessed by name) are also assigned an access level. Users are able to gain access to any named File Section or Message Area if it's access level is less than or equal to his. The exception to this rule is Conferences. Users can gain access to a conference if their access level is higher than the level of the conference, but usually the conferences are set high enough so that only the Sysop and assistants can access it this way. There are seven flags contained in each user record. The Sysop may set these flags from the Sysop subsystem edit user command. If the flag for a particular conference is set, the user has access to that conference regardless of his access level, or the access level for the conference. When a user record is first created, none of the falgs is set. The recommended levels of User access are defined as follows. (You should follow this guide when setting up access levels for the named Message Areas and File Sections described below.) 0-9 Twit - will be logged off immediately 10-19 Unvalidated user - limited message and files access 20-249 Normal user - full message and files access 250-254 Alternate sysops 255 Sysop The PICS system consists of four sub-systems: 1. The Messages Sub-System. 2. The Files Sub-System. 3. The Utilities Sub-System. 4. The Sysop Sub-System. The MESSAGE subsystem consists of named 'MESSAGE AREAS' where callers can read and leave messages. In addition there are 'ARTICLES' that can be read by callers. Each 'Message Area' and 'Article' is assigned a minimum user access level by the sysop. the Drive/User location for each 'Article' is also sysop definable. POST This is the MESSAGE AREA every user 'sees' initially. The access level of this area will be set to zero. SYSTEM This MESSAGE AREA is special since ALL messages (including those that have been erased) will be visible. IT IS IMPORTANT that the access level of this area be left high enough that normal users do not have access. To avoid potential problems, the access level for this area this area will be set at 250. There are no required Articles. You may enter any that you want after you have an operating PICS system. The FILES sub-system is a group of named 'FILE SECTIONS' where files available for distribution (download) and receipt (upload) are kept. Access to these Sections is controlled by the minimum user access level set by the sysop. The Drive/User location for each Section is sysop definable. SYSTEM This FILE SECTION is the location for all of the PICS system and data files. LOGIN This is the FILE SECTION every user 'sees' initially. The access level of this area will be set to zero. NEWIN This is the FILE SECTION into which uploads will be placed. The access level of this area will be set to 20, the default access level for validated users. There is no fixed limit to the number of MESSAGE AREAS, FILE SECTIONS and ARTICLES on the system, but remember that the names and descriptions of these will be stored in memory and might limit the operation of the system if you have too many. The Utilities and Sysop sub-sections require no special setup. After completing the setup procedure, the following files should be moved to the Drive and User area that you setup as the System File area: PICS.COM PICS.000 - PICS.003 SECTION.BB# SYSMSG.TXT =============================================================== STEP 6. RUN PICS TO CREATE NEW FILES AND LOGIN AS SYSOP ----------------------------------------------- The first time PICS is run, it will automatically create all the data files that it needs on the same drive/user as the PICS object files, and will announce that it is doing so. If successful the screen will clear and start randomly moving the cursor around. This is the normal idle state for PICS. At this time PICS is waiting for: 1) A signal from the modem indicating a remote user call. 2) a command from the console indicating a local user. (^L) 3) a command from the console to show system status. (^J) Enter a CONTROL L at the sysop console (telling PICS that you want to use the system locally). After the "FIRST name:" prompt appears, enter the name "SYSOP." Do NOT use your first and last name. Not finding SYSOP, the system will prompt for a password - enter one of your choice. You are now logged into the system as the Sysop with an access level of 255 (the max). If you want to be on the system with your name, re-sign in after login as Sysop. This will allow you to send and receive messages as either Sysop or using your real name. C A U T I O N !!! ----------------- It is VERY IMPORTANT that you log in as sysop before putting the system up for others to use. There are folks out there who will try to log in as sysop. If you have not set your password, they will set it for you and will consequently have full sysop level access. Files that PICS has created and will use in the future: MESSAGE.BB# The text of messages in the message file. SUMMARY.BB# Message headers and pointers to the text in the MESSAGE.BB# file. USERDAT.BB# The user file random record data file. USERIDX.BB# The Turbo Access index to USERDAT.BB#. SECTION.BB# The system organization random record file. LOG.BB# Coded log of system use. STATS.BB# Coded record of system usage by time & date. NEWIN.BB# Records of Uploads & info about them. SYSMSG.BB# Random record file made from SYSMSG.TXT file. Other than the SYSMSG.TXT file, these files are not meant to be edited by the sysop with a text editor. PICS has routines built in that will handle these files. In addition, PICS can create text files from the Messages and Log files when the Audit feature is used by the Sysop. This will be discussed in detail in the Theory of Operation Section of this manual. In this way, you have the ability to generate a text file from the random files shown above. Be sure to test the system from a remote computer using a modem, as this is the only way to be sure that the modem dependent routines are working properly. Les Archambault