Array attributes specify the size of an array or the part of an array that is to be transferred during a call. An array attribute specifies a variable that is either a field in the same structure as the array or a parameter in the same operation as the array.
An array_attribute can take the following forms:
min_is ([*] variable)
max_is ([*] variable)
size_is ([*]
variable)
last_is ([*] variable)
first_is ([*] variable)
length_is ([*] variable)
where variable specifies a variable whose value at runtime will determine the bound or element count for the associated dimension. A pointer variable is indicated by preceding the variable name with an * (asterisk).
If the array is a member of a structure, any referenced variables must be members of the same structure. If the array is a parameter of an operation, any referenced variables must be parameters of the same operation.
Only the ..._is(variable) form is allowed when the array is a field of a structure. In this case, the ..._is(*variable) form is not allowed.
Note that an array with an array attribute (that is, a conformant or varying array) is not allowed to have the transmit_as attribute.
The min_is Attribute
The min_is attribute is used to specify the variable(s) from which the values of one or more lower bounds of the array will be obtained at runtime. If any dimension of an array has an unspecified lower bound, the array must have a min_is attribute. A variable must be identified for each such dimension. The following examples show the syntax of the min_is attribute:
/* Assume values of variables are as follows
long a = -10;
long b = -20;
long c = -30;
*/
long [min_is(a)] g1[*..10]; /* g1[-10..10] */
long [min_is(a)] g2[*..10][4]; /* g2[-10..10[0..3] */
long [min_is(a,b)] g3[*..10][*..20]; /* g3[-10..10][-20..20] */
long [min_is(,b)] g4[2][*..20]; /* g4[0..1][-20..20] */
long [min_is(a,,c)] g5[*..7][2..9][*..8]; /* g5[-10..7][2..9][-30..8] */
long [min_is(a,b,)] g6[*..10][*..20][3..8]; /* g6[-10..10][-20..20][3..8] */
The following examples show the min_is attribute being applied to the first dimensions of an array in an IDL type definition and parameter declaration, and how the definition or parameter is translated into its C equivalent:
IDL Type Definition:
typedef struct {
long n;
[min_is(n)] long fa3[*..10][-4..1][-1..2]
} t2;
C Translation:
typedef struct {
idl_long_int n;
idl_long_int fa3[1][6][4];
} t2;
IDL Parameter Declaration:
[in,out,min_is(n)] long fa3[*..10][-4..1][-1..2]
C Translation:
/* [in, out] */ idl_long_int fa3[][6][4]
The max_is Attribute
The max_is attribute is used to specify the variables from which the values of one or more upper bounds of the array are obtained at runtime. If any dimension of an array has an unspecified upper bound, the array must have a max_is or size_is attribute. A variable must be identified for each dimension in which the upper bound is unspecified. In a max_is attribute, the value in the identified variable specifies the maximum array index in that dimension. An array with one or more unspecified upper bounds may have a max_is attribute or a size_is attribute, but not both.
The max_is attribute is for use with conformant arrays. The following is an example of the max_is attribute:
/* Assume values of variables are as follows:
long a = 10;
long b = 20;
long c = 30;
*/
long [max_is(a)] f1[]; /* f1[0..10] /*
long [max_is(a)] f2[][4]; /* f2[0..10][0..3] */
long [max_is(a,b)] f3[][]; /* f3[0..10][0..20] */
long [max_is(,b)] f4[2][]; /* f4[0..1][0..20] */
long [max_is(a,,c)] f5[1..*][2..9][3..*]; /* f5[1..10][2..9][3..30] */
long [max_is(a,b,)] f6[1..*][2..*][3..8]; /* f6[1..10][2..20][3..8] */
The size_is Attribute
The size_is attribute is used to specify the variables from which the values of the element counts for one or more dimensions of the array are obtained at runtime. If any dimension of an array has an unspecified upper bound, the array must have a max_is or size_is attribute. A variable must be identified for each dimension in which the upper bound is unspecified. In a size_is attribute, the value in the identified variable specifies the number of elements in that dimension. An array with one or more unspecified upper bounds may have a max_is attribute or a size_is attribute, but not both.
The size of a dimension is defined as the upper bound, minus the lower bound, + 1.
The size_is attribute is for use with conformant arrays. The following is an example of the size_is attribute:
/* Assume the following values for the referenced variables:
n3 = 5;
x2 = 12;
x3 = 14;
z2 = 9;
z3 = 10;
*/
/* The following declaration */
int [min_is(,,n3),max_is(,x2,x3)] hh[3..13,4..*,*..*];
/* specifies the same data to be transmitted as the declaration */
int [min_is(,,n3),size_is(,z2,z3)] hh[3..13,4..*,*..*];
The last_is Attribute
The last_is attribute is one of the attributes that can be used to allow the amount of data in an array that will be transmitted to be determined at runtime. Each last_is attribute specifies an upper data limit, which is the highest index value in that dimension for the array elements to be transmitted. If the entry in a last_is attribute for a dimension is empty, the effect is as if the upper bound in that dimension had been specified.
An array can have either the last_is attribute or the length_is attribute, but not both.
When an array with the last_is attribute is used in a remote procedure call, the elements actually passed in the call can be a subset of the maximum possible.
The last_is attribute is for use with varying arrays. The following is an example of the last_is attribute:
/* Assume the following values for the referenced variables:
long a = 1;
long b = 2;
long c = 3;
long e = 25;
long f = 35;
*/
long [last_is(a,b)] bb1[10][20]; /* transmit bb1[0..1][0..2] */
long [last_is(a,b)] bb2[-1..10][-2..20][-3..30];
/* transmit bb2[-1..1][-2..2][-3..30] */
long [last_is(a,,c)] bb3[-1..10][-2..20][-3..30];
/* transmit bb3[-1..1][-2..20][-3..3] */
long [last_is(,b,c),max_is(,e)] cc1[10][][30];
/* transmit cc1[0..9][0..2][0..3] */
long [last_is(a,b),max_is(,e,f)] cc2[-4..4][][];
/* transmit cc2[-4..1][0..2][0..35] */
The first_is Attribute
The first_is attribute is one of the attributes that can be used to allow the amount of data in an array that will be transmitted to be determined at runtime. Each first_is attribute specifies a lower data limit, which is the lowest index value in that dimension for the array elements to be transmitted. If the entry in a first_is attribute for a dimension is empty, the effect is as if the lower bound in that dimension had been specified.
When an array with the first_is attribute is used in a remote procedure call, the elements actually passed in the call can be a subset of the maximum possible.
The first_is attribute is for use with varying arrays. The following is an example of the first_is attribute:
/* Assume the following values for the referenced variables:
long p = -1;
long q = -2;
long r = -3;
long t = -25;
long u = -35;
long x = 1;
long y = 2;
long z = 3;
*/
long [first_is(p)] dd1[-10..10]; /* transmit dd1[-1..10] */
long [first_is(p),last_is(x)] dd2[-10..10]; /* transmit dd2[-1..1] */
long [first_is(p,q)] ee1[-10..10][-20..20]; /* transmit ee1[-1..10][-2..20] */
long [first_is(p,q)] ee2[-10..10][-20..20][-30..30];
/* transmit ee2[-1..10][-2..20][-30..30] */
long [first_is(p,q,r),last_is(,,z)] ee3[-10..10][-20..20][-30..30]:
/* transmit ee3[-10..10][-20..20[-30..30] */
double [first_is(,q,r),min_is(,t)] ff1[10][*..2][-30..30];
/* transmit ff1[0..9][-2..2][-3..30] */
double [first_is(p,q),min_is(,t,u)] ff2[-4..4][*..2][*..35];
/* transmit ff2[-1..4][-2..2][-35..35] */
double [max_is(x,,z),min_is(,t,u),first_is(p,,r)] ff3[-20..*][*..30][*..*]
/* transmit ff3[-1..1][-25..30[-3..3] */
The length_is Attribute
The length_is attribute is one of the attributes that can be used to allow the amount of data in an array that will be transmitted to be determined at runtime. Each length_is attribute specifies the number of elements in that dimension to be transmitted. If the entry in a length_is attribute for a dimension is empty, the effect is for the highest index value in that dimension for the elements to be transmitted to be determined from the upper bound in that dimension.
An array can have either the last_is attribute or the length_is attribute, but not both.
When an array with the length_is attribute is used in a remote procedure call, the elements actually passed in the call can be a subset of the maximum possible.
The length_is attribute is for use with varying arrays. The following is an example of the length_is attribute:
/* Assume the following values for the referenced variables:
n3 = 5;
f2 = 10;
a1 = 11;
a2 = 12;
a3 = 14;
e1 = 9;
e2 = 3;
e3 = 10;
*/
/* The following declaration: */
int [min_is(,,n3),first_is(,f2,),last_is(a1,a2,a3)] gg[3..13,4..14,*..15];
/* specifies the same data to be transmitted as the declaration: */
int [min_is(,,n3),first_is(,f2,),length_is(e1,e2,e3)] gg[3..13,4..14,*..15];