home *** CD-ROM | disk | FTP | other *** search
/ PSION CD 2 / PsionCDVol2.iso / Programs / 282 / PROGRAM.TXT < prev    next >
Text File  |  1998-02-22  |  8KB  |  225 lines
  1. Program.txt - Notes for programming external shell modules
  2. -----------
  3. This file contains information necessary for writing OPL modules
  4. that can be used by Shell5 as external commands.
  5.  
  6. Contents: How commands are executed
  7.           Command arguments
  8.           Wildcards
  9.           Shell5 variables
  10.           Shell5 procedures
  11.           Programming for 'pipes'
  12.           Detailed descriptions of some procedures
  13.  
  14. 1) How commands are executed
  15. ============================
  16.  
  17. When a command is typed the shell processes it as follows:
  18.  
  19. (a) The input is compared with the aliases and any substitutions
  20.    are made. A '%' as the first non-blank character prevents
  21.    aliases being expanded.
  22. (b) The arguments are parsed one at a time. If a wildcard is
  23.    found this is expanded. If no matches are found an error is
  24.    generated, otherwise all arguments are stored in memory. The
  25.    array argv&() points to successive arguments. The last
  26.    argument in this array is always 0. Comments and variable
  27.    substitutions are made.
  28. (c) Redirection of output is handled.
  29. (d) The first argument is matched against the following:-
  30.    (i) The shell builtins
  31.    (ii) Stored entries in the path
  32.    (iii) A valid .bat, .opo file in the path
  33.    (iv) A valid directory to 'cd' to
  34.  
  35. Modules are stored in the shell's path as their filename. ie.
  36. C:\OPO\MORE.OPO would be stored as 'more.opo' and can be
  37. accessed as either 'more' or 'more.opo'. When 'more' is typed at
  38. the prompt and found not to match any of the builtin functions or
  39. aliases, the path is searched and it's found here. The module
  40. C:\OPO\MORE.OPO is then LOADMed and a function more%:(x%)
  41. is called.
  42.  The module MUST contain a function of this specification - it
  43. must be called the same as the .opo file, return an integer and
  44. Take 1 integer argument. The return value of the procedure will
  45. give the variable $? its value.
  46.  
  47. e.g. To have a command 'newcom' recognized:
  48.  
  49. (a) Write an opl module with a procedure newcom%:(int%)
  50. (b) Compile this module to newcom.opo
  51. (c) Move newcom.opo into a directory in the path
  52. (d) If you want a manual page for your command (e.g. if you want
  53.    to distribute the module), creare a help file 'newcom.hlp'
  54.    (using the Series 5 database application), and put it in the
  55.    helppath directory.
  56.  
  57.  
  58. 2) Command arguments
  59. ====================
  60. The input string is parsed by the shell and split into separate
  61. arguments. These are stored on the heap and are referenced by
  62. the argv&(n%) array. For example
  63.  
  64. cp file1.txt file2.txt
  65.  
  66. Stores: argv&(1)="cp"
  67.         argv&(2)="file1.txt"
  68.         argv&(3)="file2.txt"
  69.         argv&(4)=0            <- marks the end of the list
  70.  
  71.  Your module is passed the number of arguments - in this case 3 -
  72. as it's only parameter.
  73.  All text within quotes is stored as a single argument.
  74.  
  75.  
  76. 3) Wildcards
  77. ============
  78. Wildcards are expanded before they are passed to the individual
  79. commands. e.g. ls C:/* would pass 'ls' a command line like
  80.  
  81.      ls,C:\Documents,C:\System,...
  82.  
  83. Note that wildcards are expanded to absolute pathnames and always
  84. have the native separator '\'. 
  85.  To pass wildcards to a module they need to be quoted "*".
  86.  
  87.  
  88. 4) Shell5 variables
  89. ===================
  90. Internal global variables that are generally not intended for
  91. external use have names starting with "_" to avoid accidental
  92. conflicts.
  93.  
  94. See the source code for details of the globals used.
  95.  
  96.  
  97. 5) Shell5 procedures
  98. =====================
  99. Internal functions are prefaced by '_'; to avoid possible
  100. conflicts you should avoid functions starting '_...'. Also
  101. avoid function names that appear as builtin commands and the
  102. ones listed below.
  103.  
  104. Procedures that will be useful in writing modules are listed
  105. below. Some are described in greater detail in section (6) and
  106. are denoted with an asterix:
  107.  
  108.  SetVar%:(var$,val$)    Store val$ in the shell variable var$
  109.  s$=GetVar$:(var$)      Return the value of the shell variable var$
  110.  FreeVar%:(var$)        Delete the shell variable var$
  111. *ret%=Fparse%:(add&,s$) Enhanced PARSE$ function
  112. *ret%=fprint%:(string$) Handle output redirection
  113.  p$=PrPath$:(buf$)      convert a path to UNIX form (if necessary)
  114. *err$:(n%)              Enhanced err$ function
  115.  _Err:(i%,n%)           PRINT PrPath$:(PEEK$(argv%(i%))),"-",err$:(n%)
  116. *_log:(flag%,message$)  Display a message in the status window
  117.  
  118.  
  119. 6) Programming for 'pipes'
  120. ==========================
  121. As stated in the general Readme, commands must be specially written
  122. for input/output edirection and pipes to work. Pipes aren't coded
  123. for specially, if you code commands to use redirection, pipes will
  124. work!
  125.  
  126. Output Redirection: A command is informed if the output is
  127. redirected by a non-zero value for _out%. This value is the OPL
  128. handle for the file that output is to be written to with the
  129. IOWRITE command. The easiest way to handle this is to use fprint%:
  130. to produce any output. The command should only write to _out%,
  131. it shouldn't change the value or close the file handle.
  132.  
  133. Input redirection: A command is informed if the output is
  134. redirected by a non-zero value for _in%. In general input
  135. redirection is only really useful for commands that could already
  136. take their input from a file. For redirected input, rather than
  137. opening a file whose name was supplied on the command line, data is
  138. read directly from SHin% with IOREAD. As with _out%, _in% should
  139. not have it's value changed and it should not be closed.
  140.  Included is Wc.opl, the source for a command that counts the
  141. characters, words and lines of a file, to demonstrate the redirection
  142. of input.
  143.  
  144.  
  145. 7) Detailed descriptions of some procedures
  146. ===========================================
  147. (a) ret%=Fparse%:(add&,s$) Enhanced PARSE$ function
  148.  
  149. It handles relative paths and appends the trailed \ onto
  150. directories.
  151.  
  152. add& - the address of a string, length 255 bytes. This will
  153.        contain the parsed string.
  154. s$   - the path to be parsed.
  155. ret%  - the status of the file as follows:
  156.  
  157. -33 : File / directory doesn't exist
  158. -127: Path contains wildcards
  159.  <0 : OPL error - the status of the returned pathname is undefined
  160.                  and shouldn't be used.
  161.  
  162.  0  : pathname is an ordinary file
  163.  >0 : Bit  4: pathname is a Directory
  164.  
  165. eg. To test for a directory
  166.  
  167.  LOCAL x%,path$(128)
  168.  
  169.  x%=Fparse%:(ADDR(path$),"C:/TEST")
  170.  IF x%<0
  171.    IF x%=-33
  172.      PRINT "Directory doesn't exist"
  173.    ELSE
  174.      PRINT ERR$(x%)
  175.    ENDIF
  176.  ELSEIF x% AND 16
  177.    PRINT "Found directory"
  178.  ELSE
  179.    PRINT "Isn't a directory"
  180.  ENDIF
  181.  
  182. -------------------------------------------------------------------
  183.  
  184. (b) ret%=fprint%:(string$)  Handle output redirection
  185.  
  186.  This procedure should be used to make use of output redirection.
  187. Depending on internal variables it either prints the string to the
  188. screen or to the file specified on the command line.
  189.  
  190. -------------------------------------------------------------------
  191.  
  192. (c) s$=err$:(n%)  Enhanced err$ function
  193.  
  194.  Returns error string as ERR$ except for these values for n%:
  195.  
  196. -127 "Wildcards not allowed"
  197. -111 "Argument overflow"
  198. -71  "Buffer overflow"
  199. -33  "No such file or directory"
  200. 1    "Not a directory"
  201. 2    "Must be a directory"
  202. 3    "Not a plain file"
  203. 4    "No match"
  204. 5    "Input/output redirection invalid for batch files"
  205. 6    "No such variable"
  206. 7    "Missing '"
  207. 8    "Bad ${..}"
  208. 9    "Cannot write system read-only variables"
  209. 10   "Bad redirection"
  210. 11   "Not unique"
  211.  
  212. -------------------------------------------------------------------
  213.  
  214. (d)  _log:(flag%,message$)  Display a message in the status window
  215.  
  216. Display message$ modified by flag% as follows:
  217.  
  218. 1: create/redisplay the window
  219. 2: destroy the window
  220. 3: display message$ on a new line
  221. 4: append message$ to current line
  222. 5: scroll back
  223. 6: scroll forward
  224. 7: clear log
  225.