CP/M

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

/ CP/M / CPM_CDROM.iso / cpm / turbopas / comdemo.ark / CLIB180.DOC next >

Wrap

Text File | 1986-08-24 | 20.9 KB | 472 lines

Turbo Pascal Communications Library 1.0 Introduction Turbo Pascal provides a fairly uniform programming environment for a variety of microcomputers running CP/M and MS-DOS. It is fast, and the differences between versions can, in general, be worked around. Certain areas are a problem, however - communications, and system dependent function. This set of routines is intended to address the first of these problems, difficulty in communicating with the outside world. Each operating system is different in the way it handles communications, and different hardware implementations create problems when trying to use communications ports. There is a need for a standard set of routines that provide the basic communications needs for most programs. If the routines are rewritten for various micros, generalized communications programs can be written. Any programming tricks can be used to perform the actual functions, but a uniform calling sequence can be used. 1.1 Sample Programs A sample communications library is available as 'CLIB180.INC'. This library includes an example of each function and procedure listed below. Some of the functions are very simple, as the VT180 has PSETUP available to set parity and/or baudrates. CLIB180 also supports the RAINBOW (100A,100B) running CP/M version 2 or higher. A sample of the use of the communications library is given in the program 'COMDEMO.PAS'. This program implements a 'connect' mode and allows simple file transfer by capturing data from the communications port and storing it in a file, or sending a file to a remote system. COMDEMO.PAS was written as a 'test-case' for CLIB180.INC - it's also useful as the "first piece" to "customize" a "text-capture" utility for a new micro-system, which doesn't have yet a way to "talk protocol". TURBO-Pascal's inherent compilation-speed and (relatively high - see above) portability will help in getting the "first" and "crucial" step accomplished : Enable TEXT-capture "to" and "from" another system. The typical "next step" seen is to establish an (preferably) Error-Correcting protocol like KERMIT. 2.0 General Library Description 2.1 Variables, Constants, and Typed Variables All library functions, procedures, and global variables begin with 'c_'. This should minimize collisions with other program variables. Any variables that begin with 'c__' are for the use of the library itself, and should NEVER be modified by the main program. All variables required by the library only should be included here. This would include such variables as IOBYTE definitions for CP/M, etc. The following are predefined types, constants, and variables in the library: Types c__string10 = string[10]; c__string5 = string[5]; c__port_names = an array of string10's that will list the possible ports for the computer. c__baud_names = an array of string10's that will list the possible baud rates for the computer. c__parity_names = an array of string10's that will list the possible parity settings for the computer. Constants c_lib_version = computer type, revision of library, and date. c_port_str = all possible strings that the available ports are equivalent to. The first two MUST be 'NOT SET' and 'DEFAULT'. After all ports are defined, the last element in the array MUST be null (''). c_baud_str = all possible strings that the available baud rates are equivalent to. The first two MUST be 'NOT SET' and 'DEFAULT'. After all baud rates are defined, the last element in the array MUST be null (''). c_parity_str = all possible strings that the available parity settings are equivalent to. The first two MUST be 'NOT SET' and 'DEFAULT'. After all ports are defined, the last element in the array MUST be null (''). Variables c_kbd_char : The returned keyboard character. c_comm_char : The returned comm port character. c_current_port : The number of the current port. the string equivalent of the port number is : c_port_str(c_current_value). c_current_baud : The number of the current baud rate. The string equivalent of the baud rate is : c_baud_str(c_current_baud). c_current_parity : The number of the current parity setting. The string equivalent if the parity is : c_parity_str(c_current_parity). 2.2 Functions 2.2.1 C_INIT Initialize a communications port. Initialization is system dependent, but should include such items as setting hardware specific values, obtaining the initial value of the IOBYTE in CP/M systems, etc. It should be run at the beginning of each program that uses the communications library. The way the port, baud rate, and parity variables are set up, executing c_init(1,1,1) will set up a default communications port. This is a good way to begin any program so the at least some communication port is initialized. For some systems, having no port set up will cause system hangups. c_init(port, baud, parity : integer) : boolean; Inputs : port - Number of the port. This can be obtained by scanning the list of ports contained in the array c_port_str. parity - desired parity setting on port. The number of the available parity values for the particular computer. These can be obtained by scanning the list of parity settings available in the array c_parity_str. speed - desired port speed. The number of the available baud rate settings can be obtained by scanning the list of available baud rate settings in the array c_baud_str. Output : Function returns TRUE if the desired setup is valid, and FALSE if the setup is invalid. Variables affected : c_current_port, c_current_baud, and c_current_parity are set to their new values if the operation was successfull. Other effects: depends on implementation. 2.2.2 C_SET_PORT Select the desired communications port. c_set_port(port : integer) : boolean; Input : port - Number of the port. System dependent. A list of the available ports can be found in the array c_port_str. Output : Function returns TRUE if new port was selected, and FALSE if the new port was an invalid port. Variables affected : sets c_current_port, c_current_baud, and c_current_parity to those for the new port. Other variables are system dependent. Other effects : current port should not be changed if function returns FALSE. 2.2.3 C_SET_PARITY Set the parity on the current port, if possible. c_set_parity(parity : integer) : boolean; Input : port - Number of the port. System dependent. A list of the available ports can be found in the array c_port_str. parity - desired parity setting on port. The number of the available parity values for the particular computer. These can be obtained by scanning the list of parity settings available in the array c_parity_str. Output: Function returns TRUE if the parity is reset to the new value, and FALSE if the parity could not be set. Variables affected: c_current_parity is changed to the new parity if the operation was successfull. Other variables are system dependent. Other effects: should leave same parity if result is FALSE. 2.2.4 C_SET_BAUD Set the baud rate on the specified port, if possible. c_set_baud(speed : integer) : boolean; Inputs : speed - desired port speed. The number of the available baud rate settings can be obtained by scanning the list of available baud rate settings in the array c_baud_str. Output: Function returns TRUE if the baud rate can be set and FALSE if the baud rate cannot be set. Variables Affected: c_current_baud is set to the number of the new baud rate if the operation successfull. Other variables are system dependent. Other effects : Should leave the baud rate the same if error. 2.2.5 C_GET_KBD_CHAR Check the keyboard for an available character. c_get_kbd_char : boolean; Input : none. Output : Function returns TRUE if a character is available and false if no character is available. Variables affected : c_kbd_char is changed to new character if function returns true. Other effects : function must always leave the computer in the same state as it was found, i.e. for CP/M the IOBYTE must be returned so that CON: is set to main console. 2.2.6 C_GET_COMM_CHAR Check the currently selected communications port for an available character. c_get_comm_char : boolean; Input : none. Output : Function returns TRUE if a character is available and false if no character is available. Variables affected : c_comm_char is changed to new character if function returns true. Other effects : Function must always leave the computer in the same state as it was found, i.e. for CP/M the IOBYTE must be returned so that CON: is set to main console. 2.3 Procedures 2.3.1 C_PUT_SCR_CHAR Send a character to the console screen. c_put_scr_char(character : char); Input : character to be output. Output : none. Variables affected : none. Other effects : Function must always leave the computer in the same state as it was found, i.e. for CP/M the IOBYTE must be returned so that CON: is set to main console. 2.3.2 C_PUT_COMM_CHAR Send a character to the selected communications port. c_put_comm_char(character : char); Input : character to be output. Output : none. Variables affected : none. Other effects : Function must always leave the computer in the same state as it was found, i.e. for CP/M the IOBYTE must be returned so that CON: is set to main console. 3.0 VT180 Communications Library This is an implementation of a standard set of routines for communications, for the DEC VT180 (Robin). The VT180's main features are as follows: Microprocessor: Z80A Memory: 64k bytes Operating system: CP/M-80 Communications ports: 4 serial CRT: hard-wired terminal port to VT100 terminal LPT: printer port UC1: user defined console port PTR: high speed reader port PTP: high speed punch port The VT180 uses the Digital Research standard IOBYTE for port switching. 3.1 The IOBYTE A few words about the IOBYTE are in order. The ports on a CP/M-80 computer are described by PHYSICAL names (CRT:, LPT:, etc.). When the IOBYTE is used, they are mapped to LOGICAL ports, and the IOBYTE allows reassignment of the physical ports to different logical ports. For example, on the VT180, the pysical ports UC1: and CRT: can be assigned to be the logical port CON:. When booted normally all console I/O goes to CRT:, the internal VT100 port. If desired, the UC1: port can be assigned to be CON: and an external device can act as the system console. I use this method with a modem so I can dial up my computer and use the remote terminal as the console. The IOBYTE is the device that allows this reassignment of physical ports. The IOBYTE is a byte in memory, normally located at address 0003. This may vary in some implementation of CP/M. There are four fields to the IOBYTE: LIST PUNCH READER CONSOLE bits 6,7 bits 4,5 bits 2,3 bits 0,1 The values below are the possible IOBYTE assignments: Console field (bits 0,1) 00 console is assigned to the console printer device (TTY:) 01 console is assigned to the CRT device (CRT:) 10 batch mode, RDR: is console input device, LST: device is console output. 11 console is assigned to the user defined console (UC1:) READER field (bits 2,3) 00 reader is teletype device (TTY:) 01 reader is the high speed reader device (PTR:) 10 reader is user defined reader #1 (UR1:) 11 reader is user defined reader #2 (UR2:) PUNCH field (bits 4,5) 00 punch is teletype device (TTY:) 01 punch is high speed punch device (PTP:) 10 punch is user defined punch #1 (UP1:) 11 punch is user defined punch #2 (UP2:) LIST field (bits 6,7) 00 list device is teletype (TTY:) 01 list device is CRT device (CRT:) 10 list device is lineprinter device (LPT:) 11 list device is user defined list device (UL1:) Two of the serial ports on the VT180 can be used for serial communication, the READER/PUNCH port, and the UC1 (user defined console) port. From the chart above, setting the two least significant bits of the IOBYTE to 01 will allow normal console I/O to the VT100 terminal. Setting the same two bits to 11 will allow the UC1: port to be the system console. Working with the READER/PUNCH port is a little different. This is because the status of the reader port cannot be obtained directly with reader system calls. If a call to get character from reader is done, the routine will hang there until a character is available. This will not allow the alternating status checking required. However, there is a way. The reader port can be made the console port (IOBYTE value xxxxxx10). Now the status of the reader can be obtained without waiting. The characters received from the keyboard are sent to the punch port with a system call to punch output. 2.5.3 Eight Bit Data The Digital Research manual for CP/M specifies that the hight order bit of a character obtained with the CONIN bios call will be zero. This is not the case with the VT180. All 8 bits are significant. This allows binary data to be transmitted and received by the VT180. Other systems may vary. 2.5.4 Function Descriptions 2.5.4.1 Function C_INIT The c_init function sets up the intial values for the communications library. This function MUST be executed at the beginning of any program that will use the comm library. It initializes the iobyte settings, and sets up the default values for all the possible ports. On entry, it sets all the ports to their default values. Since the parity and baud rate on the VT180 cannot be easily set, DEFAULT is all that is allowed for these settings. The default port is the comm port, which is the normal VT180 comm port. If an illegal port, baud rate, or parity is requested, the function returns FALSE. 2.5.4.2 Function C_SET_PORT Two ports are allowed for the VT180. Valid values for port are 1, 2, and 3, yielding default (COMM), COMM, and UC1, respectively. 2.5.4.3 Function C_SET_BAUD In this version of the library, baud rates cannot be set, and the function will return FALSE if any value other than 1 (default) is requested. 2.5.4.4 Function C_SET_PARITY In this version of the library, parity cannot be set, and the function will return FALSE if any value other than 1 (default) is requested. 2.5.4.5 Function C_GET_KBD_CHAR This function uses bios(1) to obtain keyboard status and bios(2) to obtain a character. 2.5.4.6 Function C_GET_COMM_CHAR This function uses bios(1) to obtain port status and bios(2) to obtain a character. 2.5.5 Procedures 2.5.5.1 Procedure C_PUT_SCR_CHAR This procedure uses bios(3) to send a character the screen. 2.5.5.2 Procedure C_PUT_COMM_CHAR This function checks whether the selected port is the reader or the UC1 port and uses bios(5) to write to the punch port or bios(3) to write to UC1.