October, 1988 Electronic Bulletin Board Service This document is meant to assist in installing the electronic Bulletin Board utility that is being used at the Naval Research Laboratory (NRL), in Washington, D.C., on other VAX/VMS systems. This code is currently running at NRL on a VAX/VMS cluster of four 11/785 machines running VMS 4.6 operating system. I have attempted to document the steps used to get a new version up and running at NRL. This new version of the utility is definately an improvement over the previous version in user friendliness and consistency of operation. I have also written a few new programs to help maintain the data bases. There are many small programs and procedures which need to be integrated to make this system go. It is not a truly automated system. As you will see on the following pages, there needs to be some intervention almost daily to make sure that all is running smoothly. This usually only takes a few minutes if the tasks are done regularly. Good luck, and do not hesitate to call if we can be of service in getting this code running for you. Alta M. Paul User Services, Research Computation Division Naval Research Laboratory 4555 Overlook Avenue, SW Washington, D.C. 20375-5000 (202) 767-3884 paul@nrl.arpa Page 2 GENERAL INFORMATION ABOUT THE BULLETIN BOARD UTILITY The following pages relate some useful and historical information about the electronic Bulletin Board project at the Naval Research Laboratory, Washington, D.C. These sections should be edited and updated frequently as new information appears, bugs are fixed or any major changes are made to this Bulletin Board utility. Page 3 HISTORY The electronic Bulletin Board utility was given to NRL in 1985. It was originally written by Mark Resmer at Vassar College. John Shirron from the Acoustics Division at NRL worked on recoding and installing the first version of this utility on the Research Computation Division (RCD) VAXes at NRL. In 1987, Charles Brown, of User Services, RCD, made some major changes to the utility and installed the new and improved version that was used June, 1987 - April, 1988. When Charles Brown left the RCD in November, 1987, there was a new version of the product under development. Alta Paul, Century Technologies, finished debugging this version and spent much time reformatting the code to conform with standard Pascal. This new version was installed April, 1988. An updated version of the utility that fixed several very minor bugs and made user messages and help files easier to understand was installed July, 1988. The main changes apparent to users in the April and July, 1988, versions are cosmetic and include the introduction of new fields to help the user know which topics contain new information to read. Changes not apparent to the user include splitting the data base file into three separate files of topic categories. Many of the original routines no longer in use have been removed from the code. Several routines were incorporated as inline code and this helped to significantly speed up the operation of the utility by reducing the number of subroutine calls, especially in the routines where linked lists are built. All routines have now been reformatted and commented. The online help files and the online Bulletin Board User's Guide have been rewritten. The program version released in October, 1988, improved overall performance in time needed to read the larger topic boards. No further versions are planned at this time. Page 4 KNOWN BULLETIN BOARD PROBLEMS AND THEIR SOLUTIONS NOTE: These problems are listed in the order in which they were reported or discovered by the Bulletin Board manager beginning with the version running in November, 1987, when I became the Bulletin Board manager. Solutions and date of solution are given where appropriate. Some of these problems surfaced as older problems were solved. 1. The Bulletin Board manager and system were to have a password function. This feature was causing abnormal terminations in the program so is presently disabled. JANUARY, 1988 SOLUTION: This feature has been permanently removed from the Bulletin Board code. The original version of the Bulletin Board allowed users on remote nodes to run the NRL executable software on their system but access NRL data base files if these users had valid RCD VAX accounts. This was accomplished in the original version by building a small file on the remote machine that contained the users username and password into the Central Computing Facility (CCF) system. Then when file access was needed, the Bulletin Board program would effect a login to the CCF with this information. This was an insecure arrangement. The same thing can be accomplished by using the NETNONPRIV account set up by systems with access control granted to the NETNONPRIV account. The remote system will need the small command file that resides at NRL::DUA103:[PAUL.FIFTH_BB]ASSIGN.COM which will be executed before the Bulletin Board is run on the remote system. Then when file access is needed on the CCF system there will be no charges to the remote user. APRIL, 1988 (AMP) 2. Local boards and Bitnet boards should be separated. The first screen should give a choice on whether the user wishes local or Bitnet boards. Then the proper list can be built and execution will be the same from that point on. Programs needing modification to do this: o bbmain o the arpa program o the program to count the messages o the archive program o need 2 separate data base files o need 2 count files SOLUTION: The Bulletin Board was changed to contain 3 categories of topics - research topics, computer related topics and NRL administrative topics. These 3 categories receive mail in 3 different locations and have their messages added and counted from these same locations. This splitting has greatly enhanced the user friendliness of the utility. APRIL, 1988 (AMP) Page 5 3. The program needs to be modified to handle adding a new Bulletin Board manager without recoding the module GET_UIC and then re-linking. 4. The topic boards should be split into separate files. This should enable the program to execute more quickly. NOTE: The ARPA program and the counting program will also have to be altered. SOLUTION: The Bulletin Board currently has data stored in 3 files. To further split this to individual files for each topic would require an inordinate amount of code and would not significantly speed up program operation. This option will probably not be implemented. JULY, 1988 (AMP) 5. The file called BB$USER_INFO.DAT is not deleted from the users account when he first accesses the new version of the utility. This file was used by the June, 1987, production version of the utility. SOLUTION: This file will be allowed to expire naturally during normal system cleanup routines. Most of these files are very small and the cost of checking every time a user invokes the Bulletin Board to see if the file still exists is not worth the cost of the processing. New sites to use this software will not have this problem since this file was only generated under the 1987 version of the utility. SEPTEMBER, 1988 (AMP) 6. The file called BB$USERFILE3.DAT gets larger every time the user calls up the new utility. Some method of removing addresses of expired messages needs to be developed. Each time the user reads a message an address to it is put in the BB$USERFILE3.DAT file. After about 30 days these messages will be removed from the data base so the address is no longer valid or needed. 7. Do not ever delete the last message in the data base files. Deletes should be done through the archiver function program from the earliest messages in the topic. SOLUTION: Pointer problem fixed, FEBRUARY, 1988. (AMP) 8. When the topic screen appears, the user cannot tell whether there are new messages to read or not. SOLUTION: Two new columns added to the topic menu. The fields are total messages in the topic and total new messages since the last time the board was accessed by the user. MARCH, 1988 (AMP) 9. The screens are a little "busy" in content. They need to be simplified as much as possible and error messages need to be clearer. The topic being examined should be identified on the message menu. Page 6 SOLUTION: Some reformatting has been done to make the topic screen and message screens look a little nicer. The topic being examined is tagged at the top of the message screen. When a topic is loading a message is displayed about which board is being located. FEBRUARY, 1988 (AMP) 10. Several options are not returning to the proper screen. SOLUTION: These problems are now fixed. Also, if an option is selected incorrectly, or a user changes his mind, s will bring the user backwards to the topic or message menu again. JANUARY, 1988. (AMP) 11. The user cannot tell if a message is new or read when looking at the message menu. SOLUTION: Messages are now marked as READ, SKIPPED or NEW in the message menu. This marking causes large boards to load even more slowly than before. NOVEMBER, 1988. Speed was restored by changing the code and making subroutines that were being called the most into inline code. APRIL, 1988. (AMP) 12. After a user adds and/or deletes messages there are several files called BB.TMP in the directory. SOLUTION: Put_local, put_internet, add_edit and the main module were changed so these "temporary" files are really temporary. MARCH, 1988 (AMP) 13. Some administrative boards should be protected from users adding and deleting messages. These boards should have a designated moderator that keeps the information current in the topic. SOLUTION: Local boards are assigned to a specific person. Only the "owner" or a manager may add and erase messages to these topics. Bitnet boards are available to everyone to add and erase messages. Protections on selected topics are changed by running the protection_changer and this program updates the file called topic_users.dat. MARCH, 1988 (AMP) 14. It seems to take a very long time for the utility to produce the first screen of information. Page 7 SOLUTION: Messages are now stored in the data base by the date they are entered into the data base instead of the date the sender posted them on the net. This will result in the messages being stored sequentially by arrival date. This should speed up the loading of the topic boards since the addresses will always be increasing while the lists are being built. In the old version the messages were stored by the date posted. This caused messages that were received after several days of "bouncing" around the net to be stored in a higher address than the message that would follow it in the actual list of the messages in the topic. MARCH, 1988 (AMP) 15. The BB$TRACKER.COM prints 3 lines of information for each use of the Bulletin Board. Most of the words are extraneous. SOLUTION: The BB$TRACKER.COM procedure was changed in JULY, 1988 so that only one line of information is printed to the BB$TRACKER.LOG file for each BB use. This eliminates the problem of the BB$TRACKER.LOG records becoming garbage if two of the users exit at the same time. This also allows much simplification of the BBR.PAS program which no longer has to parse 3 lines of text per user to produce the monthly report. (AMP) 16. Some of the digests are going into the data base files in the reverse order of the volume numbers. SOLUTION: The files BB$NEWMAIL3.COM were changed so that messages are put into the data base in the order in which they are received over the internet. JULY, 1988 (AMP) 17. The topic menu line repaints after each Dir, Frwd and Back even if the line is already present. SOLUTION: A flag was added to detect when the line is present and not repaint it. JULY, 1988 (AMP) 18. The message menu line repaints after every Dir, Frwd, Back, Nxt and Prev even if line is already present. SOLUTION: A flag was added to detect when the line is present and not repaint it. JULY, 1988 (AMP) 19. The subject field is not large enough to display the volume numbers in INFO-ATARI. SOLUTION: Several requests were sent to the moderator of INFO-ATARI about this problem to ask that volumes be labeled in a shortened format like the other digests we receive. These requests were ignored. So, the subject field was lengthened by 4 spaces and the poster field reduced by 4 spaces. JULY, 1988 (AMP) 20. It is taking a very long time to read new messages in the larger topic boards. Page 8 SOLUTION: I examined the code and found many redundant calls to the routines that did the update to the user file for the last access record. These redundancies were removed as were several very short procedures that were not necessary. AUGUST, 1988 (AMP) 21. The fourth option on the category screen is being covered up by the error message if the user tries to enter any key except 1, 2, 3 or 4. SOLUTION: The file BB$BANNER.TXT was reformatted to allow for an extra line at the bottom of the text. AUGUST, 1988 (AMP) 22. An error message appears on the delete even when the delete is successful. SOLUTION: Pointer problem fixed AUGUST, 1988 (AMP) 23. If there are no messages in a topic, then you add a message, then delete the message, the menu stays the same. It should blank and say "no messages". SOLUTION: Fixed AUGUST, 1988 (AMP) 24. After adding or deleting a message, the message list should update automatically and not wait for a Dir option. SOLUTION: Fixed AUGUST, 1988 (AMP) 25. After adding or deleting a topic, the topic list should update automatically without waiting for a Dir option. SOLUTION: Fixed AUGUST, 1988 (AMP) 26. If the message menu is at the top of the message list and Dir is selected, the menu should NOT repaint. SOLUTION: Fixed AUGUST, 1988 (AMP) 27. On message menu, "Poster" is jumping around when screen is painted. SOLUTION: Removed redundant code AUGUST, 1988 (AMP) 28. On the message directory, if Frwd is selected, the bottom number becomes top number on next screen. SOLUTION: Fixed AUGUST, 1988 (AMP) 29. On the message menu, if Back is selected, a message gets skipped in the list. SOLUTION: Fixed AUGUST, 1988 (AMP) Page 9 30. If there are no messages in a topic and the user selects it anyway, the topic menu is only partially erased. SOLUTION: Fixed AUGUST, 1988 (AMP) 31. If select a topic with no messages and then select Dir, error window changes to "Top of messages". SOLUTION: Fixed AUGUST, 1988 (AMP) 32. When delete last message in topic then do Dir, it aborts the program. SOLUTION: Fixed AUGUST, 1988 (AMP) 33. When delete last message of a topic, the message header stays on the screen. SOLUTION: Fixed AUGUST, 1988 (AMP) 34. If no messages exist, the wrong header is being printed. SOLUTION: Fixed AUGUST, 1988 (AMP) 35. If do Select from topic menu, then , the program stalls. SOLUTION: Fixed AUGUST, 1988 (AMP) 36. After read last message in topic, can't do Dir. SOLUTION: Fixed AUGUST, 1988 (AMP) 37. If select topic with no messages then do Dir, program aborts. SOLUTION: Fixed AUGUST, 1988 (AMP) 38. The monthly report should have added information - total number of users, total number oF uses, total time of usage and a chart of how many users used the utility during any given 60 minute period. SOLUTION: BBR.PAS has been changed to include this information. SEPTEMBER, 1988 (CCB) 39. The "Adjusting message list" message appears in menu box after selecting and or delete, even if no adds or deletes are done. Similar problem on topic list. SOLUTION: Fixed OCTOBER, 1988. (AMP) Page 10 40. User requested that a version number be added to initial screen so he can tell which version is running on their remote system. SOLUTION: Incorporated version number into row of asterisks in BB$BANNER.TXT file. OCTOBER, 1988. (AMP) 41. User complained that cursor seems to get "lost" when error message prints. SOLUTION: Fixed OCTOBER, 1988. (AMP) Page 11 FILES USED BY THE BULLETIN BOARD ******************************** SOURCE FILES USED BY THE MAIN BULLETIN BOARD UTILITY - All but BBMAIN are maintained in object library called BBLIB. At NRL these source files reside in Bulletin Board manager's account. BBMAIN.PAS ADD_EDIT.PAS ADD_FILE.PAS ADD_MENU.PAS ADD_TOPIC.PAS BROADCAST_HANDLER.PAS CHOOSE_DATABASE.PAS CREATE_MESSAGE_DATA_LIST.PAS CREATE_MESSAGE_DIR_LIST.PAS CREATE_TOPIC_DIR_LIST.PAS DELETE_MESSAGE.PAS DELETE_TOPIC.PAS EXTRACT.PAS FIND_MESSAGE.PAS GETCHAR.PAS GET_CLUSTER_DATA.PAS GET_MESSAGE_INFO.PAS GET_NODE_DATA.PAS GET_UIC.PAS GET_USERNAME.PAS INVERT.PAS LOG_MESSAGE.PAS MESSAGES.PAS MESSAGE_MENU.PAS MESSAGE_STATE.PAS NEXT_MESSAGE.PAS OPEN_FILES.PAS OUT_OF_BAND_HANDLER.PAS PREVIOUS_MESSAGE.PAS PREVIOUS_MESSAGE_DIRECTORY_PAGE.PAS PREVIOUS_MESSAGE_PAGE.PAS PROTECTED_TOPIC_BOARD.PAS PUT_HELP.PAS PUT_INTERNET.PAS PUT_LOCAL.PAS READSTR.PAS REPLY_MENU.PAS SELECT_TOPIC.PAS SETUP.PAS TOPIC_MENU.PAS Page 12 UPDATE_LAST_ACCESS.PAS UPDATE_TOPIC_INFO.PAS WRITE_ERROR.PAS WRITE_MENU.PAS WRITE_MESSAGE_DATA.PAS WRITE_MESSAGE_DIRECTORY.PAS WRITE_TOPIC_DIRECTORY.PAS FILES USED DAILY TO ADD MESSAGES - Files reside in each of the topic category mail areas. At NRL these mail areas are: CCF_RESEARCH, CCF_BITNET, CCFBULLETIN. BB$NEWMAIL3.COM ARPA3.PAS BB$COUNT_MESSAGES.PAS ADDBAD3.COM MISCELLANEOUS FILES - These 2 files must be compiled and be resident in the area of object library before link can be done. At NRL these files reside in the Bulletin Board manager's area. LIB$SPAWN.PAS SMG$REPAINT_LINE.PAS This file must be resident in the area where object library resides before link can be done. At NRL this file resides in the Bulletin Board manager's area. SMGDEFS.PEN HELP FILES - Files must be resident on machine executing BB in HELP area. At NRL this area is called SYSTEM3:[BB$PROGRAM.HLP]. BB$BANNER.TXT BB$MESSAGE1.HLP BB$MESSAGE2.HLP BB$TOPIC.HLP Page 13 FILES USED FOR ARCHIVING MESSAGES - At NRL the archiving program file resides in the Bulletin Board manager's area. BB$ARCHIVE3_PROGRAM.PAS Then run BB$COUNT_MESSAGES.PAS program in each mail area. At NRL archive files go to SYSTEM3:[BB$PROGRAM.DATA] and then are written to tape with the SI ARCHIVER utility. The archive files are retained for about six months. FILES USED TO PRODUCE THE MONTHLY USAGE REPORT - BBR.PAS - produces the monthly report. At NRL this file resides in the Bulletin Board manager's area. BB$TRACKER.COM - actually produces tracker log and runs BB. This file resides in the EXE area. At NRL file resides at SYSTEM3:[BB$PROGRAM.EXE]. BB$TRACKER.LOG - log of actual BB use This file resides in the DATA area. At NRL file resides at SYSTEM3:[BB$PROGRAM.DATA]. FILES USED TO PROTECT INDIVIDUAL TOPICS FROM GENERAL ADDS AND DELETES - PROTECTION_CHANGER.PAS - resides in Bulletin Board manager's area. TOPIC_USERS.DAT - file of protections. This file resides in the DATA area. At NRL file resides at SYSTEM3:[BB$PROGRAM.DATA]. USEFUL COM FILES TO HELP MANAGE BULLETIN BOARD - These files reside in the Bulletin Board manager's area. COMPMODS.COM - uses TEMP.SPAS to compile all BB modules, with or without debug. LIBMOD.COM - uses TEMP.SOBJ to create object library or replace all modules in the object library after extensive modification or if manager needs to use debugger and therefore must recompile all modules then replace the modules in the library. REPLACELIB.COM - replace 1 module in library. PRINT_ALL_MODULES.OUT - print all BB modules. Page 14 FDL FILE - TEST.FDL - for data base files. Resides in Bulletin Board manager's area. Used with CONVERT to compress data base files. COM FILE NEEDED ON REMOTE NODES FOR EXECUTION - Used when executing code on a remote node and accessing data base files over the network. Used on the remote node in place of BB$TRACKER.COM. ASSIGN.COM DATA BASE FILES - Resides in the DATA area. At NRL files reside at SYSTEM3:[BB$PROGRAM.DATA]. BB$LOCAL_BOARDS.DAT BB$RESEARCH_BOARDS.DAT BB$BITNET_BOARDS.DAT COUNT FILES - Reside in the DATA area. At NRL files reside at SYSTEM3:[BB$PROGRAM.DATA]. BB$LOCAL_COUNT.DAT BB$RESEARCH_COUNT.DAT BB$BITNET_COUNT.DAT Page 15 Setting up to run the Bulletin Board as a stand alone system The following steps are meant to be a guide in setting up this software to run on other VAX/VMS systems. There will need to be some modification of modules, but there should be no real coding changes needed unless you wish to further customize this program for your site. I have tried to put these items in a logical order. Hopefully, I have made things clear enough that you will have immediate (or at least fairly quick) success. Alta 1. How many categories of topics do you want? EX: at NRL we have 3: local NRL administrative topics, BITNET computer topics, topics for RESEARCH. It is best to have more than one category of topics if you plan to have more than ten topics in your data base. Group your topics into logical categories. 2. What will the data base files be called for the above topic categories? EX: at NRL we use BB$LOCAL_BOARDS.DAT, BB$BITNET _BOARDS.DAT, and BB$RESEARCH_BOARDS.DAT and store them in SYSTEM3:[BB$PROGRAM.DATA]. 3. What will the count files for the categories be called? EX: at NRL we use BB$LOCAL_COUNT.DAT, BB$BITNET_COUNT.DAT and BB$RESEARCH_COUNT.DAT and store them in SYSTEM3:[BB$PROGRAM.DATA]. 4. Create the above mentioned files in the location where you will keep all the Bulletin Board data files. Use CREATE/FDL=TEST filename for the data base files. Create the count files as regular sequential files. Set the ACL on the files as follows: on the count files use W:RE; on the data base files use W:RWE. The Bulletin Board manager should have RWED ACL set for all files. 5. Where will the help files reside? Move the 3 HLP files and BB$BANNER.TXT to this location. Set ACL for these files to be W:RE and RWED for the manager. Edit BB$BANNER.TXT in the help area to reflect your chosen categories. At NRL we store these files in SYSTEM3:[BB$PROGRAM.HLP]. 6. Create an account for each category above where mail will be received to add to the board. EX: at NRL we have 3 areas - CCFBULLETIN, CCF_BITNET and CCF_RESEARCH. 7. Set the ACL on the corresponding count files to be RWED for each category of topics. For example the file SYSTEM3:[BB$PROGRAM.DATA]BB$BITNET_COUNT.DAT has ACL set for RWED for the account CCF_BITNET. 8. In each of the accounts where a category of topics will receive mail, do the following: Page 16 o You will need these files: BB$NEWMAIL3.COM, ADDBAD3.COM, ARPA3.COM, BB$COUNT_MESSAGES.PAS o These files will need to be edited to reflect current location of corresponding data base and count files for this category of topics. o Compile and link the .PAS files in each category. o Submit BB$NEWMAIL3.COM to one of your queues so that is runs daily. See directions under ARPA programs and procedures on how to submit this procedure to a queue. 9. Select the topics for each category and send electronic mail to the topic moderators to begin sending topic messages to the proper account. See the file TOPIC_PROTECTIONS.DAT for information on how to get a list of available internet topics from the Network Information Center. These messages should be mailed to the topic moderators from the account where you wish the messages to be sent. For example: The message to subscribe to the topic INFO-VAX was mailed from the account CCF_BITNET. 10. Where will the Pascal source files be? Move all the modules listed in TEMP.SPAS plus BBMAIN.PAS, SMGDEFS.PEN, LIB$SPAWN.PAS, SMG$REPAINT_LINE.PAS to this location. At NRL these files reside in the manager's account for ease in maintenance programming. 11. Make the following code modifications to the pascal modules: o GET_UIC.PAS needs to have correct codes for your system. See the instructions later in this document on how to designate Bulletin Board managers. o Edit CHOOSE_DATABASE.PAS to reflect the number of categories you will have and your chosen filenames. 12. Compile LIB$SPAWN.PAS and SMG$REPAINT_LINE.PAS. Compile BBMAIN.PAS and all the *.PAS modules listed in TEMP.SPAS in the Bulletin Board manager's area. Use @COMPMODS which reads from TEMP.SPAS. 13. Create the object library with LIBRARY/CREATE BBLIB.OLB. Build the object library. Use @libmod which reads from TEMP.SOBJ. 14. Link the main program with LINK BBMAIN,BBLIB/LIBRARY. Page 17 15. Move the EXE file to your chosen EXE area and set ACL for W:RE and RWED for the manager. 16. Edit the file BB$TRACKER.COM to reflect the proper data, help and exe areas you have chosen. Move this file to your chosen EXE area and set ACL for W:RE and ACL of RWED for the manager. Pay careful attention to the ASSIGN section and make sure you get these correct. 17. Create a sequential file called BB$TRACKER.LOG in the data area. Set ACL to W:RWE and RWED for the manager. 18. Run the program with @[exe_dir_name]BB$TRACKER.COM. In each category, add the required topics, descriptions and internet addresses. See instructions later in this document for adding topics. 19. Edit the program called PROTECTION_CHANGER.PAS in the Bulletin Board manager's account to reflect the location of the file TOPIC_USERS.DAT in the data area. Run this program and add records for each topic added to the Bulletin Board. See the instructions later in this document for adding topics and setting protections. The program will create the file TOPIC_USERS.DAT in the same area as the data base files. Set ACL on the TOPIC_USERS.DAT file to W:RE and RWED for the manager. 20. In the selected manager's account you will need BB$ARCHIVE3_PROGRAM.PAS. Edit this file to reflect the data base file area and your data base file names. This program is run to remove old messages from the Bulletin Board. See instructions later in this document for archiving procedures. 21. Set up the system symbol: BULLETIN*BOARD :== @[exe_dir_name]BB$TRACKER 22. See instructions later in this document for daily, weekly and monthly tasks. 23. The sequence of events should be something like this: a user types the system symbol BULLETINBOARD. The [exe_dir_name]BB$TRACKER.COM is invoked which assigns the logical names of the file areas for the Bulletin Board program. Then the actual Bulletin Board program executes. The user reads, adds, etc. and exits the utility. The BB$TRACKER writes one line in the [data_dir_name]BB$TRACKER.LOG about the time of the Bulletin Board access. Page 18 24. The [exe_dir_name]BB$TRACKER.COM file writes records into the file [data_dir_name]BB$TRACKER.LOG. This log file is used to produce a monthly usage report for management. If your site does not want this report, edit the [exe_dir_name]BB$TRACKER.COM file so that the time query and write operations do not occur. In this case your command file to assign logicals and run the program will be very simple. If you wish to produce the report, edit the file BBR.PAS in the manager's account to reflect the location of the BB$TRACKER.LOG file. See the instructions later in this document on producing the monthly report. Page 19 SUMMARY OF FILE LOCATIONS - In the DATA area - data base files to hold messages for each category of topics a count file for each file above TOPIC_USERS.DAT - contains protections on topics BB$TRACKER.LOG - used by BB$TRACKER.COM to track usage archive and archive list files created by BB$ARCHIVE3_PROGRAM - these files are usually stored on tape for a few months and then deleted In the HELP area - BB$BANNER.TXT BB$TOPIC.HLP BB$MESSAGE1.HLP BB$MESSAGE2.HLP In the EXECUTABLE area - BBMAIN.EXE - executable image of Bulletin Board program BB$TRACKER.COM - actually runs bbmain and produces BB$TRACKER.LOG records of BB usage In each category area where mail is received for the category - BB$NEWMAIL3.COM - runs ARPA3 to add mail to data base ARPA3.PAS - program actually adds mail messages to data base BB$BAD_MAIL.TXT - files that contain messages that ARPA3 could not add to the proper data base file BB$NEWMAIL3.LOG - created by BB$NEWMAIL3.COM contains information about messages added or defines why a message cound not be added BB$COUNT_MESSAGES.PAS - count messages by date in category ADDBAD3.COM - daily interactive run of ARPA3 Page 20 File created by first program run in users login area - SYS$LOGIN:BB$USERFILE3.DAT Files that reside in the Bulletin Board manager's area - BBMAIN.PAS - main program module all pascal modules used by Bulletin Board program listed in TEMP_.SPAS LIB$SPAWN_.PAS - used to spawn editor and mail jobs SMG$REPAINT__LINE_.PAS - used by screen management routines SMGDEFS_.PAS - used by screen management routines BBLIB - object library of above modules COMPMODS.COM - compiles modules listed in TEMP.SPAS LIBMOD.COM - puts compiled modules into BBLIB library reads file names from TEMP.SOBJ REPLACELIB.COM - replace one module in BBLIB BB$ARCHIVE3_PROGRAM.PAS - archive files sent to DATA area remember to run the count programs in each category mail area after archiving messages BBR.PAS - program that uses BB$TRACKER.LOG in data area to create monthly useage report BBREPORT.DAT - monthly report created by BBR program PROTECTION_CHANGER.PAS - protects topics - writes to TOPIC_USERS.DAT in data area F$GETJPI.COM - used to get member and group numbers to set protections on topics PRINT_ALL_MODULES.OUT - prints modules of BB TEST.FDL - fdl used to create data base files in data area ASSIGN_.COM - used if running executable on remote host Page 21 COMPILING, LINKING AND RUNNING THE BULLETIN BOARD There are several files available to make maintaining the Bulletin Board utility, library and associated files a little easier. At NRL these files all reside in: NRL::DUA103:[PAUL.FIFTH_BB] 1. COMPMODS.COM is an interactive procedure. You will be asked if you wish to use debug and you may choose whether or not to compile the main program. This procedure reads from file TEMP.SPAS and each module listed in this file will be compiled with or without debug depending on the beginning response to questions. 2. LIBMOD.COM will put all the newly compiled modules into the library called BBLIB. This procedure reads from the file TEMP.SOBJ. 3. REPLACELIB.COM will take a single newly compiled module and replace it in BBLIB. 4. PRINT_ALL_MODULES.OUT will print all the modules and the BBMAIN whenever a current listing is needed. ********** The link step: LINK BBMAIN,BBLIB/LIBRARY The execution step: @BB$TRACKER.COM During normal execution the procedure BB$TRACKER.COM will assign the program logicals and actually run the main program and records are written to BB$TRACKER.LOG about each Bulletin Board access. Page 22 HOW TO ADD A TOPIC TO THE BULLETIN BOARD There are two steps to adding a topic to the Bulletin Board. Only a Bulletin Board manager may add topics. The current valid Bulletin Board managers at NRL are K. Howell, A. Paul, C. Bazemore, SYSTEMS and USERSERVICES. 1. A manager must run the Bulletin Board utility. At the first screen select the ADD option. Then answer the prompts. When done adding topics use s to return to the first screen. You will be prompted for an internet address. Type this very carefully as mailer will use this address if a user chooses the Send option on any message. The internet address may be the designation for the "owner" of the new topic for local boards in which case the address will be something like NRL::username. For BITNET boards you will have to obtain the internet address from TELNET SRI-NIC. These addresses must reside in the local system host table. 2. The second step is to run the program PROTECTION_CHANGER, which usually resides in the Bulletin Board manager's account, to put a record into the file called TOPIC_USERS.DAT that will enable the Bulletin Board utility to determine who may add messages to the new topic. At NRL the topic file resides at SYSTEM3:[BB$PROGRAM.DATA]. Be sure to type the topic name exactly as it appears on the topic screen menu in the Bulletin Board utility. To make a topic world access and write put in -1111 for the group and member number when prompted for. Most boards will be of this type, although many are protected for USERSERVICES management only. At NRL, to make a board protected for USERSERVICES use 11 for member number and 54 for group number. Alternately you can convert the UIC codes given in the USERLIST from octal to decimal numbers and enter these decimal values for the group and member numbers. Be sure that each "protection" is thoroughly tested by the owner of the topic. To obtain group and member numbers for a user if your system does not have a USERLIST utility, run the procedure F$GETJPI.COM in the account for which you need the group and member numbers. To get the group number respond to pid prompt and GRP to item prompt. To get the member number respond to pid prompt and MEM to item prompt. If you do not do the above steps no one will be able to use the new board. Page 23 CHANGING TOPIC INFORMATION In order to change the internet address or description of a topic, a Bulletin Board manager must run the utility and select ADD on the first screen. Type the topic number for which the change is to be done as prompted for. The utility will inform you that the topic already exists and then will give you a chance to change the internet address and/or the topic description. Page 24 CHANGING PROTECTION OF A TOPIC BOARD In order to change the id of who may add and delete messages from a particular topic, in other words, to change the "owner" of a topic, a Bulletin Board manager must run the PROTECTION_CHANGER. Choose the option for DELETE a topic first, then select ADD and reenter the topic name and the appropriate group and member numbers for the topic. More than 1 manager may be added per topic. Page 25 MAKING A NEW BULLETIN BOARD MANAGER Current Bulletin Board managers at NRL are A. PAUL, K. HOWELL, C. Bazemore, SYSTEMS and USERSERVICES. To make a person a valid Bulletin Board manager requires two steps. 1. The codes for group and member numbers must be edited in the module GET_UIC.PAS. These codes must be given in decimal value. Then the module must be compiled and replaced in the library and the program must be relinked: PASCAL GET_UIC @REPLACELIB GET_UIC LINK BBMAIN,BBLIB/LIBRARY 2. The second step is to run the program PROTECTION_CHANGER to put a record into the file called TOPIC_USERS.DAT that will enable the Bulletin Board utility to know the new manager. The topic name in this case is BB_MANAGER. Then respond with proper group and member numbers in decimal values when prompted for. To obtain group and member numbers for a person, run the procedure F$GETJPI.COM in the account for which you need the group and member numbers. To get the group number respond to pid prompt and GRP to item prompt. To get the member number respond to pid prompt and MEM to item prompt. Alternately, octal codes in the USERLIST can be converted to decimal and these values can be used in the procedures. There is no limit to the number of Bulletin Board managers allowed. Page 26 ARPA PROGRAMS AND PROCEDURES These instructions are for the programs and procedures that are executed daily in each category area in order to add messages to the Bulletin Board data bases. At NRL, the category areas are CCF_RESEARCH, CCF_BITNET and CCFBULLETIN. All of these programs and procedures reside in each of the category areas and have been edited to reflect the location of the data base and count file associated with the area in which they reside. Page 27 BB$NEWMAIL3.COM *************** The original procedure was written by Charles Brown, 1987. It was revised and simplified by Alta M. Paul, 1988. This procedure automatically resubmits itself at 3a.m. from each category area. At NRL this procedure is submitted via the NRL3_QUICKBATCH queue. To submit this file to NRL3_QUICKBATCH, enter the following command from the category area where you wish the procedure to run: SUBMIT/NOPRINTER/QUEUE=NRL3_QUICKBATCH BB$NEWMAIL3 To delete an entry from the queue: SHOW QUEUE NRL3_QUICKBATCH Get the entry number of the job to delete. DELETE/ENTRY=entry_number NRL3_QUICKBATCH The current version of the Bulletin Board is interfaced with the VMS mail system in each category area. During the 3a.m. run of this procedure, all new mail messages received in each category area for the past 24 hours are written to files with the name BB$MAIL.TXT. These mail messages are then deleted from the mail utility. This procedure then picks up the files called BB$MAIL.TXT one at a time and calls the ARPA3 program which will attempt to add the messages to the Bulletin Board data base. Files that are invalid for the Bulletin Board in some way are stored as versions of BB$BAD_MAIL.TXT. The separate categories of topics are necessary since the data base file quickly becomes so large that the program is too slow to be useful when loading some of the larger topics. This procedure must be run in the separate areas for several reasons. Some of the topics have so many new messages to add every day that if only one submit were done in the night, the procedure would time out or remain unfinished at the start of the next business day. This procedure also counts the messages in the relevant data base file using BB$COUNT_MESSAGES since that is also a very time consuming process. Each category area must be granted access control of RWED to the count file that resides in the DATA area. At NRL, the DATA area is SYSTEM3:[BB$PROGRAM.DATA]. Page 28 To set forward from one of the category areas to test a new version of the utility, in the chosen category area, invoke the VMS MAIL utility and type the following: SET FORWARD "_category_area_name,your_username" Then the Bulletin Board manager can build test data bases in another area for testing revisions of the Bulletin Board utility. Page 29 ARPA3.PAS ********* This program was written by Charles Brown. It was extensively commented, documented and reformatted to conform with standard pascal by Alta Paul. Some minor modifications were made, especially in making the messages generated to the log file more descriptive. A change was also made so that the messages that were duplicates of messages already in the Bulletin Board data base are not saved as BB$BAD_MAIL.TXT. Under the old version, duplicate messages were saved and had to be examined and deleted each day by the Bulletin Board manager. This is definitely too tedious since separate accounts are now used for the storing and loading of messages in each category. This program is invoked by two separate procedures. BB$NEWMAIL3.COM will invoke this program during the 3a.m. run for each file in the directory with the name BB$MAIL.TXT. The Bulletin Board manager will run this program interactively each working day from the procedure called ADDBAD3.COM when the messages that could not be added by previous 3a.m. runs for some reason are inspected and the Bulletin Board manager can decide on the disposition of each file named BB$BAD_MAIL.TXT. A daily inspection of the log file BB$NEWMAIL3.LOG will be necessary in all category areas to make sure that nothing unforseen occurred during the 3a.m. run. Page 30 ADDBAD3.COM ********** This is an interactive procedure that the Bulletin Board manager should execute each working day from all category areas if there are files called BB$BAD_MAIL.TXT in the directory. Upon invoking the procedure a menu is displayed. Following is a description of each option: 1. BYE - all processing stops. This is the only way to exit the procedure. 2. DELETE - delete the current BB$BAD_MAIL.TXT under inspection 3. EDIT - edit the current BB$BAD_MAIL.TXT under inspection 4. READ - execute ARPA3 trying to add highest version of BB$BAD_MAIL.TXT to the data base 5. FAST - delete current BB$BAD_MAIL.TXT and use ARPA3 on next highest version 6. MAIL - invokes VMS mail utility to forward current BB$BAD_MAIL.TXT 7. HELP - redisplays the topic menu There are several very common problems that cause a message not to be added to the data base file. The Bulletin Board manager will have to inspect each file that is not added to the data base and decide if the message is really something that belongs in the Bulletin Board. If the message should be added, the manager should check that the topic field in the TO: line is correct. Occasionally the use of double quote marks can cause problems. Replace these with single quotes and try to add the message again. Another trick that sometimes works is to delete the top four lines from the message header and try to add the message. If all else fails and the message is of general interest, the Bulletin Board manager can log onto the Bulletin Board and use the Add option in the proper topic and add the message. However, the manager then becomes the poster of the message and users cannot now use the Send option if they wish to reply to the real poster of the message. The manager should remember to run BB$COUNT_MESSAGES if any of the messages stored as BB$BAD_MAIL.TXT are added interactively during the daily cleanup. Page 31 BB$COUNT_MESSAGES ***************** This program was written by Alta M. Paul, 1988. The program will access the proper data base and count the number of messages in each topic, storing the counts by date in a sequential file in the data area for the Bulletin Board. These counts are used to produce the total columns on the topic screens in the Bulletin Board program. Since this program is run only at 3a.m., if a user adds messages during the day, the counts will be slightly incorrect until this count program is run again. If the Bulletin Board Manager adds messages during the daily cleanup of messages called BB$BAD_MAIL.TXT, then this program should be run again to correct the counts. This procedure replaces code in the old 1987 version of the Bulletin Board program which touched each record in the data base when the program was invoked in order to produce these counts. Creating the columns of total and new messages sometimes took more than 15 minutes if the data base file contained a great number of messages. By creating a master sequential count file and reading these totals during creation of the total columns, the topic screen usually appears in under one minute, even for categories with hundreds of messages. For this time savings, a slight occasional inconsistency in count totals and actual number of messages is acceptable. Page 32 WEEKLY BULLETIN BOARD ARCHIVE NOTE: At NRL, the data files mentioned reside in SYSTEM3:[BB$PROGRAM.DATA]. Before doing any archiving, the Bulletin Board should be inspected and a decision made on which boards are to be archived and through which date to remove the messages. It is suggested that no more than 350 messages reside in any one topic after the archive is complete and that messages not be allowed to remain for over 30 days. At NRL, archiving is done as early as possible on the first working day each week. If the archive is performed regularly it will not take too long. After the archive is done the data base files should be examined with: DIR/SIZE SYSTEM3:[BB$PROGRAM.DATA]BB$*_BOARDS.DAT When any of these files become larger than 40,000 blocks, a compress should be done to empty the "buckets" and keep the file a manageable size. This is done with: CONVERT/FDL=TEST.FDL SYSTEM3:[BB$PROGRAM.DATA]filename - SYSTEM3:[BB$PROGRAM.DATA]filename It is best to do this convert on the scratch disk since so much extra memory will be required to finish the process that it often aborts and leaves the new data base file empty. Copy the file TEST.FDL to the scratch disk along with the data file to be converted. Copy the newly converted file back to the original directory with the same file name as before. After this is complete, the Bulletin Board utility should be invoked and the topics inspected carefully to insure that all the topics are present and that there are the expected number of messages in each topic. Occasionally there is a problem with the CONVERT utility and the data base file becomes empty. If the convert is successful then the old version of the data base file may be archived with SI ARCHIVER and the smaller file becomes the production file. If the convert is unsuccessful the old data base file can be retained after deleting the new empty version and the convert can be attempted at a later time. NOTE: If a convert is needed, do the archiving procedure and run the count program before doing the convert. Page 33 BB$ARCHIVE3_PROGRAM ******************* This program is run independently of the Bulletin Board utility and will take about 30 minutes of the Bulletin Board manager's time each week. This program replaces the archive functions that were built into the 1987 version of the Bulletin Board utility. The old archiving function wrote messages that were removed to indexed files that could not be loaded back into the Bulletin Board or examined with an editor. Since the only person who could do the archive function was the Bulletin Board manager, this archiving code was removed from the Bulletin Board utility and this new program was written using the old code to extract messages but write the extracted text to sequential files that could be archived with SI ARCHIVER and easily recalled for users if they are requested. AT NRL this program resides in the Bulletin Board manager's account. The files for each topic archived are written to SYSTEM3:[BB$PROGRAM.DATA]. Removed messages are stored in sequential files by topic and a log file is produced that will tell what files are produced for the messages and the date, sender and subject of each message removed. It is suggested the the log files be printed and retained for a period of time so that if any Bulletin Board user wishes to have a particular board recalled for some range of dates the files can be easily located and the user can use EDT to inspect the messages. Message files will have file names of the form: SYSTEM3[BB$PROGRAM.DATA]topicname_ending-date-of-messages.ARCHIVE The log file will have a name of the form: SYSTEM3[BB$PROGRAM.DATA]BB$ARCHIVE_FROM_today's-date.LIST After the archive, the program: BB$COUNT_MESSAGES should be run in the proper category areas to reflect the lowered totals of messages in the archived topics. The Bulletin Board utility should be inspected after any archiving to make sure that the program is working correctly. ************************************ The following chart illustrates how we keep track of archiving done on the Bulletin Board at NRL. We keep these lists around for a few weeks just to have an idea of the traffic on the various topics. Page 34 DATE OF ARCHIVE: _______________________________ _______________________________________________________________________| |______________________________________________________________________| | TOPIC NAME | # MESSAGES | # MESSAGES | ARCHIVE | | | BEFORE ARCHIVE | AFTER ARCHIVE | THROUGH | |------------------|------------------|-----------------|--------------| 1| CALENDAR | | | | |------------------|------------------|-----------------|--------------| 2| CCF-NEWS | | | | |------------------|------------------|-----------------|--------------| 3| NRL-CAR-POOLS | | | | |------------------|------------------|-----------------|--------------| 4| NRL-INSTRUCTIONS | | | | |------------------|------------------|-----------------|--------------| 5| NRL-MEETINGS | | | | |------------------|------------------|-----------------|--------------| 6| NRL1000/1001 | | | | |------------------|------------------|-----------------|--------------| 7| NRL2000 | | | | |------------------|------------------|-----------------|--------------| 8| PW-NEWS | | | | |------------------|------------------|-----------------|--------------| 9| RUAC | | | | |------------------|------------------|-----------------|--------------| 10| SUPPLY-BOARD | | | | |------------------|------------------|-----------------|--------------| 11| YACC | | | | |------------------|------------------|-----------------|--------------| |------------------|------------------|-----------------|--------------| |------------------|------------------|-----------------|--------------| |------------------|------------------|-----------------|--------------| 1| ATARI16 | | | | |------------------|------------------|-----------------|--------------| 2| INFO-C | | | | |------------------|------------------|-----------------|--------------| 3| INFO-HAMS | | | | |------------------|------------------|-----------------|--------------| 4| INFO-IBMPC | | | | |------------------|------------------|-----------------|--------------| 5| INFO-MAC | | | | |------------------|------------------|-----------------|--------------| 6| INFO-PASCAL | | | | |------------------|------------------|-----------------|--------------| 7| INFO-UNIX | | | | |------------------|------------------|-----------------|--------------| 8| INFO-VAX | | | | |------------------|------------------|-----------------|--------------| 9| LASER-LOVERS | | | | |------------------|------------------|-----------------|--------------| 10| TCP-IP | | | | |------------------|------------------|-----------------|--------------| Page 35 DATE OF ARCHIVE: _______________________________ _______________________________________________________________________| |______________________________________________________________________| | TOPIC NAME | # MESSAGES | # MESSAGES | ARCHIVE | | | BEFORE ARCHIVE | AFTER ARCHIVE | THROUGH | |------------------|------------------|-----------------|--------------| 1| AILIST | | | | |------------------|------------------|-----------------|--------------| 2| BIONET-20 | | | | |------------------|------------------|-----------------|--------------| 3| BIOTECH | | | | |------------------|------------------|-----------------|--------------| 4| PHYSICS | | | | |------------------|------------------|-----------------|--------------| 5| POLYMERP | | | | |------------------|------------------|-----------------|--------------| 6| RSRCH-ADVANCES | | | | |------------------|------------------|-----------------|--------------| 7| RSRCH-INQUIRIES | | | | |------------------|------------------|-----------------|--------------| 8| THEORYNET | | | | |------------------|------------------|-----------------|--------------| |------------------|------------------|-----------------|--------------| Page 36 PROGRAMS ASSOCIATED WITH PRODUCTION OF THE MONTHLY REPORT The following documentation explains the programs that are used to produce the monthly Bulletin Board usage report. The report can be generated at any time, but should be generated at least the first working day of each month. At NRL, the report is given to the head of User Services Branch. Page 37 BBR.PAS ******* This program was written by Charles Brown. It was reformatted to conform with standard pascal by Alta Paul. A few simplifications were also made to the code. A second simplification was made in JULY, 1988 to this program when the BB$TRACKER.COM procedure was simplified. The main changes under the JULY revision deal with the simplified parsing after the BB$TRACKER.LOG file was changed. In the previous version of the BB$TRACKER.COM, three lines of text were produced for each use of the Bulletin Board. In the new version, only one line of text is written. Carla Bazemore added the code to produce the summary page and commented the code in SEPTEMBER, 1988. This pascal program reads the sequential file SYSTEM3:[BB$PROGRAM.DATA]BB$TRACKER.LOG and produces linked lists of the records found there. The program totals the number of times each Bulletin Board user uses the utility, the total time used, and keeps a record of the last date accessed. The report produced is in four parts, sorted by name of user, total access time, number of uses and last accessed date. A summary page reports number of users, number of uses, total usage time and a table of uses during each 60 minute period. Before running this report, copy the BB$TRACKER.LOG file into the area where the BBR program will run. The BB$TRACKER.LOG should be edited to reflect only the dates you wish the report to cover. To run this program type RUN BBR and respond to the questions about the start and end date for the report. After successful completion of the report, the BB$TRACKER.LOG file in SYSTEM3:[BB$PROGRAM.DATA] should be edited so that the old dates of use are no longer in the current file. The report file is called BBREPORT.DAT. Page 38 BB$TRACKER.COM ************** This procedure was written by Charles Brown and resides in SYSTEM3:[BB$PROGRAM.EXE]. Alta Paul commented and simplified this procedure. It produces the sequential file SYSTEM3:[BB$DATA]BB$TRACKER.LOG. The tracker file contains one line for each use of the bulletin board utility. These lines are read and parsed by the BBR program. This procedure is used to actually run the Bulletin Board utility. At CCF the symbol BULLETINBOARD points to this procedure file. Page 39 Using VAX/VMS mail to add messages It is possible for users to add messages to the Bulletin Board using the VAX/VMS mail utility. The address on the TO: line must be the mail account area for the category that the message is associated with. The subject should be followed by "@topicname". For example, to mail a message at NRL to the topic CALENDAR, do the following: TO: NRL::CCFBULLETIN SUBJECT: Meeting on Sept. 30@CALENDAR The message will be added to the Bulletin Board the next time the BB$NEWMAIL3.COM file runs in the CCFBULLETIN area under the category Local Administrative Topics in the CALENDAR topic.