FKEclock^TM

The program set is also going to be ported to Win32.

The delivery package includes the DOS device driver module, a device control interface program, and an alarm interface control program.

This program set is currently under development. Watch this site for release info.

Specifications

• FKE-clk- device interface
  
• Speaker device interface
  
• FKECLOCK.EXE control program interface:
  
• FKEALARM.EXE control program interface:
  

FKE-clk- device interface:

• WRITE escape sequences to the device after it has been opened to control the clock's display and operations, and settings (PROMPT notation):
  
  • $e[aa - alarm acknowledge (turns off alarm sound)
  • $e[ac# - alarm chime control, #=0 == off, #=1 == on (default)
  • $e[adt##-##-##;##:##:##{x} - set alarm with date and time, string must match current formats, {x}='a' or 'p' if needed
  • $e[ai# - INT 214 (0D6H) alarm signal ctrl, #=0 == off (default), #=1 == on
  • $e[as# - alarm sound, 0=5 chirps (default), 1=alternating tones, 2=intersecting tones
  • $e[at##:##:##{x} - set alarm with time only, as above
  • $e[cd#;## - date color (default = YELLOW)
  • $e[ct#;## - time color (default = RED)
  • $e[cw#;## - day of week color (default = GREEN)
  • $e[fd# - date format, 0=MMDDYY (default), 1=DDMMYY, 2=YYMMDD, (#+4)=4-digit year
  • $e[ft## - time format, ## = 12 (default) or 24
  • $e[init=####:####{,CGA} - initialize clock, link to DOS InDOS flag, select CGA "no-snow" special screen write mode if ",CGA" specified. InDOS flag address is passed as ASCII hex characters seg:ofs value.
  • $e[p##;## - display position (row,column), HOME (top left corner)=0;0. no ##'s sets home, one ## sets row, column to 0. (default = 0,56)
  • $e[mc## - maximum screen column (1-n range) (default = 80)
  • $e[mr## - maximum screen row (1-n range) (default = 25)
  • $e[ra - request alarm time, next read returns alarm time. Aborts any other read operations in progress or pending.
  • $e[rf - request the full current time string, even if part or all of the display has been deactivated. Aborts any other read operations in progress or pending.
  • $e[rr - request revision level, next read returns device ID string. Aborts any other read operations in progress or pending.
  • $e[rs - request status, next 12 reads return status code strings. Aborts any other read operations in progress or pending.
  • $e[s# - seconds control, #=0 == off, #=1 == on (default)
  • $e[v# - visible display control, range for # is 0 - 7
    • #=0 == off (default)
    • #=1 == time display on
    • #=2 == date display on
    • #=4 == day-of-week display on
    • Add values to enable multiple displays (i.e., 7 == all on).
  • $e[w# - Winchester chimes control, #=0 == off, #=1 == on (default)
• READ returns strings terminated with a ^Z and a NULL byte.
  • Normal reads return the current date and time, formatted like "Sun 11-22-93 3:30:35 am". The device does not need to be opened to read the current date and time.
  • Alarm time can be read by writing an alarm time request, followed by a clock read. The FKE-clk- device must have been opened first, and the alarm time request must come within 10 seconds of the command sequence. The alarm time will be supplied only once per request, and normal read operations resume after the alarm time has been read, if the time-out expires, or if the device is closed before the alarm time is read. Alarm time strings are formatted the same as normal date/time strings, except without the day-of-week prefix. If the alarm was set with a time only, only the time will be in the returned string. If no alarm is pending when an alarm time request is received, the string will only contain the ^Z character before the NULL terminator byte. Alarm time requests abort any other read operations in progress or pending.
  • Status reads are initiated by sending a "Request Status" escape string to the device driver. The FKE-clk- device must be opened first, and the status reads must come within 20 seconds of the command sequence. Normal read operations resume after the status has been read, if the time-out expires, or if the device is closed before all of the strings are read. Following the request command string, the next 12 reads of the FKE-clk- device will return the following strings, one per read, with values as defined for writing to the corresponding control:
    • $e[ac# - alarm chime control state
    • $e[ai# - INT 214 (0D6H) alarm signal control state
    • $e[as# - alarm sound type selected
    • $e[cd#;## - date color
    • $e[ct#;## - time color
    • $e[cw#;## - day of week color
    • $e[fd# - date format selected
    • $e[ft## - time format selected
    • $e[p##;## - display position (row,column)
    • $e[s# - seconds control state
    • $e[v# - visible display control state
    • $e[w# - Winchester chimes control state
  • Individual status strings are separated by carriage returns (no ^Z) and terminated with a NULL byte. Only the last string returned is terminated with the normal ^Z+NULL sequence. Status requests abort any other read operations in progress or pending.
• Escape sequences written to the FKE-clk- device can be terminated with carriage returns, ^Z characters, a NULL byte, or a combination of the three. Multiple escape sequences can be transmitted in one string. Each escape sequence is processed before any following ones are read, so that multiple settings within one string will override each other: Only the last setting will remain in effect. Unrecognized strings are ignored, and improperly terminated strings can lead to unpredictable behavior. Strings can be up to 255 characters in length (including terminating characters). Excess input is ignored.
• The FKE-clk- display is only active in DOS text modes. It is automatically disabled when the display adapter changes to a graphic display mode.
• Only one alarm is supported. If a program wants to set an alarm, it should first check to see if one is pending, saving the pending date & time if an existing request is outstanding before setting its own. Once the program's alarm has rung, it should restore the previous alarm.
• If a program requests an INT 214 alarm signal, it _must_ either reset the alarm before terminating, or remain in memory until the alarm has been received: FKE-clk- has no way of knowing whether the alarm handler address is still valid when the alarm time comes, and must assume it is if a request is pending. Failure to adhere to this interface _WILL_ cause problematic (and quite possibly catastrophic) system behavior.

Spkr device interface:

• WRITE frequency,duration pair(s), separated by semicolons. Terminate the output with a carriage return, ^Z, or NULL byte. Up to 255 freq./dur. pairs are stored in a circular buffer. Excess tone requests received when the buffer is full are discarded.
• READ the device ID string, including revision level and number of notes pending. The returned string is terminated with a ^Z and a NULL byte.
• Four levels of sound priority are available through the Spkr driver: Continuous alarms have the lowest priority, and the Winchester chimes are next. Programmatic sound output generally supercedes clock sound requests, except that chirp alarms are at the top of the sound output priority chain.
• Durations of 0 are considered 65,536.
• Spkr: functions like SPK: in all other respects.

FKECLOCK.EXE control program interface:

• operation controlled by command line parameters. If no parameters are specified on the command line, the current time/date is written to stdout.
• supported controls:
  • /alarm=off - silences the alarm currently sounding
  • /chime=[on|off] - turns the clock chimes on or off
  • /display=[on|off] - turns the on-screen clock display on or off
  • /file=filespec - specifies a command file to be processed. Command file entries are the same as escape sequences written to the device, minus the leading ESC-bracket sequence. Data returned by the device in response to requests will be written to stdout when a request command is encountered in the command file. Suggested file format is one command per line. However, commands can be strung together as long as the line length is less than 127 characters. Subsequent commands on an input line MUST include the ESC-bracket sequence to be recognized by the clock device, since they are not interpreted by FKEclock^TM itself. Requests must be at the start of a line to be found and handled properly. The entire string containing a request will be sent to the device before any data is read from it.
• /help - writes a brief help display to the screen
• /init - required in AUTOEXEC.BAT to initialize the timer interrupt
• /return - writes the date/time and a newline to stdout
• /status - returns the FKE-clk- revision level string, and the status as reported by the $e[rs command
• /version - displays the FKECLOCK.EXE version string

FKEALARM.EXE control program interface:

• interactive program for setting multiple alarms for the FKE-clk- device driver. also provides an interactive interface for controlling the device driver.

Return to the top of the page

L5 Software Development