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.