User-Defined Variables

#### Search Results

Search

# User-Defined Variables

User-defined variables are fields which you define yourself in a program. They are used to store values or intermediate results obtained at some point in program processing for additional processing or display.

This document covers the following topics:

- Definition of Variables

- Referencing of Database Fields Using (r) Notation

- Renumbering of Source-Code Line Number References

- Format and Length of User-Defined Variables

- Special Formats

- Index Notation

- Referencing a Database Array

- Referencing the Internal Count for a Database Array (C* Notation)

- Qualifying Data Structures

- Examples of User-Defined Variables

See also Naming Conventions for User-Defined Variables in Using Natural.

## Definition of Variables

You define a user-defined variable by specifying its name and its format/length in the `DEFINE DATA` statement.

You define the characteristics of a variable with the following notation:

(r,format-length/index)

This notation follows the variable name, optionally separated by one or more blanks.

No blanks are allowed between the individual elements of the notation.

The individual elements may be specified selectively as required, but when used together, they must be separated by the characters as indicated above.

Example:

In this example, a user-defined variable of alphanumeric format and a length of 10 positions is defined with the name `#FIELD1`.

    DEFINE DATA LOCAL
    1 #FIELD1 (A10)
    ...
    END-DEFINE

Notes:

1. If operating in structured mode or if a program contains a `DEFINE DATA LOCAL` clause, variables cannot be defined dynamically in a statement.
2. This does not apply to application-independent variables (AIVs); see also Defining Application-Independent Variables

## Referencing of Database Fields Using (r) Notation

A statement label or the source-code line number can be used to refer to a previous Natural statement. This can be used to override Natural's default referencing (as described for each statement, where applicable), or for documentation purposes. See also Loop Processing, Referencing Statements within a Program.

The following topics are covered below:

- Default Referencing of Database Fields

- Referencing with Statement Labels

- Referencing with Source-Code Line Numbers

### Default Referencing of Database Fields

Generally, the following applies if you specify no statement reference notation:

- By default, the innermost active database loop (`FIND`, `READ` or `HISTOGRAM`) in which the database field in question has been read is referenced.

- If the field is not read in any active database loop, the last previous `GET` statement (in reporting mode also `FIND FIRST` or `FIND UNIQUE` statement) is referenced which is not contained in an already closed loop and which has read the field.

### Referencing with Statement Labels

Any Natural statement which causes a processing loop to be initiated and/or causes data elements to be accessed in the database may be marked with a symbolic label for subsequent referencing.

A label may be specified either in the form `label.` before the referencing object or in parentheses `(label.)` after the referencing object (but not both simultaneously).

The naming conventions for labels are identical to those for variables. The period after the label name serves to identify the entry as a label.

Example:

    ...
     RD. READ PERSON-VIEW BY NAME STARTING FROM 'JONES'
       FD. FIND AUTO-VIEW WITH PERSONNEL-ID = PERSONNEL-ID (FD.)
             DISPLAY NAME (RD.) FIRST-NAME (RD.) MAKE (FD.)
        END-FIND
     END-READ
     ...

### Referencing with Source-Code Line Numbers

A statement may also be referenced by using the number of the source-code line in which the statement is located.

All four digits of the line number must be specified (leading zeros must not be omitted).

Example:

    ...
    0110 FIND EMPLOYEES-VIEW WITH NAME = 'SMITH'
    0120   FIND VEHICLES-VIEW WITH MODEL = 'FORD'
    0130     DISPLAY NAME (0110) MODEL (0120)
    0140   END-FIND
    0150 END-FIND
    ...

## Renumbering of Source-Code Line Number References

