Version 4.2.6 for Mainframes (Update)
 —  Programming Guide  —

X-Arrays

When an ordinary array field is defined, you have to specify the index bounds exactly, hence the number of occurrences for each dimension. At runtime, the complete array field is existent by default; each of its defined occurrences can be accessed without performing additional allocation operations. The size layout cannot be changed anymore; you may neither add nor remove field occurrences.

However, if the number of occurrences needed is unknown at development time, but you want to flexibly increase or decrease the number of the array fields at runtime, you should use what is called an X-array (eXtensible array).

An X-array can be resized at runtime and can help you manage memory more efficiently. For example, you can use a large number of array occurrences for a short time and then reduce memory when the application is no longer using the array.

This document covers the following topics:


Definition

An X-array is an array of which the number of occurrences is undefined at compile time. It is defined in a DEFINE DATA statement by specifying an asterisk (*) for at least one index bound of at least one array dimension. An asterisk (*) character in the index definition represents a variable index bound which can be assigned to a definite value during program execution. Only one bound - either upper or lower - may be defined as variable, but not both.

An X-array can be defined whenever a (fixed) array can be defined, i.e. at any level or even as an indexed group. It cannot be used to access MU-/PE-fields of a database view. A multidimensional array may have a mixture of constant and variable bounds.

Example:

