TARGET

Category

Object code control

Pragma equivalent

#pragma target (C only)

Purpose

Generates an object module for the target operating system or runtime library.

Syntax

Read syntax diagramSkip visual syntax diagram TARG (,CURRENTLEIMSzOSV2R2zOSV2R3zOSV2R40xnnnnnnnn)

Defaults

TARGET(LE, CURRENT)

Parameters

The following suboptions target the runtime environment:

LE
Generates object code to run under the Language Environment® runtime environment.
IMS
Generates object code to run under the Information Management System (IMS) subsystem. If you are compiling the main program, you must also specify the PLIST(OS) option. TARGET(IMS) is not supported by LP64.

The following suboptions target the release at program run time:

CURRENT
Generates object code that runs under the same version of z/OS® with which the compiler is included. As the compiler is included with Start of changez/OS V2R4End of change, TARGET(CURRENT) is the same as Start of changeTARGET(zOSV2R4)End of change.1
zOSV2R2
Generates object code to run under z/OS Version 2 Release 2 and subsequent releases.
zOSV2R3
Generates object code to run under z/OS Version 2 Release 3 and subsequent releases.
Start of changezOSV2R4End of change
Start of changeGenerates object code to run under z/OS Version 2 Release 4 and subsequent releases.End of change
0xnnnnnnnn
An eight-digit hexadecimal literal string that specifies an operating system level. This string is intended for library providers and vendors to test header files on future releases. Most applications should use the other release suboptions. The layout of this literal is the same as the __TARGET_LIB__ macro.

Usage

With the TARGET option, you can specify the z/OS release of the runtime environment for your program's object module that z/OS XL C/C++ generates. This option enables you to compile and link a program on the current level of the z/OS operating system and run the resulting application on an earlier release of the z/OS operating system that is supported by the TARGET option. However, you cannot use library functions or new features that are not available on the target release of the operating system. The status of the TARGET option is inserted in the object file to aid you in diagnosing problems in your program.

To use the TARGET option, select a runtime environment of either LE or IMS. Then, select a TARGET release (CURRENT, zOSV2R2, zOSV2R3, or Start of changezOSV2R4End of change), which helps you to generate code that can be run on a particular release of z/OS and on subsequent releases. If you do not select a runtime environment or release, the compiler uses the default of Start of changeTARGET(LE, zOSV2R4), which is the same as TARGET(LE, CURRENT)End of change. If you specify the release suboption to a release that is earlier than Start of changezOSV2R2End of change, the compiler issues a warning message.

When the hexadecimal string literal suboption is in effect, the compiler checks the existence of exactly eight hexadecimal digits only but does not perform further validation checks. The compiler specifies the operating system level through the following two steps:
  1. Sets the __TARGET_LIB__ macro with the specified hexadecimal value, even if the value does not correspond to a valid operating system level.
  2. Determines the operating system level that is implied by this string literal. If the level corresponds to a valid suboption name, the compiler behaves as though that suboption is specified. Otherwise, the compiler uses the next lower operating system suboption name. If there is no lower suboption name, the compiler behaves as though you have specified an unsupported release.
If you specify more than one suboption from each group of suboptions (that is, the runtime environment or the release), the compiler uses the last specified suboption for each group. For example:
  • TARGET(LE, Start of change0x42030000End of change, IMS, Start of changezOSV2R4End of change, LE) resolves to TARGET(LE, Start of changezOSV2R4End of change).
  • TARGET(LE, Start of change0x42040000End of change, IMS, Start of changezOSV2R4End of change) resolves to TARGET(IMS, Start of changezOSV2R4End of change).
  • TARGET(LE, Start of change0x42040000End of change, IMS) resolves to TARGET(IMS, Start of change0x42040000End of change).
All input libraries that are used during the application build process must be available and at the appropriate level for the target release.
  • The current level of the Language Environment data sets can be used to target previous releases. Use these Language Environment data sets during the assembly, compilation, pre-link, link-edit, and bind phases.
  • You must use the z/OS class library header files of the current release (found in the CBC.SCLBH.* data sets) during compilation and use the current level of the class library header files during pre-link, link-edit, and bind phases. For details, see Prelinking and linking z/OS XL C/C++ programs.
  • Any other libraries that are incorporated in the application must be compatible with the target release.
