GAPUTI - UTI Drivers For GAP Communications September 16, 1990 Version 2.2 The programs included with this documentation consist of a set of Universal Text Interface (UTI) drivers to be used in conjunction with GAP Communications and the PCRelay Networking software. This software is provided AS IS, without warranty of any kind. GAP Development Company provides this software as a service to the BBS Community and makes no warranties, express or implied, as to the suitability of the programs described within this documentation. The end user agrees to use these programs at his/her sole risk and agrees that GAP Development Company is not liable for any damges directly or indirectly caused by said programs. The form and function of the UTI drivers are described in a document produced by the PCRelay author and will not be detailed here. GAPUTI.CNF - This is a configuration file for the GAP UTI drivers. It currently consists of one line which lists the full path to the GAP default directory (IE, the directory where GAPBBS.CNF can be found). UTIHIGH.EXE - This program will read the GAP Communications MESSNO.DAT file to determine the next available message number in the Echo Mail Forum. It will create a file with the name passed to it as the second parameter on the command line. UTIEXPRT.EXE - This program will extract any messages from an Echo Mail Forum (Forum number passed to it as the first parameter) that are marked as echo mail, beginning with the message number passed as the second parameter, to a file with the full path name that is passed as the third parameter. UTIIMPRT.EXE - This program will read the UTI file (passed as the second command line parameter) and create the ISAM messages in the Echo Mail Forum. UTILSTRD.EXE - This program operates will either update a caller's last read message pointers by reading a text file, or it will write a text file containing the caller's last read pointers. UTILIST.EXE - This program creates a text file listing the available Forums. The Main Board is always listed as the first Forum. All Forums are listed, whether they are echo mail Forums or not. UTIVER.EXE - This program simply writes a file containing the UTI revision number and the GAP UTI version number. UTIDOOR.EXE - This program is provided as a substitute for DOOR.SYS. It will create a "mini" DOOR.SYS file (in fact, it reads DOOR.SYS to obtain its information). This program is run prior to running any door program that uses the UTI drivers. As such, it must be run from the BBS DEFAULT directory. The seven programs and the one configuration file may be placed in any directory. The configuration file will be read by six of the programs to determine where your GAPBBS.CNF file is located. The configuration file MUST be located in the same directory as the UTI drivers. Last Read Date The UTI specification supports the Message Read flag, however it does not support the Message Read Date. Therefore, if a message has been read and it is echoed, it will show up on the other nodes with the Read flag set to Yes, but the Read Date will be the same date as the message. Multi-User Notes There are two versions of all the drivers except for UTIVER. One set is for Multi-User systems, the other is for Single User systems. We strongly suggest that when you run your Export/Import, that you bring all nodes to DOS and use the single user version of the UTI drivers. The reasons for this are many so we will briefly explain the most important ones: If, during the import process, another node saves a message in the same Forum that is currently having mail imported to it, the Refer To message numbers will be incorrect. This is because the Multi-User version of UTIIMPRT obtains its message numbers directly from MESSNO.DAT (in exactly the same manner GAP uses). The number that is read from MESSNO.DAT will be the same as the message number in the UTI mail file ONLY if other nodes are NOT allowed to save messages at the same time. Because of the safety features inherent within multi- user systems, importing with the multi-user version of UTIIMPRT will be much slower than the single user version. During the import process, the driver must do the following: Read a message from the UTI text file. Read and lock MESSNO.DAT. Read the last message to get the number of active messages. Lock the MSGS.DAT record where the message will be saved (this entails an elaborate process used by the ISAM routines which includes locking DUMMYLOK.DAT and the header record of the MSGS.DAT file). Save the message. Unlock all the files. It should be noted that this process must be used for each message that is saved. If you absolutely MUST have your nodes up while you are importing mail, then you live with the consequences of Refer To numbers being incorrect and your import taking about twice as long. The following ERROR codes are returned by the programs: -1 - Could not open Text File. 2 - File not found. 9 - File is locked by another process. 13 - Another process has exclusive access to file. 24 - Too many open files. 28 - Disk Full. 99 - Fatal ISAM error. Rebuild ISAM files. If an error occurs during an ISAM operation, the error codes will range from 2 - 300. Any error above 196 is Fatal and the ISAM files should be rebuilt. An error code of 99 will be returned for fatal errors. Some of the more common ISAM errors that can occur are: 2 - Duplicate message number. 10 - Insufficient memory for index buffers. 12 - Could not open ISAM file. 14 - ISAM file is corrupt. Rebuild files. 35 - Either out of Disk Space or file is corrupt. 36 - Corrupted record in ISAM file. 37 - Out of Disk Space. UTIIMPRT, UTIEXPRT, and UTILSTRD will write any errors encountered to a file with the same name as the program but with an extension of LOG. Command Line Arguments This information is provided for the benefit of any person that wishes to use the GAP UTI Drivers for other than their intended purpose. UTIHIGH.EXE Parameter 1 - Forum Number to operate on. Parameter 2 - Full path and file name of the file to write the highest numbered message to. UTIEXPRT.EXE Parameter 1 - Forum Number to operate on. Parameter 2 - The message number to start exporting messages from. Parameter 3 - Full path and file name of the file to write the Message Text File to. Parameter 4 - Optional. If present, will be /NETWORK. If passed to the program, only those messages which are marked as "echoed" will be exported, otherwise, ALL messages will be exported. UTIIMPRT.EXE Parameter 1 - Forum Number to operate on. Parameter 2 - Full path and file name of the Message Text File to import into the Forum. Parameter 3 - Optional. If present, will be the full path and name of a descrepancy file that the UTI driver will write to if there is a descrepancy in message numbers (if the Message Text File says to use a message number that is already in use). The number written to this file will be the difference between the highest message number in the Message Text File and the highest message number actually used by the UTI driver. Parameter 4 - Optional (can be either parameter 3 or 4). If present, will be /NETWORK. If passed to the program, all messages imported will be flagged as having come in from a network, so that they will not be re-exported to the network. UTILSTRD.EXE Parameter 1 - Will be either READ or WRITE. READ means the UTI driver will read the user's last read message pointers from the User File and write the numbers to a text file. WRITE means the driver will write the last read message pointers read from a text file to the User File. Parameter 2 - Full path and file name of the text file to either write to or read from. Parameter 3 - First name of the user the driver is currently working with. Parameter 4 - Last name of the user. UTILIST.EXE Parameter 1 - Full path and name of the file to write Forum Information for each Forum the user is a member of. UTIDOOR.EXE Parameter 1 - Full path and name of the file to write caller information to. UTIVER.EXE Parameter 1 - Full path and name of the file to write the version number of the UTI Drivers to. MegaDoor and MegaReader Notes UTIDOOR.EXE needs to be placed in the default directory of each Node (or in a DOS path). The batch file that runs the MegaDoor must first call UTIDOOR from the Node default directory. GAPUTI.CNF *must* be placed in the same directory as the MegaDoor files. It also needs to stay in your PCRelay directory as well. If your UTI drivers are placed in the PCRelay directory, remember to set a DOS path to that directory. LOCAL.BAT *must* be configured as follows: You need to configure LOCAL.BAT so that it passes the names you have set up in your sysop record. You may not use SYSOP here or any other name. You MUST use the name that you would use if you were calling GAP from remote. If you are calling in from remote, UTIDOOR.EXE will correctly write your remote sysop log in names to UTIDOOR.TXT.