# Image Selectors

An image selector determines the image index for a coindexed object. It takes the following form:

lbracket cosubscript-list [ , selector-spec-list ] rbracket

lbracket | Is a left bracket "[". This is required.
cosubscript | Is a scalar integer expression. Its value must be within the cobounds for its codimension. The number of cosubscripts must be equal to the corank of the object. If the lower bound is not specified, it is assumed to be 1.
selector-spec | Is TEAM=team-var or TEAM_NUMBER=scalar-integer-expression or STAT=stat-var
team-var | Is a scalar of type TEAM_TYPE defined in the intrinsic module ISO_FORTRAN_ENV.
stat-var | Is a scalar integer variable with an exponent range of at least 4 (KIND=2 or greater). stat-var cannot be coindexed.
rbracket | Is a right bracket "]". This is required.

Considering the cobounds and bounds, respectively, the cosubscript list in an image selector determines the image index in the same way that a subscript list in an array element determines the subscript order value.

The selector-specs may appear in any order in the selector-spec-list. TEAM= and TEAM_NUMBER must not both be specified. A given selector-spec may appear at most once.

If TEAM= is specified, team-var must be the current or an ancestor team. If TEAM_NUMBER= appears and the initial team is not the current team, scalar-integer-expression must have a value of -1 indicating the initial team, or a positive integer value that identifies a sibling team of the current team. If the initial team is the current team and TEAM_NUMBER appears, scalar-integer-expression must have the value -1. If TEAM or TEAM_NUMBER is specified, the team of the image selector is the specified team; the image index specified by the cosubscript list applies to the specified team. Otherwise, the team of the image selector is the current team.

If the image selector specifies TEAM_NUMBER=, and the value of scalar-integer-expression is a positive integer that is not that of the current team, the coarray object must be established on an ancestor team or be an associating entity on the enclosing CHANGE TEAM construct. Otherwise, the coarray object must be established in the specified team, or in an ancestor of that team.

An image selector must specify an image index value that is not greater than the number of images on the specified team.

When a statement containing an image selector with STAT= specified is executed, stat-var becomes defined with value STAT_FAILED_IMAGE defined in the intrinsic module ISO_FORTRAN_ENV if the object referenced by the image selector is on a failed image. Otherwise, stat-var becomes defined with the value zero.

A stat-var in an image selector cannot depend on the evaluation of any other entity in the same statement. An expression cannot depend on the value of any stat-var that is specified in the same statement. The value of stat-var cannot depend on execution of any part of the statement, other than if the object is on a failed image.

## Examples

Assume that there are 16 images and the coarray C is declared as follows:

    REAL :: C(15)[5,*]

C(:)[1,4] is valid because it selects image 16, but C(:)[2,4] is invalid because it selects image 17.

C(1)[2, 1, STAT=istatus] will cause istatus to become defined with the value STAT_FAILED_IMAGE if image 6 has failed; otherwise, istatus becomes defined with the value zero.

Consider the following program:

      PROGRAM main
        USE, INTRINSIC       :: ISO_FORTRAN_ENV
        TYPE (TEAM_TYPE)     :: initial, odd_even
        REAL                 :: ca[4:*], x, y, z
        INTEGER              :: me
        initial = GET_TEAM (CURRENT_TEAM)
        me = THIS_IMAGE ()
        FORM TEAM (2-MOD(me, 2), odd_even, NEW_INDEX=(me+1)/2)
         . . .
        CHANGE TEAM (odd_even, ae[2,*]=>ca)
          x = ca[2,3, TEAM=initial]
          y = ae[2,4, TEAM_NUMBER=2]
          x = ae[2,2]

        . . .
        END TEAM
      . . .
      END PROGRAM

Assuming there are 16 images, `ca` is then a 4x4 coarray. The FORM TEAM statement divides the images into two teams. Team 1 contains images [1, 3, …, 15] and team 2 contains images [2, 4, …, 16] with image indices on the new teams [1, 2, …, 8] respectively.

The CHANGE TEAM statement has an associating entity `ae` which is a 2x4 coarray on each team executing the CHANGE TEAM construct. Within the CHANGE TEAM construct for team 1, ae[1, 1] is ca[1, 1], ae[2, 1] is ca[3, 1], ae[1, 2] is ca[1, 2], ae[2,2] is ca[3,2], ae[1,3] is ca[1,3], ae[2, 3] is ca[3,3], ae[1,4] is ca[1,4] and ae[2,4] is ca[3,4], and for team 2, ae[1, 1] is ca[2, 1], ae[2, 1] is ca[4, 1], ae[1, 2] is ca[2, 2], ae[2,2] is ca[4,2], ae[1,3] is ca[2,3], ae[2, 3] is ca[4,3], ae[1,4] is ca[2,4] and ae[2,4] is ca[4,4].

The first statement in the CHANGE TEAM construct assigns x the value of ca[2,3] on the initial team, which is on image 10 on the initial team. The second statement in the CHANGE TEAM construct assigns y the value of ae[2, 2] on team number 2 that is on image 8 of team 2; it is the same as ca[4,4], that is on image 16 of the initial team. The third statement in the CHANGE TEAM construct assigns z the value of ae[2,2]. ae[2,2] is on image 4 of both team 1 and team 2; on team 1 it is the same as ca[3,2] on image 7 of the initial team, and on team 2 it is the same as ca[4,2], which is on image 8 of the initial team.

Parent topic: Coarrays

## See Also

Coarrays
ISO_FORTRAN_ENV Module
FORM TEAM
CHANGE TEAM