System Functions

DIM( )

Generate String/Get Array Size

Formats

1.

Generate or Initialize String:

DIM (len[,fill$][,ERR=stmtref])

2.

Read Total Elements in Array:

DIM (READ NUM(array_name[$][,subscript] ))

3.

Get Maximum Index for an Array:

DIM (READ MAX(array_name[$][,subscript] ))

4.

Get Minimum Index for an Array:

DIM (READ MIN(array_name[$][,subscript] ))

The following were added in PxPlus v8.00:

5.

Find Max/Min Value in Array:

DIM (FIND [ MIN | MAX ] ( array_name[$] ))

6.

Scan Array for Value:

DIM (FIND array_name[$]=comparison value[$], ERR=stmtref)

7.

Total Numeric Array:

DIM (ADD array_name)

The following was added in PxPlus v9.00:

8.

Return Associated Index:

DIM (INDEX array_name[$] [keyword$] )

The following were added in PxPlus v11.00:

9.

Return Key from Index:

DIM (KEY array_name[$] [index] )

10.

Remove Key:

DIM (DROP array_name[$] [keyword$] )

11.

Generate JSON Data from Array:

DIM (LIST [ SORT | EDIT ] array_name[$][ {ALL} ] [ WITH NUM(namelist$) ] )

The following was added in PxPlus 2016:

12.

Get an Elements Type-Flag:

strvar$ = DIM (CLASS array$[ strName$ ] )

Where: 

array$

String array whose element you want to retrieve.

array_name[$]

Name of a previously dimensioned array.

comparison

Type of comparison to be done against each element of the array.

fill$

Text string or value that will be used to fill the variable up to the length specified. String expression.

[index]

Numeric index for the element in the array whose keyword is to be returned.

Note:
The square brackets around the keyword are required.

[keyword$]

Keyword associated with the element in the array whose index is to be returned or dropped.

Note:
The square brackets around the keyword are required.

len

Desired length of the string variable. Numeric expression, integer.

stmtref

Program line number or statement label to which to transfer control.

strName$

String expression or literal containing the index of the element being referenced.

strvar$

String variable that will receive either an "N" (numeric) or "S" (string).

subscript

Array's dimensions (first, second or third).

value[$]

Value to compare each element against. Type of value must match the type of array (string values for string array, numeric values for numeric array).

WITH NUM(namelist$)

Optional list of subscript names, whose values are not to be quoted in JSON option.

Returns

Initialized string, or information about dimensions of array.

Description

Use the DIM( ) function to generate or initialize a string. You can also use it to obtain information about the size of an array you have already defined using the DIM directive.

Format 1

Generate or Initialize String

DIM(len[,fill$][,ERR=stmtref])

Use this format to generate or initialize a string whose length you specify. The function fills the string by using the value for fill$.

Note:
This format of the function behaves almost like the DIM directive's format to initialize strings. However, instead of repeating only the first character of the string, as in the directive, the function repeats the complete value of the fill string. See DIM directive for the format to initialize strings.

If you omit the fill string, the system uses spaces as fill characters:

print ":",dim(11,"*Cat"),":"

->run
*Cat*Cat*Ca:

     print 'CS',"A Title",@(0,1),dim(80,"-")
rem The dim( ) above returns a string of hyphens "-" 80 characters long

->run
A Title
--------------------------------------------------------------------------------

See Also

'+S' & '-S' Substitute Solid Lines On/Off

Formats 2, 3 and 4

Read Dimensions (Size) of Array

Use Formats 2, 3 and 4 of the DIM( ) function to read a given array's total number of elements, the minimum element's number and the maximum element's number. If the variable you specify is not an array, NUM and MIN will return 0, MAX will return -1.

DIM(READ NUM(array_name[$][,subscript]))

The DIM(READ NUM( )) function is used to read the total number of elements in a dimensioned array:

dim X[0:15]
print dim(read num(X))

->run
16

DIM(READ MAX(array_name[$][,subscript]))

The DIM(READ MAX( )) function is used to read the maximum element number in a dimensioned array:

dim X[0:15]
print dim(read max(X))

->run
15

DIM(READ MIN(array_name[$][,subscript]))

The DIM(READ MIN( )) function is used to read the minimum element number in a dimensioned array:

dim X[0:15]
print dim(read min(X))

->run
0

Format 5

Find Max/Min Value in Array

DIM (FIND [ MIN | MAX ] ( array_name[$] ))

(added in PxPlus v8.00)

Use this format to scan an array to determine the index of the highest or lowest element. The return value will be the index into the array.

Example:

Assuming an array X$ contained 'Cat', 'Dog', 'Zebra', 'Ant', 'Pig' in elements 1 through 5:

 

