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

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

    USAGE
        runcmd [name] [filename] [#args]

	    [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.

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

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

	runcmd w - 0           # Delete any previous defintion for 'w'

    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'

	The '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

    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 adapted after examples set by the UNIX Bourne 
	and C Shells.  UNIX (was) a trademark of AT&T.
© Copyright 1997 Greg Ercolano. All rights reserved.