TARGET

Pragma equivalent

Purpose

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

Syntax


            .-,------------------.      
            | .-CURRENT--------. |      
            V | .-LE--.        | |      
>>-TARG--(----+-+-IMS-+--------+-+--)--------------------------><
              '-+-zOSV1R12---+-'        
                +-zOSV1R13---+          
                +-zOSV2R1----+          
                '-0xnnnnnnnn-'

Defaults

TARGET(LE, CURRENT)

Parameters

The following suboptions target the runtime environment:

LE: Generates object code to run under the Language Environment® runtime environment. This is the default.
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 with 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 z/OS V2R1, TARGET(CURRENT) is the same as TARGET(zOSV2R1). This is the default.¹
Note: 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.
zOSV1R12: Generates object code to run under z/OS Version 1 Release 12 and subsequent releases.
zOSV1R13: Generates object code to run under z/OS Version 1 Release 13 and subsequent releases.
zOSV2R1: Generates object code to run under z/OS Version 2 Release 1 and subsequent releases.
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 and is an advanced feature. Most applications should use the other release suboptions. The layout of this literal is the same as the __TARGET_LIB__ macro.

Usage

Note: The suboptions for TARGET are not case-sensitive.

With the TARGET option, you can specify the runtime environment and release for your program’s object module that z/OS XL C/C++ generates. This enables you to generate code that is downward compatible with earlier levels of the operating system while at the same time disallowing you from using library functions not available on the targeted release. With the TARGET option, you can compile and link an application on a higher level system, and run the application on a lower level system.

If you specify a release that is out of service, the compiler issues a warning message and accepts the specified release.

The compiler generates a comment that indicates the value of TARGET in your object module 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 the required release, for example, zOSV1R12. If you do not select a runtime environment or release, the compiler uses the default of TARGET(LE, zOSV2R1).

TARGET() generates object code to run under the Language Environment runtime environment. It is the same as TARGET(LE,CURRENT).

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.

The compiler applies and resolves defaults after it views all the entered suboptions. For example, TARGET(LE,0x410C0000, IMS, zOSV1R12, LE) resolves to TARGET(LE, zOSV1R12). TARGET(LE, 0x410C0000, IMS, zOSV1R12) resolves to TARGET(IMS, zOSV1R12). TARGET(LE, 0x410C0000, IMS) resolves to TARGET(IMS, 0x410C0000).

The default value of the ARCHITECTURE compiler option depends on the value of the TARGET release suboption. For TARGET(zOSV2R1) and above, the default is ARCH(7).

The TARGET release suboptions (CURRENT, zOSV1R12, zOSV1R13 and zOSV2R1) help you to generate code that can be executed on a particular release of a z/OS system, and on subsequent releases.

In order to use these suboptions, you must use the z/OS V2R1 class library header files (found in the CBC.SCLBH.* data sets) during compilation.

See Prelinking and linking z/OS XL C/C++ programs for details on prelinking and linking applications.

The TARGET release suboptions will not allow you to exploit new functions provided on the newer release. Rather, they allow you to build an application on a newer release and run it on an older release.

The hexadecimal string literal suboption enables you to specify an operating system level. It is an advanced feature that is intended for library providers and vendors to test header files on future releases. Most applications should use the other release suboptions instead of this string literal. The layout of this literal is the same as the __TARGET_LIB__ macro.

The compiler checks that there are exactly 8 hexadecimal digits. The compiler performs no further validation checks.

The compiler uses a two step process to specify the operating system level:

The hexadecimal value will be used, as specified, to set the __TARGET_LIB__ macro.
The compiler determines the operating system level implied by this 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. Note that the compiler sets the __TARGET_LIB__ macro to the value that you specify, even if it does not correspond to a valid operating system level.

The following information describes the restrictions for C/C++:

All input libraries used during the application build process must be the appropriate level for the target release.
- The current level of the Language Environment data sets can be used to target to previous releases. Use these Language Environment data sets during the assembly, compilation, pre-link, link-edit, and bind phases.
- For C++ class libraries, use the current release class library header files during compilation; use the class library data sets for the targeted release during pre-link, link-edit, and bind.
- Ensure that any other libraries incorporated in the application, are compatible with the target release.

While there are no restrictions on the use of ARCH and TUNE with TARGET, ensure that the level specified is consistent with the target hardware.

Only options or features that cannot be supported on that operating system level are disabled. For example, STRICT_INDUCTION is allowed on all operating system levels. An option or feature that is disabled by one operating system level is also disabled by all earlier operating system levels.

The following information describes the restrictions for C:

See the z/OS XL C/C++ Language Reference for information about the #pragma target() directive.
If you specify TARGET(zOSVxRy) on the command line, and one or more of the disallowed options is specified, the compiler issues a warning message and disables the option.

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 are performing the IPA Compile to generate IPA Object files, ensure that you are using the appropriate header library files.

If you specify TARGET on the IPA link step:

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 may 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 zOSV2R1. However, when using TARGET suboptions ensure that:

All IPA Object files are compiled with the appropriate TARGET suboption and header files
All 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(OSVxRy) release suboptions, the compiler sets the __TARGET_LIB__ macro. See z/OS XL C/C++ Language Reference for more information about this macro.

Examples

To generate code that will execute on a z/OS V2R1 system, using a XL C/C++ V2R1 application development system, you must:

Specify the compiler option TARGET(zOSV2R1) on the C/C++ compiles. Note: The programmer is responsible for ensuring that they are not exploiting any Language Environment functions that are unavailable on z/OS V2R1.
Use the z/OS V2R1 Language Environment data sets (CEE.SCEE*) during the assembly, compilation, pre-link, link-edit, and bind phases.
Use the z/OS V2R1 class library header data sets (CBC.SCLBH.*) during compilation. Use the z/OS V2R1 class library data sets (SCLBCPP and SCLBSID) during pre-link, link-edit, and bind.

The following information shows examples of using the hexadecimal string literal suboption:

TARGET(0x42010000): Equivalent to TARGET(zOSV2R1).
TARGET(0x410D0000): Equivalent to TARGET(zOSV1R13).
TARGET(0x410C0000): Equivalent to TARGET(zOSV1R12).
TARGET(0xA3120000): This does not match any existing operating system release suboption name. The next lower operating system level 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 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.

¹ Note that 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.