DIM

ANSI

The DIM instruction defines a character string variable or an array of character string variables. If defining an array, any number of the array items may be initialized. The instruction uses one of the following formats:

Where:

label

Optional. A Data Definition Label.

%

Optional. Denotes the item as being GLOBAL.

%%

Optional. Denotes the item as GLOBAL but does not initialize it in any way.

*

Optional. Denotes the item or file as being COMMON.

size

Required. A decimal constant or EQUATEd value indicating the variable size.

arraysize

Optional. An Integer decimal constant, CONST variable or equated value indicating the number of array items.

????

Optional. The initialization for the appropriate array, based on the order given.

target

Optional. A previously declared DIM variable that initializes the array.

^

Optional. Denotes the item as being a POINTER.

@

Optional. Denotes the item as being a POINTER.

variable

Required. The name of a previously defined variable of the same type.

mmm

Optional. A array element size.

Flags Affected: NONE

Note the following:

1. DIM variables are blank filled unless an initialized array.

2. The Physical Length is set to the declared size while both the Length Pointer and Form Pointer are set to zero indicating a Null String. If the DIM is an initialized array, the Form Pointer is set to one and the Length Pointer is set to the last character of the initialized contents (that may be less than the Physical Length) for each appropriate array item.

3. DIMs up to 32MB are supported. When a DIM size larger than 65535 is specified, the DIM data construct is implemented as an auto load DIM variable. This helps to keep the object code file size as small as possible. See the compiler option to change the default auto load DIM variable size. If a user application requires a DIM data variable with a size larger than 32MB, a DIM pointer can be used and an DMAKE creates a DIM with a size up to 2GB (2147483647 value). This size is limited by the OS memory allowed for the PLB program space. The runtime 'm' or 'MV' command line options increases the PLB program memory size. Note that:

    If WRITE operations are performed using very large DIM variables, FILE variables with small buffer sizes should be avoided because it can result in a lengthy IO operation.

    If a WRITE operation is performed using a very large DIM variable, opening a FILE variable in a SHARENF or EXCLUSIVE mode can give the best performance.

4. The processing for the auto load DIM pointers only allocates a DIM pointer when the variable is first used and not allocated when the PLC program is loaded. Therefore, there is no wasted memory allocations used for auto load DIM pointers that are never used in a program.

Example:

 

In this example, the 'B' pointer is not used. Therefore, there is never any memory allocated for the 1000 byte variable. Also, the memory allocation for the 'A' variable only occurs when the variable first used in the program.

 

A      DIM      ^100      ;Auto load DIM pointer

B      DIM      ^1000      ;Auto Load DIM pointer

C      INIT      "Test"

.

     MOVE      C,A      ;'A' DIM is allocated when 1st used.

.

     DISPLAY      "A:",*LL,A

 

5. The processing for the static auto load DIM variables only allocates memory when the variable is first used and not when the PLC program is loaded. Thus, there is no wasted memory allocations used for auto load DIM variables that are never used. Also, note that the PLBCMP compiler gives a complication error when a static auto load DIM variable is encountered in an instruction that uses a pointer as a destination.

Example:

 

Also, the memory allocation for the 'B' variable only occurs when the variable first used in the program.

 

B      DIM      1000000      ;Auto Load DIM variable

C      INIT      "Test"

.

     MOVE      C,B      ;'B' DIM is allocated when 1st used.

.

     DISPLAY      "A:",*LL,A

 

6. String literals that initialize a DIM must be enclosed in quotes and surrounded by parentheses, while valid Ctrl codes need only be surrounded by parentheses.

7. Multi-dimension arrays (format 4) are supported up to a maximum of fourteen dimensions (three in ANSI mode).

8. The ^ denotes a Pointer Variable.

9. If the % form is used, the data item is placed in the Global Data Area. The variable is then available to other programs that also declared it with the percent form. Global Data Items are available with PLBCMP only.

10. If the %% form is used, the data label is placed in the Global Data Area but no initialization takes place if it has not already been defined in the Global Data Area. If an array data label is placed in the Global Data Area, when initialized, it must have the same number of elements in the array. Global Data Items are available with PLBCMP only.

11. If the * form is used, the data item is in common with other programs and all of the rules of COMMON must be followed.

12. If an array is defined, each element may have a label.

13. If WRITE operations are performed using very large DIM variables, FILE variables with small buffer sizes should be avoided because it can result in a long time to perform the IO operation.

14. If a WRITE operation is performed using a very large DIM variable, opening the FILE variable in a SHARENF or EXCLUSIVE mode can give the best performance time to perform the IO operation.

15. Format (12) provides an alternative array initialization syntax. Support for Format (12) is enabled only when the compiler option zc=3 is used. The {????} initialization for format (12) can be a string literal or a character literal.

16. Format (13) provides an alternative DIM syntax to declare a one-dimensional array of DIM pointers.

17. The syntax formats for (14), (15), and (16) are used to declare a DIM array-pointer construct that can contain the address of a one-dimensional, two-dimensional, and three-dimensional DIM array, respectively.

For example.

D1arr DIM 2(4) //one-dimensional array

D2arr DIM 2(3,4) //two-dimensional array

D3arr DIM 2(2,3,4) //three-dimensional array

.

pArr1 DIM @() //one-dimensional DIM array pointer

pArr2 DIM @(,) //two-dimensional DIM array pointer

pArr3 DIM @(,,) //three-dimensional DIM array pointer

.

          MOVEADR D1arr, pArr1

          MOVEADR D2arr, pArr2

          MOVEADR D3arr, pArr3

See Also: Example Code, INIT, Character String Variables, Data Definitions