Reading the command descriptions

Related information

Each shell command appears in alphabetic order. The description for each command is divided into several topics, which are explained in the following paragraphs. Some of these topics apply only to a few command descriptions. Also, some command descriptions include special topics that are not explained here.

Format

The Format topic provides a quick summary of the command's format, or syntax. The syntax was chosen to conform to general UNIX usage. For example, here is the format of the ls command:

ls [–AabCcdFfgiLlmnopqRrstuWx1] [pathname …]

The format takes the form of a command line as you might type it into the system; it shows what you can type in and the order in which you should do it. The parts enclosed in square brackets are optional; you can omit them if you choose. Parts outside the square brackets must be present for the command to be correct.

The format begins with the name of the command itself. Command names always appear in bold font.

After the command name comes a list of options, if there are any. A typical z/OS shell command option consists of a dash (–) followed by a single character, typically an uppercase or lowercase letter. For example, you might have –A or –a.

Note: The case of letters is important; for example, in the format of ls, –a and –A are different options, with different effects.

If you are going to specify several options for the same command, you can put all the option characters after the same dash. Or you can put each option after its own dash. Or you can rearrange the order of options. For example, the following formats are all equivalent:

ls -Aa
ls -a -A
ls -aA

The format line shows options like -a in bold font. In the description of ls, all options are shown in one long string after the single dash. But another common option form is:

-x value

where –x is a dash followed by a character, and value provides extra information for using that option. For example, here is the format for the sort command, which takes unsorted input and sorts it:

sort [–cmu]
[–o outfile]
[–t char]
[–yn]
[–zn]
[–bdfiMnr]

[-k startpos[,endpos]] …
[file …]

sort [–cmu]
[–o outfile]
[–tchar]
[–yn]
[–zn]
[–bdfiMnr]

[+startposition[–endposition]] …
[file …]

You can see that there are two possibilities here; you would need to choose which of the two versions of sort met your requirements. In either possibility, however, we have the option:

–o outfile

This option tells the sort command where to save its sorted output. The form of the option is –o, followed by a space, followed by outfile. In a command format, anything appearing in italic serif font is a placeholder for information that you are expected to supply. Sometimes after the format, the kind of information expected in place of the placeholder is explained. In our sort example, outfile stands for the name of a file where you want sort to store its output. For example, if you wanted to store the output in the file sorted.dat, you would specify:

sort -o sorted.dat

(followed by the rest of the command).

The format for sort also contains an option of the form:

–tchar

This is similar to the option form we were just discussing, except that there is no space between the –t and char. char in italics is a placeholder; in this case, it stands for any single character. If you want to use the –t option for sort, you just type –t followed immediately by another character, as in:

sort -t:

In this case, we use a colon (:) in the position of the placeholder char.

The end of the sort format is:

[file …]

This means a list of one or more file names; the ellipsis (….) stands for repetitions of whatever immediately precedes it. Since there are square brackets around the previous list, you can omit the list if you like.

The format of ls ended in:

[pathname …]

As you might guess, this means that an ls command can end with an optional list of one or more path names. What's the difference between this and our sort example? A path name (specified with pathname) can be the name of either a file or a directory; a file name (specified with file) is always the name of a file.

The order of items on the command line is important. When you type a command line, you should specify its parts in the order they appear in the command format. The exceptions to this are options marked with a dash (–); they do not have to be given in the exact order shown in the format. However, all the – options must appear in the correct area of the command line. For example, you can specify:

ls -l -t myfiles
ls -t -l myfiles

but you will not get correct results if you specify:

ls myfiles -l -t           ***incorrect***

or:

ls -l myfiles -t           ***incorrect***

and so on. If you enter the last example, for instance, ls interprets –t as the path name of a file or directory, and the command will try to list the characteristics of that item.

As a special notation, most z/OS shell commands let you specify two dashes (––) to separate the options from the nonoption arguments; –– means that there are no more options. Thus, if you really have a directory named –t, you could specify:

ls –– –t

to list the contents of that directory.

Description

The Description topic describes what the command does. For a particularly complex command, this topic may be divided into a large number of subtopics, each dealing with a particular aspect of the command.

The Description topic often mentions the standard input (stdin) and the standard output (stdout). The standard input is typically the workstation keyboard; the standard output is typically the display screen. The process of redirection can change this. Redirection is explained in z/OS UNIX System Services User's Guide.

The shell differentiates between hexadecimal, octal, and decimal format as follows:

Any number that starts with 0x is in hexadecimal format.
Any number that starts with 0 is in octal format.
Any number that does not start with 0x or 0 is in decimal format.

Options

The Options topic describes each of the options used by the command.

Examples

The Examples topic is present in many command descriptions, giving examples of how the z/OS shell can be used.

Before you try to run any of the provided examples, you need to know that the z/OS shell uses the EBCDIC code page 01047 (Latin-1). Characters entered on a workstation keyboard and passed to the shell by z/OS do not have the same hexadecimal encoding as the code page used by the shell. You may need to customize your keyboard so that those characters have the encoding that the shell uses. See z/OS UNIX System Services User's Guide for more information about code page conversion.

Environment variables

The Environment Variables topic lists the environment variables that affect the command, if any, and describes the purposes that those variables serve. For example, the ls command description lists two environment variables (COLUMNS and TZ). It also explains that COLUMNS is the terminal width and that TZ contains information about the local time zone.

Localization

All shell commands are affected by the following special localization variables:

LANG
LC_ALL
LC_MESSAGES
NLSPATH

The Localization topic describes how the locale-related environment variables affect the behavior of the command. These environment variables allow you to access locale information, including alternate character sets; alternate numeric, monetary, and date and time formats; and foreign language translations of common messages. Locales make it easier for users around the world to use the shell and utilities.

