How To Interpret IBM Syntax Diagrams
By: Walter Metcalf
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 recently 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:
This is only a summary of the syntax diagram scheme. Some statements are sufficiently
complex that they may not conform to this summary. If you have a problem with a
particular command, the best thing to do is to carefully study the examples provided
in the online documentation. If it is still not clear, then some careful experimentation
should clear things up.
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:
Making a point of noting the baseline when you first see a syntax diagram will
speed up identifying the important points in the diagram.
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.)
An arrow at the end of the baseline indicates a continuation of the baseline;
An arrow at the beginning of the baseline indicates this baseline is a continuation
of the baseline above it.
A short vertical line at the end of a baseline (i.e. -| )is
often used to indicate the end of the syntax diagram.
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.
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.
I will occasionally use the term argument to refer to fields following the
As implied above, all optional commands are on lines below the baseline segment
they apply to.
Drive and Path
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:
Note that these are only guidelines; individual commands often have their
If the argument is in the same directory as the current directory, omit all backslashes.
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!)
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.
Remember that a backslash at the beginning of a path means to change the root directory.
Never specify a leading backslash if to specify a subdirectory of the current directory.
Otherwise the system will try to change root directories!
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
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.
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.)
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.)
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.
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.)
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.
Next week I plan to take a first look at Aurora, now called OS/2 Warp
Server, including a peek at what will likely be included in the client version.
For further reading:
Command Reference by IBM,
converted to HTML by Peter Childs.
Focus on Linux by Mining
Co. Guide Aron Hsiao.
Unless otherwise noted, all content on this site is Copyright © 2004, VOICE