Preliminary documentation of BYERSX operations. C.B. Falconer, 85/12/15 See changes to calls 84, 85 replaced by 92 and 93. BYERSX provides the fundamental communication primitives, and allows imple- mentation of all communication programs without customization. When BYERSX is installed the functions of MDM, MODEM, MEX, IMP, XMODEM, KMD, and other communication programs may be implemented. (In general KMD and/or XMODEM versions suffice for all file transfers). Any BBS system may run under this and can control the entire system. The chain facility provides the linkage from program to program. Any BYE replacement can perform all the operations needed to answer calls and evaluate the caller without any special instal- lation. BDOS calls allow control of various parameters, including whether or not carrier checks should be made (thus permitting hard-wired connection to other systems), echo (for half-duplex and/or terminal operation), exact drives available (for systems with "holes" in the drive map), and more. I expect that apart from XMODEM most users will only need a separate MODEM style program to perform Ascii captures, and possible hard-logging of term- inal sessions. Another reason might be to filter and/or translate screen control sequences, thus emulating various terminals. This is an edited version of Paul Trainas BYE338 appendix, since BYERSX attempts to support exactly the same BDOS calls (as a subset of the BYERSX calls), with one exception and several caveats. This is intended to preserve upward compatibility with most programs executing under BYE338. In addition all BYERSX functions meet the CPM standards, and return the identical values in the ba and hl registers. Thus all the functions documented below return slightly different registers under BYERSX, and in particular the GRTCBUFF call does NOT return TON in the A register. Functions shown below as returning byte values in A return the same value in L, with B and H set to zero. All functions return a value, and most of the "set" functions echo back the resultant value. TERMINAL provides a simple terminal at the local system, connected to the remote. It is entered whenever conoff flag is set, and dcsta is called. A ^E at the local keyboard exits this mode. The settings of echon, echol, remon, carck, bits of systatus, also lfeeds and nulls flags, affect the operation. This feature makes the system immediately testable. Terminal mode is entered by typing CTRL-^ followed by U (for union), or by executing a BDOS call 87 (57h) with an argument 12 (0ch). Other values of the argu- ment can provide various echoing configurations, for half-duplex operation. CTRL-^ followed by Q enters SYSOP MESSAGE variant when the remote system is connected. Exit via ^E. This mode is only available when BYERSX is active. Here is a list of "BDOS functions" that BYERSX supports. Command numbers are passed in register C, and entry data is passed in register DE. Exit data is returned in HL or A depending upon the function. Most BYERSX functions also return meaningful flags (using the Z/NZ flag), but this is not guaranteed. 32 *BYE EXISTANCE TEST* for BYE338 compatibility. See call 87 This is also the CP/M set/get user area command. Use 87 for BYERSX 20h This will test if BYE is there, IF and ONLY IF register E = 241 (decimal). Entry: E = 0-31 set user area (CP/M std) E = 255 get user area (CP/M std) E = 241 test if BYE exists. Exit: if E=241 & BYE exists 77 (decimal) if E=241 & no BYE something else (unknown) if E<>241 see CP/M manual 61 Get raw modem input status (modem only) Entry: nil 3dh Exit: if not ready: 0 & zero flag set if ready: 255 & zero flag cleared 62 Get raw modem output status (modem only) Entry: nil 3eh Exit: if not ready: 0 & zero flag set if ready: 255 & zero flag cleared 63 Send 8 bit character to modem (no waiting) Check modem output status first, or you may overrun the modem. 3fh Entry: E= 8 bit character Exit: input character echoes 64 Get 8 bit character from modem (no waiting) Check modem input status first, or you may input garbage. 40h Entry: nil Exit: A= 8 bit character 65 Get carrier status Entry: nil 41h Exit: if carrier present: 255 & zero flag cleared if no carrier: 0 & zero flag set 66 Get local console input status Entry: nil 42h Exit: if not ready: 0 & zero flag set if ready: 255 & zero flag cleared 67 Get character from local console (BYE338 restricts to 7 bits) (wait until key struck) 43h Entry: nil Exit: A= character 68 Send character to local console (BYE338 restricts to 7 bits) (wait until console ready) 44h Entry: E= character to send Exit: send char echoes 69 Set/Get maximum drive allowed on system Entry: E= drive (0=A:, 1=B:, etc) 45h if E=255 then return current setting Exit: current maximum drive 70 Set/Get maximum user area allowed on system Entry: E= user area (0=0, 1=1, etc) 46h if E=255 then return current setting Exit: current maximum user area 71 Set/Get timeout # of minutes Entry: E= number of minutes (between 0 and 254) 47h if E=255 then return current setting Exit: current setting 72 Set/Get number of nulls (after line feed to external terminal) 48h Entry: E= nulls (between 0 and 9 only! (or 255)) if E=255 then return current setting Exit: current number of nulls 73 Set/Get upper-case only flag (to external terminal) Entry: for upper case only: E <> 0 49h for upper/lower case: E=0 to read current setting: E=255 Exit: current setting, 0 or 0ffh 74 Set/Get line feed-masking for external terminal (different than BYE338) 4ah Entry: no lf appended to cr: E=0 to append lf to cr: E=1 to read current setting: E=255 Exit: current setting 75 Set/Get RBBS WRTLOC flag Entry: if normal operation: E=0 4bh if nohangup active: E=1 if read current setting: E=255 Exit: current setting 76 Set/Get hardlog active flag (will do nothing if HARDLOG=NO. Not now implemented) 4ch Entry: if disable hardlog: E=0 if enable hardlog: E=1 if read current setting: E=255 Exit: current setting 77 Set/Get modem block-out flag Entry: if modem I/O ok: E=0 4dh if modem squelched: E=1 if read current setting: E=255 Exit: current setting 78 Set/Get console bell enable Entry: if quiet console: E=0 4eh if bell-ringing ok: E=1 if read current setting: E=255 Exit: current setting 79 Return address of RTC buffer. Avoid, PREFER calls 89 and 90. Entry: nil 4fh Exit: HL = address of RTC buffer A = time on system (NOT for BYERSX) Format: byte hours BCD read only byte minutes BCD read only byte seconds BCD read only byte century BCD read only byte year BCD read only byte month BCD read only byte day BCD read only byte time online binary read only byte binary reserved byte current hour binary read only byte current minute binary read only byte login hour binary read/write byte login minute binary read/write Note: If you don't have the clock reader installed, the first byte of the buffer will be 099 HEX. This way application programs can sense NO clock. 80 Return address of LASTCALR buffer (for whokey) Entry: nil 50h Exit: HL = address of buffer The buffer has room for 78 ascii characters, which will be displayed on warmboot (if desired). Application programs could look into this buffer for information, however, some systems may not support the buffer because BYE is so LARGE. On BYERSX an option exists, where the first byte in the buf- fer specifies the available size of the buffer. This is con- figured at assembly time. Note: If the first byte of the LASTCALR buffer is a space, the buffer has not been programed the BBS or by BYE. If the first byte of the LASTCALR buffer is a null, then the buffer should not be read from or written to, as it doesn't exist. BYERSX may vary, see above. 81 Set maximum time allowed on system (if RTC is present) Entry: E= number of minutes allowed (1..255) 51h if E=255 then return current setting if E=0 then unlimited time allowed on system Exit: current maximum time on system 82 Set initial login time. (future 0ffffh will get login time) Entry: D = hours (0..23) 52h E = minutes (0..59) Exit: entry value 83 Print "Time on system nn minutes." message. Entry: nil 53h Exit: nil (Null procedure on BYERSX at present) The following additional operations are available in BYERSX. Calls 84 and 85 following have been redefined as 92 and 93, due to conflicts with BYE5. All new software should use 92 and 93. 84 Set/get status byte Entry: if E=0..254 then set status 54h Exit: current system status byte (* System state bit fields, via sgstate *) whlbit = 128; (* special priv, implies next two *) dunochk = 64; (* no access restrictions *) devices = 32; (* non-sharable device access, eg LST *) carcks = 16; (* check for carrier on *) conoff = 8; (* remote console disabled *) remon = 4; (* remote char. i/o enabled *) echol = 2; (* local console echoes *) echon = 1; (* remote console echoes *) NOTE : IF ((state XOR 04h) AND 084h) <> 0 THEN wheel status is on. This allows privileged operations whenever the remote is off. 85 Pause DE milliseconds. If DE=0 then return immediately. This 55h allows programs to be written independant of CPU clock speed. 86 Set/get baud rate, stop bits, parity. The input parameter in E is made up of three fields 56h Most Significant bit 8, 7 stop bits 0 Do nothing 1 Set 1 stop bit 2 Set 1.5 stop bits 3 Set 2 stop bits 6,5 parity 0 Do nothing 1 No parity 2 Odd parity 3 Even parity 4,3,2,1 baud 0 Do nothing 1 Set 110 baud 2 Set 300 baud 3 Set 450 baud 4 Set 600 baud 5 Set 710 baud 6 Set 1200 baud 7 Set 2400 baud 8 Set 4800 baud 9 Set 9600 baud 10 Set 19200 baud 11 to 14 Installation specific 15 Do not use. Exit: The present setting is returned, but any fields that could not be set are zeroes. At present the Stop and parity fields are not implemented, and always return zeroes. Thus the output will be the echo of the input unless that baud rate is unavailable, when the output value will be zero. 87 The master control operation. Entry: DE = (see table below) 57h Exit: 0 if BYERSX not available, else see table below 88 Set/get drive vector Entry DE (non-zero) is a bit vector of permissable drives. The 58h LSB is representative of the A drive, and the MSB of the P drive. The bit representing the configured value for "homdrv" is forced on, and the value stored. The stored value is always returned. Thus a zero argument is purely an enquiry. 89 Set/get date Entry DE = 0ffffh to enquire for date 59h DE = other to set date The date is kept in the following format (note 0ffffh is invalid) MSbit yyyyyyy mmmm ddddd LSbit with y field (0..127) the offset from 1980 (dates to 2107) m field (1..12) the numerical month (Jan to Dec) d field (1..31) the day of month (Identical to MSDOS format) 90 Set/get time of day Entry DE = 0ffffh to enquire for time of day 5ah DE = other to set time of day The time is kept in the following format (note 0ffffh is invalid) MSbit hhhhh mmmmmm sssss LS bit with h field (0..23) hour of day (0 is midnight) m field (0..59) minute of hour s field (0..29) seconds DIV 2 (resolution 2 seconds) (Identical to MSDOS format) 91 Set write protect vector Entry DE = bit vector of drives to be write protected 5bh (see call 88 for bit format) Exit: Current write protect vector (input echo) ---- CHANGE ---- The following pair were implemented as calls 84 and 85, but have been redefined as 92 and 93 to avoid BYE5 conflicts. Future BYERSX versions will use these values 92 Set/get status byte (see table below) Entry: if E=0..254 then set status 5ch Exit: current system status byte (* System state bit fields, via sgstate *) whlbit = 128; (* special priv, implies next two *) dunochk = 64; (* no access restrictions *) devices = 32; (* non-sharable device access, eg LST *) carcks = 16; (* check for carrier on *) conoff = 8; (* remote console disabled *) remon = 4; (* remote char. i/o enabled *) echol = 2; (* local console echoes *) echon = 1; (* remote console echoes *) NOTE : IF ((state XOR 04h) AND 084h) <> 0 THEN wheel status is on. This allows privileged operations whenever the remote is off. 93 Pause DE milliseconds. If DE=0 then return immediately. This 5dh allows programs to be written independant of CPU clock speed. Enumeration of 4 lo bit configurations for SYSTATE. ** for pointless values hx dec 0 0 Normal console. BYERSX does not exist (almost) 1 ** Useless. All remote input is echoed 2 ** Useless. Double chars. All local keys echoed to screen 3 ** Useless. Combination of 1 & 2. 4 4 Remote console 5 ** Useless. Double chars from remote console 6 ** Useless. Double chars from local keyboard 7 ** Useless. Combination of 5 and 6 8 ** Useless. Local keys discarded, no remote input 9 ** Useless. Local key discarded, no remote input a 10 Local keys to screen only b 11 Same as 10. Remote disabled The following are TERMINAL modes c 12 Local to remote, remote keys to local screen d 13 Local keys to remote, remote keys echo to remote and local e 14 Local keys to remote, echo on screen. Remote to screen f 15 Local keys to remote & screen, Remote to screen & remote Echo implies that cr is expanded into cr/lf Any remote lf emitted may be padded by nulls. Separate value Any remote output may be upshifted (incl. graphics). Separate flag. set/get modem baud rate, stops, parity (only baud for now) fields hold zeros for no change. 0 returns current value fields: MSB stops(2), parity (2), baud (4) LSB stops: 0..3 = no change, 1, 1.5, 2 stop bits parity: 0..3 = no change, no, odd, even baud: 0..10 = no change, 110, 300, 450, 600, 710, 1200, 2400, 4800, 9600, 19200 baud. 11..15 special returns 0 for no capability, else echo setting. ----------------------------------------------- Auxiliary calls via BYERSX function #87 Where values are returned they appear in the A and HL registers. (de) value dec. hex killrsx, remove system -1 0ffffh is RSX executing? 0 0000 ; ; The remainder ignore the value in the D register get version number of running system 1 1 get cpu clock rate in 100kHz units. 2 2 get state of security flag 3 3 set security off 4 4 set security on (any reboot disconnects) 5 5 get state of noise suppression flag 6 6 reset noise suppression (no chars absorbed) 7 7 set noise suppression ("{" absorbed) 8 8 screen dump to printer (only if f0k setup) 9 9 get default drive for ENDCALL on line drop 10 a get default user " " " " " 11 b get home drive (set on access violations) 12 c get home user " " " " 13 d Following not enforced. For auxiliary use get receive drive for file transfers 14 e get receive user " " " 15 f get private receive drive, file transfers 16 10 get private receive user, " " 17 11 get private send drive, file transfers 18 12 get private send user, " " 19 13 get current write protect vector (see 91) 20 14 Table of modem primitives available via RSX call #87 (057 hex) This table is extendable for other cases Note that mdquit and mdstop are usually identical, but will differ for interrupt driven systems, where mdquit disarms the interrupt system (so that the whole system can be removed), and mdstop only breaks the con- nection. Used for operations not already available initialize 64 40 de-init and hang-up (mdquit) 65 41 hang-up (mdstop) 66 42 re-enable after hang-up 67 43 emit a break 68 44 Go off hook, answer 69 45 Is phone ringing? 70 46 Stop disk drive motors 71 47 Start disk drive motors 72 48 Clear local screen 73 49 Add 1 min. to timer (systems with no RTC) 74 4a