z/OS® UNIX supports the IBM-supplied locales listed in Table 1. User-generated locales using IBM® code page 1047 are also supported.

Table 1. Locales supplied by z/OS UNIX
Country or region	Language	Locale name
Bulgaria	Bulgarian	Bg_BG.IBM-1025
Czech Republic	Czech	Cs_CZ.IBM-870
Denmark	Danish	Da_DK.IBM-277
Denmark	Danish	Da_DK.IBM-1047
Switzerland	German	De_CH.IBM-500
Switzerland	German	De_CH.IBM-1047
Germany	German	De_DE.IBM-273
Germany	German	De_DE.IBM-1047
Greece	Ellinika	El_GR.IBM-875
United Kingdom	English	En_GB.IBM-285
United Kingdom	English	En_GB.IBM-1047
Japan	English	En_JP.IBM-1027
United States	English	En_US.IBM-037
United States	English	En_US.IBM-1047
Spain	Spanish	Es_ES.IBM-284
Spain	Spanish	Es_ES.IBM-1047
Finland	Finnish	Fi_FI.IBM-278
Finland	Finnish	Fi_FI.IBM-1047
Belgium	French	Fr_BE.IBM-500
Belgium	French	Fr_BE.IBM-1047
Canada	French	Fr_CA.IBM-037
Canada	French	Fr_CA.IBM-1047
Switzerland	French	Fr_CH.IBM-500
Switzerland	French	Fr_CH.IBM-1047
France	French	Fr_FR.IBM-297
France	French	Fr_FR.IBM-1047
Croatia	Croatian	Hr_HR.IBM-870
Hungary	Hungarian	Hu_HU.IBM-870
Iceland	Icelandic	Is_IS.IBM-871
Iceland	Icelandic	Is_IS.IBM-1047
Italy	Italian	It_IT.IBM-280
Italy	Italian	It_IT.IBM-1047
Israel	Hebrew	Iw_IL.IBM-424
Japan	Japanese	Ja_JP.IBM-939
Japan	Japanese	Ja_JP.IBM-1027
Korea	Korean	Ko_KR.IBM-933
Belgium	Dutch	Nl_BE.IBM-500
Belgium	Dutch	Nl_BE.IBM-1047
Netherlands	Dutch	Nl_NL.IBM-037
Netherlands	Dutch	Nl_NL.IBM-1047
Norway	Norwegian	No_NO.IBM-277
Norway	Norwegian	No_NO.IBM-1047
Poland	Polish	Pl_PL.IBM-870
Brazil	Brazilian	Pt_BR.IBM-037
Brazil	Brazilian	Pt_BR.IBM-1047
Portugal	Portugese	Pt_PT.IBM-037
Portugal	Portugese	Pt_PT.IBM-1047
Romania	Romanian	Ro_RO.IBM-870
Russia	Russian	Ru_RU.IBM-1025
Serbia	Serbian(Latin)	Sh_SP.IBM-870
Slovakia	Slovak	Sk_SK.IBM-870
Slovenia	Slovenian	Sl_SI.IBM-870
Serbia	Serbian(Cyrillic)	Sr_SP.IBM-1025
Sweden	Swedish	Sv_SE.IBM-278
Sweden	Swedish	Sv_SE.IBM-1047
Turkey	Turkish	Tr_TR.IBM-1026
People's Republic of China	Simplified Chinese	Zh_CN.IBM-935
Taiwan	Traditional Chinese	Zh_TW.IBM-937

For more information about locales, see Localization.

Files

The Files topic lists any supplementary files (files not specified on the command line) that the command refers to. Such files typically provide information the command needs; the command accesses these files during its operation. If the files cannot be found, the command issues a message to this effect.

Files documented in this topic may be temporary files, output files, databases, configuration files, and so on.

The z/OS XL C/C++ run-time library supports a file naming convention of // (the file name can begin with exactly two slashes). However, z/OS UNIX System Services does not support this convention. Do not use this convention (//) unless it is specifically indicated (as in the description for the c89 command). z/OS UNIX System Services does support the POSIXfile naming convention, where the file name can be selected from the set of character values excluding the slash and the null character.

Usage notes

The usage notes section gives additional notes for those using the shell. Its purpose is similar to that of the Caution topic (see Caution). That is, it provides important information that the reader should not overlook. However, it typically deals with issues that are more benign than what the Caution topic deals with.

Exit values

The Exit Values topic presents the error messages that the shell may display, along with a description of what caused the message and a possible action you can take to avoid getting that message. Occasionally, this topic refers you to another command description for more information about an error message.

This topic also contains information about the exit status returned by the command. You can test this status to determine the result of the operation that the command was asked to perform.

Limits

The Limits topic lists any limits on the operation of the shell. Some limits are implicit rather than explicit and may be lower than the explicitly stated limit.

Portability

The Portability topic includes two types of information:

Availability of a version of the command on existing UNIX systems (System V, BSD)
Compatibility with industry standards—for example, the POSIX.2 Draft Standard or the X/Open Portability Guide, Issue 4 (XPG4**).

Caution

The Caution topic contains important advice for users. In z/OS shell documentation, the Caution topic is often aimed at those who are familiar with UNIX systems. Since the z/OS shell primarily conforms to the emerging POSIX standards, its behavior may not precisely match the corresponding UNIX commands. The Caution topic may point out discrepancies in behavior that may catch experienced POSIX or UNIX users by surprise.

Related information

The Related Information topic refers to other command descriptions that may contain information relevant to the command description you have just read. For example, consider the head command; by default, head displays the first 10 lines of each file given on the command line. Its Related Information topic refers you to tail, the command that displays the last 10 lines of a file.