User Commands are like custom toolbar buttons with one important difference—the command template. When you read the description of any Opus Raw Command, you will see each command has a its own template—the collection of various switches and options that govern what you can pass to the command, and how those options affect the command's behavior. When you make your own User command, you must create such a template. Otherwise, anything you can do in a User Command, you can also accomplish in a toolbar button.
The guidelines of how the options should work (not how you make them) is discussed in the Opus Help/Manual on the first page under the Opus Raw Commands section, where you see: /S, /O, /K, /A, and /M listed. You'll want to print that page out and have it handy. How the User Command template is actually constructed is discussed in the Opus Help/Manual under Predefined Commands - User-Predefined. That section could use a little more detail, but it has most of what you need. You'll want to print that page out and have it handy.
ADVICE: Do not be in a hurry to create a user command.
If what you want to accomplish has an ad-hoc, one-of, or unique nature then you will be better served by a custom toolbar button. When you find yourself making several toolbar buttons of very similar nature, with only a couple things varying between each, then it's time to start thinking about making a user command. If the various toolbar buttons aren't really related, then it makes less sense to make a user command out of them. Of course, there is some gray area here.
It's much easier to iron out all the wrinkles in a regular toolbar button. I recommend you start by reasoning out how to do each branch of your User Command as a separate toolbar button, which will help you ensure that each branch works without issue. Where you can, use Opus variables to pass the values to the various Internal and External commands in your toolbar buttons. While you do this, try to use the same descriptive variable names and a similar process flow across the various buttons. Then the logic will tend to emerge and help you see how the separate toolbar buttons might become one user command. Then you can go and design your user command by reconciling the various branch-buttons into one user command.
Q: Can multiple lines be stuffed into one command?
Yes, but with one important consideration, and you will see it touched upon from time-to-time in the forums here when users try to do a lot in one toolbar button—the race condition. I'm going to muddle through an explanation here, but Leo could provide better clarity than I can.
Opus is multi-threaded, for example when you list a folder, several processing threads will work to extract image thumbnails and display them in the current lister. When you start a Copy operation, I'm pretty sure it gets its own thread, which is what allows you to minimize the Copy Progress dialog and still keep right on working in the same file display doing something else. When you want to create a toolbar button or user command that does several different things in sequence, this concept is going to work against you. Consider this pseudo code:
A. Copy all images files from Location A to location B
B. Go to Location B
C. Select all the image files
D. Rename files to Image - 01.ext to Image - NN.ext
E. Reselect all image files (or never deselect them)
F. For each image file selected, resize it 256 x 256 in-place
(The Opus Image command can actually accomplish steps A and F above in a single command line. But set that knowledge aside because I need a simple multi-command example here.) If you tried to use multiple raw commands to accomplish the above, you might have issues. The lister display needs to be updated in Location B with all of the new file Meta Data before the Rename can work correctly on all the files; the more files, the longer Step A will take to complete and the longer the OS will take to update the meta data. The same is true after the Rename in Step D and before the resize in Step F. For some commands there is no reliable way for your toolbar button (or User Command) to be certain when such a processing step is complete. And each step in the above process is going to be reliant on the completion of the previous step. It depends a lot on what you are trying to do.
If you want to make something complex, you most likely will want/need logic branching. Opus toolbar buttons and user commands do not provided logic branching. The internal workings of each raw command definitely have logic branching, and you can pass those command parameters to interact with it. But the Opus Command Editor does not provide logic branching that governs the flow between different raw commands or external commands
The Advanced Command Editor now provides variables (new in Opus 9), but they must all be set upfront, and they cannot be changed later. (I'm still working myself on understanding the boundaries of what can be accomplished with Opus variables, but I do not think that you can @Set one variable based on the value of another variable.)
If it sound like I'm trying to discourage you, I'm not. But you need to be aware of the obstacles.
Personally, I use NT Command Scripts for my logic branching. Most of my User Commands work with external commands. And nearly all of them are MS-DOS Batch functions. I use Opus to pass things like the selected files, or the currently listed folder. I use the NT Command script (stored inside an Opus User Command) for my logic branching. When I want to have Opus perform a tack from within my NT Command Script, I use dopusrt.exe /CMD to call the Opus raw command.
NOTE: Keep in mind that this approach will actually increase the risk of a race condition occurring.
For the curious, you cannot (yet) take a previously existing and working NT Command script and simply paste into an Opus toolbar button or User Command and expect it to work straight away. But if you already have a working NT Command Script, it should now be possible to store it in Opus with minimal modification. Jon did a lot of work on the Advanced Command Editor for Opus 9 and its MS-DOS Batch Function processing is much better than that of Opus 8. There are still a few unresolved issues remaining, But so far nothing I don't know a workaround to.
Check out the PrintTree User Command I posted in Buttons & Toolbars. Download that and add it to your configuration. You can open up that User Command and see what I'm doing inside, as well as the toolbar buttons I included that use the command. If you have any questions on what I doing in that command or why, post them back here to this thread. PrintTree only takes two parameters. I have a couple more-complex User Commands under development, but I'm a ways from publishing them. So much Opus, so little time!
Also, something I have not played around with yet in Opus 9 is the @script modifier, which I believe allows you to store VBScript or JScript inside an Opus toolbar button or User Command. If you check out the Rename Scripting forum I believe they are using VBScript for complicated file rename operations.