CHANGE TEAM construct

Standard: F77 F90 F95 F2003 F2008 F2018 Example program

＜Syntax＞

[ construct-name : ] CHANGE TEAM ( team-value [ , coarray-association ]... [ , sync-stat ]... )
[ executable-construct ]...
END TEAM [ construct-name ]

The END TEAM statement may have a construct name only if the same name appears on the CHANGE TEAM statement.

Transfer of control out of the construct, e.g. by a RETURN or GOTO statement is prohibited.

team-value ::= scalar-expr
A team-value must be of type TEAM_TYPE from the intrinsic module ISO_FORTRAN_ENV.

sync-stat ::= STAT = stat-variable | ERRMSG = errmsg-variable
At most one STAT= and ERRMSG= specifier may appear in a CHANGE TEAM statement. The stat-variable must be a non-coindexed scalar integer variable (and at least 16 bits), and errmsg-variable must be a scalar default character variable.

coarray-association :: = local-coarray-name [ explicit-coshape-spec ] => outer-coarray-name

＜Semantics＞

Executing the CHANGE TEAM statement changes the current team (of images) to team-value, which must identify a subteam of the previously-current team; all images of this new team are implicitly synchronised, and all active images of the new team must execute the same CHANGE TEAM statement at this time.

If the STAT= specifier appears, the stat-variable is assigned the value zero for successful execution, and a positive value if an error occurs. If an error occurs and no STAT= specifier appears, the program is error-terminated.

If both STAT= and ERRMSG= appear and an error occurs, errmsg-variable is assigned an explanatory error message; otherwise, errmsg-variable is unchanged.

The setting of the current team remains in effect during procedure calls, so any procedure referenced by the construct will also be executed with the new team current.

The construct may be exited only by executing its END TEAM statement, or by executing an EXIT statement that belongs to the construct.

While executing a CHANGE TEAM construct, image selectors operate using the new team's image indices, the intrinsic functions NUM_IMAGES and THIS_IMAGES return the data for the new team, and SYNC ALL synchronises the new team only. The SYNC TEAM statement can be used to synchronise the parent team.

If one of the images in the new team has failed, e.g. by executing a FAIL IMAGE statement, the STAT_FAILED_IMAGE error is raised (this named constant is in the intrinsic module ISO_FORTRAN_ENV). If no STAT= specifier appears, the program is error-terminated; otherwise, the CHANGE TEAM construct is executed as if it were successful (including setting the current team and the implicit synchronisations), apart from the value assigned to the stat-variable.

If any other error occurs, the behaviour is undefined; a non-zero error code might (or might not) be assigned to stat-variable, the current team might be changed, the new team might be synchronised, or the program might be error-terminated. Any stat-variable value other than zero (for success) or STAT_FAILED_IMAGE (for image failure) should be treated by the program as fatal.

Coarray association within a CHANGE TEAM construct is more complicated (but less capable) than argument association, and is thus an advanced concept that should only be attempted by experienced programmers. It establishes local-coarray-name, with cobounds specified by explicit-coshape-spec, to be an alias for remote-coarray-name within the construct.