Believe it or not, OS/2's online documentation contains a lot of excellent information. Much of it contains a number of IBM syntax diagrams. Over the years I have come to the point where I can read them fairly easily; however when a reader asked me for help, I realized he was probably not the only one having trouble. The result is this article.

The following material is largely based on the online document, OS/2 Warp Command Reference, contained in the "Reference and Commands" folder within the "Assistance" folder on the OS/2 Desktop. This document can also be found in HTML format on OS/2 Command Reference.  I have "pre-digested" the typical IBM technical jargon. To further simplify the discussion I shall be concentrating on a specific example. (I have not attempted to deal with specialized OS/2 areas such as REXX that have their own peculiarities. If enough of you email me asking for it, then I'll try to write another feature.)

Let's look at the syntax diagram for the XCOPY command:

(I "painted" the background a different colour to make it show up better.)

The XCOPY syntax diagram contains most of the syntax diagram features. (For the sake of the newbies, let me just mention that XCOPY is an eXtended COPY command with several important additional features, including directory recursion and a faster, more sophisticated copying algorithm. Where possible to do so, using XCOPY will be generally be faster and more effective than COPY.)

Let's now study the syntax diagram:

1. Basics
   1. Baseline
      1. The baseline is the top line in a syntax diagram, and may have arrows at the beginning or the end of the line. The baseline has these important properties:
         1. All fields on the baseline are required. Therefore it is possible to enter the command with just those fields and have it work. (Of course it may not do what you want.)
         2. An arrow at the end of the baseline indicates a continuation of the baseline;
         3. An arrow at the beginning of the baseline indicates this baseline is a continuation of the baseline above it.
         4. A short vertical line at the end of a baseline (i.e. -| )is often used to indicate the end of the syntax diagram.

         Making a point of noting the baseline when you first see a syntax diagram will speed up identifying the important points in the diagram.

   2. Verb
      1. Each OS/2 command contains a single verb, which is the same as the command name: in this case, XCOPY. This verb appears on baseline, is therefore required, and may be the only required element in the command.

      2. Note that XCOPY has three required fields: the verb, and two filenames: filename1 and filename2. This is of course very common, and are always the source and destination (or target) filenames respectively.

   3. Arguments
      • I will occasionally use the term argument to refer to fields following the command name.

2. Optional Fields

   As implied above, all optional commands are on lines below the baseline segment to which they apply.

   1. Drive and Path
      1. Most commands can be specified with a pathname, and so will be preceded by Drive and Path on the baseline. It's important to realize that Drive is assumed to have the colon and Path is assumed to have all necessary backslashes ('\'.) Since it is sometimes not clear where backslashes belong, let me give you some guidelines:
         1. If the argument is in the same directory as the current directory, omit all backslashes.
         2. Use a trailing backslash to indicate a directory argument. For example, XCOPY text d:\dir\ will cause XCOPY to copy the file text into the directory d:\dir leaving the filename unchanged; omitting the backslash will confuse XCOPY, and could potentially cause it to copy text and change its name to dir; (Generally, XCOPY will display a question, asking you what you want to do, but other commands are not so accommodating!)
         3. Always leave a space before an initial backslash if no drive name is present: cd \archives is correct; however cd\archives will usually produce an error.
         4. Remember that a backslash at the beginning of a path means to change the root directory.
         5. Never specify a leading backslash if to specify a subdirectory of the current directory. Otherwise the system will try to change root directories!

         Note that these are only guidelines; individual commands often have their own peculiarities.

      2. All fields except Drive, Path and either the Command or Filename MUST have at least one space between them. This is not clear from the the diagrams. Drive, Path, Command or Filename must have NO spaces anywhere except at the end. (Lest you think I'm being condescending, many people I help out have only a fuzzy idea where the spaces go.)

   2. Filename

      In the case of XCOPY, filenames are always preceded by the Drive, Path pair which is the normal case; however this is not always true. In the case of RENAME, for example, the first argument, the source, contains all three fields, however the target syntax permits only a filename. This contrasts with the BACKUP command in which the first argument permits either a filename or a path but not both; the second argument permits only a drive letter. It's important to check the syntax of each command and not to generalize from other syntax diagrams.

   3. Switches
      1. In OS/2 switches are always preceded by forward ('/') slashes unlike UNIX or Linux, where they are preceded by hyphens or dashes.
         • Many OS/2 programs, like InfoZip's Zip, are ports from Linux, and the parameters for those programs, unlike OS/2 commands, follow the UNIX convention and precede switches with hyphens. (This can be a little confusing, especially for the relatively new OS/2 user, since ported UNIX programs, native OS/2 programs, and OS/2 commands can all be entered in the same command line window! The only solution is to read the fine documentation.)

      2. Some switches permit, or even require, you to specify a value. For example the FORMAT commands may need to be told the filesystem (FAT or HPFS) in which to format the drive. This value is entered by means of the /FS (filesystem) switch. A colon is used to separate the switch from this value.
         • For example the XCOPY permits a /D switch to specify a date to tell the command which files to copy. The date must be in the format specified in current system format (specified in the COUNTRY statement in the CONFIG.SYS file) and is preceded by a colon:

           XCOPY C:\MEMOS A:\ /D:10-27-1998 copies all the files created or modified on or after 10-27-1998 from the directory C:\MEMOS to the floppy on drive A:. (Note that the trailing backslash is not required on C:\MEMOS for XCOPY. However it would probably be safer to put it in.)

      3. In most cases switches have default values that the program will assume if no switch is specified on the command line. For example if the /D switch is not specified, XCOPY will copy all files. Likewise if the /FS is not specified on a FORMAT command a default filesystem type that depends on the type of device and the current format type, if any, will be used.

3. Conditional Fields

   Some fields are optional, but are only permitted in certain cases or with certain other options. In the XCOPY syntax drive, note that the /M switch hangs down from or "depends" on the /A. This indicates that /M can only be used if /A is also specified. This is a conditional  field. Other fields beside switches can be conditional. (For example, see the COPY command syntax diagram.)

4. Repeated Fields

   Some fields, notably switches, can be repeated to provide for multiple fields of the same time. Drive and path fields can also be repeated as, for example, in TYPE D:\CONFIG.SYS E:\CONFIG.SYS; this will cause each file to be displayed in turn. A repeated field is indicated by a back arrow on the baseline over the field(s) that can be repeated. Notice the bottom baseline segment of the XCOPY diagram near the right. Repeated fields are usually separated by spaces. If a different separator is required, it will be shown on the syntax diagram.

—Walter Metcalf

For Further Reading:

OS/2 Command Reference by IBM, converted to HTML by Peter Childs.

Focus on Linux by ABOUT Guide Aron Hsiao.