Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / COMMCDS.ZIP / COMMCDS.DOC next >

Wrap

Text File | 1993-01-04 | 19.7 KB | 402 lines

COMMCDS UNIT A Turbo Pascal unit that implements the Call Data Standard Version 0.90 by Rob Rosenberger CDS Development Team Leader A public domain utility from BARN OWL SOFTWARE P.O. Box #74 O'Fallon, IL 62269 VOX: (618) 632-7345 BBS: (618) 398-5703 HST: (618) 398-2305 CIS: 74017,1344 This unit, known as CommCDS, implements the functionality of the powerful new Call Data Standard as it applies to communica- tions programs and BBS software. Please read the CDS specs for further information. A copy of the specs is available in Compu- Serve's IBMCOM forum LIBrary 2, filename CDS.ARC. CDS defines standard methods for storing modem usage details in a "Call History File." This lets a class of programs known as phone bill analyzers study the file to determine how much a user has spent in modem-related telephone calls. CDS goes beyond modem usage details. It lets communications programs "talk" to external protocol applications and phone bill analyzers. A communications program could determine the cost of the current call ── even if it's still in progress ── if the user wants to know it. (CommCDS v0.90 has not yet implemented this powerful feature.) This unit requires the Turbo Professional 5.0 toolkit from TurboPower Software. Write to them for a free brochure if you don't already have this powerful toolkit. TurboPower's address is P.O. Box #66747, Scotts Valley, CA 95066-0747. DEFINITIONS ProgramName : STRING[08] = 'UNKNOWN'; Your communications program's name goes here in place of the word "unknown". You may use up to eight characters for the name. ── page 2 of 9 ── HostName : STRING[16] = ''; If your communications program falls under the definition of "navigation" software, then put your host service's name here. TAPCIS, for example, would specify 'CompuServe'. The max length is 16 chars. Leave this null if your comm program is for general purpose communications. CDSProtocolType = (UnknownProtocol, NoProtocolUsed, ASCII, Bimodem, CISA, CISB, CISQuickB, CISBPlus, Jmodem, Kermit, Modem7, Telink, Xmodem, Xmodem1K, {sometimes mistakenly referred to as Ymodem} Xmodem1KG, XmodemCRC, Ymodem, {the true Ymodem Batch protocol} YmodemG, {the true Ymodem Batch protocol} Zmodem); These protocols are currently "known" to CDS. ReasonType = (UnknownReason, BusinessReason, PersonalReason); CDS can tell when calls are placed specifically for business or personal reasons. Use the UnknownReason value if your program doesn't know otherwise. CDSIORESULT : BYTE; This variable always contains the IORESULT at the end of a call to the CommCDS unit. You must check it like you would check IORESULT. Unlike IORESULT, this variable retains its value after studying it. ── page 3 of 9 ── ROUTINES PROCEDURE ChangeCallParams(CommSpeed : LONGINT; CommBits : BYTE; CommParity : CHAR; CommStopBits : BYTE; CallerName : STRING; HostBBSName : STRING; SecurityLevel : INTEGER; Comment : STRING); This procedure lets you change the details about the call in progress. It is extremely useful when you switch baud rates or change the security level of a caller. CommSpeed, CommBits, CommParity, and CommStopBits combine to produce the standard modem settings for the call. Good examples would be "19200 8 N 1" or "1200 7 E 1". The current values must be supplied for each of these items; there is no default. CallerName is either the name of the person using your comm program for an outgoing call, or the name of the person calling into your BBS program for an incoming call. This variable is ignored if it contains a null string. HostBBSName is the name of the system the user is calling. It applies only to outgoing calls. This variable is ignored if it contains a null string. SecurityLevel is the current security level of the user who has placed an incoming call. The correct value must be supplied for this item; there is no default. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. PROCEDURE InitCommCDS(CDSPath : STRING); This procedure initializes the CommCDS unit. You cannot use any other routines in this unit before this one. You MUST call this procedure when your program first starts up. CDSPath provides a specific path where all CDS files will be kept. A null string means CDS files will be kept on the default drive & directory. CommCDS will hunt for old copies of its files and append to them if they exist. Therefore, it would be to your advantage to provide a specific path instead of using a null string. ── page 4 of 9 ── PROCEDURE LogChargeChange(Suspend : BOOLEAN; Comment : STRING); Networks such as CompuServe and GEnie charge for their ser- vices. Yet they temporarily suspend charges when a user uploads a file or takes advantage of a special service. CDS recognizes this and accommodates for it. This procedure suspends/resumes charges only for host system charges. CDS lets you suspend/resume phone company charges, but few people will have a need to record such information. You can easily upgrade this procedure to handle phone company charges as well, if you need such a capability. Suspend dictates whether CommCDS should temporarily suspend charges. True = suspend charges; false = resume charges. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. ── page 5 of 9 ── PROCEDURE LogFileXfer(FileName : STRING; WasUploaded : BOOLEAN; FileSize : LONGINT; Reason4Transfer : ReasonType; Protocol : CDSProtocolType; SuspendBBSCharge : BOOLEAN; StartingDateTime : DateTimeRec; EndingDateTime : DateTimeRec; AbortedBySender : BOOLEAN; AbortedByRecvr : BOOLEAN; CallDiedInXfer : BOOLEAN; TotalXmitErrors : WORD; Efficiency : REAL; AverageCPS : WORD; Comment : STRING); This routine logs details about transferred files in the CDS Call History File. Filename is the name of the transferred file. The path to the file can be included, but it is not necessary. WasUploaded is true if the file was uploaded, false if the file was downloaded. FileSize is the size of the file in bytes. Reason4Transfer dictates whether the file was transferred for personal or business reasons, if such information is known. Protocol describes the protocol used to transfer the file. SuspendBBSCharge should be set to true if the host system suspended charges during this transfer. StartingDateTime and EndingDateTime tell when the transfer began and ended. DateTimeRec is defined in TPRO5's TpDate unit. AbortedBySender is true only if the sender aborted the file transfer before completion. AbortedByRecvr is true only if the receiver aborted the file transfer before completion. CallDiedInXfer is true only if the connection was lost while the file was being transmitted. TotalXmitErrors contains the number of erroneous blocks of data discovered during the file transfer. Efficiency contains a (real) number describing how efficient the transfer was. Efficiency = 96.4 if a file transfer was 96.4% efficient. Efficiency is ignored if it is 0.0. AverageCPS contains the average characters per second trans- mitted during the file transfer. AverageCPS is ignored if it is zero. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. ── page 6 of 9 ── PROCEDURE LogForumSwitch(ForumName : STRING; Comment : STRING); This routine logs a CDS entry that shows the user switched to a different forum, or area, of the host system. For example, CompuServe users can switch from the TAPCIS forum to the LOTUS forum, and PCBoard users can switch from the MAIN conference to the PROGRAMS conference. CDS methodology dictates you first show a user entered some sort of "main" forum. The time spent getting to the "main" forum is then considered to be the natural overhead of logging onto the system. You should use this routine only if you keep accurate track of where users go within the host system. ForumName is the name of the forum (or conference) the user is accessing. The forum name will be truncated to 16 characters. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. PROCEDURE LogFreeFormatComment(CommentString : STRING); This procedure puts a comment of ANY length in the Call History file. NOTE: This procedure works different from all other CommCDS procedures. There is only one CommentString variable ── however, you may call this procedure as many times as it takes to store an entire comment. The only requirement is that you MUST terminate the comment by calling this procedure with a null string. This signals you are finished with your free-format comment. Comments are automatically tied to a phone call if a call is in progress. Otherwise it is written to the Call History File as a 'generic' comment. CDSIORESULT is initialized after you finish the comment. Do not bother to check it until you call this procedure with a null string. CommentString can be any length up to the max 255 characters imposed by Turbo Pascal. Word-wrapping is performed if necessary to make CommentString fit within CDS constraints. A new line is started when the entire CommentString has been stored in the Call History File. Please be aware of this if you want to format each string when it goes into the CDS comment record. ── page 7 of 9 ── PROCEDURE LogIncomingCall(CommPort : INTEGER; CommSpeed : LONGINT; CommBits : BYTE; CommParity : CHAR; CommStopBits : BYTE; CallerName : STRING; SecurityLevel : INTEGER; LocalLogon : BOOLEAN; Comment : STRING); This procedure logs an incoming call. This is common for BBS applications as well as communications programs that offer a limited host mode service. CommPort is the numeric port designator handling this call. COM1 is 1, COM2 is 2, and so forth. This value MUST be supplied. The reason will become obvious if you study the CDS specs. CommSpeed, CommBits, CommParity, and CommStopBits combine to produce the standard modem settings for the call. Good examples would be "19200 8 N 1" or "1200 7 E 1". The current values must be supplied for each of these items; there is no default. CallerName is the name of the caller. Use "SYSOP" when the system operator is logging into the host system. Securitylevel is the security level of the caller. LocalLogon is true only when the caller is logging onto the host system from a local terminal. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. ── page 8 of 9 ── PROCEDURE LogOutgoingCall(CommPort : INTEGER; CommSpeed : LONGINT; CommBits : BYTE; CommParity : CHAR; CommStopBits : BYTE; CallerName : STRING; Reason4Call : ReasonType; HostBBSName : STRING; PhoneNumber : STRING; HostCallback : BOOLEAN; Comment : STRING); This procedure logs an outgoing call. This is common for communications programs, and for BBS applications (and communica- tions programs) that offer a security callback feature. CommPort is the numeric port designator handling this call. COM1 is 1, COM2 is 2, and so forth. This value MUST be supplied. The reason will become obvious if you study the CDS specs. CommSpeed, CommBits, CommParity, and CommStopBits combine to produce the standard modem settings for the call. Good examples would be "19200 8 N 1" or "1200 7 E 1". The current values must be supplied for each of these items; there is no default. CallerName is the name or userID of the person making this outgoing call (if known). In cases of security callbacks, you might want to say the caller was "Security Callback Mode". This item is ignored if it is a null string. Reason4Call dictates if the call was placed for personal or business reasons, if such information is known. HostBBSName can be a little confusing. If this is a regular outgoing call, the user has dialed either a BBS or a network like CompuServe. Obviously then, HostBBSName contains the name of the host system. But if it is a security callback call, HostBBSName contains the name of the user. ...HostBBSName is usually known, but there are some exceptions. You won't know the name of a BBS when the user performs a manual dial, so use "UNKNOWN" (all caps) for the name. The same holds true if you detect a call when the program first loads into memory. PhoneNumber obviously contains the phone number. If this is a null string, it means you don't know what the phone number was. This could be due to a user typing an AT dialing command directly to the modem, or if a call was in progress when the program first loaded in memory. NOTE: Vanity numbers such as "1-800-DEC-DEMO" are not allowed. You MUST convert it to its equivalent numeric form. CDS phone bill analyzers view letters in the phone number as redefinable prefix/suffix codes. Consult the CDS specs for further information. HostCallback is true only if a security callback feature is making the outgoing call. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. ── page 9 of 9 ── PROCEDURE LogTerminatedCall(PasswordFailure : BOOLEAN; CallContinuedOn : BOOLEAN; CallEndedAbrupt : BOOLEAN; AverageCPS : WORD; Comment : STRING); This procedure logs the termination of a call. It applies to both incoming and outgoing calls. PasswordFailure is true only if the (incoming) call was ter- minated due to excessive password failures. CallContinuedOn is true only if the current call in progress remained active after the communications program terminated. If you leave DTR up upon termination, you MUST call this procedure and set set CallContinuedOn to true. CallEndedAbrupt is true only if the modem dropped connection without warning. AverageCPS contains the average characters per second trans- mitted during the call. AverageCPS is ignored if it is zero. Comment is any text you wish to add as a comment entry. It is truncated if it exceeds 56 characters. PROCEDURE WrapupCommCDS; This procedure wraps up the CommCDS unit. You cannot use any other routines in this unit after this one. You MUST call this procedure when your program terminates.