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
arguments. 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
(i.e. not 'variable'). If variable args are used, then commands
CANNOT be stacked.
RUNCMD(OPCSDEFS) defined commands will show up in the '?' help listing
contained in parentheses, 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 few short lines of text with a
description of the command and its 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 occurrences 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.