home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / znode3 / z3shell / tex13.lbr / TEX.DZC / TEX.DOC
Encoding:
Text File  |  1993-06-08  |  8.8 KB  |  190 lines
  1.                         TEX Documentation
  2.                        ------------------- 
  3.  
  4.    The  major use of real-time clocks until now,  in  ZCPR3-based 
  5. computers  at  least,  has been time and date stamping of  files. 
  6. There have been several approaches to this, including DateStamper 
  7. and Z80DOS.  One possibility that seems to have been neglected is 
  8. time-scheduling of programs and real-time control. 
  9.  
  10.    TEX represents my solution to this problem. It allows entry of 
  11. entire command lines with associated absolute execution times and 
  12. optional  repeat intervals.  The maximum number of command  lines 
  13. allowable  is  at present 20,  but this can be  changed  with  an 
  14. equate   in  the  source  code,   supplied  with   this   library 
  15. (naturally!). TEX operates as a ZCPR3 shell, whose function is to 
  16. determine when a command line should be executed and to put it in 
  17. ZCPR3's Multiple Command Line Buffer when it is due.  This allows 
  18. the  programmer  to concentrate on writing application  programs, 
  19. and allow the operator to schedule them as required. 
  20.  
  21.    The only requirements for TEX are a Z80-based computer running 
  22. ZCPR3 or ZCPR33, and equipped with a real-time clock. The TEX.COM 
  23. file  included with this library is designed for use with  Z80DOS 
  24. and  other compatible BDOS replacements which contain a  function 
  25. to retrieve system time using BDOS function 105.  If your  system 
  26. differs  from  this,  you  can still run TEX  by  re-writing  the 
  27. GETTIME  function  in TEX.MAC.  Instructions are included  within 
  28. this routine,  and should present little difficulty. TEX will run 
  29. even  faster if you have a RAM disk or hard disk,  but these  are 
  30. not necessary. 
  31.  
  32.    Since  TEX  is  a shell,  you should note  that  it  can  only 
  33. schedule  and run programs when it is itself  running:  that  is, 
  34. when all other programs have terminated. You can use the computer 
  35. normally  while  TEX is running,  with a short delay  after  each 
  36. program  is  run while TEX reloads itself and loads its  variable 
  37. file,  but programs scheduled for execution while other  programs 
  38. are  running will not be executed until TEX is entered after  the 
  39. first program terminates. TEX is not a multi-tasking system.
  40.  
  41.    When  TEX executes a program,  all current commands and  their 
  42. time  information are saved in a disk file  called  TEX.VAR.  The 
  43. distribution   version  of  TEX  saves  this  file  in  the  root 
  44. directory,  but either a re-assembly,  or your favourite patcher, 
  45. will allow any other drive/user area combination to be used. 
  46.  
  47.    Uses for TEX are up to you. Unless you have a RAM disk or hard 
  48. disk to carry TEX.COM and its variable file,  it usually takes  a 
  49. few  seconds  after  a program terminates until  the  TEX  prompt 
  50. appears. This may or may not be acceptable when you are trying to 
  51. use  the computer,  but it usually doesn't matter if you  aren't. 
  52. For  example,  you  can make what is probably one of the  world's 
  53. biggest alarm clock programs using TEX and SAK alone: 
  54.  
  55. !X 06:30 !R /1;SAK /B WAKE UP! 
  56.  
  57. schedules SAK to ring the console bell continuously every day  at 
  58. 6:30  am!   (See  below  for  meaning  of  TEX  commands).  Other 
  59. possibilities   include  control  of  appliances  such  as  video 
  60. recorders  when you're not home.  If you can write a  program  to 
  61. control it, TEX can schedule it! 
  62.  
  63.  
  64.                      TEX Command Line Format
  65.                      ----------------------- 
  66.  
  67.    The general format of a TEX command line is: 
  68.  
  69. TEX commands;required command line;other commands as normal
  70.  
  71.    Note  the  semicolon between the TEX commands and the  command 
  72. line.  This  is required to separate the two:  TEX will  flag  an 
  73. error if this is omitted. 
  74.  
  75.    There  are presently three TEX commands which can be  included 
  76. in the command line to specify execution details: 
  77.  
  78. !X [dd:mm:yy] hh:mm[:ss]
  79.           - Specifies  an absolute execution time.  The date  and 
  80.           seconds are optional,  as indicated by the brackets. If 
  81.           the date is not supplied, execution will proceed on the 
  82.           current day.  If no !X command is  supplied,  execution 
  83.           commences immediately. 
  84.  
  85. !R [/days] hh:mm[:ss]
  86.           - Specifies a time period for repeated execution of the 
  87.           command line.  Days and seconds are optional.  If no !R 
  88.           command  is  entered,  the program is run once  at  the 
  89.           specified time, then deleted from the execution list. 
  90.  
  91. !P number
  92.           - Specifies a priority for the command,  in the range 1 
  93.           to  254,  where  1 is the highest priority.  If  no  !P 
  94.           command is entered,  the default priority (99) is used. 
  95.           Priority  can  be  specified  to ensure  that  a  given 
  96.           program executes before another,  if they are scheduled 
  97.           at the same time. 
  98.  
  99.    The order of the three command types is unimportant. 
  100.  
  101. Examples:  See the SAK example above. Another is: 
  102.  
  103. !R /2 10:5:3 !X 15/3/88 12:04;SEND NEATPROG.WOW;SAK /BP10 SENT
  104. >> IT!;MAKE COFFEE 
  105.  
  106.    which would schedule the program SEND at 12:04 pm on March 15, 
  107. 1988 with the parameter NEATPROG.WOW,  then schedule SAK to  ring 
  108. the  console  for  10 seconds and type SENT IT!,  then  make  the 
  109. coffee (!).  Finally the whole sequence would be re-scheduled  to 
  110. occur  again  2 days,  10 hours,  5 minutes and 3 seconds  later. 
  111. (Never mind why you'd want to do all this!) 
  112.  
  113.  
  114.                            Running TEX
  115.                            ----------- 
  116.  
  117.    TEX is invoked with 
  118.  
  119. TEX [command file] /options 
  120.  
  121.    where  <command  file>  is an  optional  file  containing  TEX 
  122. commands as above (these can be prepared using a text editor, and 
  123. can be useful for often-used commands).  Default filetype is .TEX 
  124. if  none is specified.   The only option at present is /C,  which 
  125. deletes  any  current TEX.VAR file and thus starts  TEX  with  no 
  126. embedded commands. 
  127.  
  128.    After  loading,  TEX  will  install  itself  as  a  shell  (if 
  129. possible),  then read any specified input file.  It will then try 
  130. to  read a TEX.VAR file (unless disabled with the /C  option)  to 
  131. load any pending commands.  It will then display the user prompt, 
  132. which  is  similar  to the standard ZCPR3 prompt  (including  any 
  133. named directory information),  but preceded by the current  time, 
  134. e.g. [21:55] B0:WORK> 
  135.  
  136.    This time is updated once each minute, to demonstrate that TEX 
  137. hasn't fallen over. 
  138.  
  139.    At  this point normal commands and TEX commands can be  typed. 
  140. Note  that  even a simple directory change requires reloading  of 
  141. TEX after completion:  all commands (except control-C) are loaded 
  142. into  the  Multiple Command Line Buffer and control is passed  to 
  143. the  CCP.  There  are also some control  functions  performed  by 
  144. single keys, as follows: 
  145.  
  146. Control keys:
  147.    - Line-feed gives a short help display.
  148.    - ESCAPE  will  cause TEX to terminate (the  current  commands 
  149.      will be saved in the TEX.VAR file).
  150.    - Control-D gives a display of current commands.
  151.    - Control-E  will  allow commands to be deleted.  The user  is 
  152.      prompted  with  a  request for the  number  of  the  command 
  153.      (obtained  with the Control-D command),  the command line is 
  154.      displayed,  and  the user asked for confirmation before  the 
  155.      line is deleted. 
  156.  
  157.  
  158.                     Location of TEX.VAR File
  159.                     ------------------------
  160.  
  161.    As  noted  above,  the  temporary file TEX uses  to  save  the 
  162. current commands can either be placed in the ROOT:  directory  or 
  163. in  a  user-specified  directory.  The  distribution  version  of 
  164. TEX.COM places it in the ROOT: directory, but this can be changed 
  165. either  by  modifying the source code at the  rootfl:  and  nrdu: 
  166. labels  (comments in the source will assist),  or by using a file 
  167. patcher (or even DDT/SID, if you must). To assist this, there are 
  168. two  "signposts" just after the beginning of the code (at 0110h). 
  169. The  byte after the ROOT> signpost should be set to 0ffh  if  the 
  170. ROOT:  directory is required.  If not, this byte should be set to 
  171. zero,  and the bytes after the following signpost (DU:>) modified 
  172. to  the required drive and user area (drive first, (A = 0),  then 
  173. user area 0-15 (16-31 might work; who knows?)). If you have a RAM 
  174. disk or hard disk,  it's probably better to force the use of this 
  175. as TEX will load and save the TEX.VAR file more quickly.
  176.  
  177.  
  178.                           Final Remarks
  179.                           ------------- 
  180.  
  181.    I hope you will find TEX useful. Feel free to direct comments, 
  182. bug reports etc. to me at: 
  183.  
  184.    Z-Node 62
  185.    Perth, Western Australia
  186.    (061+) 09-450-0200 
  187.  
  188.                         - Ron Murray
  189.                           6 May, 1988
  190.