dim (find max(X$))

This would yield 3 (for Zebra).

 

dim (find min(X$))

This would yield 4 (for Ant).

Format 6

Scan Array for Value

DIM (FIND array_name[$]=comparison value[$], ERR=stmtref)

(added in PxPlus v8.00)

Use this format to locate a value in an array that will match an expression. The return value will be the index into the array. If not found, an Error 11 will be generated; therefore, the ERR= branch should be specified on the function call.

Example:

Assuming an array X$ contained 'Cat', 'Dog', 'Zebra', 'Ant', 'Pig' in elements 1 through 5:

 

dim (find X$ = "Dog"

This would yield 2.

 

dim (find X$ > "Man")

This would yield 3 (for Zebra).

Format 7

Total Numeric Array

DIM (ADD array_name)

(added in PxPlus v8.00)

Use this format to quickly total a numeric array.

Format 8

Lookup and Return Index for Given Keyword

DIM (INDEX array_name[$] [keyword$] )

(added in PxPlus v9.00)

This format can be used against any associative array in order to return the index of the element for the specified keyword. If no element with the specified keyword is found, the return value will be 0 (zero).

Format 9

Lookup and Return Keyword for Given Index

DIM (KEY array_name[$] [index] )

(added in PxPlus v11.00)

This format can be used against any associative array in order to return the keyword of the element for the specified index. If no keyword is assigned to the specified element, an Error #11 will be generated.

Format 10

Lookup and Remove the Keyword from an Array

DIM (DROP array_name[$] [keyword$] )

(added in PxPlus v11.00)

This format can be used against any associative array to remove the specified keyword. If no element with the specified keyword is found, the return value will be 0 (zero); otherwise, the function will return the index of the element whose key was dropped.

Note:
Using the DIM (DROP xxx["keyword"] ) format does not remove the element from the array but only removes the associated keyword.

Format 11

Generate JSON Data from Array

DIM (LIST [ SORT | EDIT ] array_name[$][ {ALL} ] [ WITH NUM(namelist$) ] )

(added in PxPlus v11.00)

The DIM (LIST xxx {ALL}) format can be used against any associative array in order to generate and return all the elements in the array and their values in a JSON string. This JSON string can then be used to subsequently load/reload an array or for passing the data to an external application.

A JSON string consists of a series of comma-separated name/value pairs where the variable name is separated from the value using a : (colon):

Example:

X$["FirstName"] = "John"
X$["LastName"] = "Doe"

When represented as a JSON string would become:

"FirstName": "John", "LastName":"Doe"

If the value is numeric, the quotes are not needed.

The function has two optional keywords that may be supplied after LIST:

SORT: The output will be sorted alphabetically.

EDIT: The output will be output with each item on a separate line and two spaces indentation for each level.

Structured data can also be represented with the inclusion of a period in the associative name:

X$["Company"] = "PVX Plus Technologies"
X$["Address.Street"] = "45B West Wilmot"
X$["Address.City"] = "Richmond Hill"
X$["Address.Province"] = "Ontario"
X$["Phone"] = "888-975-7587"

When represented as a JSON string generated by DIM(LIST EDIT X${ALL}) would become:

"Company":"PVX Plus Technologies"
"Address":{
  "Street":"45B West Wilmot",
  "City":"Richmond Hill",
  "Province":"Canada" },
"Phone":"888-975-7587"

Null/empty arrays are supported by including a ".0" element in the array:

<pre>
->x$="{ var1: ""someString"", var2: 1.3 }"
->dim load json$=x$
->json$["varArray.0"]=""
->print dim(list edit json$)
{
  "var1":"someString",
  "var2":1.3,
  "varArray":[ ]
}
</pre>

Note:
The empty array will be included only if no other elements other than .0 are defined in the array.

(Support for null/empty arrays for JSON was added in PxPlus 2019 Update 2.)

Suppressing QUOTES for Numeric Values

When outputting numeric data in JSON, you generally do not want the values to be quoted. This can be accomplished by adding WITH NUM("name, name, name,...") to the function parameters. The array elements whose names are supplied will not have their values quoted.

Generally, this is used for numeric data; however, it can also be used for the value true and false. By default, when an array is loaded using the DIM LOAD directive, the system will attempt to remember if the value coming in had quotes or not. If there were no quotes coming in, the variable will not have quotes when output.

Format 12

Get an Elements Type-Flag

strvar$ = DIM (CLASS array$[ strName$ ] )

(added in PxPlus 2016)

You can determine the type-flag of any element in a string associative array using the DIM (CLASS array$) function. If the element does not exist, it will be created dynamically, and the type-flag of "S" will be returned.