The levels that are specified for the ARCH and TUNE options must be consistent with the target hardware. The default value of the ARCHITECTURE compiler option depends on the value of the TARGET release suboption:
  • Start of changeFor TARGET(zOSV2R4), the default is ARCH(10).End of change
  • For TARGET(zOSV2R3), the default is ARCH(10).
  • For TARGET(zOSV2R2), the default is ARCH(8).

The compiler disables options or features that cannot be supported with the target release and issues a message.

To make full use of the latest binder features, you need to explicitly specify the binder option COMPAT. The binder default value for this option is MIN, so the binder uses only the minimal set of features that are required to satisfy the program being processed.

IPA effects

If you specify the TARGET option for any compilation unit in the IPA compile step, the compiler generates information for the IPA link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option.

When you generate IPA object files during the IPA compile step, you must use the appropriate header library files.

If you specify TARGET on the IPA link step, it has the following effects:
  • It overrides the TARGET value that you specified for the IPA compile step.
  • It overrides the value that you specified for #pragma runopts(ENV). If you specify TARGET(LE) or TARGET(), the IPA link step specifies #pragma runopts(ENV(MVS)). If you specify TARGET(IMS), the IPA link step specifies #pragma runopts(ENV(IMS)).
  • It might override the value that you specified for #pragma runopts(PLIST), which specifies the runtime option during program execution. If you specify TARGET(LE) or TARGET(), and you set the value set for the PLIST option to something other than HOST, the IPA link step sets the values of #pragma runopts(PLIST) and the PLIST compiler option to IMS. If you specify TARGET(IMS), the IPA link step unconditionally sets the value of #pragma runopts(PLIST) to IMS.
The IPA link step accepts the release suboptions, for example, CURRENT or Start of changezOSV2R4End of change. However, you must comply with the following rules to avoid unexpected behavior:
  • All IPA and non-IPA object files are compiled with the appropriate TARGET suboption and header files.
  • All other input libraries are compatible with the specified runtime release.

Predefined macros

When you invoke the TARGET(zOSVxRy) release suboptions, the compiler sets the __TARGET_LIB__ macro. For details, see General macros in z/OS XL C/C++ Language Reference.

Examples

Example 1
When you use the z/OS V2R4 XL C/C++ compiler to generate an application to run on a z/OS V2R3 system, you must take the following steps:
  1. Specify the TARGET(zOSV2R3) compiler option.
  2. Ensure that the libraries that are incorporated in the application are compatible with the z/OS V2R3 release.
  3. Run the application on a z/OS V2R3 system.
Example 2
The usage of the hexadecimal string literal suboption is shown as follows:
Start of changeTARGET(0x42040000)End of change
Start of changeEquivalent to TARGET(zOSV2R4).End of change
TARGET(0x42030000)
Equivalent to TARGET(zOSV2R3).
TARGET(0x42020000)
Equivalent to TARGET(zOSV2R2).
TARGET(0xA3120000)
This string literal does not match any existing operating system release suboption name. The next lower operating system level that is implied by this literal, which the compiler considers valid, is CURRENT. Thus, the compiler sets the __TARGET_LIB__ macro to 0xA3120000, and behaves as though you have specified TARGET(CURRENT).
TARGET(0x21010000)
This string literal does not match any existing operating system release suboption name, and specifies a release earlier than the earliest supported release. In this instance, the compiler sets the __TARGET_LIB__ macro to 0x21010000, and behaves as though you have specified an unsupported release.

Related information

1 Note: For some releases of z/OS, z/OS XL C/C++ might not include a new release of the compiler. The same release of the compiler is then included with more than one z/OS release. The compiler is designed to run on all these z/OS releases. In this case, the compiler sets CURRENT to the z/OS release on which it is running. (It does so by querying the Language Environment Library version of the system.) You can specify a zOSVxRy suboption that corresponds to a release that is earlier or the same as CURRENT. You cannot specify a zOSVxRy suboption that corresponds to a release later than CURRENT.