3.2 Toolkit Program Usage Conventions

In order to make the multitude of Toolkit programs easier to use, the developers have attempted to use consistent commandline argument styles. The Toolkit programs all require at least one commandline argument. Therefore, if a program is executed without commandline arguments, it is assumed that the user is asking for help. In this case, a help message is printed that shows syntax and (usually) describes the meaning of the switches. In general, program usage is of the following form:
  programName fileNames switches.
Probably the simplest example would be
  sddsquery fileName,
which would invoke sddsquery to describe the contents of an SDDS file. A slightly more complicated example would be
  sddsquery fileName -columnList,
which invokes sddsquery to list just names of columns in a file.

Programs assume that any commandline argument beginning with a minus sign (’-’) is an option; all others are assumed to be filenames. Note that case is ignored in commandline switches. The specific meaning of a filename is dictated by its order on the commandline. For example, if two filenames are given, the first would commonly be an input file while the second would commonly be an output file.

In some cases, a command with a single filename implies replacement of the existing file. For example,
  sddsconvert fileName -binary
would replace the named file with a binary version of the same data. This command is completely equivalent to
  sddsconvert -binary fileName
That is, unlike many UNIX commands, the position of filenames relative to options is irrelevant.

One might also wish to make a new file, rather than replacing the existing file. This could be done by
  sddsconvert -binary fileName fileName2
Note that while the option may appear anywhere on the commandline, the order of the filenames is crucial to telling the program what to do.

In following manual pages and in the program-generated help text, program usage is described using the following conventions:

• The first token on the commandline is the name of the program.
• Items in square-brackets ([]) are optional. Items not in square brackets are required.
• Items in curly-brackets ({}) represent a list of choices. The choices are separated by a | character, as in
  { choice1 | choice2 | choice3 }
• Items in italics are descriptions of arguments or data that must be supplied by the user. These items are not typed literally as shown.
• Items in normal print are typed as shown, with optional abbreviation. These are usually switch keywords or qualifiers. Any unique abbreviation is acceptable.

In addition to using files, most toolkit programs also take input from pipes, which obviates the need for temporary files in many cases. For those programs that support pipes, one can employ the -pipe option. This option provides a good example of what options look like. For example, one could do the following to test binary-ascii conversion:
  sddsconvert -binary -pipe=out fileName | sddsconvert -ascii -pipe=in fileName1
The -pipe=out option to sddsconvert tells it to deliver its output to a pipe; it still expects a filename for input. Similarly, the -pipe=in option to sddsquery tells it to accept input from a pipe.

The -pipe switch may be given in one of five forms: -pipe, -pipe=input,output, -pipe=output,input, -pipe=input, -pipe=output . The first three forms are equivalent. In a usage message, these forms would be summarized as -pipe[=input][,output]. One could also use abbreviations like -pipe=i, -pipe=i,o, etc. For convenience in the manual, the data stream from or to a pipe will often be referred to by the name of the file for which it substitutes. Note that you may not deliver more than one file on the same pipe.