When you use z/OS XL C/C++, can you always remember which option to use? Do you find it troublesome to browse hundreds of pages of a user manual in order to find the right option? Then, you might wonder if there is a way to get the compiler option or command information conveniently and quickly. The answer is yes, use the compiler embedded help!
What information can be found in XL compiler embedded help
There are two types of XL compiler embedded help information: utility reference and xlc help.
1 - Utility reference
You can find reference information for the following utilities:
The xlc utility reference includes the following information:
- A list of all compiler invocation commands and their description and usage
- Acceptable input files
- How to set environment variables to set up compilation environment
- How to set up a configuration file to invoke a compiler
- How to invoke the compiler
- How to invoke the binder
- Supported -q option syntax and flag option syntax
- How to specify compiler options
2 - xlc help
You can find the following information in the xlc help:
- A list of all compiler invocation commands
- A list of all compiler options, which are listed in the alphabetic order.
- Brief description for each option, including:
- Option name
- Syntax
- Supported sub-options
- Purpose
- Default
What does z/OS XL compiler embedded help look like
The z/OS XL C/C++ compiler embedded help is in plain text format. Indentation is used to improve readability.
Example of xlc utility reference
Below is a portion of xlc utility reference.
Example of xlc help file
Below is an example of option description in the xlc help.
How to invoke embedded help
1 - Utility reference
You can view the utility reference by the following command under z/OS UNIX:
man <utility_name>
where utility_name can be one of the following:
2 - xlc help
To view the xlc help for option information, you can run the following command under z/OS Unix:
<compiler_invocation_command>
Where compiler_invocation_command can be one of the following:
Note: the same xlc help is displayed for all these compiler invocation commands.
How to enable embedded help for the xlc utility
You must enable the embedded help for the xlc utility first before viewing the information. You must add the full directory path to the NLSPATH environment variable to read the embedded help.
Different commands are used to set the environment variables depending on the shell you are using. The supported shells include:
- The z/OS® UNIX System Services shell (sh), which is based on the Korn Shell and is upward-compatible with the Bourne shell
- The tcsh shell, which is upward-compatible with the C shell.
To determine the current shell, use the following echo command:
echo $SHELL
For example:
Setting environment variables in sh shell
You can use the following commands to set environment variables in the sh shell:
LANG=En_US
NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%L/%N.cat
PATH=/bin:/usr/lpp/cbclib/xlc/bin${PATH:+:${PATH}}
export LANG NLSPATH PATH
To set the variables so that all users have access to them, add the commands to the file /etc/profile. To set them for a specific user only, add the commands to the .profile file in the user's home directory. The environment variables are set each time the user logs in.
Setting environment variables in tcsh shell
You can use the following commands to set environment variables in the tcsh shell:
setenv LANG En_US
setenv NLSPATH /usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%L/%N.cat
setenv PATH /bin:/usr/lpp/cbclib/xlc/bin${PATH:+:${PATH}}
To set the variables so that all users have access to them, add the commands to the file /etc/csh.cshrc. To set them for a specific user only, add the commands to the .tcshrc file in the user's home directory. The environment variables are set each time the user logs in.
The LANG environment variable specifies the national language for message and help files and can be set to any of the locales provided on the system:
The national language code for United States English may be En_US or C. If the Japanese message catalog has been installed on your system, you can substitute Ja_JP for En_US.
The NLSPATH environment variable specifies the path name of the message and help files.
To determine the current setting of the national language on your system, see the output from both of the following echo commands:
echo $LANG
echo $NLSPATH
For example:
The LANG and NLSPATH environment variables are initialized when the operating system is installed, and may differ from the ones you want to use.
How to find information in embedded help
The z/OS XL C/C++ embedded help is in plain text format, so you can search for any string and then locate the occurrences. Here are some useful commands:
- /string: Search for the specified string downwards
- ?string: Search for the specified string upwards
- n: Find the next occurrence
- N: Find the previous occurrence
When you are viewing embedded help with multiple pages, press “Enter” to display the next page, or enter “q” then “Enter” to quit viewing embedded help and return to the command line.
If you have not yet used the embedded help to look up the information about the XL compiler options and commands under z/OS® UNIX, we bet you would love to give it a try after you learn about it here. Let us know what you think of the embedded help after you use it!
Related reference
z/OS XL C/C++ User's Guide: https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.cbcux01/toc.htm