RUNCMD(OPCSDEFS)	Optical Printer Control System         RUNCMD(OPCSDEFS)

  NAME
      runcmd - define your own OPCS command as a RUN script

  USAGE
      runcmd [name] [filename] [#args] # create new (or redefine old) runcmd
      runcmd -clear                    # clears all runcmd definitions (K2.02+)

	  [name] The name of the new command. 10 characters max.

	  [filename] The full pathname of the script to be executed
	  in place of [name] when executed as a command by the operator. 

	  NOTE: If [filename] is a '-' (dash), this will delete any commands
	  previously defined as [name]. (ie. 'runcmd w - 0' will delete any 
	  previously defined 'w' command). [filename] is 80 characters max.

	  [#args] is the number of arguments OPCS will pass to the script.
	  NOTE: If -1 is specified, the arguments can be variable; all 
	  arguments the user specifies up to the end of the line are 
	  passed on to the script.

	  See below 'ARGUMENTS' for how to pass arguments to a script. 
	  Any value 0-9 and -1 is allowed.

	  If a file of 'name.hlp' exists, it is assumed to be a 'help file' 
	  which will be printed to the screen if the camera operator invokes
	  the command with the wrong arguments.

	  -clear Clears all previous runcmd definitions.

  EXAMPLES
      runcmd lineup .\run\lineup.run 0 # Setup a 'lineup' script

      runcmd woff .\run\w.run 1        # Setup 'woff' (windoff) command
                                       # that expects 1 argument.

      runcmd woff - 0                  # Delete any previous 'woff' command

  DESCRIPTION
      RUNCMD(OPCS) lets you define your own commands as run scripts, with
      optional help text for users if they specify the wrong number of 
      argments. These commands will be recognized as if they were built 
      in to the OPCS program. 

      Whenever the OPCS software reads a command from the operator, it
      checks to see if the [name] for any RUNCMD matches a command the
      operator entered. If so, OPCS will use [filename] as the name of
      a RUN script to execute in place of the command. Arguments can be
      specified by the operator if the RUNCMD and the associated script 
      file are set up for it. If the user does not specify all the 
      arguments, the text in the help file (name.hlp) will be displayed, 
      if the file exists.

      All techniques that can be used in a RUN(OPCS) script can be used in
      scripts defined with RUNCMD(OPCSDEFS). Additionally, the $ argument
      mechanism allows the passing of arguments to run scripts.

      Commands defined with RUNCMD can be stacked on one line like any 
      other OPCS commands, as long as the number of arguments is not -1
      (ie. not 'variable'). If variable args are used (ie. [#args] is -1),
      commands CANNOT be stacked.

      RUNCMD(OPCSDEFS) defined commands will show up in the '?' help listing 
      contained in parenthesis, indicating they are commands not part of
      the software. DOSCMD(OPCSDEFS) definitions also show up this way.

  OPTIONAL HELP FILES (K1.13a+)
      When a runcmd is invoked without the proper number of arguments, 
      an error message will be printed. If you want, you can also have
      some help text printed.

      To make a 'help file' for the command, create a file in the same
      directory, and of the same name as the runcmd's filename, but with 
      a .HLP extension. If the file exists, the files contents are displayed
      along with the error.  Consider the following runcmd:

	      runcmd foo /opcs/mystuff/foo.run 3

      In this case, the optional help file would be called:

	      /opcs/mystuff/foo.hlp

      The file should just contain ascii text that is printed verbatim
      to the user's screen following the 'bad/missing arguments' error.
      This should probably just be a short few lines of text indicating
      a short description of the command, and a description of the
      expected arguments.

  LIMITS
      Currently, no more than 30 different RUNCMD definitions can be setup.
      There is a 10 character limit on [name], an 80 character limit on
      [filename], and anywhere from 0 to 9 arguments are allowed per 
      command.

  ACTUAL EXAMPLES
	  .\SCRIPTS\LINEUP.RUN:

	      @go c 1000     # seat camera for lineups
	      # CAMERA IS NOW SEATED FOR SMPTE LINEUP
	      @pse           # pause while operator does lineup
	      @go c -1000    # unseat, without loosing frame position

	  Note the use of the '@' prefix. This allows the commands to
	  execute without echoing to the screen. See RUN(OPCS) for more
	  on the '@' prefix.

  ARGUMENTS
	  The following example shows how to pass arguments from the command
	  line to a script using the $ mechanism. $ followed by a digit 1-9
	  is replaced by arguments specified on the operator's command line,
	  and $* is replaced by ALL arguments that were supplied.
	  (Note: Use $$ to specify an actual '$' to prevent it being
	  interpreted as an argument variable)

	  .\run\w.run might look like:

	      # RUNNING OFF $1 FRAMES WITH SHUTTER CLOSED
	      @! echo seekcap yes > foo.foo !  ldefs foo.foo
	      @seek $1

	  If 'runcmd w .\run\w.run 1' is defined in the OPCSDEFS.OPC
	  file, when the operator types 'w 80', the script file will execute,
	  and the argument 80 will replace all occurrances of $1 in the 
	  script file. The resulting script will automatically be interpreted
	  as the following during execution:

	      # RUNNING OFF 80 FRAMES WITH SHUTTER CLOSED
	      @! echo seekcap yes > foo.foo !  ldefs foo.foo
	      @seek 80

	  You can specify up to 9 arguments if the script file and RUNCMD
	  are setup for it. Here is an example that uses two arguments in 
	  a cross dissolve command. The first argument is the number of 
	  cross dissolves, the second argument is the number of frames in
	  each cross dissolve:

	  ----  OPCSDEFS.OPC:
	      runcmd xdx .\run\xdx.run 2     # X-dissolve command

	  ----  .\RUN\XDX.RUN:
	      # DOING $1 CROSS DISSOLVE(S) $2 FRAMES EACH
	      do $1  dxo $2 cam $2 cam -$2 pro ($2+20) dxi $2 cam $2

	  When the operator executes 'xdx 70 8', the script is interpreted:

	      # DOING 70 CROSS DISSOLVE(S) 8 FRAMES EACH
	      do 70  dxo 8 cam  cam -8 pro 28 dxi 8 cam 8

	  Here's an example that uses variable arguments:

	  ----  OPCSDEFS.OPC:
	      runcmd zoom .\run\zoom.run -1    # setup a zoom

	  ----  .\RUN\ZOOM.RUN:
	      ! ease foo.tmp $*
	      feed e foo.tmp

	 In this case, any number of arguments can be specified to 'zoom',
	 and will be expanded into the script where the $* is specified.

  GOTCHYAS
      The RUNCMD can seem really nice at first, but it does have drawbacks.

      You are basically 'customizing' a system when you add such 
      definitions, which can be as bad as 'creating a new version' of
      the software. Symptoms will be:

	  o Operators used to a plain-jane OPCS system will be confused
	    by commands they have never seen before.

	  o RUN scripts containing commands that are really defined by RUNCMD
	    will cause errors on systems that dont have the same definitions.

  BUGS
      OPCS does not do any argument type checking when arguments are passed
      through commands defined by RUNCMD. If the user forgets to specify
      an argument, such as with the 'w' command in the following example:

	      w pro 12       # user forgot #frames following 'w'

      'pro' will be passed as an argument to 'w', and the executing script
      will fail with an error because 'pro' will eventually be used as a
      frame argument to the SEEK command, which will cause a somewhat 
      confusing error:

	  seek: bad or missing argument
	  Stopped at line 2 of 1: .\run\w.run

  HISTORY
      The -clear option was added in K2.02.

  SEE ALSO
      RUN(OPCS)         - run a script file
      DOSCMD(OPCSDEFS)  - define DOS commands to the OPCS software
      CUSTOM(OPCS)      - how to make your own 'custom' opcs commands
      LOAD(OPCS)        - 'load' is really a custom runcmd
      LINEUP(OPCS)      - 'lineup' is really a custom runcmd
      UNLOCK(OPCS)      - 'unlock' is really a custom runcmd

  ORIGIN
      Gregory Ercolano, Los Feliz California 04/19/91
      $1 and $* notation used in the UNIX Bourne and C Shells. 
© Copyright 1997 Greg Ercolano. All rights reserved.