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:

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


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

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 nn.m, where nn 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 nn and m must not exceed 29, and the value of m must not exceed 7.

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

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.

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:

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:

Tamino With XML databases, the C* notation cannot be used.
SQL With SQL databases, the C* notation cannot be used.

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