Introduction to AMODE 31 and AMODE 64 programs interoperability

The AMODE 31 and AMODE 64 interoperability support provides the capability to run AMODE 31 programs and AMODE 64 programs together in an application in the same address space. Language Environment® provides compiler-writer interfaces (CWIs) to allow users to execute a target program of a different AMODE.

Language Environment does not require the programs interoperating between AMODE 31 and AMODE 64 in the same high-level language. The Language Environment support is language-agnostic, but it does need a high-level language compiler or runtime support to achieve transparency in AMODE 31 and AMODE 64 application programs interoperability.

Language Environment CWIs CEL4RO31/CEL4RO64 establishes a secondary Language Environment environment of a different AMODE to execute the target program. The initial Language Environment environment that is created for the caller program is called the primary Language Environment. The two independent Language Environment environments reside in the same task.

The supported scenarios are as follows:
Figure 1. Scenarios that start with 31-bit programs
Boxes representing 31-bit applications with directional arrows pointing back and forth
Figure 2. Scenarios that start with 64-bit programs
Boxes representing 64-bit applications with directional arrows pointing back and forth
31-bit program scenarios
  1. AMODE 31 program A calls AMODE 64 program B. AMODE 31 program A can do subsequent calls of other AMODE 64 programs.
  2. AMODE 31 program A calls AMODE 64 program B, which in turn calls another AMODE 31 program C. AMODE 31 program C can call another AMODE 64 program, and so forth.
  3. AMODE 31 program A calls AMODE 64 program B, which then creates another thread to run a new AMODE 64 program D. AMODE 64 program D cannot call an AMODE 31 program.
64-bit program scenarios
  1. AMODE 64 program A calls AMODE 31 program B. AMODE 64 program A can do subsequent calls of other AMODE 31 programs.
  2. AMODE 64 program A calls AMODE 31 program B, which in turn calls another AMODE 64 program C. AMODE 64 program C can call another AMODE 31 program, and so forth.
  3. AMODE 64 program A creates another thread to run AMODE 64 program D. Meanwhile, AMODE 64 program A calls AMODE 31 program B. The AMODE 31 program B can call another AMODE 64 program, and so forth.

AMODE Switching Status control block

AMODE Switching Status can be retrieved from the SW3164 control block, which is pointed to by both 31-bit CEECAA_SW3164 and 64-bit CEECAA_SW3164 after the secondary Language Environment is set up.
Table 1. SW3164 field descriptions
Decimal offset Hex offset Type Length Name (DIM) Description
0 (0) BITSTRING 4 SW_EYE Eyecatcher 'SWTH'
4 (4) BITSTRING 1 SW_FLAG1 SW3164 flags
    1... ....   SW_PRIMARY If ON, primary environment is 31-bit. If OFF, primary environment is 64-bit.
    .1.. .....   SW_ACTIVE_31 If ON, 31-bit environment is active. If OFF, 64-bit environment is active.
    ..1. ....   SW_ENV_READY If ON, secondary environment is ready. If OFF, secondary environment is not ready.

Considerations and restrictions

Program management
All AMODE 31 programs that are involved in the interoperability scenario need to be non-XPLINK. All AMODE 31 and AMODE 64 programs that are involved in the interoperability scenario need to be reentrant.

There is no support for AMODE 24 programs and AMODE 64 programs interoperability.

Parameters and return types
Complex parameters and return types(that is, a structure or a pointer) are passed without deep copy. AMODE 64 pointers are passed to AMODE 31 programs as is, which cannot be dereferenced in AMODE 31 programs.
POSIX behaviors
POSIX runtime option can be set to ON in both AMODE 31 and AMODE 64 primary Language Environment environments. After calling CEL4RO64, the AMODE 31 primary Language Environment environment is not allowed to call POSIX functions. The AMODE 31 secondary Language Environment environment is forced to be POSIX(OFF) while the AMODE 64 secondary Language Environment environment is forced to be POSIX(ON).

The mixed use of pthread_create() and CEL4RO64 in AMODE 31 programs is not allowed. For a multi-threaded AMODE 64 program, only one thread can make AMODE switching calls. An asynchronous signal is handled only when the AMODE switching thread is executing AMODE 64 programs when it is received. The received asynchronous signal is put back when the AMODE switching thread is executing AMODE 31 programs.

Setting options
The secondary environment of Language Environment inherits the runtime option TRAP and the first suboption of runtime option TERMTHDACT and TEST values of the primary environment of Language Environment. Any other runtime option in the secondary environment of Language Environment will be the default value.
Recovery
Language Environment supports condition handling for programs interoperating between AMODE 31 and AMODE 64 in the respective environment of Language Environment. Language Environment will traverse stack frames to find a condition handler until the AMODE 31 and AMODE 64 environments boundary is reached. Therefore, an AMODE 31 condition handler or an AMODE 64 exception handler may not be called. Registering your own ESTAE/ESPIE exit routine in an AMODE 31 and AMODE 64 interoperability application may result in unexpected behaviors.
ENTermination
The normal termination and abnormal termination process would terminate both Language Environment environments. If an unhandled condition with a severity higher than 2 occurs in the secondary Language Environment environment that causes the termination, the primary Language Environment environment is terminated with abend 4094-1024.
Performance
Transitions between AMODE 31 and AMODE 64 programs have more overhead than a normal function call. Avoid using it in a performance sensitive area.
Standard stream
The redirection of standard streams in the secondary Language Environment environment results in unpredictable behavior. The redirection of standard streams in the primary Language Environment environment does not impact the standard streams in the secondary Language Environment environment.

Environment variables propagation to secondary Language Environment

To set environment variables in secondary Language Environment before running the target program, use one of the following methods:
  • Specify the environment variables through DD:STDENV in primary Language Environment.
  • Specify the environment variables through _CEE_ENVFILE in primary Language Environment.
Considerations for setting environment variables in secondary Language Environment are as follows:
  1. DD:STDENV or _CEE_ENVFILE must be set before the first call of CEL4RO31() or CEL4RO64(), otherwise it will not take effect.
  2. DD:STDENV has higher priority than _CEE_ENVFILE. Therefore, once DD:STDENV is set, _CEE_ENVFILE will be ignored.
  3. The environment variables set using other methods by applications in primary Language Environment will not be passed to secondary Language Environment.
  4. The environment variables set in secondary Language Environment are not passed back to the primary Language Environment.