DEFINE DATA LOCAL
1 #X-ARR1 (A5/1:*)          /* lower bound is fixed at 1, upper bound is variable
1 #X-ARR2 (A5/*)            /* shortcut for (A5/1:*)
1 #X-ARR3 (A5/*:100)        /* lower bound is variable, upper bound is fixed at 100
1 #X-ARR4 (A5/1:10,1:*)     /* 1st dimension has a fixed index range with (1:10)
END-DEFINE                  /* 2nd dimension has fixed lower bound 1 and variable upper bound

Top of page

Storage Management of X-Arrays

Occurrences of an X-array must be allocated explicitly before they can be accessed. To increase or decrease the number of occurrences of a dimension, the EXPAND, RESIZE and REDUCE statements may be used.

However, the number of dimensions of the X-array (1, 2 or 3 dimensions) cannot be changed.

Example:

DEFINE DATA LOCAL
1 #X-ARR(I4/10:*)
END-DEFINE
EXPAND ARRAY #X-ARR TO (10:10000) 
/* #X-ARR(10) to #X-ARR(10000) are accessible
WRITE *LBOUND(#X-ARR)                  /* is 10
   *UBOUND(#X-ARR)                     /* is 10000
   *OCCURRENCE(#X-ARR)                 /* is 9991
#X-ARR(*) := 4711                      /* same as #X-ARR(10:10000) := 4711
/* resize array from current lower bound=10 to upper bound =1000 
RESIZE ARRAY #X-ARR TO (*:1000)
/* #X-ARR(10) to #X-ARR(1000) are accessible
/* #X-ARR(1001) to #X-ARR(10000) are released
WRITE *LBOUND(#X-ARR)                  /* is 10
   *UBOUND(#X-ARR)                     /* is 1000
   *OCCURRENCE(#X-ARR)                 /* is 991
/* release all occurrences
REDUCE ARRAY #X-ARR TO  0
WRITE *OCCURRENCE(#X-ARR)              /* is 0

Top of page

Storage Management of X-Group Arrays

If you want to increase or decrease occurrences of X-group arrays, you must distinguish between independent and dependent dimensions.

A dimension which is specified directly (not inherited) for an X-(group) array is independent.

A dimension which is not specified directly, but inherited for an array is dependent.

Only independent dimensions of an X-array can be changed in the EXPAND, RESIZE and REDUCE statements, dimensions must be changed by using the name of the corresponding X-group array which owns this dimension as independent dimension.

Example - Independent/Dependent Dimensions:

DEFINE  DATA LOCAL                                    
1 #X-GROUP-ARR1(1:*)                  /* (1:*)        
  2 #X-ARR1    (I4)                   /* (1:*)        
  2 #X-ARR2    (I4/2:*)               /* (1:*,2:*)    
  2 #X-GROUP-ARR2                     /* (1:*)        
    3 #X-ARR3  (I4)                   /* (1:*)        
    3 #X-ARR4  (I4/3:*)               /* (1:*,3:*)    
    3 #X-ARR5  (I4/4:*, 5:*)          /* (1:*,4:*,5:*)
END-DEFINE

The following table shows whether the dimensions in the above program are independent or dependent.

Name Dependent Dimension Independent Dimension
#X-GROUP-ARR1   (1:*)
#X-ARR1 (1:*)  
#X-ARR2 (1:*) (2:*)
#X-GROUP-ARR2 (1:*)  
#X-ARR3 (1:*)  
#X-ARR4 (1:*) (3:*)
#X-ARR5 (1:*) (4:*,5:*)

The only index notation permitted for a dependent dimension is either a single asterisk (*), a range defined with asterisks (*:*) or the index bounds defined.

This is to indicate that the bounds of the dependent dimension must be kept as they are and cannot be changed.

The occurrences of the dependent dimensions can only be changed by manipulating the corresponding array groups.

EXPAND ARRAY #X-GROUP-ARR1 TO (1:11)       /* #X-ARR1(1:11) are allocated
                                           /* #X-ARR3(1:11) are allocated
EXPAND ARRAY #X-ARR2 TO (*:*, 2:12)        /* #X-ARR2(1:11, 2:12) are allocated
EXPAND ARRAY #X-ARR2 TO (1:*, 2:12)        /* same as before
EXPAND ARRAY #X-ARR2 TO (*  , 2:12)        /* same as before
EXPAND ARRAY #X-ARR4 TO (*:*, 3:13)        /* #X-ARR4(1:11, 3:13) are allocated
EXPAND ARRAY #X-ARR5 TO (*:*, 4:14, 5:15)  /* #X-ARR5(1:11, 4:14, 5:15) are allocated

The EXPAND statements may be coded in an arbitrary order.

The following use of the EXPAND statement is not allowed, since the arrays only have dependent dimensions.

EXPAND ARRAY #X-ARR1 TO ...
EXPAND ARRAY #X-GROUP-ARR2 TO ...
EXPAND ARRAY #X-ARR3 TO ...

Top of page

Referencing an X-Array

The occurrences of an X-array must be allocated by an EXPAND or RESIZE statement before they can be accessed.

As a general rule, an attempt to address a non existent X-array occurrence leads to a runtime error. In some statements however, the access to a non materialized X-array field does not cause an error situation if all occurrences of an X-array are referenced by using the complete range notation, for example: #X-ARR(*). This applies to

If individual occurrences of a non materialized X-array are referenced in one of these statements, a corresponding error message is issued.

Example:

DEFINE DATA LOCAL 
1 #X-ARR (A10/1:*) /* X-array only defined, but not allocated
END-DEFINE        
RESET #X-ARR(*)    /* no error, because complete field referenced with (*)   
RESET #X-ARR(1:3)  /* runtime error, because individual occurrences (1:3) are referenced
END  

The asterisk (*) notation in an array reference stands for the complete range of a dimension. If the array is an X-array, the asterisk is the index range of the current allocated lower and upper bound values which are determined by *LBOUND and *UBOUND.

Top of page

Parameter Transfer with X-Arrays

X-arrays that are used as parameters are treated like constant arrays with regard to the verification of the following:

In addition, X-array parameters can also change the number of occurrences by using the statement RESIZE, REDUCE or EXPAND. The question if a resize of an X-array parameter is permitted depends on three factors:

The following tables demonstrate when an EXPAND, RESIZE or REDUCE statement can be applied to an X-array parameter.

Example with CALL By Value

CALLER PARAMETER
Static Variable (1:V) X-Array
Static NO NO YES
X-Array subrange, e.g. CALLNAT...#XA(1:5) NO NO YES
X-Array complete range, e.g. CALLNAT...#XA(*) NO NO YES

CALL By Reference/CALL By Value Result

CALLER PARAMETER
Static Variable (1:V) X-Array with a fixed lower bound, e.g.
DEFINE DATA PARAMETER
1 #PX (A10/1:*)
X-Array with a fixed upper bound, e.g.
DEFINE DATA PARAMETER
1 #PX (A10/*:1)
Static NO NO NO NO
X-Array subrange, e.g.
CALLNAT...#XA(1:5)
NO NO NO NO
X-Array with a fixed lower bound, complete range, e.g.
DEFINE DATA LOCAL
1 #XA(A10/1:*) 
... 
CALLNAT...#XA(*)
NO NO YES NO
X-Array with a fixed upper bound, complete range, e.g.
DEFINE DATA LOCAL
1 #XA(A10/*:1)
... 
CALLNAT...#XA(*)
NO NO NO YES

Top of page

Parameter Transfer with X-Group Arrays

The declaration of an X-group array implies that each element of the group will have the same values for upper boundary and lower boundary. Therefore, the number of occurrences of dependent dimensions of fields of an X-group array can only be changed when the group name of the X-group array is given with the RESIZE, REDUCE and EXPAND statement (see Storage Management of X-Group Arrays above).

Members of X-group arrays may be transferred as parameters to X-group arrays defined in a parameter data area. The group structures of the caller and the callee need not necessarily be identical. A RESIZE, REDUCE and EXPAND done by the callee is only possible as far as the X-group array of the caller stays consistent.

Example - Elements of X-Group Array Passed as Parameters:

Program:

DEFINE DATA LOCAL
1 #X-GROUP-ARR1(1:*)                    /* (1:*)
   2 #X-ARR1 (I4)                       /* (1:*)
   2 #X-ARR2 (I4)                       /* (1:*)
1 #X-GROUP-ARR2(1:*)                    /* (1:*)
   2 #X-ARR3 (I4)                       /* (1:*)
   2 #X-ARR4 (I4)                       /* (1:*)
END-DEFINE
...
CALLNAT ... #X-ARR1(*) #X-ARR4(*)
...
END

Subprogram:

DEFINE DATA PARAMETER
1 #X-GROUP-ARR(1:*)                     /* (1:*)
   2 #X-PAR1 (I4)                       /* (1:*)
   2 #X-PAR2 (I4)                       /* (1:*)
END-DEFINE
...
RESIZE ARRAY #X-GROUP-ARR to (1:5)
...
END

The RESIZE statement in the subprogram is not possible. It would result in an inconsistent number of occurrences of the fields defined in the X-group arrays of the program.

Top of page

X-Array of Dynamic Variables

An X-array of dynamic variables may be allocated by first specifying the number of occurrences using the EXPAND statement and then assigning a value to the previously allocated array occurrences.

Example:

DEFINE DATA LOCAL
 1 #X-ARRAY(A/1:*)  DYNAMIC
END-DEFINE
EXPAND  ARRAY   #X-ARRAY TO (1:10)
  /* allocate #X-ARRAY(1) to #X-ARRAY(10) with zero length.
  /* *LENGTH(#X-ARRAY(1:10)) is zero 
#X-ARRAY(*) := 'abc'
  /* #X-ARRAY(1:10) contains 'abc',
  /* *LENGTH(#X-ARRAY(1:10)) is 3
EXPAND  ARRAY   #X-ARRAY TO (1:20)
  /* allocate #X-ARRAY(11) to #X-ARRAY(20) with zero length
  /* *LENGTH(#X-ARRAY(11:20)) is zero
#X-ARRAY(11:20) := 'def'
  /* #X-ARRAY(11:20) contains 'def'
  /* *LENGTH(#X-ARRAY(11:20)) is 3

Top of page

Lower and Upper Bound of an Array

The system variables *LBOUND and *UBOUND contain the current lower and upper bound of an array for the specified dimension(s) (1,2 or 3).

If no occurrences of an X-array have been allocated, the access to *LBOUND or *UBOUND is undefined for the variable index bounds, that is, for the boundaries that are represented by an asterisk (*) character in the index definition, and leads to a runtime error. In order to avoid a runtime error, *OCCURRENCE may be used to check against zero occurrences before *LBOUND or *UBOUND is evaluated:

Example:

IF *OCCURRENCE (#A) NE 0  AND  *UBOUND(#A) < 100 THEN ...

Top of page