KANSAS CITY TRACKER/TUNER Driver Service-Call Functions Version Dated 6/21/88 ******************************************************************************* * * * This document is in the public domain and may be freely distributed * * and copied. This document should be copied or distributed intact. * * * * Brooks Van Pelt KB2CST 41 Acadia Drive * * (609) 751-1018 Voorhees, NJ 08043 * * * ******************************************************************************* NOTES: 1) The driver service routines are invoked by performing an INT nn. Parameters are expected to be passed to the driver in registers. The default interrupt is INT 63H. While 63h is the recommended interrupt, this parameter is set at installation and can be varied. 2) DOS normally fills unused user-interrupt-vectors with 0000:0000, which is not a usable processing address. Application programs that attempt to invoke the rotor driver when the rotor driver is not installed will cause the system to immediately crash. Application programs should test for the presence of the driver before trying to call a driver interrupt service. The presence of the driver can be established by using the driver's software interrupt vector number to obtain through DOS the driver's software interrupt processing address, adding 10 (0AH) to the displacement, and comparing the data at this address to this eight-byte field: "RotorDRV". The compare should be case sensitive. If this data is found the driver is present. 3) Time/Target table entries that have expired (the date & time of the entry has passed) are deleted when they arrive at the top of the Time/Traget table. 4) The service interrupt to be used to access the driver services can be determined from an application program by searching memory from 40:0 to the application's load point for the this 23-byte string (excluding the double quotes): "RotorDRV - SVC Vector Z". The string will be located at displacement 0103H from the base segment address of the driver. The byte after the last byte of the string will contain the interrupt vector number (00h to FFh). This method is not recommended as using this method precludes having more than one copy of the driver installed and active at a time. ^L ************************************************************************** Function: Read driver status & binary rotor positions At Entry: AH=0 At Exit: AL contains the status bits. The bits are set as follows... 80 - =0 if the PC-card is responding to I/O poll correctly =1 if the PC-card is absent or not reponding correctly 40 - =0 if the controller is enabled =1 if the controller is disabled 20 - =1 if the ELEV rotor is stalled & has been disabled 10 - =1 if the AZIM rotor is stalled & has been disabled 08 - =1 if the ELEV rotor is being moved or needs moving 04 - =0 if ELEV rotor is being moved to decrease degree setting =1 if ELEV rotor is being moved to increase degree setting 02 - =1 if the AZIM rotor is being moved or needs moving 01 - =0 if AZIM rotor is being moved to decrease degree setting =1 if AZIM rotor is being moved to increase degree setting BH contains 0 if this is a azimuth-only installation, and 01h if this is an azimuth-and-elevation installation. BL contains the signed local-time offset (UTC + local-time-offset = local time) CH contains the current binary ELEV rotor position (0-255) CL contains the current binary AZIM rotor position (0-255) ************************************************************************** Function: Read current slew setting At Entry: AH=1 At Exit: CH contains the ELEV slew binary value (-25 to +25 degrees) CL contains the AZIM slew binary value (-25 to +25 degrees) ************************************************************************** Function: Write new slew setting At Entry: AH=2 CH contains the ELEV slew binary value (-25 to +25 degrees) CL contains the AZIM slew binary value (-25 to +25 degrees) Note: If either value is invalid the entire command will be ignored. At Exit: No parameters are returned ************************************************************************** Function: Read current position and target position At Entry: AH=3 At Exit: AX - current ELEV value in degrees (-90 to 269, signed binary) BX - current AZIM value in degrees (0-359, signed binary) CX - target ELEV value in degrees (-90 to 269, signed binary) DX - target AZIM value in degrees (0-359, signed binary) ^L ************************************************************************** Function: Set Target position At Entry: AH=4 CX - target ELEV value in degrees (-90 to 269, signed binary) DX - target AZIM value in degrees (0-359, binary) Note: If either value is invalid the entire command will be ignored. At Exit: No parameters are returned ************************************************************************** Function: Clear Time/Target table At Entry: AH=5 At Exit: No parameters are returned ************************************************************************** Function: Get Time/Target table data At Entry: AH=6 CX contains the maximum number of table records to be returned DX contains the relative table-record number of the first table entry to be returned. The first entry of the table has a relative table-record number of zero. If the relative table- record number is out of range the returned-entry count in CX will be zero. ES:[BX] contains the address of where the data should be placed. At Exit: AL contains the driver's current table mode... 00=normal 01=repetitive-table-processing mode. CX contains the number of table entries returned. DX if the driver is in BBSROTOR mode, DX contains the relative table entry# of the Time/Target table currently in force. ^L - - - - - - - - - - - - - - - - - - - - - - - - - - Normal Table Entry Format For Time/Target Read And Write: +0: Word : Year (the full year, eg, 1987) in binary +2: Byte : Month in binary (1 to 12) +3: Byte : Day of month in binary (1 to 31) +4: Byte : Time hour in binary (0 to 23) (UTC) : This byte can be OR'd with 80H to indicate it is the : first entry of a satellite pass. This is optional. +5: Byte : Time minute in binary (0 to 59) (UTC) : This byte can be OR'd with 80H to indicate it is the : last entry of a satellite pass. This is optional. +6: Byte : Time second in binary (0 to 59) (UTC) +7: Word : Target ELEV in signed binary (-90 to 269) +9: Word : Target AZIM in binary (0 to 359) +11:BYTEs: 8-byte ASCII satellite identifier. This field MUST be present and accurate in every table entry for a pass. +19:L-INT: This field contains the doppler-shifted beacon frequency of the satellite in hertz. It is a 32-bit integer whose most significant byte is in the right- most byte and whose least significant byte is in the left-most byte. Table-entry length = 23 bytes - - - - - - - - - - - - - - - - - - - - - - - - - - Repetitive-table-processing mode Table Entry Format For Time/Target Read And Write: +0: Word : FFFFh +2: Word : Starting minute within cycle period (relative to 0) +4: Word : Azimuth for this segment (0-359) +6: Byte : Ten-byte ASCII segment description +16: Byte : 7-byte unused field Table-entry length = 23 bytes ^L ************************************************************************** Function: Add Time/Target table entry At Entry: AH=7 ES:[BX] points to the Time\Target table image to be added to the table. This image is copied during the SVC-call processing and does not need to be maintained after control is returned to the calling program. The formats of the table-entry images are described above in the "GET TIME/TARGET TABLE DATA" section. The driver should be disabled when adding BBSROTOR-mode table entries. At Exit: AL - =0 if the add went ok =1 if a parameter was invalid =2 if the table was full & the entry could not be added ************************************************************************** Function: Read driver's computed date and time At Entry: AH=8 At Exit: AX contains the years value in binary (1987 = 07C3h) BH contains the month in binary (1 to 12) BL contains the day of month in binary (1 to 31) CH contains the hours value in binary (UTC) CL contains the minutes value in binary (UTC) DH contains the seconds value in binary (UTC) DL contains the quarter-secs value in binary (roughly 9/8 fast) ^L ************************************************************************** Function: Disable/Enable driver movements. The disable function forcibly stops rotor movements and sets the rotor status as disabled. The enable function reverses this effect. At Entry: AH=9 AL=0 for disable, =1 for enable At Exit: No parameters are returned. ^L ************************************************************************** Function: Notify driver of pop-up installation. This command is used by the TSRs (eg, OSC.COM) during their installation to ensure that the TSR is only installed once. THIS FUNCTION SHOULD NOT BE USED BY APPLICATION PROGRAMS AS IT COULD INTERFERE WITH THE CORRECT INSTALLATION OF THE TSRs. At Entry: AH=0Ah BX contains the bit-mask value assigned to this program (eg., OSC.COM uses 0001h) At Exit: AX contains zero if the calling program has not been loaded yet, and 0001h if the program has already been loaded. BX contains the driver's version#. ************************************************************************** Function: Set ASCII satellite identifier. This command can be used by application programs to set the satellite identifier displayed by the OSC status pop-up. This function is entirely optional. This function is not needed when tabling satellite position entries, as the table structure has a satellite-id field. At Entry: AH=0BH ES:BX - points to the 8-byte satellite-ID text string. At Exit: No parameters are returned. ************************************************************************** Function: This function places the driver into either normal mode or repetitive-table-processing mode. It also acts to clear the driver's time/target table, because the table formats for the various modes are incompatible. At Entry: AH=0CH AL=00h - place driver in normal mode. 01h - place the driver into repetitive-table-processing mode. BX - Contains the cycle period in minutes when entering repetitive-table-processing mode. Must be less than or equal to 10,080 (decimal). At Exit: No parameters are returned. ************************************************************************** Function: This function returns the number of time-target table entries defined within the driver. At Entry: AH=0DH At Exit: AX contains the number of table entries defined within the driver ^L ************************************************************************** Function: This function returns the driver's current table-processing mode, a pointer to the target ID if mode 1, and the current and period values if mode 2. At Entry: AH=0EH At Exit: AL contains the driver's table mode (0=normal, 1=repeat) * Mode 1 * ES:BX - points to the 8-byte ASCII text of the current satellite ID per the text supplied in the last "First of Pass" record. * Mode 2 * BX contains the cycle period in minutes (1-10080) CX contains the current minute# within the cycle. ************************************************************************** Function: This function enables or disables the driver's processing of the Time/Target table during clock interrupts. The function has been implemented to allow the status pop-up's "spool tbl to disk" function to work with an unchanging table. At Entry: AH=0FH AL=0 means the table-processing function should be disabled. =1 means the table-processing function should be enabled. At Exit: AL =0 if the table function was disabled before this call. =1 if the table function was enabled before this call. ************************************************************************** Function: This function passes a text string to the audible morse-code sender imbedded in the rotor driver. The text string must consist of ascii characters with a null (00h) terminator. Unrecognised characters will be replaced with a space. Multiple spaces will be replaced with a single space. A 0FFh byte will generate the rising warble used for AOS notification. A 0FEh byte will generate the dropping warble used for LOS notification. At Entry: AH=10H ES:SI - points to the ASCIIZ string. At Exit: No parameters are returned. ************************************************************************** Function: This function controls the morse-annunicator enablement. It can also provide the current enablement status. GET STATUS SubFunction Entry: AH=11h, AL=0FFH Exit: AL=current enablement status (0=dsbl otherwise enbl'd) DISABLE MORSE SubFunction (also clears any text queued for sending) Entry: AH=11h, AL=00H Exit: AL=prior enablement status (0=dsbl otherwise enbl'd) ENABLE MORSE WITH OPTIONS SubFunction Entry: AH=11h, AL=00H to 0FEH Exit: AL=prior enablement status (0=dsbl otherwise enbl'd) ^L ************************************************************************** Function: This function forces the driver to enable to morse-annunciator and send the status of the driver in CW. The annunciator enablement is ignored for this function. At Entry: AH=12H ES:SI - points to a 22-byte work area used by the driver as a work area. At Exit: No parameters are returned. ************************************************************************** Function: This function forces the driver to delete from the Time/Target table the remainder of the satellite pass. If the first entry in the table is a start-of-pass record the entire pass is deleted. At Entry: AH=13H At Exit: No parameters are returned. ************************************************************************** Function: This function controls the rotor-parking enablement. It can also provide the current parking enablement parameters. GET PARAMETERS SubFunction Entry: AH=14h, AL=00H Exit: BX=Parking delay time in minutes; (0 to 60; 0 means disable parking function) CX=Park-position azimuth (0-359) DX=Park-position elevation (0-90) SET PARAMETERS SubFunction Entry: AH=14h, AL=01H BX=Parking delay time in minutes; (0 to 60; 0 means disable parking function) CX=Park-position azimuth (0-359) DX=Park-position elevation (0-90) Exit: No parameters are returned; Use GET PARAMETERS subfunction to verify operation of this function. The park timer function will stopped if it was active when this function was invoked. STOP PARKING TIMER SubFunction Entry: AH=14h, AL=02H Exit: No parameters are returned. START PARKING TIMER SubFunction Entry: AH=14h, AL=03H Exit: No parameters are returned. **************************************************************************