CREATE-ARRAY

Function

Creates an array of fields to store and process data.

Syntax

CREATE-ARRAY NAME=array_name SIZE=nn 
[EXTENT=nn]
{FIELD=name:type[:occurs]
[={init_value_txt_lit|_num_lit|_binary_lit}]}...

Arguments

NAME

Name of the array. Referenced in other array commands.

SIZE

Number of array elements.

EXTENT

Number of array elements used to incrementally extend the array size beyond the initial allocation defined in SIZE. The value entered for EXTENT must be a numeric literal.

FIELD

Defines each field or column in the array.

DECIMAL[(p)]—Decimal numbers with an optional precision (p).
FLOAT—Double precision floating point numbers.
INTEGER—Whole numbers.
NUMBER—Uses the DEFAULT-NUMERIC type. (See DECLARE-VARIABLE.)
CHAR (or TEXT)—Character string.
DATE—Same as date variable.

You can specify an initialization value for each field. Each field is set to this value when the array is created and when CLEAR-ARRAY is executed. If no initialization value is specified, numeric fields (DECIMAL, FLOAT, INTEGER) are set to zero, character fields are set to null, and date fields are set to null. All occurrences of a multiple occurring field are set to the same value. For dates, the initialization string must be formatted as 'SYYYYMMDD[HH24[MI[SS[NNNNNN]]]]'. See Table 57, Date Edit Format Characters for a description of the format codes.

OCCURS

Fields can optionally have a number of occurrences (occurs), that is, they can be repeated any number of times.

Description

You can define arrays to store intermediate results or data retrieved from the database. For example, a SELECT paragraph can retrieve data, store it in an array, and gather statistics all at the same time. When the query finishes, a summary could be printed followed by the data previously stored in the array.

Production Reporting creates arrays before a program starts to execute. CREATE-ARRAY can be used in any section of a program.

Commands to process arrays include:

CREATE-ARRAY

CLEAR-ARRAY

GET

PUT

ARRAY-ADD

ARRAY-SUBTRACT

ARRAY-MULTIPLY

ARRAY-DIVIDE

LET

The maximum number of arrays in a program is 128; the maximum number of fields per array is 200.

Figure 1. Sample Array with Three Fields

The image shows a sample array with three fields.

The following CREATE‑ARRAY command defines the array:

create-array name=emps size=10
 field=name:char='Unknown'
  field=rate:number:2=10.50
  field=phone:char='None'

The name is a simple field (one occurrence), rate has two occurrences, and phone is a simple field. Both array elements and field occurrences are referenced beginning with zero (0). The rate is referenced by rate(0) or rate(1). The emps array contains 10 elements, 0 through 9. All name fields are initialized to “Unknown”, all phone fields are initialized to “None”, and all rate fields are initialized to 10.50.

Examples

The following example defines an array names custs with 100 elements that can be incrementally extended by 25 elements:

create-array  name=custs size=100 extent=25
  field=name:char
  field=no:number
  field=state:char
  field=zip:char
  field=contacts:char:5
  field=last-contacted:date

The following example defines point labels as part of a data array.

create-array  name=multi_series_radar_data_with_labels  size=7   
  field=label:char ! point label
  field=theta:number:1 ! angle
  field=radius:number:2 ! two series of point