Line number references (see Referencing of Database Fields Using (r) Notation and Referencing Statements within a Program) within a source are changed if a related line number is changed by the `RENUMBER` command. Renumbering applies to all line reference patterns, except those within an alphanumeric or a Unicode constant. For example:

    #FIELD1 := '(1150)'   /* is not renumbered
    RESET NAME(1150)      /* is renumbered

Note
By default, line number references in alphanumeric and Unicode constants are not renumbered. If they are also to be renumbered, you have to set the profile parameter `RNCONST` to `ON`.

The following patterns are recognized as being valid source code line number references and are renumbered (`nnnn` is a four-digit number):

Pattern | Sample Statement
--- | ---
`(nnnn)` | `ESCAPE BOTTOM (0150)`
`(nnnn/` | `DISPLAY ADDRESS-LINE(0010/1:5)`
`(nnnn,` | `DISPLAY ADDRESS-LINE (0010,A10/1:5)`

If the left parenthesis is not immediately followed by `nnnn` or if `nnnn` is followed by any character other than a right parenthesis, a comma or a slash, the pattern is not considered a line number reference and will not be changed.

## Format and Length of User-Defined Variables

Format and length of a user-defined variable are specified in parentheses after the variable name.

Fixed-length variables can be defined with the following formats and corresponding lengths.

For the definition of Format and Length in dynamic variables, see Definition of Dynamic Variables.

Format | Explanation | Definable Length | Internal Length (in Bytes)
--- | --- | --- | ---
A | Alphanumeric | 1 - 1073741824 (1GB) | 1 - 1073741824
B | Binary | 1 - 1073741824 (1GB) | 1 - 1073741824
C | Attribute Control | - | 2
D | Date | - | 4
F | Floating Point | 4 or 8 | 4 or 8
I | Integer | 1 , 2 or 4 | 1, 2 or 4
L | Logical | - | 1
N | Numeric (unpacked) | 1 - 29 | 1 - 29
P | Packed numeric | 1 - 29 | 1 - 15
T | Time | - | 7
U | Unicode (UTF-16) | 1 - 536870912 (0.5 GB) | 2 - 1073741824

Length can only be specified if format is specified. With some formats, the length need not be explicitly specified (as shown in the table above).

For fields defined with format N or P, you can use decimal position notation in the form `n.m`, where `n` represents the number of positions before the decimal point, and `m` represents the number of positions after the decimal point. The sum of the values of `n` and `m` must not exceed 29.

The maximum "Definable Length" (1 GB for alphanumeric, binary and Unicode fields) represents the limit which is imposed by the Natural compiler. In reality, however, the amount of memory that can be obtained as data storage is very much smaller. Especially if running in a "Natural thread" based environment, the size of the session dependent user areas, hence the extent of the user fields in the data area, is restricted to the size of the thread.

Notes:

1. When a user-defined variable of format P is output with a `DISPLAY`, `WRITE`, or `INPUT` statement, Natural internally converts the format to N for the output.
2. In reporting mode, if format and length are not specified for a user-defined variable, the default format/length N7 will be used, unless this default assignment has been disabled by the profile/session parameter `FS`.

For a database field, the format/length as defined for the field in the data definition module (DDM) apply. (In reporting mode, it is also possible to define in a program a different format/length for a database field.)

In structured mode, format and length may only be specified in a data area definition or with a `DEFINE DATA` statement.

#### Example of Format/Length Definition - Structured Mode:

    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 FIRST-NAME
    1 #NEW-SALARY (N6.2)
    END-DEFINE
    ...
    FIND EMPLOY-VIEW ...
    ...
    COMPUTE #NEW-SALARY = ...
    ...

In reporting mode, format/length may be defined within the body of the program, if no `DEFINE DATA` statement is used.

#### Example of Format/Length Definition - Reporting Mode:

    ...
    ...
     FIND EMPLOYEES
    ... ... COMPUTE #NEW-SALARY(N6.2) = ...
    ...

## Special Formats

In addition to the standard alphanumeric (A) and numeric (B, F, I, N, P) formats, Natural supports the following special formats:

- Format C - Attribute Control

- Formats D - Date, and T - Time

- Format L - Logical

- Format: Handle

### Format C - Attribute Control

A variable defined with format C may be used to assign attributes dynamically to a field used in a `DISPLAY`, `INPUT`, `PRINT`, `PROCESS PAGE` or `WRITE` statement.

For a variable of format C, no length can be specified. The variable is always assigned a length of 2 bytes by Natural.

Example:

    DEFINE DATA LOCAL
    1 #ATTR (C)
    1 #A (N5)
    END-DEFINE
    ...
    MOVE (AD=I CD=RE) TO #ATTR
    INPUT #A (CV=#ATTR)
    ...

For further information, see the session parameter `CV`.

### Formats D - Date, and T - Time

Variables defined with formats D and T can be used for date and time arithmetic and display. Format D can contain date information only. Format T can contain date and time information; in other words, date information is a subset of time information. Time is counted in tenths of seconds.

For variables of formats D and T, no length can be specified. A variable with format D is always assigned a length of 4 bytes (P6) and a variable of format T is always assigned a length of 7 bytes (P12) by Natural. If the profile parameter `MAXYEAR` is set to `9999`, a variable with format D is always assigned a length of 4 bytes (P7) and a variable of format T is always assigned a length of 7 bytes (P13) by Natural.

Example:

    DEFINE DATA LOCAL
    1 #DAT1 (D)
    END-DEFINE
    *
    MOVE *DATX TO #DAT1
    ADD 7 TO #DAT1
    WRITE '=' #DAT1
    END

For further information, see the session parameter `EM` and the system variables `*DATX` and `*TIMX`.

The value in a date field must be in the range from 1st January 1582 to 31st December 2699.

### Format L - Logical

A variable defined of format L may be used as a logical condition criterion. It can take the value `TRUE` or `FALSE`.

For a variable of format L, no length can be specified. A variable of format L is always assigned a length of 1 byte by Natural.

Example:

    DEFINE DATA LOCAL
    1 #SWITCH(L)
    END-DEFINE
    MOVE TRUE TO #SWITCH
    ...
    IF #SWITCH
       ...
       MOVE FALSE TO #SWITCH
    ELSE
       ...
       MOVE TRUE TO #SWITCH
    END-IF

For further information on logical value presentation, see the session parameter `EM`.

### Format: Handle

A variable defined as `HANDLE OF OBJECT` can be used as an object handle.

For further information on object handles, see the section NaturalX.

## Index Notation

An index notation is used for fields that represent an array.

An integer numeric constant or user-defined variable may be used in index notations. A user-defined variable can be specified using one of the following formats: N (numeric), P (packed), I (integer) or B (binary), where format B may be used only with a length of less than or equal to 4.

A system variable, system function or qualified variable cannot be used in index notations.

#### Array Definition - Examples:

1. #ARRAY (3)
   Defines a one-dimensional array with three occurrences.

2. FIELD (label.,A20/5) or label.FIELD(A20/5)
   Defines an array from a database field referencing the statement marked by `label.` with format alphanumeric, length 20 and 5 occurrences.

3. #ARRAY (N7.2/1:5,10:12,1:4)
   Defines an array with format/length N7.2 and three array dimensions with 5 occurrences in the first, 3 occurrences in the second and 4 occurrences in the third dimension.

4. FIELD (label./i:i + 5) or label.FIELD(i:i + 5)
   Defines an array from a database field referencing the statement marked by `label.`.

   `FIELD` represents a multiple-value field or a field from a periodic group where `i` specifies the offset index within the database occurrence. The size of the array within the program is defined as 6 occurrences (`i:i + 5`). The database offset index is specified as a variable to allow for the positioning of the program array within the occurrences of the multiple-value field or periodic group. For any repositioning of `i`, a new access must be made to the database using a `GET` or `GET SAME` statement.

Natural allows the definition of arrays where the index does not begin with `1`. At runtime, Natural checks that index values specified in the reference do not exceed the maximum size of dimensions as specified in the definition.

Notes:

1. For compatibility with earlier Natural versions, an array range may be specified using a hyphen (-) instead of a colon (:).
2. A mix of both notations, however, is not permitted.
3. The hyphen notation is only allowed in reporting mode (but not in a `DEFINE DATA` statement).

The maximum index value is 1,073,741,824 (1 GB).

Simple arithmetic expressions using the plus (+) and minus (-) operators may be used in index references. When arithmetic expressions are used as indices, these operators must be preceded and followed by a blank.

Arrays in group structures are resolved by Natural field by field, not group occurrence by group occurrence.

#### Example of Group Array Resolution:

    DEFINE DATA LOCAL
     1 #GROUP (1:2)
       2 #FIELDA (A5/1:2)
       2 #FIELDB (A5)
     END-DEFINE
     ...

If the group defined above were output in a `WRITE` statement:

    WRITE #GROUP (*)

the occurrences would be output in the following order:

    #FIELDA(1,1) #FIELDA(1,2) #FIELDA(2,1) #FIELDA(2,2) #FIELDB(1) #FIELDB(2)

and not:

    #FIELDA(1,1) #FIELDA(1,2) #FIELDB(1) #FIELDA(2,1) #FIELDA(2,2) #FIELDB(2)

#### Array Referencing - Examples:

1. #ARRAY (1)
   References the first occurrence of a one-dimensional array.

2. #ARRAY (7:12)
   References the seventh to twelfth occurrence of a one-dimensional array.

3. #ARRAY (i + 5)
   References the i+fifth occurrence of a one-dimensional array.

4. #ARRAY (5,3:7,1:4)
   Reference is made within a three dimensional array to occurrence 5 in the first dimension, occurrences 3 to 7 (5 occurrences) in the second dimension and 1 to 4 (4 occurrences) in the third dimension.

5. An asterisk may be used to reference all occurrences within a dimension:

       DEFINE DATA LOCAL
       1 #ARRAY1 (N5/1:4,1:4)
       1 #ARRAY2 (N5/1:4,1:4)
       END-DEFINE
       ...
       ADD #ARRAY1 (2,*) TO #ARRAY2 (4,*)
       ...

### Using a Slash before an Array Occurrence

If a variable name is followed by a 4-digit number enclosed in parentheses, Natural interprets this number as a line-number reference to a statement. Therefore a 4-digit array occurrence must be preceded by a slash (/) to indicate that it is an array occurrence; for example:

    #ARRAY(/1000)

not:

    #ARRAY(1000)

because the latter would be interpreted as a reference to source code line 1000.

If an index variable name could be misinterpreted as a format/length specification, a slash (/) must be used to indicate that an index is being specified. If, for example, the occurrence of an array is defined by the value of the variable N7, the occurrence must be specified as:

    #ARRAY (/N7)

not:

    #ARRAY (N7)

because the latter would be misinterpreted as the definition of a 7-byte numeric field.

## Referencing a Database Array

The following topics are covered below:

- Referencing Multiple-Value Fields and Periodic-Group Fields

- Referencing Arrays Defined with Constants

- Referencing Arrays Defined with Variables

- Referencing Multiple-Defined Arrays

Note
Before executing the following example programs, please run the program `INDEXTST` in the library `SYSEXPG` to create an example record that uses 10 different language codes.

### Referencing Multiple-Value Fields and Periodic-Group Fields

A multiple-value field or periodic-group field within a view/DDM may be defined and referenced using various index notations.

For example, the first to tenth values and the Ith to Ith+10 values of the same multiple-value field/periodic-group field of a database record:

    DEFINE DATA LOCAL
    1 I (I2)
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 LANG (1:10)
      2 LANG (I:I+10)
    END-DEFINE

or:

    RESET I (I2)
    ...
    READ EMPLOYEES
    OBTAIN LANG(1:10) LANG(I:I+10)

Notes:

1. The same lower bound index may only be used once per array (this applies to constant indexes as well as variable indexes).
2. For an array definition using a variable index, the lower bound must be specified using the variable by itself, and the upper bound must be specified using the same variable plus a constant.

### Referencing Arrays Defined with Constants

An array defined with constants may be referenced using either constants or variables. The upper bound of the array cannot be exceeded. The upper bound will be checked by Natural at compilation time if a constant is used.

#### Reporting Mode Example:

    ** Example 'INDEX1R': Array definition with constants  (reporting mode)
    ***********************************************************************
    *
    READ (1) EMPLOYEES WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      OBTAIN LANG (1:10)
      /*
      WRITE 'LANG(1:10):' LANG (1:10) //
      WRITE 'LANG(1)   :' LANG (1)    /  'LANG(5:9) :' LANG (5:9)
    LOOP
    *
    END

#### Structured Mode Example:

    ** Example 'INDEX1S': Array definition with constants (structured mode)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 FIRST-NAME
      2 CITY
      2 LANG (1:10)
    END-DEFINE
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      WRITE 'LANG(1:10):' LANG (1:10) //
      WRITE 'LANG(1)   :' LANG (1)    /  'LANG(5:9) :' LANG (5:9)
    END-READ
    END

If a multiple-value field or periodic-group field is defined several times using constants and is to be referenced using variables, the following syntax is used.

#### Reporting Mode Example:

    ** Example 'INDEX2R': Array definition with constants (reporting mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (1:5)
      2 LANG (4:8)
    END-DEFINE
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      DISPLAY 'NAME'         NAME
              'LANGUAGE/1:3' LANG (1.1:3)
              'LANGUAGE/6:8' LANG (4.3:5)
    LOOP
    *
    END

#### Structured Mode Example:

    ** Example 'INDEX2S': Array definition with constants (structured mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (1:5)
      2 LANG (4:8)
    END-DEFINE
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      DISPLAY 'NAME'         NAME
              'LANGUAGE/1:3' LANG (1.1:3)
              'LANGUAGE/6:8' LANG (4.3:5)
    END-READ
    *
    END

### Referencing Arrays Defined with Variables

Multiple-value fields or periodic-group fields in arrays defined with variables must be referenced using the same variable.

#### Reporting Mode Example:

    ** Example 'INDEX3R': Array definition with variables (reporting mode)
    ***********************************************************************
    RESET I (I2)
    *
    I := 1
    READ (1) EMPLOYEES WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      OBTAIN LANG (I:I+10)
      /*
      WRITE 'LANG(I)      :' LANG (I) /
            'LANG(I+5:I+7):' LANG (I+5:I+7)
    LOOP
    *
    END

#### Structured Mode Example:

    ** Example 'INDEX3S': Array definition with variables (structured mode)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 I (I2)
    *
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (I:I+10)
    END-DEFINE
    *
    I := 1
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      WRITE 'LANG(I)      :' LANG (I) /
            'LANG(I+5:I+7):' LANG (I+5:I+7)
    END-READ
    END

If a different index is to be used, an unambiguous reference to the first encountered definition of the array with variable index must be made. This is done by qualifying the index expression as shown below.

#### Reporting Mode Example:

    ** Example 'INDEX4R': Array definition with variables (reporting mode)
    ***********************************************************************
    RESET I (I2) J (I2)
    *
    I := 2
    J := 3
    *
    READ (1) EMPLOYEES WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      OBTAIN LANG (I:I+10)
      /*
      WRITE 'LANG(I.J)  :' LANG (I.J) /
            'LANG(I.1:5):' LANG (I.1:5)
    LOOP
    *
    END

#### Structured Mode Example:

    ** Example 'INDEX4S': Array definition with variables (structured mode)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 I (I2)
    1 J (I2)
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (I:I+10)
    END-DEFINE
    *
    I := 2
    J := 3
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      WRITE 'LANG(I.J)  :' LANG (I.J) /
            'LANG(I.1:5):' LANG (I.1:5)
    END-READ
    END

The expression `I.` is used to create an unambiguous reference to the array definition and "positions" to the first value within the read array range (`LANG(I.1:5)`).

The current content of `I` at the time of the database access determines the starting occurrence of the database array.

### Referencing Multiple-Defined Arrays

For multiple-defined arrays, a reference with qualification of the index expression is usually necessary to ensure an unambiguous reference to the desired array range.

#### Reporting Mode Example:

    ** Example 'INDEX5R': Array definition with constants (reporting mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL                  /* For reporting mode programs
    1 EMPLOY-VIEW VIEW OF EMPLOYEES    /* DEFINE DATA is recommended
      2 NAME                           /* to use multiple definitions
      2 CITY                           /* of same database field
      2 LANG (1:10)
      2 LANG (5:10)
    *
    1 I (I2)
    1 J (I2)
    END-DEFINE
    *
    I := 1
    J := 2
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      WRITE 'LANG(1.1:10) :' LANG (1.1:10) /
            'LANG(1.I:I+2):' LANG (1.I:I+2) //
      WRITE 'LANG(5.1:5)  :' LANG (5.1:5)  /
            'LANG(5.J)    :' LANG (5.J)
    LOOP
    END

#### Structured Mode Example:

    ** Example 'INDEX5S': Array definition with constants (structured mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (1:10)
      2 LANG (5:10)
    *
    1 I (I2)
    1 J (I2)
    END-DEFINE
    *
    *
    I := 1
    J := 2
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
      WRITE 'LANG(1.1:10) :' LANG (1.1:10) /
            'LANG(1.I:I+2):' LANG (1.I:I+2) //
      WRITE 'LANG(5.1:5)  :' LANG (5.1:5)  /
            'LANG(5.J)    :' LANG (5.J)
    END-READ
    END

A similar syntax is also used if multiple-value fields or periodic-group fields are defined using index variables.

#### Reporting Mode Example:

    ** Example 'INDEX6R': Array definition with variables (reporting mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 I (I2) INIT <1>
    1 J (I2) INIT <2>
    1 N (I2) INIT <1>
    1 EMPLOY-VIEW VIEW OF EMPLOYEES    /* For reporting mode programs
      2 NAME                           /* DEFINE DATA is recommended
      2 CITY                           /* to use multiple definitions
      2 LANG (I:I+10)                  /* of same database field
      2 LANG (J:J+5)
      2 LANG (4:5)
    *
    END-DEFINE
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
    *
      WRITE 'LANG(I.I)    :' LANG (I.I) /
            'LANG(1.I:I+2):' LANG (I.I:I+10) //
    *
      WRITE 'LANG(J.N)    :' LANG (J.N) /
            'LANG(J.2:4)  :' LANG (J.2:4) //
    *
      WRITE 'LANG(4.N)    :' LANG (4.N) /
            'LANG(4.N:N+1):' LANG (4.N:N+1) /
    LOOP
    END

#### Structured Mode Example:

    ** Example 'INDEX6S': Array definition with variables (structured mode)
    **                   (multiple definition of same database field)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 I (I2) INIT <1>
    1 J (I2) INIT <2>
    1 N (I2) INIT <1>
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 LANG (I:I+10)
      2 LANG (J:J+5)
      2 LANG (4:5)
    *
    END-DEFINE
    *
    READ (1) EMPLOY-VIEW WITH NAME = 'WINTER' WHERE CITY = 'LONDON'
    *
      WRITE 'LANG(I.I)    :' LANG (I.I) /
            'LANG(1.I:I+2):' LANG (I.I:I+10) //
    *
      WRITE 'LANG(J.N)    :' LANG (J.N) /
            'LANG(J.2:4)  :' LANG (J.2:4) //
    *
      WRITE 'LANG(4.N)    :' LANG (4.N) /
            'LANG(4.N:N+1):' LANG (4.N:N+1) /
    END-READ
    END

## Referencing the Internal Count for a Database Array (C* Notation)

It is sometimes necessary to reference a multiple-value field and/or a periodic group without knowing how many values/occurrences exist in a given record. Adabas maintains an internal count of the number of values of each multiple-value field and the number of occurrences of each periodic group. This count may be referenced by specifying `C*` immediately before the field name.

#### Note concerning databases other than Adabas:

SQL | With SQL databases, the `C*` notation cannot be used.
VSAM | With VSAM, the `C*` notation does not return the number of values/occurrences but the maximum occurrence/value as defined in the DDM (`MAXOCC`).

See also the data-area-editor line command `.*` (in the Editors documentation).

The explicit format and length permitted to declare a `C*` field is either

- integer (I) with a length of 2 bytes (I2) or 4 bytes (I4),

- numeric (N) or packed (P) with only integer (but no precision) digits; for example (N3).

If no explicit format and length is supplied, format/length (N3) is assumed as default.

#### Examples:

`C*LANG` | Returns the count of the number of values for the multiple-value field `LANG`.
`C*INCOME` | Returns the count of the number of occurrences for the periodic group `INCOME`.
`C*BONUS(1)` | Returns the count of the number of values for the multiple-value field `BONUS` in periodic group occurrence 1 (assuming that `BONUS` is a multiple-value field within a periodic group.)

#### Example Program Using the C* Variable:

    ** Example 'CNOTX01': C* Notation
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPL-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 C*INCOME
      2 INCOME
        3 SALARY  (1:5)
        3 C*BONUS (1:2)
        3 BONUS   (1:2,1:2)
      2 C*LANG
      2 LANG      (1:2)
    *
    1 #I (N1)
    END-DEFINE
    *
    LIMIT 2
    READ EMPL-VIEW BY CITY
      /*
      WRITE NOTITLE 'NAME:' NAME /
           'NUMBER OF LANGUAGES SPOKEN:' C*LANG 5X
           'LANGUAGE 1:' LANG (1) 5X
           'LANGUAGE 2:' LANG (2)
      /*
      WRITE 'SALARY DATA:'
      FOR #I FROM 1 TO C*INCOME
        WRITE 'SALARY' #I SALARY (1.#I)
      END-FOR
      /*
      WRITE 'THIS YEAR BONUS:' C*BONUS(1)  BONUS (1,1) BONUS (1,2)
          / 'LAST YEAR BONUS:' C*BONUS(2)  BONUS (2,1) BONUS (2,2)
      SKIP 1
    END-READ
    END

Output of Program `CNOTX01`:

    NAME: SENKO
    NUMBER OF LANGUAGES SPOKEN:    1     LANGUAGE 1: ENG     LANGUAGE 2:
    SALARY DATA:
    SALARY  1      36225
    SALARY  2      29900
    SALARY  3      28100
    SALARY  4      26600
    SALARY  5      25200
    THIS YEAR BONUS:    0          0          0
    LAST YEAR BONUS:    0          0          0

    NAME: CANALE
    NUMBER OF LANGUAGES SPOKEN:    2     LANGUAGE 1: FRE     LANGUAGE 2: ENG
    SALARY DATA:
    SALARY  1     202285
    THIS YEAR BONUS:    1      23000          0
    LAST YEAR BONUS:    0          0          0

### C* for Multiple-Value Fields Within Periodic Groups

For a multiple-value field within a periodic group, you can also define a `C*` variable with an index range specification.

The following examples use the multiple-value field `BONUS`, which is part of the periodic group `INCOME`. All three examples yield the same result.

#### Example 1 - Reporting Mode:

    ** Example 'CNOTX02': C* Notation (multiple-value fields)
    ************************************************************************
    *
    LIMIT 2
    READ EMPLOYEES BY CITY
      OBTAIN C*BONUS (1:3)
             BONUS   (1:3,1:3)
      /*
      DISPLAY NAME C*BONUS (1:3) BONUS (1:3,1:3)
    LOOP
    *
    END

#### Example 2 - Structured Mode:

    ** Example 'CNOTX03': C* Notation (multiple-value fields)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPL-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 INCOME    (1:3)
        3 C*BONUS
        3 BONUS   (1:3)
    END-DEFINE
    *
    LIMIT 2
    READ EMPL-VIEW BY CITY
      /*
      DISPLAY NAME C*BONUS (1:3) BONUS (1:3,1:3)
    END-READ
    *
    END

#### Example 3 - Structured Mode:

    ** Example 'CNOTX04': C* Notation (multiple-value fields)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPL-VIEW VIEW OF EMPLOYEES
      2 NAME
      2 CITY
      2 C*BONUS  (1:3)
      2 INCOME   (1:3)
        3 BONUS  (1:3)
    END-DEFINE
    *
    LIMIT 2
    READ EMPL-VIEW BY CITY
      /*
      DISPLAY NAME C*BONUS (*) BONUS (*,*)
    END-READ
    *
    END

| Warning: As the Adabas format buffer does not permit ranges for count fields, they are generated as individual fields; therefore a `C*` index range for a large array may cause an Adabas format buffer overflow.

## Qualifying Data Structures

To identify a field when referencing it, you may qualify the field; that is, before the field name, you specify the name of the level-1 data element in which the field is located and a period.

If a field cannot be identified uniquely by its name (for example, if the same field name is used in multiple groups/views), you must qualify the field when you reference it.

The combination of level-1 data element and field name must be unique.

#### Example:

    DEFINE DATA LOCAL
    1 FULL-NAME
      2 LAST-NAME (A20)
      2 FIRST-NAME (A15)
    1 OUTPUT-NAME
      2 LAST-NAME (A20)
      2 FIRST-NAME (A15)
    END-DEFINE
    ...
    MOVE FULL-NAME.LAST-NAME TO OUTPUT-NAME.LAST-NAME
    ...

The qualifier must be a level-1 data element.

#### Example:

    DEFINE DATA LOCAL
    1 GROUP1
      2 SUB-GROUP
        3 FIELD1 (A15)
        3 FIELD2 (A15)
    END-DEFINE
    ...
    MOVE 'ABC' TO GROUP1.FIELD1
    ...

#### Qualifying a Database Field:

If you use the same name for a user-defined variable and a database field (which you should not do anyway), you must qualify the database field when you want to reference it.

| Warning: If you do not qualify the database field when you want to reference it, the user-defined variable will be referenced instead.

## Examples of User-Defined Variables

    DEFINE DATA LOCAL
    1 #A1 (A10)       /* Alphanumeric, 10 positions.
    1 #A2 (B4)        /* Binary, 4 positions.
    1 #A3 (P4)        /* Packed numeric, 4 positions and 1 sign position.
    1 #A4 (N7.2)      /* Unpacked numeric,
                      /* 7 positions before and 2 after decimal point.
    1 #A5 (N7.)       /* Invalid definition!!!
    1 #A6 (P7.2)      /* Packed numeric, 7 positions before and 2 after decimal point
                      /* and 1 sign position.
    1 #INT1 (I1)      /* Integer, 1 byte.
    1 #INT2 (I2)      /* Integer, 2 bytes.
    1 #INT3 (I3)      /* Invalid definition!!!
    1 #INT4 (I4)      /* Integer, 4 bytes.
    1 #INT5 (I5)      /* Invalid definition!!!
    1 #FLT4 (F4)      /* Floating point, 4 bytes.
    1 #FLT8 (F8)      /* Floating point, 8 bytes.
    1 #FLT2 (F2)      /* Invalid definition!!!
    1 #DATE (D)       /* Date (internal format/length P6).
    1 #TIME (T)       /* Time (internal format/length P12).
    1 #SWITCH (L)     /* Logical, 1 byte (TRUE or FALSE).
                      /*
    END-DEFINE

### On this page

- Definition of Variables
- Referencing of Database Fields Using (r) Notation
- Renumbering of Source-Code Line Number References
- Format and Length of User-Defined Variables
- Special Formats
- Index Notation
- Referencing a Database Array
- Referencing the Internal Count for a Database Array (C* Notation)
- Qualifying Data Structures
- Examples of User-Defined Variables