Dyalog APL 13.2 Help

Welcome to Dyalog APL's online Help and Documentation for Version 13.2.

Documentation is available in two formats: Help systems and PDF files.

Help Systems:

  • If you are using Dyalog APL under Windows, then the documentation is referenced under the Help Menuitem in the session. Note also that hitting <F1> when the cursor is over a primitive function or operator or a system function etc. will bring up an appropriate page in the help system.
  • There is also online help at http://help.dyalog.com/13.2.
  • These two help systems contain the equivalent of the Dyalog APL Object Reference, the Dyalog APL Language Reference and the Dyalog APL Programmer’s Guide, and the Release Notes from recent versions of Dyalog APL.

PDF Files:

  • All of the documentation supplied with a release of Dyalog APL resides in the help subdirectory of the Dyalog installation.
  • If you wish to print any of the manuals which form part of the Help system, then PDFs suitable for printing are available at http://docs.dyalog.com/13.2; the PDFs supplied with the release are intended for on-screen browsing.

From Version 13.1 onwards Dyalog intends to update the manuals and help files throughout the period that a version of Dyalog APL is on full support.

The latest versions of the files will be available at http://docs.dyalog.com/13.2.

If you report an issue with the documentation, could you please include the following information: Version 13.2, revision 22186.


Language Elements

Table 1: Primitive Functions

+ | - | × | ÷ | | | ⌈ | ⌊ | * | ⍟ |
○ | ! | ? | ~ | ∧ | ∨ | ⍲ | ⍱ |  |
< | ≤ | = | > | ≥ | ≠ | ≡ | ≢ |  |
⍴ | , | ⍪ | ⌽ | ⊖ | ⍉ | ↑ | ↓ |  |
⊂ | ⊃ | ∊ | ⍷ | / | ⌿ | \ | ⍀ |  |
∩ | ∪ | ⍳ | ⌷ | ⍋ | ⍒ | ⍎ | ⍕ | ⊥ | ⊤
⊣ | ⊢ | ⌹ | ⍬ | → |  |  |  |  |

Table 2: Primitive Operators

¨ | ⍨ | ∘ | . | ∘. | /
⌿ | \ | ⍀ | ⍣ | & | ⌶
⍠ |  |  |  |  |

Table 3: Other Language Elements

Brackets
Special Syntax
Variables
Namespaces
Defined Fns & Ops
Dynamic Fns & Ops
MultiThreading
Object Oriented Programming
Control Structures
Triggers
System Functions
System Commands
Error Messages


Brackets ()[]{}

Round Parentheses

Round brackets are used in APL expressions to control the order of execution. A right parenthesis is also used to introduce a System Command.

Square Brackets

Square brackets are have two distinct meanings in APL. They are used to select sub-arrays from an n-dimensional array and to indicate an axis along which a function (operand) is to apply. See Bracket Indexing and Bracket Axis Operator.

Curly Brackets

Curly brackets have two distinct meanings in Dyalog APL. They are used to indicate shy results and optional left arguments in defined functions. They are also used to enclose the definition of a dynamic function. See Model Syntax and D-functions.

Language Elements


Special Symbols

Hash is a namespace identifier.
# Root | ## Parent
Alpha identifies left arguments of dynamic functions/operators.
⍺ Left Argument | ⍺⍺ Left Operand
Omega identifies right arguments of dynamic functions/operators.
⍵ Right Argument | ⍵ Right Operand
Del is used for self-reference in dynamic functions/operators (as well as for the traditional APL Line Editor).
∇ Function Self | ∇∇ Operator Self
Quotation marks are used to surround character strings.
' APL Quote | '' Empty Vector
Diamond character is used to separate APL statements on one line.
⋄ Statement Separator
Lamp symbol is used to identify following comments.
⍝ Comment Symbol
Colon is used to indicate end of line label or start of control word.
: End of Label | : Start Control Word
Semicolon is used to separate index selection arrays in simple indexing, and to separate local names in the header of defined functions/operators.
; Index Separator | ; Localize Name
High Minus or Overbar is used to indicate that a number is negative.
¯ Negative

The following National Language characters may be used in names:

   À Ä Å Æ É Ñ Ö Ø Ü ß
   à á â ä å æ ç è é ê ë
   í î ï ñ ó ô ö ø ù ú û ü

The three special characters

   _ ∆ ⍙

can also be used in names.


Arrays

A Dyalog APL data structure is called an array. An array is a rectangular arrangement of items, each of which may be a single number, a single character, a namespace reference (ref), another array, or the ⎕OR of an object. An array which is part of another array is also known as a subarray.

An array has two properties; structure and data type. Structure is identified by rank, shape, and depth.

Rank

An array may have 0 or more axes or dimensions. The number of axes of an array is known as its rank. Dyalog APL supports arrays with a maximum of 15 axes.

  • An array with 0 axes (rank 0) is called a scalar.
  • An array with 1 axis (rank 1) is called a vector.
  • An array with 2 axes (rank 2) is called a matrix.
  • An array with more than 2 axes is called a multi-dimensional array.

Shape

Each axis of an array may contain zero or more items. The number of items along each axis of an array is called its shape. The shape of an array is itself a vector. Its first item is the length of the first axis, its second item the length of the second axis, and so on. An array, whose length along one or more axes is zero, is called an empty array.

Depth

An array whose items are all simple scalars (i.e. single numbers, characters or refs) is called a simple array. If one or more items of an array is not a simple scalar (i.e. is another array, or a ⎕OR), the array is called a nested array. A nested array may contain items which are themselves nested arrays. The degree of nesting of an array is called its depth. A simple scalar has a depth of 0. A simple vector, matrix, or multi-dimensional array has depth 1. An array whose items are all depth 1 subarrays has depth 2; one whose items are all depth 2 subarrays has depth 3, and so forth.

Type

An array, whose elements are all numeric, is called a numeric array; its TYPE is numeric. A character array is one in which all items are characters. An array whose items contain both numeric and character elements is of MIXED type.


Numbers

Dyalog APL supports both real numbers and complex numbers.

Real Numbers

Numbers are entered or displayed using conventional decimal notation (e.g. 299792.458) or using a scaled form (e.g. 2.999792458E5).

On entry, a decimal point is optional if there is no fractional part. On output, a number with no fractional part (an integer) is displayed without a decimal point.

The scaled form consists of:

  1. an integer or decimal number called the mantissa,
  2. the letter E or e,
  3. an integer called the scale, or exponent.

The scale specifies the power of 10 by which the mantissa is to be multiplied.

Example

      12 23.24 23.0 2.145E2
12 23.24 23 214.5

Negative numbers are preceded by the high minus (¯) symbol, not to be confused with the minus (-) function. In scaled form, both the mantissa and the scale may be negative.

Example

      ¯22 2.145E¯2 ¯10.25
¯22 0.02145 ¯10.25

Complex Numbers

Complex numbers use the J notation introduced in IBM APL2 and are written as aJb or ajb (without spaces) where the real and imaginary parts a and b are written as described above. The capital J is always used to display a value.

Examples

      2+¯1*.5
2J1
      .3j.5
0.3J0.5
    1.2E5J¯4E¯4
120000J¯0.0004

The empty vector (⍳0) may be represented by the numeric constant ⍬ called ZILDE.


Characters

Characters are entered within a pair of APL quotes. The surrounding APL quotes are not displayed on output. The APL quote character itself must be entered as a pair of APL quotes.

Examples

      'DYALOG APL'
DYALOG APL
      'I DON''T KNOW'
I DON'T KNOW
      '*'
*


Enclosed Elements

An array may be enclosed to form a scalar element through any of the following means:

  • by the enclose function (⊂)
  • by inclusion in vector notation
  • as the result of certain functions when applied to arrays

Examples

      (⊂1 2 3),⊂'ABC'
1 2 3  ABC

    (1 2 3) 'ABC'
1 2 3  ABC

      ⍳2 3
1 1  1 2  1 3
2 1  2 2  2 3


Legal Names

APL objects may be given names. A name may be any sequence of characters, starting with an alphabetic character, selected from the following:

0123456789(but not as the 1st character in a name)
ABCDEFGHIJKLMNOPQRSTUVWXYZ_
abcdefghijklmnopqrstuvwxyz
ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝß
àáâãäåæçèéêëìíîïðñòóôõöøùúûüþ
∆⍙
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

Note that using a standard Unicode font (rather than APL385 Unicode used in the table above), the last row above would appear as the circled alphabet, Ⓐ to Ⓩ.

Examples

Legal | Illegal
THIS∆IS∆A∆NAME | BAD NAME
X1233 | 3+21
SALES | S!H|PRICE
pjb_1 | 1_pjb


Specification of Variables

A variable is a named array. An undefined name or an existing variable may be assigned an array by specification with the left arrow (←).

Examples

      A←'CHIPS WITH EVERYTHING'
      A
CHIPS WITH EVERYTHING

      X Y←'ONE' 'TWO'
      X
ONE
      Y
TWO


Vector Notation

A series of two or more adjacent expressions results in a vector whose elements are the enclosed arrays resulting from each expression. This is known as VECTOR (or STRAND) NOTATION. Each expression in the series may consist of one of the following:

  1. a single numeric value;
  2. single character, within a pair of quotes;
  3. more than one character, within a pair of quotes;
  4. the name of a variable;
  5. the evaluated input symbol ⎕;
  6. the quote-quad symbol ⍞;
  7. the name of a niladic, defined function yielding a result;
  8. any other APL expression which yields a result, within parentheses.

Examples

      ⍴A←2 4 10
3
      ⍴TEXT←'ONE' 'TWO'
2

Numbers and characters may be mixed:

      ⍴X←'THE ANSWER IS ' 10
2
      X[1]
 THE ANSWER IS
      X[2] + 32
42

Blanks, quotes or parentheses must separate adjacent items in vector notation. Redundant blanks and parentheses are permitted. In this manual, the symbol pair '←→' indicates the phrase 'is equivalent to'.

      1  2  ←→ (1)(2) ←→ 1  (2)  ←→ (1)  2
      2'X'3 ←→ 2 'X' 3 ←→ (2) ('X') (3)
      1  (2+2) ←→ (1) ((2+2)) ←→ ((1))  (2+2)

Vector notation may be used to define an item in vector notation:

       ⍴X ← 1 (2 3 4) ('THIS' 'AND' 'THAT')
3
      X[2]
 2 3 4
      X[3]
  THIS  AND  THAT

Expressions within parentheses are evaluated to produce an item in the vector:

      Y ← (2+2) 'IS' 4
      Y
4  IS  4

The following identity holds:

      A  B  C  ←→ (⊂A), (⊂B), ⊂C


Structuring of Arrays

A class of primitive functions re-structures arrays in some way. Arrays may be input only in scalar or vector form. Structural functions may produce arrays with a higher rank. The Structural functions are reshape (⍴), ravel, laminate and catenate (,), reversal and rotation (⌽), transpose (⍉), mix and take (↑), split and drop (↓), and enclose (⊂). These functions are described in Chapter 4.

Examples

      2 2⍴1 2 3 4
1 2
3 4

      2 2 4⍴'ABCDEFGHIJKLMNOP'
ABCD
EFGH

IJKL
MNOP
         ↓2 4⍴'COWSHENS'
 COWS  HENS


Display of Arrays

Simple scalars and vectors are displayed in a single line beginning at the left margin. A number is separated from the next adjacent element by a single space. The number of significant digits to be printed is determined by the system variable ⎕PP whose default value is 10. The fractional part of the number will be rounded in the last digit if it cannot be represented within the print precision. Trailing zeros after a decimal point and leading zeros will not be printed. An integer number will display without a decimal point.

Examples

      0.1 1.0 1.12
0.1 1 1.12

      'A' 2 'B' 'C'
A 2 BC

      ÷3 2 6
0.3333333333 0.5 0.1666666667

If a number cannot be fully represented in ⎕PP significant digits, or if the number requires more than five leading zeros after the decimal point, the number is represented in scaled form. The mantissa will display up to ⎕PP significant digits, but trailing zeros will not be displayed.

Examples

      ⎕PP←3

      123 1234 12345 0.12345 0.00012345 0.00000012345
123 1.23E3 1.23E4 0.123 0.000123 1.23E¯7

Simple matrices are displayed in rectangular form, with one line per matrix row. All elements in a given column are displayed in the same format, but the format and width for each column is determined independently of other columns. A column is treated as numeric if it contains any numeric elements. The width of a numeric column is determined such that the decimal points (if any) are aligned; that the E characters for scaled formats are aligned, with trailing zeros added to the mantissae if necessary, and that integer forms are right-adjusted one place to the left of the decimal point column (if any). Numeric columns are right-justified; a column which contains no numeric elements is left-justified. Numeric columns are separated from their neighbours by a single column of blanks.

Examples

      2 4⍴'HANDFIST'
HAND
FIST

      1 2 3 ∘.× 6 2 5
 6 2  5
12 4 10
18 6 15

      2 3⍴2 4 6.1 8 10.24 12
2  4     6.1
8 10.24 12

      2 4⍴4 'A' 'B' 5 ¯0.000000003 'C' 'D' 123.56
 4E0  AB   5
¯3E¯9 CD 123.56

In the display of non-simple arrays, each element is displayed within a rectangle such that the rows and columns of the array are aligned. Simple items within the array are displayed as above. For non-simple items, this rule is applied recursively, with one space added on each side of the enclosed element for each level of nesting.

Examples

      ⍳3
1 2 3

      ⊂⍳3
 1 2 3

      ⊂⊂⍳3
  1 2 3

      ('ONE' 1) ('TWO' 2) ('THREE' 3) ('FOUR' 4)
  ONE  1   TWO  2   THREE  3   FOUR  4

      2 4⍴'ONE' 1 'TWO' 2 'THREE' 3 'FOUR' 4
 ONE    1  TWO   2
 THREE  3  FOUR  4

Multi-dimensional arrays are displayed in rectangular planes. Planes are separated by one blank line, and hyper-planes of higher dimensions are separated by increasing numbers of blank lines. In all other respects, multi-dimensional arrays are displayed in the same manner as matrices.

Examples

      2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      3 1 1 3⍴'THEREDFOX'
THE

RED

FOX

The power of this form of display is made apparent when formatting informal reports.

Examples

      +AREAS←'West' 'Central' 'East'
 West  Central  East

      +PRODUCTS←'Biscuits' 'Cakes' 'Buns' 'Rolls'
 Biscuits  Cakes  Buns  Rolls

      SALES←50 5.25 75 250 20.15 900 500
      SALES,←80.98 650 1000 90.03 1200
      +SALES←4 3⍴SALES
  50  5.25   75
 250 20.15  900
 500 80.98  650
1000 90.03 1200

      ' ' PRODUCTS ⍪., AREAS SALES
            West  Central  East
 Biscuits     50     5.25    75
 Cakes       250    20.15   900
 Buns        500    80.98   650
 Rolls      1000    90.03  1200

If the display of an array is wider than the page width, as set by the system variable ⎕PW, it will be folded at or before ⎕PW and the folded portions indented six spaces. The display of a simple numeric or mixed array may be folded at a width less than ⎕PW so that individual numbers are not split across a page boundary.

Example

      ⎕PW←40

      ?3 20⍴100
54 22  5 68 68 94 39 52 84  4  6 53 68
85 53 10 66 42 71 92 77 27  5 74 33 64
66  8 64 89 28 44 77 48 24 28 36 17 49
       1  39  7 42 69 49 94
      76 100 37 25 99 73 76
      90  91  7 91 51 52 32

The Display Function

The DISPLAY function is implemented as a user command ]display distributed with Dyalog APL and may be used to illustrate the structure of an array. ]display is monadic. Its result is a character matrix containing a pictorial representation of its argument. ]display is used throughout this manual to illustrate examples. An array is illustrated with a series of boxes bordering each sub-array. Characters embedded in the border indicate rank and type information. The top and left borders contain symbols that indicate its rank. A symbol in the lower border indicates type. The symbols are defined as follows:

→ | Vector.
↓ | Matrix or higher rank array.
⊖ | Empty along last axis.
⌽ | Empty along other than last axis.
∊ | Nested array.
~ | Numeric data.
- | Character data.
+ | Mixed character and numeric data.
∇ | ⎕OR object.
# | array of refs.
      ]display 'ABC' (1 4⍴1 2 3 4)
.→-----------------.
| .→--.  .→------. |
| |ABC|  ↓1 2 3 4| |
| '---'  '~------' |
'∊-----------------'


Prototypes and Fill Items

Every array has an associated prototype which is derived from the array's first item.

If the first item is a number, the prototype is 0. Otherwise, if the first item is a character, the prototype is ' ' (space). Otherwise, if the first item is a (ref to) an instance of a Class, the prototype is a ref to that Class.

Otherwise (in the nested case, when the first item is other than a simple scalar), the prototype is defined recursively as the prototype of each of the array's first item.

Examples:

Array | Prototype
1 2 3.4 | 0
2 3 5⍴'hello' | ' '
99 'b' 66 | 0
(1 2)(3 4 5) | 0 0
((1 2)3)(4 5 6) | (0 0)0
'hello' 'world' | ' '
⎕NEW MyClass | MyClass
(88(⎕NEW MyClass)'X')7 | 0 MyClass ' '

Fill Items

Fill items for an overtake operation, are derived from the argument's prototype. For each 0 or ' ' in the prototype, there is a corresponding 0 or ' ' in the fill item and for each class reference in the prototype, there is a ref to a (newly constructed and distinct) instance of that class that is initialised by the niladic (default) constructor for that class, if defined.

Examples:

      4↑1 2
1 2 0 0
      4↑'ab'
ab
      4↑(1 2)(3 4 5)
 1 2  3 4 5  0 0  0 0
      2↑⎕NEW MyClass
 #.[Instance of MyClass]  #.[Instance of MyClass]

In the last example, two distinct instances are constructed (the first by ⎕NEW and the second by the overtake).

Fill items are used in a number of operations including:

  • First (⊃ or ↑) of an empty array
  • Fill-elements for overtake
  • For use with the Each operator on an empty array


Scalar Functions

There is a class of primitive functions termed SCALAR FUNCTIONS. This class is identified in Table 4 below. Scalar functions are pervasive, i.e. their properties apply at all levels of nesting. Scalar functions have the following properties:

Table 4: Scalar Primitive Functions

Symbol | Monadic | Dyadic
+ | Identity | Plus (Add)
- | Negative | Minus (Subtract)
× | Direction (Signum) | Times (Multiply)
÷ | Reciprocal | Divide
| | Magnitude | Residue
⌊ | Floor | Minimum
⌈ | Ceiling | Maximum
* | Exponential | Power
⍟ | Natural Logarithm | Logarithm
○ | Pi Times | Circular
! | Factorial | Binomial
~ | Not | $
? | Roll | $
∊ | Type (See Enlist) | $
^ |  | And
∨ |  | Or
⍲ |  | Nand
⍱ |  | Nor
< |  | Less
≤ |  | Less Or Equal
= |  | Equal
≥ |  | Greater Or Equal
> |  | Greater
≠ |  | Not Equal
$ Dyadic form is not scalar

Monadic Scalar Functions

  • The function is applied independently to each simple scalar in its argument.
  • The function produces a result with a structure identical to its argument.
  • When applied to an empty argument, the function produces an empty result. With the exception of + and ∊, the type of this result depends on the function, not on the type of the argument. By definition + and ∊ return a result of the same type as their arguments.

Example

      ÷2 (1 4)
0.5  1 0.25

Dyadic Scalar Functions

  • The function is applied independently to corresponding pairs of simple scalars in its arguments.
  • A simple scalar will be replicated to conform to the structure of the other argument. If a simple scalar in the structure of an argument corresponds to a non-simple scalar in the other argument, then the function is applied between the simple scalar and the items of the non-simple scalar. Replication of simple scalars is called SCALAR EXTENSION.
  • A simple unit is treated as a scalar for scalar extension purposes. A UNIT is a single element array of any rank. If both arguments are simple units, the argument with lower rank is extended.
  • The function produces a result with a structure identical to that of its arguments (after scalar extensions).
  • If applied between empty arguments, the function produces a composite structure resulting from any scalar extensions, with type appropriate to the particular function. (All scalar dyadic functions return a result of numeric type.)

Examples

      2 3 4 + 1 2 3
3 5 7

      2 (3 4) + 1 (2 3)
3  5 7

      (1 2) 3 + 4 (5 6)
 5 6  8 9

      10 × 2 (3 4)
20  30 40

      2 4 = 2 (4 6)
1  1 0

      (1 1⍴5) - 1 (2 3)
4  3 2

      1↑''+⍳0
0
       1↑(0⍴⊂' ' (0 0))×''
0  0 0

Note: The Axis operator applies to all scalar dyadic functions.


Mixed Functions

Mixed rank functions are summarised in Table 5. For convenience, they are sub-divided into five classes:

Table 5: Mixed rank functions

Structural | These functions change the structure of the arguments in some way.
Selection | These functions select elements from an argument.
Selector | These functions identify specific elements by a Boolean map or by an ordered set of indices.
Miscellaneous | These functions transform arguments in some way, or provide information about the arguments.
Special | These functions have special properties.

In general, the structure of the result of a mixed primitive function is different from that of its arguments.

Scalar extension may apply to some, but not all, dyadic mixed functions.

Mixed primitive functions are not pervasive. The function is applied to elements of the arguments, not necessarily independently.

Examples

      'CAT' 'DOG' 'MOUSE'⍳⊂'DOG'
2
      3↑ 1 'TWO' 3 'FOUR'
1  TWO  3

In the following tables, note that:

  • [] Implies axis specification is optional
  • $ This function is in another class

Table 6: Structural Primitive Functions

Symbol | Monadic | Dyadic
⍴ | $ | Reshape
, | Ravel [] | Catenate/Laminate []
⍪ | Table | Catenate First / Laminate []
⌽ | Reverse [] | Rotate []
⊖ | Reverse First [] | Rotate First []
⍉ | Transpose | Transpose
↑ | Mix/Disclose (First) [] | $
↓ | Split [] | $
⊂ | Enclose [] | Partitioned Enclose []
∊ | Enlist (See Type) | $

Table 7: Selection Primitive Functions

Symbol | Monadic | Dyadic
⊃ | Disclose /Mix | Pick
↑ | $ | Take []
↓ | $ | Drop []
/ |  | Replicate []
⌿ |  | Replicate First []
\ |  | Expand []
⍀ |  | Expand First []
~ | $ | Without (Excluding)
∩ |  | Intersection
∪ | Unique | Union
⊣ | Same | Left
⊢ | Identity | Right

Table 8: Selector Primitive Functions

Symbol | Monadic | Dyadic
⍳ | Index Generator | Index Of
∊ | $ | Membership
⍋ | Grade Up | Grade Up
⍒ | Grade Down | Grade Down
? | $ | Deal
⍷ |  | Find

Table 9: Miscellaneous Primitive Functions

Symbol | Monadic | Dyadic
⍴ | Shape | $
≡ | Depth | Match
≢ |  | Not Match
⍎ | Execute | Execute
⍕ | Format | Format
⊥ |  | Decode (Base)
⊤ |  | Encode (Representation)
⌹ | Matrix Divide | Matrix Inverse

Table 10: Special Primitive Functions

Symbol | Monadic | Dyadic
→ | Abort |
→ | Branch |
← | $ | Assignment
[I]← | $ | Assignment(Indexed)
(I)← |  | Assignment(Selective)
[] |  | Indexing


Conformability

The arguments of a dyadic function are said to be CONFORMABLE if the shape of each argument meets the requirements of the function, possibly after scalar extension.


Fill Elements

Some primitive functions may include fill elements in their result. The fill element for an array is the enclosed type of the disclose of the array (⊂∊⊃Y for array Y). The Type function (∊) replaces a numeric value with zero and a character value with ' '.

The Disclose function (⊃) returns the first item of an array. If the array is empty, ⊃Y is the PROTOTYPE of Y. The prototype is the type of the first element of the original array.

Primitive functions which may return an array including fill elements are Expand (\ or ⍀), Replicate (/ or ⌿), Reshape (⍴) and Take (↑).

Examples

      ∊⍳5
0 0 0 0 0

      ∊⊃(⍳3)('ABC')
0 0 0

      ⊂∊⊃(⍳3)('ABC')
 0 0 0

      ⊂∊⊃⊂(⍳3)('ABC')
  0 0 0

      A←'ABC' (1 2 3)
      A←0⍴A
      ⊂∊⊃A

      ' '=⊂∊⊃A
 1 1 1


Axis Operator

The axis operator may be applied to all scalar dyadic primitive functions and certain mixed primitive functions. An integer axis identifies a specific axis along which the function is to be applied to one or both of its arguments. If the primitive function is to be applied without an axis specification, a default axis is implied, either the first or last.

Example

      1 0 1/[1] 3 2⍴⍳6
1 2
5 6

      1 2 3+[2]2 3⍴10 20 30
11 22 33
11 22 33

Sometimes the axis value is fractional, indicating that a new axis or axes are to be created between the axes identified by the lower and upper integer bounds of the value (either of which might not exist).

Example

      'NAMES',[0.5]'='
NAMES
=====

⎕IO is an implicit argument of an axis specification.


Abort: →

This is a special case of the Branch function used in the niladic sense. If it occurs in a statement it must be the only symbol in an expression or the only symbol forming an expression in a text string to be executed by ⍎. It clears the most recently suspended statement and all of its pendent statements from the state indicator.

The Abort function has no explicit result. The function is not in the function domain of operators.

Examples

      ∇ F
[1]    'F[1]'
[2]    G
[3]    'F[3]'
      ∇

      ∇ G
[1]    'G[1]'
[2]    →
[3]    'G[3]'
      ∇

      F
F[1]
G[1]

      ⎕VR'VALIDATE'
     ∇ VALIDATE
 [1]   →(12=1↑⎕AI)⍴0 ⋄ 'ACCOUNT NOT AUTHORISED' ⋄ →
     ∇

      VALIDATE
ACCOUNT NOT AUTHORISED

      1↑⎕AI
52


Add

Add: R←X+Y

Y must be numeric. X must be numeric. R is the arithmetic sum of X and Y. R is numeric. This function is also known as Plus.

Examples

      1 2 + 3 4
4 6

      1 2 + 3,⊂4 5
4  6 7

      1J1 2J2 + 3J3
4J4 5J5

      ¯5 + 4J4 5J5
¯1J4 0J5


And Lowest Common Multiple

And, Lowest Common Multiple: R←X^Y

Case 1: X and Y are Boolean

R is Boolean is determined as follows:

             X   Y     R

             0   0     0
             0   1     0
             1   0     0
             1   1     1

Note that the ASCII caret (^) will also be interpreted as an APL And (^).

Example

      0 1 0 1 ^ 0 0 1 1
0 0 0 1

Case 2: Either or both X and Y are numeric (non-Boolean)

R is the lowest common multiple of X and Y. Note that in this case, ⎕CT is an implicit argument.

Example

      15 1 2 7 ^ 35 1 4 0
105 1 4 0

      2 3 4 ∧ 0j1 1j2 2j3
0J2 3J6 8J12

      2j2 2j4 ∧ 5j5 4j4
10J10 ¯4J12


Assignment

Assignment: X←Y

Assignment allocates the result of the expression Y to the name or names in X.

If Y is an array expression, X must contain one or more names which are variables, system variables, or are undefined. Following assignment, the name(s) in X become variable(s) with value(s) taken from the result of the expression Y.

If X contains a single name, the variable assumes the value of Y.

The assignment arrow (or specification arrow) is often read as 'Is' or 'Gets'.

Examples

      A←2.3
      A
2.3

      A←⍳3
      A
1 2 3

More than one name may be specified in X by using vector notation. If so, Y must be a vector or a scalar. If Y is a scalar, its value is assigned to all names in X. If Y is a vector, each element of Y is assigned to the corresponding name in X.

Examples

      A B←2
      A
2

      B
2

      P ⎕IO Q←'TEXT' 1 (1 2 3)
      P
TEXT
      ⎕IO
1
      Q
1 2 3

For compatibility with IBM's APL2, the list of names specified in X may be enclosed in parentheses.

Examples

      (A B C)←1 2 3
      (D E)←'Hello' 'World'

Multiple assignments are permitted. The value of Y is carried through each assignment:

      I←J←K←0

      I,J,K
0 0 0

Function Assignment

If Y is a function expression, X must be a single name which is either undefined, or is the name of an existing function or defined operator. X may not be the name of a system function, or a primitive symbol.

Examples

      PLUS←+
      PLUS
+

      SUM←+/
      SUM
+/

      MEAN←{(+/⍵)÷⍴⍵}

Namespace Reference Assignment

If an expression evaluates to a namespace reference, or ref, you may assign it to a name. A name assigned to a simple scalar ref, has name class 9, whereas one assigned to an array containing refs has name class 2.

      'f1'⎕WC'Form'
      'ns1' ⎕NS ''

      N←ns1
      ⎕NC'N'           ⍝ name class of a scalar ref
9
      F←f1
      ⎕NC'F'           ⍝ name class of a scalar ref
9
      refs←N F         ⍝ vector of refs.
      ⎕NC'refs'        ⍝ nameclass of vector.
2
      F2←2⊃refs
      ⎕NC 'F2'
9

Re-Assignment

A name that already exists may be assigned a new value if the assignment will not alter its name class, or will change it from 2 to 9 or vice versa. The table of permitted re-assignments is as follows:

 | Ref | Variable | Function | Operator
Ref | Yes | Yes |  |
Variable | Yes | Yes |  |
Function |  |  | Yes | Yes
Operator |  |  | Yes | Yes


Assignment Indexed

Assignment (Indexed): {R}←X[I]←Y

Indexed Assignment is the Assignment function modified by the Indexing function. The phrase [I]← is treated as the function for descriptive purposes.

Y may be any array. X may be the name of any array or a selection from a named array (EXP X)[I]←Y, see Assignment (Selective):. I must be a valid index specification. The shape of Y must conform with the shape (implied) of the indexed structure defined by I. If Y is a scalar or a unit vector it will be extended to conform. A side effect of Indexed Assignment is to change the value of the indexed elements of X.

R is the value of Y. If the result is not explicitly assigned or used it is suppressed.

⎕IO is an implicit argument of Indexed Assignment.

Three forms of indexing are permitted.

Simple Indexed Assignment

For vector X, I is a simple integer array whose items are from the set ⍳⍴R. Elements of X identified by index positions I are replaced by corresponding elements of Y.

Examples

      +A←⍳5
1 2 3 4 5

      A[2 3]←10 ⋄ A
1 10 10 4 5

The last-most element of Y is assigned when an index is repeated in I:

      A[2 2]←100 101 ⋄ A
1 101 10 4 5

For matrix X, I is composed of two simple integer arrays separated by the semicolon character (;). The arrays select indices from the rows and columns of X respectively.

Examples

      +B←2 3⍴'REDSUN'
RED
SUN

      B[2;2]←'O' ⋄ B
RED
SON

For higher-order array X, I is a series of simple integer arrays with adjacent arrays separated by a single semicolon character (;). Each array selects indices from an axis of X taken in row-major order.

Examples

      C
11 12 13
14 15 16

21 22 23
24 25 26

      C[1;1;3]←103 ⋄ C
11 12 103
14 15  16

21 22  23
24 25  26

An indexing array may be ELIDED. That is, if an indexing array is omitted from the Kth axis, the indexing vector ⍳(⍴X)[K] is implied:

      C[;1;2 3]←2 2⍴112 113 122 123 ⋄ C
11 112 113
14  15  16

21 122 123
24  25  26

      C[;;]←0 ⋄ C
0 0 0
0 0 0

0 0 0
0 0 0

Choose Indexed Assignment

The index specification I is a non-simple integer array. Each item identifies a single element of X by a set of indices with one element per axis of X in row-major order.

Examples

      C
11 12 13 14
21 22 23 24

      C[⊂1 1]←101 ⋄ C
101 12 13 14
 21 22 23 24

      C[(1 2) (2 3)]←102 203 ⋄ C
101 102  13 14
 21  22 203 24

      C[2 2⍴(1 3)(2 4)(2 1)(1 4)]←2 2⍴103 204 201 104 ⋄ C
101 102 103 104
201  22 203 204

A scalar may be indexed by the enclosed empty vector:

      S
10
      S[⊂⍳0]←⊂'VECTOR' ⋄ S
 VECTOR
      S[⊂⍳0]←5 ⋄ S
5

Choose Indexed Assignment may be used very effectively in conjunction with Index Generator (⍳) and Structural functions in order to assign into an array:

      C
11 12 13 14
21 22 23 24

      ⍳⍴C
1 1  1 2  1 3  1 4
2 1  2 2  2 3  2 4

      C[1 1⍉⍳⍴C]←1 2 ⋄ C
 1 12 13 14
21  2 23 24

      C[2 ¯1↑⍳⍴C]←99 ⋄ C
 1 12 13 99
21  2 23 99

Reach Indexed Assignment

The index specification I is a non-simple integer array, each of whose items reach down to a nested element of X. The items of an item of I are simple vectors (or scalars) forming sets of indices that index arrays at successive levels of X starting at the top-most level. A set of indices has one element per axis at the respective level of nesting of X in row-major order.

Examples

      D←(2 3⍴⍳6)(2 2⍴'SMITH' 'JONES' 'SAM' 'BILL')

      D
 1 2 3   SMITH  JONES
 4 5 6   SAM    BILL

      ≡J←⊂2 (1 2)
¯3

      D[J]←⊂'WILLIAMS' ⋄ D
 1 2 3   SMITH  WILLIAMS
 4 5 6   SAM    BILL

      D[(1 (1 1))(2 (2 2) 1)]←10 'W' ⋄ D
 10 2 3   SMITH  WILLIAMS
  4 5 6   SAM    WILL

      E
 GREEN  YELLOW  RED

      E[⊂2 1]←'M' ⋄ E
 GREEN  MELLOW  RED

The context of indexing is important. In the last example, the indexing method is determined to be Reach rather than Choose since E is a vector, not a matrix as would be required for Choose. Observe that:

      ⊂2 1 ←→ ⊂(⊂2),(⊂1)

Note that for any array A, A[⊂⍬] represents a scalar quantity, which is the whole of A, so:

      A←5⍴0
      A
0 0 0 0 0
      A[⊂⍬]←1
      A
1

Combined Indexed and Selective Assignment

Instead of X being a name, it may be a selection from a named array, and the statement is of the form (EXP X)[I]←Y.

      MAT←4 3⍴'Hello' 'World'
      (2↑¨MAT)[1 2;]←'#'
      MAT
 ##llo  ##rld  ##llo
 ##rld  ##llo  ##rld
 Hello  World  Hello
 World  Hello  World
      MAT←4 3⍴'Hello' 'World'
      ⎕ML←1 ⍝ ∊ is Enlist
     (∊MAT)[2×⍳⌊0.5×⍴∊MAT]←'#'
      MAT
 H#l#o  #o#l#  H#l#o
 #o#l#  H#l#o  #o#l#
 H#l#o  #o#l#  H#l#o
 #o#l#  H#l#o  #o#l#


Assignment Selective

Assignment (Selective): (EXP X)←Y

X is the name of a variable in the workspace, possibly modified by the indexing function (EXP X[I])←Y, see.Assignment (Indexed):. EXP is an expression that selects elements of X. Y is an array expression. The result of the expression Y is allocated to the elements of X selected by EXP.

The following functions may appear in the selection expression. Where appropriate these functions may be used with axis [] and with the Each operator ¨.

Functions for Selective Assignment

↑ | Take
↓ | Drop
, | Ravel
⌽ | Reverse, Rotate
⍴ | Reshape
⊃ | Disclose, Pick
⍉ | Transpose (Monadic and Dyadic)
/ | Replicate
\ | Expand
⌷ | Index
∊ | Enlist (⎕ML≥1)

Note: Mix and Split (monadic ↑ and ↓), Type (monadic ∊ when ⎕ML<1) and Membership (dyadic ∊) may not be used in the selection expression.

Examples

      A←'HELLO'
      ((A∊'AEIOU')/A)←'*'

      A
H*LL*

      Z←3 4⍴⍳12
      (5↑,Z)←0

      Z
0  0  0  0
0  6  7  8
9 10 11 12

      MAT←3 3⍴⍳9
      (1 1⍉MAT)←0

      MAT
0 2 3
4 0 6
7 8 0

      ⎕ML←1⍝ so ∊ is Enlist
      names←'Andy' 'Karen' 'Liam'
      (('a'=∊names)/∊names)←'*'
      names
 Andy  K*ren  Li*m

Each Operator

The functions listed in the table above may also be used with the Each Operator ¨.

Examples

      A←'HELLO' 'WORLD'
      (2↑¨A)←'*'
      A
 **LLO  **RLD

      A←'HELLO' 'WORLD'
      ((A='O')/¨A)←'*'
      A
 HELL*  W*RLD

      A←'HELLO' 'WORLD'
      ((A∊¨⊂'LO')/¨A)←'*'
      A
 HE***  W*R*D

Bracket Indexing

Bracket indexing may also be applied to the expression on the left of the assignment arrow.

Examples

      MAT←4 3⍴'Hello' 'World'
      (¯2↑¨MAT[;1 3])←'$'
      MAT
 Hel$$  World  Hel$$
 Wor$$  Hello  Wor$$
 Hel$$  World  Hel$$
 Wor$$  Hello  Wor$$


Binomial

Binomial: R←X!Y

X and Y may be any numbers except that if Y is a negative integer then X must be a whole number (integer). R is numeric. An element of R is integer if corresponding elements of X and Y are integers. Binomial is defined in terms of the function Factorial for positive integer arguments:

      X!Y ←→ (!Y)÷(!X)×!Y-X

For other arguments, results are derived smoothly from the Beta function:

      Beta(X,Y) ←→ ÷Y×(X-1)!X+Y-1

For positive integer arguments, R is the number of selections of X things from Y things.

Example

      1 1.2 1.4 1.6 1.8 2!5
5 6.105689248 7.219424686 8.281104786 9.227916704 10

      2!3j2
1J5


Branch

Branch: →Y

Y may be a scalar or vector which, if not empty, has a simple numeric scalar as its first element. The function has no explicit result. It is used to modify the normal sequence of execution of expressions or to resume execution after a statement has been interrupted. Branch is not in the function domain of operators.

The following distinct usages of the branch function occur:

 | Entered in a Statement in a Defined Function | Entered in Immediate Execution Mode
→LINE | Continue with the specific line | Restart execution at the specific line of the most recently suspended function
→⍳0 | Continue with the next expression | No effect

In a defined function, if Y is non-empty then the first element in Y specifies a statement line in the defined function to be executed next. If the line does not exist, then execution of the function is terminated. For this purpose, line 0 does not exist. (Note that statement line numbers are independent of the index origin ⎕IO).

If Y is empty, the branch function has no effect. The next expression is executed on the same line, if any, or on the next line if not. If there is no following line, the function is terminated.

The :GoTo statement may be used in place of Branch in a defined function.

Example

     ∇ TEST
[1]    1
[2]    →4
[3]    3
[4]    4
     ∇

      TEST
1
4

In general it is better to branch to a LABEL than to a line number. A label occurs in a statement followed by a colon and is assigned the value of the statement line number when the function is defined.

Example

     ∇ TEST
[1]    1
[2]    →FOUR
[3]    3
[4]   FOUR:4
     ∇

The previous examples illustrate unconditional branching. There are numerous APL idioms which result in conditional branching. Some popular idioms are identified in the following table:

Branch Expression | Comment
→TEST/L1 | Branches to label L1 if TEST results in 1 but not if TEST results in 0.
→TEST⍴L1 | Similar to above.
TEST↑L1 | Similar to above.
→L1⍴⍨TEST | Similar to above.
→L1⌈⍳TEST | Similar to above but only if ⎕IO←→1.
→L1×⍳TEST | Similar to above but only if ⎕IO←→1.
→(L1,L2,L3)[N] | Unconditional branch to a selected label.
→(T1,T2,T3)/L1,L2,L3 | Branches to the first selected label dependent on tests T1,T2,T3. If all tests result in 0, there is no branch.
→N⌽L1,L2,L3 | Unconditional branch to thefirst label after rotation.

A branch expression may occur within a statement including ⋄ separators:

[5]   →NEXT⍴⍨TEST ⋄ A←A+1 ⋄ →END
[6]  NEXT:

In this example, the expressions 'A←A+1' and '→END' are executed only if TEST returns the value 1. Otherwise control branches to label NEXT.

In immediate execution mode, the branch function permits execution to be continued within the most recently suspended function, if any, in the state indicator. If the state indicator is empty, or if the argument Y is the empty vector, the branch expression has no effect. If a statement line is specified which does not exist, the function is terminated. Otherwise, execution is restarted from the beginning of the specified statement line in the most recently suspended function.

Example

     ∇ F
[1]   1
[2]   2
[3]   3
     ∇

      2 ⎕STOP'F'
      F
1

F[2]
      )SI
#.F[2]*
      →2
2
3

The system constant ⎕LC returns a vector of the line numbers of statement lines in the state indicator, starting with that in the most recently suspended function. It is convenient to restart execution in a suspended state by the expression:

      →⎕LC


Catenate Laminate

Catenate/Laminate: R←X,[K]Y

Y may be any array. X may be any array. The axis specification is optional. If specified, K must be a numeric scalar or unit vector which may have a fractional value. If not specified, the last axis is implied.

The form R←X⍪Y may be used to imply catenation along the first axis.

Two cases of the function catenate are permitted:

  1. With an integer axis specification, or implied axis specification.
  2. With a fractional axis specification, also called laminate.

Catenation with Integer or Implied Axis Specification

The arrays X and Y are joined along the required axis to form array R. A scalar or unit vector is extended to the shape of the other argument except that the required axis is restricted to a unit dimension. X and Y must have the same shape (after extension) except along the required axis, or one of the arguments may have rank one less than the other, provided that their shapes conform to the prior rule after augmenting the array of lower rank to have a unit dimension along the required axis.

The rank of R is the greater of the ranks of the arguments, but not less than 1.

Examples

      'FUR','LONG'
FURLONG

      1,2
1 2

      (2 4⍴'THISWEEK')⍪'='
THIS
WEEK
====

      S,[1]+⌿S←2 3⍴⍳6
1 2 3
4 5 6
5 7 9

If, after extension, exactly one of X and Y have a length of zero along the joined axis, then the data type of R will be that of the argument with a non-zero length. Otherwise, the data type of R will be that of X.

Lamination with Fractional Axis Specification

The arrays X and Y are joined along a new axis created before the ⌈Kth axis. The new axis has a length of 2. K must exceed ⎕IO (the index origin) minus 1, and K must be less than ⎕IO plus the greater of the ranks of X and Y. A scalar or unit vector argument is extended to the shape of the other argument. Otherwise X and Y must have the same shape.

The rank of R is one plus the greater of the ranks of X and Y.

Examples

      'HEADING',[0.5]'-'
HEADING
-------

      'NIGHT',[1.5]'*'
N*
I*
G*
H*
T*
      ⎕IO←0
      'HEADING',[¯0.5]'-'
HEADING
-------


Catenate First

Catenate First: R←X⍪[K]Y

The form R←X⍪Y implies catenation along the first axis whereas the form R←X,Y implies catenation along the last axis (columns). See Catenate/Laminate above.


Ceiling

Ceiling: R←⌈Y

Ceiling is defined in terms of Floor as ⌈Y←→-⌊-Y

Y must be numeric.

If an element of Y is real, the corresponding element of R is the least integer greater than or equal to the value of Y.

If an element of Y is complex, the corresponding element of R depends on the relationship between the real and imaginary parts of the numbers in Y.

Examples

      ⌈¯2.3  0.1  100  3.3
¯2 1 100 4

      ⌈1.2j2.5 1.2j¯2.5
1J3 1J¯2

For further explanation, see Floor:.

⎕CT is an implied argument of Ceiling.


Circular

Circular: R←X○Y

Y must be numeric. X must be an integer in the range ¯12 ≤ X ≤ 12. R is numeric.

X determines which of a family of trigonometric, hyperbolic, Pythagorean and complex functions to apply to Y, from the following table. Note that when Y is complex, a and b are used to represent its real and imaginary parts, while θ represents its phase.

(-X) ○ Y | X | X ○ Y
(1-Y*2)*.5 | 0 | (1-Y*2)*.5
Arcsin Y | 1 | Sine Y
Arccos Y | 2 | Cosine Y
Arctan Y | 3 | Tangent Y
(Y+1)×((Y-1)÷Y+1)*0.5 | 4 | (1+Y*2)*.5
Arcsinh Y | 5 | Sinh Y
Arccosh Y | 6 | Cosh Y
Arctanh Y | 7 | Tanh Y
-8○Y | 8 | (-1+Y*2)*0.5
Y | 9 | a
+Y | 10 | |Y
Y×0J1 | 11 | b
*Y×0J1 | 12 | θ

Examples

      0 ¯1 ○ 1
0 1.570796327

      1○(PI←○1)÷2 3 4
1 0.8660254038  0.7071067812

      2○PI÷3
0.5
      9 11○3.5J¯1.2
3.5 ¯1.2

      9 11∘.○3.5J¯1.2 2J3 3J4
 3.5 2 3
¯1.2 3 4


Conjugate

Conjugate: R←+Y

If Yis complex, R is Y with the imaginary part of all elements negated.

If Y is real or non-numeric, R is the same array unchanged.

Note that if Y is nested, the function has to process the entire array in case any item is complex.

Examples

      +3j4
3J¯4
      +1j2 2j3 3j4
1J¯2 2J¯3 3J¯4

      3j4++3j4
6
      3j4×+3j4
25

      +A←⍳5
1 2 3 4 5

      +⎕EX'A'
1


Deal

Deal: R←X?Y

Y must be a simple scalar or unit vector containing a non-negative integer. X must be a simple scalar or unit vector containing a non-negative integer and X≤Y.

R is an integer unit vector obtained by making X random selections from ⍳Y without repetition.

Examples

      13?52
7 40 24 28 12 3 36 49 20 44 2 35 1

      13?52
20 4 22 36 31 49 45 28 5 35 37 48 40

⎕IO and ⎕RL are implicit arguments of Deal. A side effect of Deal is to change the value of ⎕RL. See Random Number Generator: and Random Link: .


Decode

Decode: R←X⊥Y

Y must be a simple numeric array. X must be a simple numeric array. R is the numeric array which results from the evaluation of Y in the number system with radix X.

X and Y are conformable if the length of the last axis of X is the same as the length of the first axis of Y. A scalar or unit vector is extended to a vector of the required length. If the last axis of X or the first axis of Y has a length of 1, the array is extended along that axis to conform with the other argument.

The shape of R is the catenation of the shape of X less the last dimension with the shape of Y less the first dimension. That is:

      ⍴R ←→ (¯1↓⍴X),1↓⍴Y

For vector arguments, each element of X defines the ratio between the units for corresponding pairs of elements in Y. The first element of X has no effect on the result.

This function is also known as Base Value.

Examples

      60 60⊥3 13
193

      0 60⊥3 13
193

      60⊥3 13
193

      2⊥1 0 1 0
10

Polynomial Evaluation

If X is a scalar and Y a vector of length n, decode evaluates the polynomial(Index origin 1):

Examples

      2⊥1 2 3 4
26
      3⊥1 2 3 4
58
      1j1⊥1 2 3 4
5J9

For higher order array arguments, each of the vectors along the last axis of X is taken as the radix vector for each of the vectors along the first axis of Y.

Examples

      M
0 0 0 0 1 1 1 1
0 0 1 1 0 0 1 1
0 1 0 1 0 1 0 1

      A
1 1 1
2 2 2
3 3 3
4 4 4

      A⊥M
0 1 1 2  1  2  2  3
0 1 2 3  4  5  6  7
0 1 3 4  9 10 12 13
0 1 4 5 16 17 20 21

Scalar extension may be applied:

      2⊥M
0 1 2 3 4 5 6 7

Extension along a unit axis may be applied:

      +A←2 1⍴2 10
 2
10
      A⊥M
0 1  2  3   4   5   6   7
0 1 10 11 100 101 110 111


Depth

Depth: (⎕ML) R←≡Y

Y may be any array. R is the number of levels of nesting of Y. A simple scalar (rank-0 number, character or namespace-reference) has a depth of 0.

A higher rank array, all of whose items are simple scalars, is termed a simple array and has a depth of 1. An array whose items are not all simple scalars is nested and has a depth 1 greater than that of its most deeply nested item.

Y is of uniform depth if it is simple or if all of its items have the same uniform depth.

If ⎕ML<2 and Y is not of uniform depth then R is negated.

If ⎕ML<2, a negative value of R indicates non-uniform depth.

Examples

      ≡1
0
      ≡'A'
0
      ≡'ABC'
1
      ≡1 'A'
1

      ⎕ML←0

      ≡A←(1 2)(3 (4 5)) ⍝ Non-uniform array
¯3
      ≡¨A          ⍝ A[1] is uniform, A[2] is non-uniform
1 ¯2
      ≡¨¨A
 0 0  0 1

      ⎕ML←2

      ≡A
3
      ≡¨A
1 2
      ≡¨¨A
 0 0  0 1


Direction Signum

Direction (Signum): R←×Y

Y may be any numeric array.

Where an element of Y is real, the corresponding element of R is an integer whose value indicates whether the value is negative (¯1), zero (0) or positive (1).

Where an element of Y is complex, the corresponding element of R is a number with the same phase but with magnitude (absolute value) 1. It is equivalent to Y÷|Y.

Examples

      ×¯15.3 0 101
¯1 0 1

      ×3j4 4j5
0.6J0.8 0.6246950476J0.7808688094

      {⍵÷|⍵}3j4 4j5
0.6J0.8 0.6246950476J0.7808688094

      |×3j4 4j5
1 1


Disclose

Disclose: (⎕ML) R←⊃Y or R←↑Y

The symbol chosen to represent Disclose depends on the current Migration Level.

If ⎕ML<2, Disclose is represented by the symbol: ⊃.

If ⎕ML≥2, Disclose is represented by the symbol: ↑.

Y may be any array. R is an array. If Y is non-empty, R is the value of the first item of Y taken in ravel order. If Y is empty, R is the prototype of Y.

Disclose is the inverse of Enclose. The identity R←→⊃⊂R holds for all R. Disclose is also referred to as First.

Examples

      ⊃1
1

      ⊃2 4 6
2

      ⊃'MONDAY' 'TUESDAY'
MONDAY

      ⊃(1 (2 3))(4 (5 6))
1  2 3

      ⊃⍳0
0

      ' '=⊃''
1

      ⊃1↓⊂1,⊂2 3
0  0 0


Divide

Divide: R←X÷Y

Y must be a numeric array. X must be a numeric array. R is the numeric array resulting from X divided by Y. System variable ⎕DIV is an implicit argument of Divide.

If ⎕DIV=0 and Y=0 then if X=0, the result of X÷Y is 1; if X≠0 then X÷Y is a DOMAIN ERROR.

If ⎕DIV=1 and Y=0, the result of X÷Y is 0 for all values of X.

Examples

      2 0 5÷4 0 2
0.5 1 2.5

      3j1 2.5 4j5÷2 1j1 .2
1.5J0.5 1.25J¯1.25 20J25

      ⎕DIV←1
      2 0 5÷4 0 0
0.5 0 0


Drop

Drop: R←X↓Y

Y may be any array. X must be a simple scalar or vector of integers. If X is a scalar, it is treated as a one-element vector. If Y is a scalar, it is treated as an array whose shape is (⍴X)⍴1. After any scalar extensions, the shape of X must be less than or equal to the rank of Y. Any missing trailing items in X default to 0.

R is an array with the same rank as Y but with elements removed from the vectors along each of the axes of Y. For the Ith axis:

  • if X[I] is positive, all but the first X[I] elements of the vectors result.
  • if X[I] is negative, all but the last X[I] elements of the vectors result.

If the magnitude of X[I] exceeds the length of the Ith axis, the result is an empty array with zero length along that axis.

Examples

      4↓'OVERBOARD'
BOARD

      ¯5↓'OVERBOARD'
OVER

      ⍴10↓'OVERBOARD'
0

      M
ONE
FAT
FLY
      0 ¯2↓M
O
F
F

      ¯2 ¯1↓M
ON
      1↓M
FAT
FLY
      M3←2 3 4⍴⎕A

      1 1↓M3
QRST
UVWX
      ¯1 ¯1↓M3
ABCD
EFGH


Drop with Axes

Drop with Axes: R←X↓[K]Y

Y may be any non scalar array. X must be a simple integer scalar or vector. K is a vector of zero or more axes of Y.

R is an array of the elements of Y with the first or last X[i] elements removed. Elements are removed from the beginning or end of Y according to the sign of X[i].

The rank of R is the same as the rank of Y:

       ⍴⍴R ←→ ⍴⍴Y

The size of each axis of R is determined by the corresponding element of X:

      (⍴R)[,K] ←→ 0⌈(⍴Y)[,K]-|,X

Examples

      ⎕←M←2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      1↓[2]M
 5  6  7  8
 9 10 11 12

17 18 19 20
21 22 23 24

      2↓[3]M
 3  4
 7  8
11 12

15 16
19 20
23 24

      2 1↓[3 2]M
 7  8
11 12

19 20
23 24


Enclose

Enclose: R←⊂Y

Y may be any array. R is a scalar array whose item is the array Y. If Y is a simple scalar, R is the simple scalar unchanged. Otherwise, R has a depth whose magnitude is one greater than the magnitude of the depth of Y.

Examples

      ⊂1
1

      ⊂'A'
A

      ⊂1 2 3
 1 2 3

      ⊂1,⊂'CAT'
 1  CAT

      ⊂2 4⍴⍳8
 1 2 3 4
 5 6 7 8

      ⊂⍳0

      ⊂⊂⍳0

      ⊂⊂10
10


Enclose with Axes

Enclose with Axes: R←⊂[K]Y

Y may be any array. K is a vector of zero or more axes of Y. R is an array of the elements of Y enclosed along the axes K. The shape of R is the shape of Y with the K axes removed:

      ⍴R ←→ (⍴Y)[(⍳⍴⍴R)~K]

The shape of each element of R is the shape of the K'th axes of Y:

      ⍴⊃R ←→ (⍴Y)[,K]

Examples

      ]display A←2 3 4⍴'DUCKSWANBIRDWORMCAKESEED'
┌┌→───┐
↓↓DUCK│
││SWAN│
││BIRD│
││    │
││WORM│
││CAKE│
││SEED│
└└────┘

      ]display ⊂[3]A
┌→─────────────────────┐
↓ ┌→───┐ ┌→───┐ ┌→───┐ │
│ │DUCK│ │SWAN│ │BIRD│ │
│ └────┘ └────┘ └────┘ │
│ ┌→───┐ ┌→───┐ ┌→───┐ │
│ │WORM│ │CAKE│ │SEED│ │
│ └────┘ └────┘ └────┘ │
└∊─────────────────────┘

      ]display ⊂[2 3]A
┌→──────────────┐
│ ┌→───┐ ┌→───┐ │
│ ↓DUCK│ ↓WORM│ │
│ │SWAN│ │CAKE│ │
│ │BIRD│ │SEED│ │
│ └────┘ └────┘ │
└∊──────────────┘

      ]display ⊂[1 3]A
┌→─────────────────────┐
│ ┌→───┐ ┌→───┐ ┌→───┐ │
│ ↓DUCK│ ↓SWAN│ ↓BIRD│ │
│ │WORM│ │CAKE│ │SEED│ │
│ └────┘ └────┘ └────┘ │
└∊─────────────────────┘


Encode

Encode: R←X⊤Y

Y must be a simple numeric array. X must be a simple numeric array. R is the numeric array which results from the representation of Y in the number system defined by X.

The shape of R is (⍴X),⍴Y (the catenation of the shapes of X and Y).

If X is a vector or a scalar, the result for each element of Y is the value of the element expressed in the number system defined by radix X. If Y is greater than can be expressed in the number system, the result is equal to the representation of the residue (×/X)|Y. If the first element of X is 0, the value will be fully represented.

This function is also known as Representation.

Examples

      10⊤5 15 125
5 5 5

      0 10⊤5 15 125
0 1 12
5 5  5

If X is a higher order array, each of the vectors along the first axis of X is used as the radix vector for each element of Y.

Examples

      A
2 0  0
2 0  0
2 0  0
2 0  0
2 8  0
2 8  0
2 8 16
2 8 16

      A⊤75
0 0  0
1 0  0
0 0  0
0 0  0
1 0  0
0 1  0
1 1  4
1 3 11

The example shows binary, octal and hexadecimal representations of the decimal number 75.

Examples

      0 1⊤1.25 10.5
1    10
0.25  0.5

      4 13⊤13?52
 3 1 0  2 3 2 0 1  3 1 2 3 1
12 2 4 12 1 7 6 3 10 1 0 3 8


Enlist

Enlist: (⎕ML≥1) R←∊Y

Migration level must be such that ⎕ML≥1 (otherwise see Type:).

Y may be any array, R is a simple vector created from all the elements of Y in ravel order.

Examples

      ⎕ML←1         ⍝  Migration level 1
      MAT←2 2⍴'MISS' 'IS' 'SIP' 'PI' ⋄ MAT
 MISS  IS
 SIP   PI
      ∊MAT
MISSISSIPPI

      M←1 (2 2⍴2 3 4 5) (6(7 8))
      M
1  2 3  6  7 8
   4 5
      ∊M
1 2 3 4 5 6 7 8


Equal

Equal: R←X=Y

Y may be any array. X may be any array. R is Boolean. ⎕CT is an implicit argument of Equal.

If X and Y are character, then R is 1 if they are the same character. If X is character and Y is numeric, or vice-versa, then R is 0.

If X and Y are numeric, then R is 1 if X and Y are within comparison tolerance of each other.

For real numbers X and Y, X is considered equal to Y if (|X-Y) is not greater than ⎕CT×(|X)⌈|Y.

For complex numbers X=Y is 1 if the magnitude of X-Y does not exceed ⎕CT times the larger of the magnitudes of X and Y; geometrically, X=Y if the number smaller in magnitude lies on or within a circle centred on the one with larger magnitude, having radius ⎕CT times the larger magnitude.

Examples

      3=3.1 3 ¯2 ¯3
0 1 0 0

      a←2+0j1×⎕CT
      a
2J1E¯14
      a=2j.00000000000001 2j.0000000000001
1 0

      'CAT'='FAT'
0 1 1

      'CAT'=1 2 3
0 0 0

      'CAT'='C' 2 3
1 0 0

      ⎕CT←1E¯10
      1=1.000000000001
1

      1=1.0000001
0


Excluding

Excluding: R←X~Y

X must be a scalar or vector. R is a vector of the elements of X excluding those elements which occur in Y taken in the order in which they occur in X.

Elements of X and Y are considered the same if X≡Y returns 1 for those elements.

⎕CT is an implicit argument of Excluding. Excluding is also known as Without.

Examples

      'HELLO'~'GOODBYE'
HLL
      'MONDAY' 'TUESDAY' 'WEDNESDAY'~'TUESDAY' 'FRIDAY'
 MONDAY  WEDNESDAY

      5 10 15~⍳10
15

For performance information, see Search Functions and Hash Tables.


Execute Monadic

Execute (Monadic): R←⍎Y

Y must be a simple character scalar or vector. If Y is an empty vector, it is treated as an empty character vector. Y is taken to be an APL statement to be executed. R is the result of the last-executed expression. If the expression has no value, then ⍎Y has no value. If Y is an empty vector or a vector containing only blanks, then ⍎Y has no value.

If Y contains a branch expression which evaluates to a non-empty result, R does not yield a result. Instead, the branch is effected in the environment from which the Execute was invoked.

Examples

      ⍎'2+2'
4
      4=⍎'2+2'
1
      A
1 2 3
4 5 6
      ⍎'A'
1 2 3
4 5 6
      ⍎'A←2|¯1↑⎕TS ⋄ →0⍴⍨A ⋄ A'
0
      A
0


Execute Dyadic

Execute (Dyadic): R←X⍎Y

Y must be a simple character scalar or vector. If Y is an empty vector, it is treated as an empty character vector. X must be a namespace reference or a simple character scalar or vector representing the name of a namespace. Y is then taken to be an APL statement to be executed in namespace X. R is the result of the last-executed expression. If the expression has no value, then X⍎Y has no value.

Example

      ⎕SE ⍎ '⎕NL 9'


Expand

Expand: R←X\[K]Y

Y may be any array. X is a simple integer scalar or vector. The axis specification is optional. If present, K must be a simple integer scalar or unit vector. The value of K must be an axis of Y. If absent, the last axis of Y is implied. The form R←X⍀Y implies the first axis. If Y is a scalar, it is treated as a one-element vector.

If Y has length 1 along the Kth (or implied) axis, it is extended along that axis to match the number of positive elements in X. Otherwise, the number of positive elements in X must be the length of the Kth (or implied) axis of Y.

R is composed from the sub-arrays along the Kth axis of Y. If X[I] (an element of X) is the Jth positive element in X, then the Jth sub-array along the Kth axis of Y is replicated X[I] times. If X[I] is negative, then a sub-array of fill elements of Y (⊂∊⊃Y) is replicated |X[I] times and inserted in relative order along the Kth axis of the result. If X[I] is zero, it is treated as the value ¯1. The shape of R is the shape of Y except that the length of the Kth axis is +/1⌈|X.

Examples

      0\⍳0
0

      1 ¯2 3 ¯4 5\'A'
A  AAA    AAAAA

      M
1 2 3
4 5 6

      1 ¯2 2 0 1\M
1 0 0 2 2 0 3
4 0 0 5 5 0 6

      1 0 1⍀M
1 2 3
0 0 0
4 5 6

      1 0 1\[1]M
1 2 3
0 0 0
4 5 6

      1 ¯2 1\(1 2)(3 4 5)
 1 2  0 0  0 0  3 4 5


Expand First

Expand First: R←X⍀Y

The form R←X⍀Y implies expansion along the first axis whereas the form R←X\Y implies expansion along the last axis (columns). See Expand:.


Exponential

Exponential: R←*Y

Y must be numeric. R is numeric and is the Yth power of e, the base of natural logarithms.

Example

      *1 0
2.718281828 1

      *0j1 1j2
0.5403023059J0.8414709848 ¯1.131204384J2.471726672

      1+*○0j1 ⍝ Euler Identity
0


Factorial

Factorial: R←!Y

Y must be numeric excluding negative integers. R is numeric. R is the product of the first Y integers for positive integer values of Y. For non-integral values of Y, !Y is equivalent to the gamma function of Y+1.

Examples

      !1 2 3 4 5
1 2 6 24 120

      !¯1.5 0 1.5 3.3
¯3.544907702 1 1.329340388 8.85534336

      !0j1 1j2
0.4980156681J¯0.1549498283 0.1122942423J0.3236128855


Find

Find: R←X⍷Y

X and Y may be any arrays. R is a simple Boolean array the same shape as Y which identifies occurrences of X within Y.

If the rank of X is smaller than the rank of Y, X is treated as if it were the same rank with leading axes of size 1. For example a vector is treated as a 1-row matrix.

If the rank of X is larger than the rank of Y, no occurrences of X are found in Y.

⎕CT and ⎕DCT are implicit arguments to Find.

Examples

      'AN'⍷'BANANA'
0 1 0 1 0 0

      'ANA'⍷'BANANA'
0 1 0 1 0 0

      'BIRDS' 'NEST'⍷'BIRDS' 'NEST' 'SOUP'
1 0 0

      MAT
IS YOU IS
OR IS YOU
ISN'T
      'IS'⍷MAT
1 0 0 0 0 0 0 1 0
0 0 0 1 0 0 0 0 0
1 0 0 0 0 0 0 0 0
      'IS YOU'⍷MAT
1 0 0 0 0 0 0 0 0
0 0 0 1 0 0 0 0 0
0 0 0 0 0 0 0 0 0


First

First: (⎕ML) R←⊃Y or R←↑Y

See function Disclose:.


Floor

Floor: R←⌊Y

Y must be numeric.

For real numbers, R is the largest integer value less than or equal to Y within the comparison tolerance ⎕CT.

Examples

      ⌊¯2.3 0.1 100 3.3
¯3 0 100 3

      ⌊0.5 + 0.4 0.5 0.6
0 1 1

For complex numbers, R depends on the relationship between the real and imaginary parts of the numbers in Y.

      ⌊1j3.2 3.3j2.5 ¯3.3j¯2.5
1J3 3J2 ¯3J¯3

The following (deliberately) simple function illustrates one way to express the rules for evaluating complex Floor.

     ∇ fl←CpxFloor cpxs;a;b
[1]   ⍝ Complex floor of scalar complex number (a+ib)
[2]    a b←9 11○cpxs
[3]    :If 1>(a-⌊a)+b-⌊b
[4]        fl←(⌊a)+0J1×⌊b
[5]    :Else
[6]        :If (a-⌊a)<b-⌊b
[7]            fl←(⌊a)+0J1×1+⌊b
[8]        :Else
[9]            fl←(1+⌊a)+0J1×⌊b
[10]       :EndIf
[11]   :EndIf
     ∇

      CpxFloor¨1j3.2 3.3j2.5 ¯3.3j¯2.5
1J3 3J2 ¯3J¯3

⎕CT is an implicit argument of Floor.


Format Monadic

Format (Monadic): R←⍕Y

Y may be any array. R is a simple character array which will display identically to the display produced by Y. The result is independent of ⎕PW. If Y is a simple character array, then R is Y.

Example

      +B←⍕A←2 6⍴'HELLO PEOPLE'
HELLO
PEOPLE

      B ≡ A
1

If Y is a simple numeric scalar, then R is a vector containing the formatted number without any spaces. A floating point number is formatted according to the system variable ⎕PP. ⎕PP is ignored when formatting integers.

Examples

      ⎕PP←5

      ⍴C←⍕⍳0
0

      ⍴C←⍕10
2

      C
10

      ⍴C←⍕12.34
5

      C
12.34

      ⍕123456789
123456789

      ⍕123.456789
123.46

Scaled notation is used if the magnitude of the non-integer number is too large to represent with ⎕PP significant digits or if the number requires more than five leading zeroes after the decimal point.

Examples

      ⍕123456.7
1.2346E5

      ⍕0.0000001234
1.234E¯7

If Y is a simple numeric vector, then R is a character vector in which each element of Y is independently formatted with a single separating space between formatted elements.

Example

      ⍴C←⍕¯123456 1 22.5 ¯0.000000667 5.00001
27

      C
¯1.2346E5 1 22.5 ¯6.67E¯7 5

If Y is a simple numeric array rank higher than one, R is a character array with the same shape as Y except that the last dimension of Y is determined by the length of the formatted data. The format width is determined independently for each column of Y, such that:

  1. the decimal points for floating point or scaled formats are aligned.
  2. the E characters for scaled formats are aligned, with trailing zeros added to the mantissae if necessary.
  3. integer formats are aligned to the left of the decimal point column, if any, or right-adjusted in the field otherwise.
  4. each formatted column is separated from its neighbours by a single blank column.
  5. the exponent values in scaled formats are left-adjusted to remove any blanks.

Examples

      C←22 ¯0.000000123 2.34 ¯212 123456 6.00002 0

      ⍴C←⍕2 2 3⍴C
2 2 29

      C
  22    ¯1.2300E¯7  2.3400E0
¯212     1.2346E5   6.0000E0

   0     2.2000E1  ¯1.2300E¯7
   2.34 ¯2.1200E2   1.2346E5

If Y is non-simple, and all items of Y at any depth are scalars or vectors, then R is a vector.

Examples

      B←⍕A←'ABC' 100 (1 2 (3 4 5)) 10

      ⍴A
4
      ≡A
¯3

      ⍴B
26
      ≡B
1

      A
 ABC  100  1 2  3 4 5   10

      B
 ABC  100  1 2  3 4 5   10

By replacing spaces with ^, it is clearer to see how the result of ⍕ is formed:

^ABC^^100^^1^2^^3^4^5^^^10

If Y is non-simple, and all items of Y at any depth are not scalars, then R is a matrix.

Example

      D←⍕C←1 'AB' (2 2⍴1+⍳4) (2 2 3⍴'CDEFGHIJKLMN')

      C
1  AB  2 3  CDE
       4 5  FGH

            IJK
            LMN

      ⍴C
4

      ≡C
¯2

      D
1  AB  2 3  CDE
       4 5  FGH

            IJK
            LMN

      ⍴D
5 16

      ≡D
1

By replacing spaces with ^, it is clearer to see how the result of ⍕ is formed:

1^^AB^^2^3^^CDE^
^^^^^^^4^5^^FGH^
^^^^^^^^^^^^^^^^
^^^^^^^^^^^^IJK^
^^^^^^^^^^^^LMN^

⎕PP is an implicit argument of Monadic Format.


Format Dyadic

Format (Dyadic): R←X⍕Y

Y must be a simple real (non-complex) numeric array. X must be a simple integer scalar or vector. R is a character array displaying the array Y according to the specification X. R has rank 1⌈⍴⍴Y and ¯1↓⍴R is ¯1↓⍴Y. If any element of Y is complex, dyadic ⍕ reports a DOMAIN ERROR.

Conformability requires that if X has more than two elements, then ⍴X must be 2×¯1↑⍴Y. If X contains one element, it is extended to (2×¯1↑⍴Y)⍴0,X. If X contains 2 elements, it is extended to (2×¯1↑⍴Y)⍴X.

X specifies two numbers (possibly after extension) for each column in Y. For this purpose, scalar Y is treated as a one-element vector. Each pair of numbers in X identifies a format width (W) and a format precision (P).

If P is 0, the column is to be formatted as integers.

Examples

      5 0 ⍕ 2 3⍴⍳6
    1    2    3
    4    5    6

      4 0⍕1.1 2 ¯4 2.547
   1   2  ¯4   3

If P is positive, the format is floating point with P significant digits to be displayed after the decimal point.

Example

      4 1⍕1.1 2 ¯4 2.547
 1.1 2.0¯4.0 2.5

If P is negative, scaled format is used with |P digits in the mantissa.

Example

      7 ¯3⍕5 15 155 1555
5.00E0 1.50E1 1.55E2 1.56E3

If W is 0 or absent, then the width of the corresponding columns of R are determined by the maximum width required by any element in the corresponding columns of Y, plus one separating space.

Example

      3⍕2 3⍴10 15.2346 ¯17.1 2 3 4
 10.000 15.235 ¯17.100
  2.000  3.000   4.000

If a formatted element exceeds its specified field width when W>0, the field width for that element is filled with asterisks.

Example

      3 0 6 2 ⍕ 3 2⍴10.1 15 1001 22.357 101 1110.1
 10 15.00
*** 22.36
101******

If the format precision exceeds the internal precision, low order digits are replaced by the symbol '_'.

Example

      26⍕2*100
1267650600228229_______________.__________________________

      ⍴26⍕2*100
59

      0 20⍕÷3
 0.3333333333333333____

      0 ¯20⍕÷3
 3.333333333333333____E¯1

The shape of R is the same as the shape of Y except that the last dimension of Y is the sum of the field widths specified in X or deduced by the function. If Y is a scalar, the shape of R is the field width.

      ⍴5 2 ⍕ 2 3 4⍴⍳24
2 3 20


Grade Down Monadic

Grade Down (Monadic): R←⍒Y

Y must be a simple character or simple numeric array of rank greater than 0. R is an integer vector being the permutation of ⍳1↑⍴Y that places the sub-arrays of Y along the first axis in descending order. The indices of any set of identical sub-arrays in Y occur in R in ascending order.

If Y is a numeric array of rank greater than 1, the elements in each of the sub-arrays along the first axis are compared in ravel order with greatest weight being given to the first element and least weight being given to the last element.

Example

      M
2 5 3 2
3 4 1 1
2 5 4 5
2 5 3 2
2 5 3 4

      ⍒M
2 3 5 1 4

      M[⍒M;]
3 4 1 1
2 5 4 5
2 5 3 4
2 5 3 2
2 5 3 2

If Y is a character array, the implied collating sequence is the numerical order of the corresponding Unicode code points (Unicode Edition) or the ordering of characters in ⎕AV (Classic Edition).

⎕IO is an implicit argument of Grade Down.

Note that character arrays sort differently in the Unicode and Classic Editions.

Example

      M
Goldilocks
porridge
Porridge
3 bears
Unicode Edition Classic Edition
      ⍒M
2 3 1 4

      ⍒M
3 1 4 2

      M[⍒M;]
porridge
Porridge
Goldilocks
3 bears

      M[⍒M;]
Porridge
Goldilocks
3 bears
porridge


Grade Down Dyadic

Grade Down (Dyadic): R←X⍒Y

Y must be a simple character array of rank greater than 0. X must be a simple character array of rank 1 or greater. R is a simple integer vector of shape 1↑⍴Y containing the permutation of ⍳1↑⍴Y that places the sub-arrays of Y along the first axis in descending order according to the collation sequence X. The indices of any set of identical sub-arrays in Y occur in R in ascending order.

If X is a vector, the following identity holds:

      X⍒Y ←→ ⍒X⍳Y

A left argument of rank greater than 1 allows successive resolution of duplicate orderings in the following way.

Starting with the last axis:

  • The characters in the right argument are located along the current axis of the left argument. The position of the first occurrence gives the ordering value of the character.
  • If a character occurs more than once in the left argument its lowest position along the current axis is used.
  • If a character of the right argument does not occur in the left argument, the ordering value is one more than the maximum index of the current axis - as with dyadic iota.

The process is repeated using each axis in turn, from the last to the first, resolving duplicates until either no duplicates result or all axes have been exhausted.

For example, if index origin is 1:

Left argument: Right argument:
abc
ABA

ab
ac
Aa
Ac

Along last axis:

Character: Value: Ordering:
ab
ac
Aa
Ac

1 2
1 3
1 1
1 3

3
=1   <-duplicate ordering with
4
=1   <-respect to last axis.

Duplicates exist, so resolve these with respect to the first axis:

Character: Value: Ordering:
ac
Ac

1 1
2 1

2
1

So the final row ordering is:

        ab              3
        ac              2
        Aa              4
        Ac              1

That is, the order of rows is 4 2 1 3 which corresponds to a descending row sort of:

        Ac              1
        ac              2
        ab              3
        Aa              4

Examples

      ⍴S1
2 27
      S1
 ABCDEFGHIJKLMNOPQRSTUVWXYZ
 abcdefghijklmnopqrstuvwxyz
      S2
 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
      S3
 AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
      S4
 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

The following results are tabulated for comparison:

X       X[S1⍒X;]    X[S2⍒X;]    X[S3⍒X;]    X[S4⍒X;]
FIRsT     TAPE        rAT         TAPE        TAPE
TAP       TAP         fIRST       TAP         TAP
RATE      RATE        TAPE        rAT         RATE
FiRST     rAT         TAP         RATE        rAT
FIRST     RAT         RATE        RAT         RAT
rAT       MAT         RAT         MAT         MAT
fIRST     fIRST       MAT         fIRST       FIRsT
TAPE      FiRST       FiRST       FiRST       FiRST
MAT       FIRsT       FIRsT       FIRsT       FIRST
RAT       FIRST       FIRST       FIRST       fIRST

⎕IO is an implicit argument of Grade Down.


Grade Up Monadic

Grade Up (Monadic): R←⍋Y

Y must be a simple character or simple numeric array of rank greater than 0. R is an integer vector being the permutation of ⍳1↑⍴Y that places the sub-arrays along the first axis in ascending order.

If Y is a numeric array of rank greater than 1, the elements in each of the sub-arrays along the first axis are compared in ravel order with greatest weight being given to the first element and least weight being given to the last element.

Examples

      ⍋22.5 1 15 3 ¯4
5 2 4 3 1

      M
2 3 5
1 4 7

2 3 5
1 2 6

2 3 4
5 2 4

      ⍋M
3 2 1

If Y is a character array, the implied collating sequence is the numerical order of the corresponding Unicode code points (Unicode Edition) or the ordering of characters in ⎕AV (Classic Edition).

⎕IO is an implicit argument of Grade Up

Note that character arrays sort differently in the Unicode and Classic Editions.

      M
Goldilocks
porridge
Porridge
3 bears

Unicode Edition Classic Edition
      ⍋M
4 1 3 2

      ⍋M
2 4 1 3

      M[⍋M;]
3 bears
Goldilocks
Porridge
porridge
      M[⍋M;]
porridge
3 bears
Goldilocks
Porridge


Greater

Greater: R←X>Y

Y must be numeric. X must be numeric. R is Boolean. R is 1 if X is greater than Y and X=Y is 0. Otherwise R is 0.

⎕CT is an implicit argument of Greater.

Examples

      1 2 3 4 5 > 2
0 0 1 1 1

      ⎕CT←1E¯10

      1 1.00000000001 1.000000001 > 1
0 0 1


Greater Or Equal

Greater Or Equal: R←X≥Y

Y must be numeric. X must be numeric. R is Boolean. R is 1 if X is greater than Y or X=Y. Otherwise R is 0.

⎕CT is an implicit argument of Greater Or Equal.

Examples

      1 2 3 4 5 ≥ 3
0 0 1 1 1

      ⎕CT←1E¯10

      1≥1
1

      1≥1.00000000001
1

      1≥1.00000001
0


Identity

Identity: R←⊢Y

Y may be any array. The result R is the argument Y.

Example

      ⊢'abc' 1 2 3
 abc  1 2 3


Index

Index: R←{X}⌷Y

Dyadic case

X must be a scalar or vector of depth ≤2 of integers each ≥⎕IO. Y may be any array. In general, the result R is similar to that obtained by square-bracket indexing in that:

      (I J ... ⌷ Y) ≡ Y[I;J;...]

The length of left argument X must be less than or equal to the rank of right argument Y. Any missing trailing items of X default to the index vector of the corresponding axis of Y.

Note that in common with square-bracket indexing, items of the left argument X may be of any rank and that the shape of the result is the concatenation of the shapes of the items of the left argument:

      (⍴X⌷Y) ≡ ↑,/⍴¨X

Index is sometimes referred to as squad indexing.

Note that index may be used with selective specification.

⎕IO is an implicit argument of index.

Examples

      ⎕IO←1

      VEC←111 222 333 444
      3⌷VEC
333
      (⊂4 3)⌷VEC
444 333
      (⊂2 3⍴3 1 4 1 2 3)⌷VEC
333 111 444
111 222 333

      ⎕←MAT←10⊥¨⍳3 4
11 12 13 14
21 22 23 24
31 32 33 34

      2 1⌷MAT
21
      2⌷MAT
21 22 23 24

      3(2 1)⌷MAT
32 31
      (2 3)1⌷MAT
21 31
      (2 3)(,1)⌷MAT
21
31
      ⍴(2 1⍴1)(3 4⍴2)⌷MAT
2 1 3 4
      ⍴⍬ ⍬⌷MAT
0 0
      (3(2 1)⌷MAT)←0 ⋄ MAT    ⍝ Selective assignment.
11 12 13 14
21 22 23 24
 0  0 33 34

Monadic case

If Y is an array, Y is returned.

If Y is a ref to an instance of a Class with a Default property, all elements of the Default property are returned. For example, if Item is the default property of MyClass, and imc is an Instance of MyClass, then by definition:

      imc.Item≡⌷imc

NONCE ERROR is reported if the Default Property is Keyed, because in this case APL has no way to determine the list of all the elements.

Note that the values of the index set are obtained or assigned by calls to the corresponding PropertyGet and PropertySet functions. Furthermore, if there is a sequence of primitive functions to the left of the Index function, that operate on the index set itself (functions such as dyadic ⍴,↑,↓,⊃) as opposed to functions that operate on the values of the index set (functions such as +,⌈,⌊,⍴¨), calls to the PropertyGet and PropertySet functions are deferred until the required index set has been completely determined. The full set of functions that cause deferral of calls to the PropertyGet and PropertySet functions is the same as the set of functions that applies to selective specification.

If for example, CompFile is an Instance of a Class with a Default Numbered Property, the expression:

       1↑⌽⌷CompFile

would only call the PropertyGet function (for CompFile) once, to get the value of the last element.

Note that similarly, the expression

      10000⍴⌷CompFile

would call the PropertyGet function 10000 times, on repeated indices if CompFile has less than 10000 elements. The deferral of access function calls is intended to be an optimisation, but can have the opposite effect. You can avoid unnecessary repetitive calls by assigning the result of ⌷ to a temporary variable.


Index with Axes

Index with Axes: R←{X}⌷[K]Y

X must be a scalar or vector of depth ≤2, of integers each ≥⎕IO. Y may be any array. K is a simple scalar or vector specifying axes of Y. The length of K must be the same as the length of X:

      (⍴,X) ≡ ⍴,K

In general, the result R is similar to that obtained by square-bracket indexing with elided subscripts. Items of K distribute items of X along the axes of Y. For example:

      I J ⌷[1 3] Y  ←→  Y[I;;J]

Note that index with axis may be used with selective specification. ⎕IO is an implicit argument of index with axis.

Examples

     ⎕IO←1

     ⎕←CUBE←10⊥¨⍳2 3 4
111 112 113 114
121 122 123 124
131 132 133 134

211 212 213 214
221 222 223 224
231 232 233 234

      2⌷[1]CUBE
211 212 213 214
221 222 223 224
231 232 233 234

      2⌷[3]CUBE
112 122 132
212 222 232

      CUBE[;;2] ≡ 2⌷[3]CUBE
1
      (1 3)4⌷[2 3]CUBE
114 134
214 234

      CUBE[;1 3;4] ≡ (1 3)4⌷[2 3]CUBE
1

      (2(1 3)⌷[1 3]CUBE)←0 ⋄ CUBE ⍝ Selective assignment.
111 112 113 114
121 122 123 124
131 132 133 134

  0 212   0 214
  0 222   0 224
  0 232   0 234


Index Generator

Index Generator: R←⍳Y

Y must be a simple scalar or vector array of non-negative numbers. R is a numeric array composed of the set of all possible coordinates of an array of shape Y. The shape of R is Y and each element of R occurs in its self-indexing position in R. In particular, the following identity holds:

      ⍳Y ←→ (⍳Y)[⍳Y]

⎕IO is an implicit argument of Index Generator. This function is also known as Interval.

Examples

      ⎕IO
1
      ⍴⍳0
0
      ⍳5
1 2 3 4 5

      ⍳2 3
 1 1  1 2  1 3
 2 1  2 2  2 3

      ⊢A←2 4⍴'MAINEXIT'
MAIN
EXIT
      A[⍳⍴A]
MAIN
EXIT

      ⎕IO←0
      ⍳5
0 1 2 3 4

      ⍳2 3
 0 0  0 1  0 2
 1 0  1 1  1 2

      A[⍳⍴A]
MAIN
EXIT


Index Of

Index Of: R←X⍳Y

Y may be any array. X may be any vector. R is a simple integer array with the same shape as Y identifying where elements of Y are first found in X. If an element of Y cannot be found in X, then the corresponding element of R will be ⎕IO+⍴X.

Elements of X and Y are considered the same if X≡Y returns 1 for those elements.

⎕IO and ⎕CT are implicit arguments of Index Of.

Examples

      ⎕IO←1

      2 4 3 1 4⍳1 2 3 4 5
4 1 3 2 6

      'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD'
2 4

For performance information, see Search Functions and Hash Tables.


Indexing

Indexing: R←X[Y]

X may be any array. Y must be a valid index specification. R is an array composed of elements indexed from X and the shape of X is determined by the index specification.

Bracket Indexing does not follow the normal syntax of a dyadic function.

⎕IO is an implicit argument of Indexing.

Three forms of indexing are permitted. The form used is determined by context.

Simple Indexing

For vector X, Y is a simple integer array composed of items from the set ⍳⍴X.

R consists of elements selected according to index positions in Y. R has the same shape as Y.

Examples

      A←10 20 30 40 50

      A[2 3⍴1 1 1 2 2 2]
10 10 10
20 20 20

      A[3]
30

      'ONE' 'TWO' 'THREE'[2]
 TWO

For matrix X, Y is composed of two simple integer arrays separated by the semicolon character (;). The arrays select indices from the rows and columns of X respectively.

Examples

      +M←2 4⍴10×⍳8
10 20 30 40
50 60 70 80

      M[2;3]
70

For higher order array X, Y is composed of a simple integer array for each axis of X with adjacent arrays separated by a single semicolon character (;). The arrays select indices from the respective axes of X, taken in row-major order.

Examples

      ⊢A←2 3 4⍴10×⍳24
 10  20  30  40
 50  60  70  80
 90 100 110 120

130 140 150 160
170 180 190 200
210 220 230 240

      A[1;1;1]
10

      A[2;3 2;4 1]
240 210
200 170

If an indexing array is omitted for the Kth axis, the index vector ⍳(⍴X)[K] is assumed for that axis.

Examples

      A[;2;]
 50  60  70  80
170 180 190 200

      M
10 20 30 40
50 60 70 80

      M[;]
10 20 30 40
50 60 70 80

      M[1;]
10 20 30 40

      M[;1]
10 50

Choose Indexing

The index specification Y is a non-simple array. Each item identifies a single element of X by a set of indices with one element per axis of X in row-major order.

Examples

      M
10 20 30 40
50 60 70 80

      M[⊂1 2]
20

      M[2 2⍴⊂2 4]
80 80
80 80

      M[(2 1)(1 2)]
50 20

A scalar may be indexed by the enclosed empty vector:

      S←'Z'
      S[3⍴⊂⍳0]
ZZZ

Simple and Choose indexing are indistinguishable for vector X:

      V←10 20 30 40

      V[⊂2]
20
      ⊂2
2
      V[2]
20

Reach Indexing

The index specification Y is a non-simple integer array, each of whose items reach down to a nested element of X. The items of an item of Y are simple vectors (or scalars) forming sets of indices that index arrays at successive levels of X starting at the top-most level. A set of indices has one element per axis at the respective level of nesting of X in row-major order.

Examples

      G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)
      G←2 3⍴G,('MNO' 5)('PQR' 6)
      G
  ABC  1   DEF  2   GHI  3
  JKL  4   MNO  5   PQR  6

      G[((1 2)1)((2 3)2)]
 DEF  6

      G[2 2⍴⊂(2 2)2]
5 5
5 5
      G[⊂⊂1 1]
  ABC  1

      G[⊂1 1]
  ABC  1

      V←,G

      V[⊂⊂1]
  ABC  1

      V[⊂1]
  ABC  1

      V[1]
  ABC  1


Intersection

Intersection: R←X∩Y

Y must be a scalar or vector. X must be a scalar or vector. A scalar X or Y is treated as a one-element vector. R is a vector composed of items occurring in both X and Y in the order of occurrence in X. If an item is repeated in X and also occurs in Y, the item is also repeated in R.

Items in X and Y are considered the same if X≡Y returns 1 for those items.

⎕CT is an implicit argument of Intersection.

Examples

      'ABRA'∩'CAR'
ARA

      1 'PLUS' 2 ∩ ⍳5
1 2

For performance information, see Search Functions and Hash Tables.


Left

Left: R←X⊣Y

X and Y may be any arrays.

The result R is the left argument X.

Example

      42⊣'abc' 1 2 3
42

Note that when ⊣ is applied using reduction, the derived function selects the first sub-array of the array along the specified dimension. This is implemented as an idiom.

Examples

      ⊣/1 2 3
1

      mat←↑'scent' 'canoe' 'arson' 'rouse' 'fleet'
      ⊣⌿mat  ⍝ first row
scent
      ⊣/mat  ⍝ first column
scarf
      ⊣/[2]2 3 4⍴⍳24 ⍝ first row from each plane
 1  2  3  4
13 14 15 16

Similarly, with expansion:

      ⊣\mat
sssss
ccccc
aaaaa
rrrrr
fffff
      ⊣⍀mat
scent
scent
scent
scent
scent


Less

Less: R←X<Y

Y may be any numeric array. X may be any numeric array. R is Boolean. R is 1 if X is less than Y and X=Y is 0. Otherwise R is 0.

⎕CT is an implicit argument of Less.

Examples

      (2 4) (6 8 10) < 6
 1 1  0 0 0

      ⎕CT←1E¯10

      1 0.99999999999 0.9999999999<1
0 0 1


Less Or Equal

Less Or Equal: R←X≤Y

Y may be any numeric array. X may be any numeric array. R is Boolean. R is 1 if X is less than Y or X=Y. Otherwise R is 0.

⎕CT is an implicit argument of Less Or Equal.

Examples

      2 4 6 8 10 ≤ 6
1 1 1 0 0

      ⎕CT←1E¯10

      1  1.00000000001 1.00000001 ≤ 1
1 1 0


Logarithm

Logarithm: R←X⍟Y

Y must be a positive numeric array. X must be a positive numeric array. X cannot be 1 unless Y is also 1. R is the base X logarithm of Y.

Note that Logarithm (dyadic ⍟) is defined in terms of Natural Logarithm (monadic ⍟) as:

      X⍟Y←→(⍟Y)÷⍟X

Examples

      10⍟100 2
2 0.3010299957

      2 10⍟0J1 1J2
0J2.266180071 0.3494850022J0.4808285788

      1 ⍟ 1
1
      2 ⍟ 1
0


Magnitude

Magnitude: R←|Y

Y may be any numeric array. R is numeric composed of the absolute (unsigned) values of Y.

Note that the magnitude of a complex number [image] is defined to be

Examples

      |2 ¯3.4 0 ¯2.7
2 3.4 0 2.7

      |3j4
5


Match

Match: R←X≡Y

Y may be any array. X may be any array. R is a simple Boolean scalar. If X is identical to Y, then R is 1. Otherwise R is 0.

Non-empty arrays are identical if they have the same structure and the same values in all corresponding locations. Empty arrays are identical if they have the same shape and the same prototype (disclosed nested structure).

⎕CT is an implicit argument of Match.

Examples

      ⍬≡⍳0
1
      ''≡⍳0
0
      A
THIS
WORD

      A≡2 4⍴'THISWORD'
1
      A≡⍳10
0
      +B←A A
 THIS  THIS
 WORD  WORD

      A≡⊃B
1

      (0⍴A)≡0⍴B
0

      ' '=⊃0⍴B
1 1 1 1
1 1 1 1

      ' '=⊃0⍴A
1


Matrix Divide

Matrix Divide: R←X⌹Y

Y must be a simple numeric array of rank 2 or less. X must be a simple numeric array of rank 2 or less. Y must be non-singular. A scalar argument is treated as a matrix with one-element. If Y is a vector, it is treated as a single column matrix. If X is a vector, it is treated as a single column matrix. The number of rows in X and Y must be the same. Y must have at least the same number of rows as columns.

R is the result of matrix division of X by Y. That is, the matrix product Y+.×R is X.

R is determined such that (X-Y+.×R)*2 is minimised.

The shape of R is (1↓⍴Y),1↓⍴X.

Examples

      ⎕PP←5

      B
3 1 4
1 5 9
2 6 5

      35 89 79 ⌹ B
2.1444 8.2111 5.0889

      A
35 36
89 88
79 75

      A ⌹ B
2.1444 2.1889
8.2111 7.1222
5.0889 5.5778

If there are more rows than columns in the right argument, the least squares solution results. In the following example, the constants a and b which provide the best fit for the set of equations represented by P = a + bQ are determined:

      Q
1 1
1 2
1 3
1 4
1 5
1 6

      P
12.03 8.78 6.01 3.75 ¯0.31 ¯2.79

      P⌹Q
14.941 ¯2.9609

Example: linear regression on complex numbers

      x←j⌿¯50+?2 13 4⍴100
      y←(x+.×3 4 5 6) + j⌿0.0001×¯50+?2 13⍴100
      ⍴x
13 4
      ⍴y
13
      y ⌹ x
3J0.000011066 4J¯0.000018499 5J0.000005745 6J0.000050328
      ⍝ i.e. y⌹x recovered the coefficients 3 4 5 6


Matrix Inverse

Matrix Inverse: R←⌹Y

Y must be a simple array of rank 2 or less. Y must be non-singular. If Y is a scalar, it is treated as a one-element matrix. If Y is a vector, it is treated as a single-column matrix. Y must have at least the same number of rows as columns.

R is the inverse of Y if Y is a square matrix, or the left inverse of Y if Y is not a square matrix. That is, R+.×Y is an identity matrix.

The shape of R is ⌽⍴Y.

Examples

      M
2 ¯3
4 10

      +A←⌹M
 0.3125 0.09375
¯0.125  0.0625

Within calculation accuracy, A+.×M is the identity matrix.

      A+.×M
1 0
0 1

      j←{⍺←0 ⋄ ⍺+0J1×⍵}
      x←j⌿¯50+?2 5 5⍴100
      x
¯37J¯41  25J015  ¯5J¯09   3J020 ¯29J041
¯46J026  17J¯24  17J¯46  43J023 ¯12J¯18
  1J013  33J025 ¯47J049 ¯45J¯14   2J¯26
 17J048 ¯50J022 ¯12J025 ¯44J015  ¯9J¯43
 18J013   8J038  43J¯23  34J¯07   2J026
      ⍴x
5 5
      id←{∘.=⍨⍳⍵}  ⍝ identity matrix of order ⍵
      ⌈/,| (id 1↑⍴x) - x+.×⌹x
3.66384E¯16


Maximum

Maximum: R←X⌈Y

Y may be any numeric array. X may be any numeric array. R is numeric. R is the larger of the numbers X and Y.

Example

      ¯2.01 0.1 15.3 ⌈ ¯3.2 ¯1.1 22.7
¯2.01 0.1 22.7


Membership

Membership: R←X∊Y

Y may be any array. X may be any array. R is Boolean. An element of R is 1 if the corresponding element of X can be found in Y.

An element of X is considered identical to an element in Y if X≡Y returns 1 for those elements.

⎕CT is an implicit argument of Membership.

Examples

      'THIS NOUN' ∊ 'THAT WORD'
1 1 0 0 1 0 1 0 0

      'CAT' 'DOG' 'MOUSE' ∊ 'CAT' 'FOX' 'DOG' 'LLAMA'
1 1 0

For performance information, see Search Functions and Hash Tables.


Minimum

Minimum: R←X⌊Y

Y may be any numeric array. X may be any numeric array. R is numeric. R is the smaller of X and Y.

Example

      ¯2.1 0.1 15.3 ⌊ ¯3.2 1 22
¯3.2 0.1 15.3


Minus

Minus: R←X-Y

See Subtract:.


Mix

Mix: (⎕ML) R←↑[K]Y or R←⊃[K]Y

The symbol chosen to represent Mix depends on the current Migration Level.

If ⎕ML<2, Mix is represented by the symbol: ↑.

If ⎕ML≥2, Mix is represented by the symbol: ⊃.

Y may be any array. All of the items of Y must be scalars and/or arrays of the same rank. It is not necessary that nonscalar items have the same shape.

K is an optional axis specification. If present it must be a scalar or unit vector. The value of K must be a fractional number indicating the two axes of Y between which new axes are to be inserted. If absent, new ones are added at the end.

R is an array composed from the items of a Y assembled into a higher order array with one less level of nesting. If items of Y have different shapes, each is padded with the corresponding prototype to a shape that represents the greatest length along each axis of all items in Y. The shape of R is the shape of Y with the shape of a typical (extended) item of Y inserted between the ⌊Kth and the ⌈Kth axes of Y.

Examples

      ↑(1)(1 2)(1 2 3)
1 0 0
1 2 0
1 2 3

      ↑[0.5](1) (1 2) (1 2 3)
1 1 1
0 2 2
0 0 3

      A←('andy' 19)('geoff' 37)('pauline' 21)

      ↑A
 andy    19
 geoff   37
 pauline 21

      ↑[0.5]A
 andy  geoff  pauline
   19     37       21


Multiply

Multiply: R←X×Y

Y may be any numeric array. X may be any numeric array. R is the arithmetic product of X and Y.

This function is also known as Times.

Example

      3 2 1 0 × 2 4 9 6
6 8 9 0

       2j3×.3j.5 1j2 3j4 .5
¯0.9J1.9 ¯4J7 ¯6J17 1J1.5


Nand

Nand: R←X⍲Y

Y must be a Boolean array. X must be a Boolean array. R is Boolean. The value of R is the truth value of the proposition "not both X and Y", and is determined as follows:

             X   Y     R

             0   0     1
             0   1     1
             1   0     1
             1   1     0

Example

      (0 1)(1 0) ⍲ (0 0)(1 1)
 1 1  0 1


Natural Logarithm

Natural Logarithm: R←⍟Y

Y must be a positive numeric array. R is numeric. R is the natural (or Napierian) logarithm of Y whose base is the mathematical constant e=2.71828....

Example

      ⍟1 2
0 0.6931471806

      ⍟2 2⍴0j1 1j2 2j3 3j4
0.000000000J1.570796327  0.8047189562J1.107148718
1.282474679J0.9827937232 1.6094379120J0.927295218


Negative

Negative: R←-Y

Y may be any numeric array. R is numeric and is the negative value of Y. For complex numbers both the real and imaginary parts are negated.

Example

      -4 2 0 ¯3 ¯5
¯4 ¯2 0 3 5

      -1j2 ¯2J3 4J¯5
¯1J¯2 2J¯3 ¯4J5


Nor

Nor: R←X⍱Y

Y must be a Boolean array. X must be a Boolean array. R is Boolean. The value of R is the truth value of the proposition "neither X nor Y", and is determined as follows:

             X   Y     R

             0   0     1
             0   1     0
             1   0     0
             1   1     0

Example

      0 0 1 1 ⍱ 0 1 0 1
1 0 0 0


Not

Not: R←~Y

Y must be a Boolean array. R is Boolean. The value of R is 0 if Y is 1, and R is 1 if Y is 0.

Example

      ~0 1
1 0


Not Equal

Not Equal: R←X≠Y

Y may be any array. X may be any array. R is Boolean. R is 0 if X=Y. Otherwise R is 1.

For Boolean X and Y, the value of R is the “exclusive or” result, determined as follows:

             X   Y     R

             0   0     0
             0   1     1
             1   0     1
             1   1     0

⎕CT is an implicit argument of Not Equal.

Examples

      1 2 3 ≠ 1.1 2 3
1 0 0

      ⎕CT←1E¯10

      1≠1 1.00000000001 1.0000001
0 0 1

      1 2 3 ≠'CAT'
1 1 1


Not Match

Not Match: R←X≢Y

Y may be any array. X may be any array. R is a simple Boolean scalar. If X is identical to Y, then R is 0. Otherwise R is 1.

Non-empty arrays are identical if they have the same structure and the same values in all corresponding locations. Empty arrays are identical if they have the same shape and the same prototype (disclosed nested structure).

⎕CT is an implicit argument of Not Match.

Examples

      ⍬≢⍳0
0
      ''≢⍳0
1

      ⊢A←⊂(⍳3) 'ABC'
  1 2 3  ABC
      A≢(⍳3)'ABC'
1
      A≢⊂(⍳3) 'ABC'
0
      ⍬≢0⍴A
1
      (1↑0⍴A)≢⊂(0 0 0) '   '
1


Or Greatest Common Divisor

Or, Greatest Common Divisor: R←X∨Y

Case 1: X and Y are Boolean

R is Boolean and is determined as follows:

             X   Y     R

             0   0     0
             0   1     1
             1   0     1
             1   1     1

Example

      0 0 1 1 ∨ 0 1 0 1
0 1 1 1

Case 2: X and Y are numeric (non-Boolean)

R is the Greatest Common Divisor of X and Y.

Examples

      15 1 2 7 ∨ 35 1 4 0
5 1 2 7

      rational←{↑⍵ 1÷⊂1∨⍵} ⍝ rational (⎕CT) approximation
                           ⍝ to floating array.
      rational 0.4321 0.1234 6.66, ÷1 2 3
 4321  617 333 1 1 1
10000 5000  50 1 2 3

⎕CT is an implicit argument in case 2.


Partitioned Enclose

Partitioned Enclose: (⎕ML<3) R←X⊂[K]Y

Y may be any array. X must be a simple Boolean scalar or vector.

The axis specification is optional. If present, it must be a simple integer scalar or one-element vector. The value of K must be an axis of Y. If absent, the last axis of Y is implied.

X must have the same length as the Kth axis of Y. However, if X is a scalar or one-element vector, it will be extended to the length of the Kth axis of Y.

R is a vector of items selected from Y. The sub-arrays identified along the Kth axis of Y at positions corresponding to each 1 in X up to the position before the next 1 in X (or the last element of X) become the successive items of Y. The length of R is +/X (after possible extension).

Examples

      0 1 0 0 1 1 0 0 0 ⊂⍳9
 2 3 4  5  6 7 8 9

      1 0 1 ⊂[1] 3 4⍴⍳12
 1 2 3 4  9 10 11 12
 5 6 7 8

      1 0 0 1 ⊂[2]3 4⍴⍳12
 1  2  3   4
 5  6  7   8
 9 10 11  12


Pi Times

Pi Times: R←○Y

Y may be any numeric array. R is numeric. The value of R is the product of the mathematical constant π=3.14159... (Pi), and Y.

Example

      ○0.5 1 2
1.570796327 3.141592654 6.283185307

      ○0J1
0J3.141592654

      *○0J1 ⍝ Euler
¯1


Pick

Pick: R←X⊃Y

Y may be any array.

X is a scalar or vector of indices of Y, viz. ⍳⍴Y.

R is an item selected from the structure of Y according to X.

Elements of X select from successively deeper levels in the structure of Y. The items of X are simple integer scalars or vectors which identify a set of indices, one per axis at the particular level of nesting of Y in row-major order. Simple scalar items in Y may be picked by empty vector items in X to any arbitrary depth.

⎕IO is an implicit argument of Pick.

Examples

      G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)

      G←2 3⍴G,('MNO' 5)('PQR' 6)

      G
  ABC  1   DEF  2   GHI  3
  JKL  4   MNO  5   PQR  6

      ((⊂2 1),1)⊃G
JKL

      (⊂2 1)⊃G
 JKL  4

      ((2 1)1 2)⊃G
K

      (5⍴⊂⍳0)⊃10
10


Plus

Plus: R←X+Y

See Add: .


Power

Power: R←X*Y

Y must be a numeric array. X must be a numeric array. R is numeric. The value of R is X raised to the power of Y.

If Y is zero, R is defined to be 1.

If X is zero, Y must be non-negative.

In general, if X is negative, the result R is likely to be complex.

Examples

      2*2 ¯2
4 0.25

      9 64*0.5
3 8

      ¯27*3 2 1.2 .5
¯19683 729 ¯42.22738244J¯30.67998919 0J5.196152423


Ravel

Ravel: R←,Y

Y may be any array. R is a vector of the elements of Y taken in row-major order.

Examples

      M
1 2 3
4 5 6

      ,M
1 2 3 4 5 6

      A
ABC
DEF
GHI
JKL

      ,A
ABCDEFGHIJKL

      ⍴,10
1


Ravel with Axes

Ravel with Axes: R←,[K]Y

Y may be any array.

K is either:

  • A simple fractional scalar adjacent to an axis of Y, or
  • A simple integer scalar or vector of axes of Y, or
  • An empty vector.

Ravel with axis can be used with selective specification.

R depends on the case of K above.

If K is a fraction, the result R is an array of the same shape as Y, but with a new axis of length 1 inserted at the K'th position.

      ⍴⍴R ←→ 1+⍴⍴Y
      ⍴R  ←→ (1,⍴Y)[⍋K,⍳⍴⍴Y]

Examples

      ,[0.5]'ABC'
ABC
      ⍴,[0.5]'ABC'
1 3
      ,[1.5]'ABC'
A
B
C
      ⍴,[1.5]'ABC'
3 1

      MAT←3 4⍴⍳12
      ⍴,[0.5]MAT
1 3 4
      ⍴,[1.5]MAT
3 1 4
      ⍴,[2.5]MAT
3 4 1

If K is an integer scalar or vector of axes of Y, then:

  • K must contain contiguous axes of Y in ascending order.
  • R contains the elements of Y raveled along the indicated axes.

Note that if K is a scalar or single element vector, R ←→ Y.

      ⍴⍴R ←→ 1+(⍴⍴Y)-⍴,K

Examples

      M
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24
      ⍴M
2 3 4

      ,[1 2]M
 1  2  3  4
 5  6  7  8
 9 10 11 12
13 14 15 16
17 18 19 20
21 22 23 24
      ⍴,[1 2]M
6 4

      ,[2 3]M
 1  2  3  4  5  6  7  8  9 10 11 12
13 14 15 16 17 18 19 20 21 22 23 24

      ⍴,[2 3]M
2 12

If K is an empty vector a new last axis of length 1 is created.

      ⍴R ←→ (⍴Y),1

Examples

      Q1←'January' 'February' 'March'
      ]display Q1
┌→─────────────────────────────┐
│ ┌→──────┐ ┌→───────┐ ┌→────┐ │
│ │January│ │February│ │March│ │
│ └───────┘ └────────┘ └─────┘ │
└∊─────────────────────────────┘
      ]display ,[⍳0]Q1
┌→───────────┐
↓ ┌→──────┐  │
│ │January│  │
│ └───────┘  │
│ ┌→───────┐ │
│ │February│ │
│ └────────┘ │
│ ┌→────┐    │
│ │March│    │
│ └─────┘    │
└∊───────────┘


Reciprocal

Reciprocal: R←÷Y

Y must be a numeric array. R is numeric. R is the reciprocal of Y; that is 1÷Y. If ⎕DIV=0, ÷0 results in a DOMAIN ERROR. If ⎕DIV=1, ÷0 returns 0.

⎕DIV is an implicit argument of Reciprocal.

Examples

      ÷4 2 5
0.25 0.5 0.2

      ÷0j1 0j¯1 2j2 4j4
0J¯1 0J1 0.25J¯0.25 0.125J¯0.125

      ⎕DIV←1
      ÷0 0.5
0 2


Replicate

Replicate: R←X/[K]Y

Y may be any array. X is a simple integer vector or scalar.

The axis specification is optional. If present, K must be a simple integer scalar or unit vector. The value of K must be an axis of Y. If absent, the last axis of Y is implied. The form R←X⌿Y implies the first axis of Y.

If Y has length 1 along the Kth (or implied) axis, it is extended along that axis to match the length of X. Otherwise, the length of X must be the length of the Kth (or implied) axis of Y. However, if X is a scalar or one-element vector, it will be extended to the length of the Kth axis.

R is composed from sub-arrays along the Kth axis of Y. If X[I] (an element of X) is positive, then the corresponding sub-array is replicated X[I] times. If X[I] is zero, then the corresponding sub-array of Y is excluded. If X[I] is negative, then the fill element of Y (⊂∊⊃Y) is replicated |X[I] times. Each of the (replicated) sub-arrays and fill items are joined along the Kth axis in the order of occurrence. The shape of R is the shape of Y except that the length of the (implied) Kth axis is +/|X (after possible extension).

This function is sometimes called Compress when X is Boolean.

Examples

      1 0 1 0 1/⍳5
1 3 5

      1 ¯2 3 ¯4 5/⍳5
1 0 0 3 3 3 0 0 0 0 5 5 5 5 5

      M
1 2 3
4 5 6

      2 0 1/M
1 1 3
4 4 6

      0 1⌿M
4 5 6

      0 1/[1]M
4 5 6

If Y is a singleton (1=×/⍴,Y) its value is notionally extended to the length of X along the specified axis.

      1 0 1/4
4 4
      1 0 1/,3
3 3
      1 0 1/1 1⍴5
5 5


Reshape

Reshape: R←X⍴Y

Y may be any array. X must be a simple scalar or vector of non-negative integers. R is an array of shape X whose elements are taken from Y in row-major sequence and repeated cyclically if required. If Y is empty, R is composed of fill elements of Y (⊂∊⊃Y). If X contains at least one zero, then R is empty. If X is an empty vector, then R is scalar.

Examples

      2 3⍴⍳8
1 2 3
4 5 6

      2 3⍴⍳4
1 2 3
4 1 2

      2 3⍴⍳0
0 0 0
0 0 0


Residue

Residue: R←X|Y

Y may be any numeric array. X may be any numeric array.

For positive arguments, R is the remainder when Y is divided by X. If X=0, R is Y. For other argument values, R is Y-N×X where N is some integer such that R lies between 0 and X, but is not equal to X.

⎕CT is an implicit argument of Residue.

Examples

      3 3 ¯3 ¯3|¯5 5 ¯4 4
1 2 ¯1 ¯2

      0.5|3.12 ¯1 ¯0.6
0.12 0 0.4

      ¯1 0 1|¯5.25 0 2.41
¯0.25 0 0.41

      1j2|2j3 3j4 5j6
1J1 ¯1J1 0J1

Note that the ASCII Broken Bar (⎕ucs 166, U+00A6) is not interpreted as Residue.


Reverse

Reverse: R←⌽[K]Y

Y may be any array. The axis specification is optional. If present, K must be an integer scalar or one-element vector. The value of K must be an axis of Y. If absent, the last axis is implied. The form R←⊖Y implies the first axis.

R is the array Y rotated about the Kth or implied axis.

Examples

      ⌽1 2 3 4 5
5 4 3 2 1

      M
1 2 3
4 5 6
      ⌽M
3 2 1
6 5 4
      ⊖M
4 5 6
1 2 3
      ⌽[1]M
4 5 6
1 2 3


Reverse First

Reverse First: R←⊖[K]Y

The form R←⊖Y implies reversal along the first axis. See Reverse:.


Right

Right: R←X⊢Y

X and Y may be any arrays. The result R is the right argument Y.

Example

      42 ⊢'abc' 1 2 3
 abc  1 2 3

Note that when ⊢ is applied using reduction, the derived function selects the last sub-array of the array along the specified dimension. This is implemented as an idiom.

Examples

      ⊢/1 2 3
3
      mat←↑'scent' 'canoe' 'arson' 'rouse' 'fleet'
      ⊢⌿mat  ⍝ last row
fleet
      ⊢/mat  ⍝ last column
tenet

      ⊢/[2]2 3 4⍴⍳24 ⍝ last row from each plane
 9 10 11 12
21 22 23 24


Roll

Roll: R←?Y

Y may be any positive integer array. R has the same shape as Y at each depth.

For each element of Y, y, the corresponding element of R is an integer, pseudo-randomly selected from the integers ⍳y with each integer in this population having an equal chance of being selected.

⎕IO and ⎕RL are implicit arguments of Roll. A side effect of Roll is to change the value of ⎕RL. See Random Number Generator: and Random Link: .

Examples

      ?9 9 9
2 7 5


Rotate

Rotate: R←X⌽[K]Y

Y may be any array. X must be a simple integer array. The axis specification is optional. If present, K must be a simple integer scalar or one-element vector.

The value of K must be an axis of Y. If absent, the last axis of Y is implied. The form R←X⊖Y implies the first axis.

If Y is a scalar, it is treated as a one-element vector. X must have the same shape as the rank of Y excluding the Kth dimension. If X is a scalar or one-element vector, it will be extended to conform. If Y is a vector, then X may be a scalar or a one-element vector.

R is an array with the same shape as Y, with the elements of each of the vectors along the Kth axis of Y rotated by the value of the corresponding element of X. If the value is positive, the rotation is in the sense of right to left. If the value is negative, the rotation is in the sense of left to right.

Examples

      3 ⌽ 1 2 3 4 5 6 7
4 5 6 7 1 2 3
      ¯2 ⌽ 1 2 3 4 5
4 5 1 2 3

      M
 1  2  3  4
 5  6  7  8

 9 10 11 12
13 14 15 16

      I
0 1 ¯1 0
0 3  2 1
      I⌽[2]M
 1  6  7  4
 5  2  3  8

 9 14 11 16
13 10 15 12

      J
2 ¯3
3 ¯2
      J⌽M
 3  4  1  2
 6  7  8  5

12  9 10 11
15 16 13 14


Rotate First

Rotate First: R←X⊖[K]Y

The form R←X⊖Y implies rotation along the first axis. See Rotate:.


Same

Same: R←⊣Y

Y may be any array.

The result R is the argument Y.

Examples

      ⊣'abc' 1 2 3
 abc  1 2 3


Shape

Shape: R←⍴Y

Y may be any array. R is a non-negative integer vector whose elements are the dimensions of Y. If Y is a scalar, then R is an empty vector. The rank of Y is given by ⍴⍴Y.

Examples

      ⍴10

      ⍴'CAT'
3

      ⍴3 4⍴⍳12
3 4

      +G←(2 3⍴⍳6)('CAT' 'MOUSE' 'FLEA')
 1 2 3   CAT  MOUSE  FLEA
 4 5 6

      ⍴G
2

      ⍴⍴G
1

      ⍴¨G
 2 3  3

      ⍴¨¨G
          3  5  4


Split

Split: R←↓[K]Y

Y may be any array. The axis specification is optional. If present, K must be a simple integer scalar or one-element vector. The value of K must be an axis of Y. If absent, the last axis is implied.

The items of R are the sub-arrays of Y along the Kth axis. R is a scalar if Y is a scalar. Otherwise R is an array whose rank is ¯1+⍴⍴Y and whose shape is (K≠⍳⍴⍴Y)/⍴Y.

Examples

      ↓3 4⍴'MINDTHATSTEP'
 MIND  THAT  STEP

      ↓2 5⍴⍳10
 1 2 3 4 5  6 7 8 9 10

      ↓[1]2 5⍴⍳10
 1 6  2 7  3 8  4 9  5 10


Subtract

Subtract: R←X-Y

Y may be any numeric array. X may be any numeric array. R is numeric. The value of R is the difference between X and Y.

This function is also known as Minus.

Example

      3 ¯2 4 0 - 2 1 ¯2 4
1 ¯3 6 ¯4

      2j3-.3j5  ⍝ (a+bi)-(c+di) = (a-c)+(b-d)i
1.7J¯2


Table

Table: R←⍪Y

Y may be any array. R is a 2-dimensional matrix of the elements of Y taken in row-major order, preserving the shape of the first dimension of Y if it exists

Table has been implemented according to the Extended APL Standard (ISO/IEC 13751:2001).

Examples

      ]display {⍵ (⍴⍵)} ⍪'a'
┌→──────────┐
│ ┌→┐ ┌→──┐ │
│ ↓a│ │1 1│ │
│ └─┘ └~──┘ │
└∊──────────┘

      ]display {⍵ (⍴⍵)} ⍪'hello'
┌→──────────┐
│ ┌→┐ ┌→──┐ │
│ ↓h│ │5 1│ │
│ │e│ └~──┘ │
│ │l│       │
│ │l│       │
│ │o│       │
│ └─┘       │
└∊──────────┘

      ]display {⍵ (⍴⍵)} ⍪2 3 4⍴⍳24
┌→─────────────────────────────────────────────┐
│ ┌→──────────────────────────────────┐ ┌→───┐ │
│ ↓ 1  2  3  4  5  6  7  8  9 10 11 12│ │2 12│ │
│ │13 14 15 16 17 18 19 20 21 22 23 24│ └~───┘ │
│ └~──────────────────────────────────┘        │
└∊─────────────────────────────────────────────┘


Take

Take: R←X↑Y

Y may be any array. X must be a simple integer scalar or vector.

If Y is a scalar, it is treated as a one-element array of shape (⍴,X)⍴1. The length of X must be the same as or less than the rank of Y. If the length of X is less than the rank of Y, the missing elements of X default to the length of the corresponding axis of Y.

R is an array of the same rank as Y (after possible extension), and of shape |X. If X[I] (an element of X) is positive, then X[I] sub-arrays are taken from the beginning of the Ith axis of Y. If X[I] is negative, then X[I] sub-arrays are taken from the end of the Ith axis of Y.

If more elements are taken than exist on axis I, the extra positions in R are filled with the fill element of Y (⊂∊⊃Y).

Examples

      5↑'ABCDEF'
ABCDE

      5↑1 2 3
1 2 3 0 0

      ¯5↑1 2 3
0 0 1 2 3

      5↑(⍳3) (⍳4) (⍳5)
 1 2 3  1 2 3 4  1 2 3 4 5  0 0 0  0 0 0

      M
1 2 3 4
5 6 7 8

      2 3↑M
1 2 3
5 6 7

      ¯1 ¯2↑M
7 8
      M3←2 3 4⍴⎕A
      1↑M3
ABCD
EFGH
IJKL
      ¯1↑M3
MNOP
QRST
UVWX


Take with Axes

Take with Axes: R←X↑[K]Y

Y may be any non scalar array. X must be a simple integer scalar or vector. K is a vector of zero or more axes of Y.

R is an array of the first or last elements of Y taken along the axes K depending on whether the corresponding element of X is positive or negative respectively.

The rank of R is the same as the rank of Y:

      ⍴⍴R ←→ ⍴⍴Y

The size of each axis of R is determined by the corresponding element of X:

      (⍴R)[,K] ←→ |,X

Examples

      ⎕←M←2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      2↑[2]M
 1  2  3  4
 5  6  7  8

13 14 15 16
17 18 19 20

      2↑[3]M
 1  2
 5  6
 9 10

13 14
17 18
21 22

      2 ¯2↑[3 2]M
 5  6
 9 10

17 18
21 22


Times

Times: R←X×Y

See Multiply:.


Transpose Monadic

Transpose (Monadic): R←⍉Y

Y may be any array. R is an array of shape ⌽⍴Y, similar to Y with the order of the axes reversed.

Examples

      M
1 2 3
4 5 6

      ⍉M
1 4
2 5
3 6


Transpose Dyadic

Transpose (Dyadic): R←X⍉Y

Y may be any array. X must be a simple scalar or vector whose elements are included in the set ⍳⍴⍴Y. Integer values in X may be repeated but all integers in the set ⍳⌈/X must be included. The length of X must equal the rank of Y.

R is an array formed by the transposition of the axes of Y as specified by X. The Ith element of X gives the new position for the Ith axis of Y. If X repositions two or more axes of Y to the same axis, the elements used to fill this axis are those whose indices on the relevant axes of Y are equal.

⎕IO is an implicit argument of Dyadic Transpose.

Examples

      A
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      2 1 3⍉A
 1  2  3  4
13 14 15 16

 5  6  7  8
17 18 19 20

 9 10 11 12
21 22 23 24

      1 1 1⍉A
1 18

      1 1 2⍉A
 1  2  3  4
17 18 19 20


Type

Type: (⎕ML<1) R←∊Y

Migration level must be such that ⎕ML<1 (otherwise ∊ means Enlist. See Enlist:).

Y may be any array. R is an array with the same shape and structure as Y in which a numeric value is replaced by 0 and a character value is replaced by ' '.

Examples

      ∊(2 3⍴⍳6)(1 4⍴'TEXT')
 0 0 0
 0 0 0

      ' '=∊'X'
1


Union

Union: R←X∪Y

Y must be a vector. X must be a vector. If either argument is a scalar, it is treated as a one-element vector. R is a vector of the elements of X catenated with the elements of Y which are not found in X.

Items in X and Y are considered the same if X≡Y returns 1 for those items.

⎕CT is an implicit argument of Union.

Examples

      'WASH' ∪ 'SHOUT'
WASHOUT

      'ONE' 'TWO' ∪ 'TWO' 'THREE'
 ONE  TWO  THREE

For performance information, see Search Functions and Hash Tables.


Unique

Unique: R←∪Y

Y must be a vector. R is a vector of the elements of Y omitting non-unique elements after the first.

⎕CT is an implicit argument of Unique.

Examples

      ∪ 'CAT' 'DOG' 'CAT' 'MOUSE' 'DOG' 'FOX'
 CAT  DOG  MOUSE  FOX

      ∪ 22 10 22 22 21 10 5 10
22 10 21 5


Without

Without: R←X~Y

See Excluding:.


Zilde

Zilde: R←⍬

The empty vector (⍳0) may be represented by the numeric constant ⍬ called ZILDE.


Operator Syntax

Operators take one or two operands. An operator with one operand is monadic. The operand of a monadic operator is to the left of the operator. An operator with two operands is dyadic. Both operands are required for a dyadic operator.

Operators have long scope to the left. That is, the left operand is the longest function or array expression to its left (see Operators). A dyadic operator has short scope on the right. Right scope may be extended by the use of parentheses.

An operand may be an array, a primitive function, a system function, a defined function or a derived function. An array may be the result of an array expression.

An operator with its operand(s) forms a DERIVED FUNCTION. The derived function may be monadic or dyadic and it may or may not return an explicit result.

Examples

      +/⍳5
15
      (*∘2)⍳3
1 4 9

      PLUS ← + ⋄ TIMES ← ×
      1 PLUS.TIMES 2
2

      ⎕NL 2
A
X
      ⎕EX¨↓⎕NL 2
      ⎕NL 2


Axis Specification

Some operators may include an axis specification. Axis is itself an operator. However the effect of axis is described for each operator where its specification is permitted. ⎕IO is an implicit argument of the function derived from the Axis operator.

The description for each operator follows in alphabetical sequence. The valence of the derived function is specifically identified to the right of the heading block.

Table 11: Primitive Operators

Class of Operator Name Producing Monadic derived function Producing Dyadic derived function
Monadic
Assignment
Assignment
Assignment
Commute
Each
I-Beam
Reduction

Scan

Spawn

f¨Y
A⌶Y
f/Y  [ ]
f⌿Y  [ ]
f\Y  [ ]
f⍀Y  [ ]
f&Y

Xf←Y
X[I]f←Y
(EXP X)f←Y
Xf⍨Y
Xf¨Y

Xf&Y
Dyadic
Axis
Composition

Inner Product
Outer Product
Power
Variant

f[B]Y
f∘gY
A∘gY
(f∘B)Y

f⍣gY
f⍠gY

Xf[B]Y
Xf∘gY

Xf.gY
X∘.gY
Xf⍣gY
Xf⍠gY
[ ]Indicates optional axis specification


Assignment Modified

Assignment (Modified): {R}←Xf←Y

f may be any dyadic function which returns an explicit result. Y may be any array whose items are appropriate to function f. X must be the name of an existing array whose items are appropriate to function f.

R is the “pass-through” value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the value of the array named by X to the result of XfY.

Examples

      A
1 2 3 4 5

      A+←10

      A
11 12 13 14 15

      ⎕←A×←2
2
      A
22 24 26 28 30

      vec←¯4+9?9 ⋄ vec
3 5 1 ¯1 ¯2 4 0 ¯3 2
      vec/⍨←vec>0 ⋄vec
3 5 1 4 2


Assignment Indexed Modified

Assignment (Indexed Modified): {R}←X[I]f←Y

f may be any dyadic function which returns an explicit result. Y may be any array whose items are appropriate to function f. X must be the name of an existing array. I must be a valid index specification. The items of the indexed portion of X must be appropriate to function f.

R is the “pass-through” value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the indexed elements of X, that is X[I], to the result of X[I]fY. This result must have the same shape as X[I].

Examples

      A
1 2 3 4 5

      +A[2 4]+←1
1

      A
1 3 3 5 5

      A[3]÷←2

      A
1 3 1.5 5 5

If an index is repeated, function f will be applied to the successive values of the indexed elements of X, taking the index occurrences in left-to-right order.

Example

      B←5⍴0

      B[2 4 1 2 1 4 2 4 1 3]+←1

      B
3 3 1 3 0


Assignment Selective Modified

Assignment (Selective Modified): {R}←(EXP X)f←Y

f may be any dyadic function which returns an explicit result. Y may be any array whose items are appropriate to function f. X must be the name of an existing array. EXP is an expression that selects elements of X. (See Assignment (Selective): for a list of allowed selection functions.) The selected elements of X must be appropriate to function f.

R is the “pass-through” value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the selected elements of X to the result of X[I]fY where X[I] defines the elements of X selected by EXP.

Example

      A
12 36 23 78 30

      ((A>30)/A) ×← 100
      A
12 3600 23 7800 30


Axis with Monadic Operand

Axis (with Monadic Operand): R←f[B]Y

f must be a monadic primitive mixed function taken from those shown in Table 12 below, or a function derived from the operators Reduction (/) or Scan (\). B must be a numeric scalar or vector. Y may be any array whose items are appropriate to function f. Axis does not follow the normal syntax of an operator.

Table 12: Primitive monadic mixed functions with optional axis.

Function | Name | Range of B
⌽ or ⊖ | Reverse | B∊⍳⍴⍴Y
↑ | Mix | (0≠1|B)^(B>⎕IO-1)^(B<⎕IO+⍴⍴Y)
↓ | Split | B∊⍳⍴⍴Y
, | Ravel | fraction, or zero or more axes of Y
⊂ | Enclose | (B≡⍳0)∨(^/B∊⍳⍴⍴Y)

In most cases, B must be an integer which identifies a specific axis of Y. However, when f is the Mix function (↑) , B is a fractional value whose lower and upper integer bounds select an adjacent pair of axes of Y or an extreme axis of Y.

For Ravel (,) and Enclose (⊂) , B can be a vector of two or more axes.

⎕IO is an implicit argument of the derived function which determines the meaning of B.

Examples

      ⌽[1]2 3⍴⍳6
4 5 6
1 2 3

      ↑[.1]'ONE' 'TWO'
OT
NW
EO


Axis with Dyadic Operand

Axis (with Dyadic Operand): R←Xf[B]Y

f must be a dyadic primitive scalar function, or a dyadic primitive mixed function taken from Table 13 below. B must be a numeric scalar or vector. X and Y may be any arrays whose items are appropriate to function f. Axis does not follow the normal syntax of an operator.

Table 13: Primitive dyadic mixed functions with optional axis.

Function | Name | Range of B
/ or ⌿ | Replicate | B∊⍳⍴⍴Y
\ or ⍀ | Expand | B∊⍳⍴⍴Y
⊂ | Partitioned Enclose | B∊⍳⍴⍴Y
⌽ or ⊖ | Rotate | B∊⍳⍴⍴Y
, or ⍪ | Catenate | B∊⍳⍴⍴Y
, or ⍪ | Laminate | (0≠1|B)^(B>⎕IO-1)^(B<⎕IO+(⍴⍴X)⌈⍴⍴Y)
↑ | Take | zero or more axes of Y
↓ | Drop | zero or more axes of Y

In most cases, B must be an integer value identifying the axis of X and Y along which function f is to be applied.

Exceptionally, B must be a fractional value for the Laminate function (,) whose upper and lower integer bounds identify a pair of axes or an extreme axis of X and Y. For Take (↑) and Drop (↓) , B can be a vector of two or more axes.

⎕IO is an implicit argument of the derived function which determines the meaning of B.

Examples

      1 4 5 =[1] 3 2⍴⍳6
1 0
0 1
1 0

      2 ¯2 1/[2]2 3⍴'ABCDEF'
AA  C
DD  F

      'ABC',[1.1]'='
A=
B=
C=

      'ABC',[0.1]'='
ABC
===

      ⎕IO←O

      'ABC',[¯0.5]'='
ABC
===

Axis with Scalar Dyadic Functions

The axis operator [X] can take a scalar dyadic function as operand. This has the effect of ‘stretching’ a lower rank array to fit a higher rank one. The arguments must be conformable along the specified axis (or axes) with elements of the lower rank array being replicated along the other axes.

For example, if H is the higher rank array, L the lower rank one, X is an axis specification, and f a scalar dyadic function, then the expressions Hf[X]L and Lf[X]H are conformable if (⍴L)←→(⍴H)[X]. Each element of L is replicated along the remaining (⍴H)~X axes of H.

In the special case where both arguments have the same rank, the right one will play the role of the higher rank array. If R is the right argument, L the left argument, X is an axis specification and f a scalar dyadic function, then the expression Lf[X]R is conformable if (⍴L)←→(⍴R)[X].

Examples

      mat
10 20 30
40 50 60

      mat+[1]1 2       ⍝ add along first axis
11 21 31
42 52 62

      mat+[2]1 2 3     ⍝ add along last axis
11 22 33
41 52 63

      cube
 100  200  300
 400  500  600

 700  800  900
1000 1100 1200

      cube+[1]1 2
 101  201  301
 401  501  601

 702  802  902
1002 1102 1202

      cube+[3]1 2 3
 101  202  303
 401  502  603

 701  802  903
1001 1102 1203

      cube+[2 3]mat
 110  220  330
 440  550  660

 710  820  930
1040 1150 1260

      cube+[1 3]mat
 110  220  330
 410  520  630

 740  850  960
1040 1150 1260


Commute

Commute: {R}←{X}f⍨Y

f may be any dyadic function. X and Y may be any arrays whose items are appropriate to function f.

The derived function is equivalent to YfX. The derived function need not return a result.

If left argument X is omitted, the right argument Y is duplicated in its place, i.e.

      f⍨Y ←→ Y f⍨Y

Examples

      N
3 2 5 4 6 1 3

      N/⍨2|N
3 5 1 3

      ⍴⍨3
3 3 3

      mean←+/∘(÷∘⍴⍨) ⍝ mean of a vector
      mean ⍳10
5.5

The following statements are equivalent:

      F/⍨←I
      F←F/⍨I
      F←I/F

Commute often eliminates the need for parentheses


Composition Form I

Composition (Form I): {R}←f∘gY

f may be any monadic function. g may be any monadic function which returns a result. Y may be any array whose items are appropriate to function g. The items of gY must be appropriate to function f.

The derived function is equivalent to fgY. The derived function need not return a result.

Composition allows functions to be glued together to build up more complex functions.

Examples

      RANK ← ⍴∘⍴
      RANK ¨ 'JOANNE' (2 3⍴⍳6)
 1  2

      +/∘⍳¨2 4 6
3 10 21

      ⎕VR'SUM'
     ∇ R←SUM X
[1]    R←+/X
     ∇

      SUM∘⍳¨2 4 6
3 10 21


Composition Form II

Composition (Form II): {R}←A∘gY

g may be any dyadic function. A may be any array whose items are appropriate to function g. Y may be any array whose items are appropriate to function g.

The derived function is equivalent to AgY. The derived function need not return a result.

Examples

      2 2∘⍴ ¨ 'AB'
 AA  BB
 AA  BB

      SINE ← 1∘○

      SINE 10 20 30
¯0.5440211109 0.9129452507 ¯0.9880316241

The following example uses Composition Forms I and II to list functions in the workspace:

      ⎕NL 3
ADD
PLUS

      ⎕∘←∘⎕VR¨↓⎕NL 3
     ∇ ADD X
[1]    →LAB⍴⍨0≠⎕NC'SUM' ⋄ SUM←0
[2]   LAB:SUM←SUM++/X
     ∇
     ∇ R←A PLUS B
[1]    R←A+B
     ∇


Composition Form III

Composition (Form III): {R}←(f∘B)Y

f may be any dyadic function. B may be any array whose items are appropriate to function f. Y may be any array whose items are appropriate to function f.

The derived function is equivalent to YfB. The derived function need not return a result.

Examples

      (*∘0.5)4 16 25
2 4 5

      SQRT ← *∘.5

      SQRT 4 16 25
2 4 5

The parentheses are required in order to distinguish between the operand B and the argument Y.


Composition Form IV

Composition (Form IV): {R}←Xf∘gY

f may be any dyadic function. g may be any monadic function which returns a result. Y may be any array whose items are appropriate to function g. Also gY must return a result whose items are appropriate as the right argument of function f. X may be any array whose items are appropriate to function f.

The derived function is equivalent to XfgY. The derived function need not return a result.

Examples

      +∘÷/40⍴1       ⍝ Golden Ratio! (Bob Smith)
1.618033989

      0,∘⍳¨⍳5
0 1  0 1 2  0 1 2 3  0 1 2 3 4  0 1 2 3 4 5


Each with Monadic Operand

Each (with Monadic Operand): {R}←f¨Y

f may be any monadic function. Y may be any array, each of whose items are separately appropriate to function f.

The derived function applies function f separately to each item of Y. The derived function need not return a result. If a result is returned, R has the same shape as Y, and its elements are the items produced by the application of function f to the corresponding items of Y.

If Y is empty, the prototype of R is determined by applying the operand function once to the prototype of Y.

Examples

      G←('TOM' (⍳3))('DICK' (⍳4))('HARRY' (⍳5))
      ⍴G
3
      ⍴¨G
 2  2  2

      ⍴¨¨G
  3  3    4  4    5  5

      +⎕FX¨('FOO1' 'A←1')('FOO2' 'A←2')
 FOO1 FOO2


Each with Dyadic Operand

Each (with Dyadic Operand): {R}←Xf¨Y

f may be any dyadic function. X and Y may be any arrays whose corresponding items (after scalar extension) are appropriate to function f when applied separately.

The derived function is applied separately to each pair of corresponding elements of X and Y. If X or Y is a scalar or single-element array, it will be extended to conform with the other argument. The derived function need not produce an explicit result. If a result is returned, R has the same shape as Y (after possible scalar extension) whose elements are the items produced by the application of the derived function to the corresponding items of X and Y.

If X or Y is empty, the operand function is applied once between the first items of X and Y to determine the prototype of R.

Examples

      +G←(1 (2 3))(4 (5 6))(8 9)10
   1  2 3   4  5 6   8 9  10
      1⌽¨G
  2 3  1   5 6  4  9 8  10

      1⌽¨¨G
 1  3 2   4  6 5   8 9  10

      1⌽¨¨¨G
 1  2 3   4  5 6   8 9  10

      1 2 3 4↑¨G
 1  4  5 6   8 9 0  10 0 0 0

      'ABC',¨'XYZ'
 AX  BY  CZ


Inner Product

Inner Product: R←Xf.gY

f must be a dyadic function. g may be any dyadic function which returns a result. The last axis of X must have the same length as the first axis of Y.

The result of the derived function has shape (¯1↓⍴X),1↓⍴Y. Each item of R is the result of f/xg¨y where x and y are typical vectors taken from all the combinations of vectors along the last axis of X and the first axis of Y respectively.

Function f (and the derived function) need not return a result in the exceptional case when 2=¯1↑⍴X. In all other cases, function f must return a result.

If the result of xg¨y is empty, for any x and y, a DOMAIN ERROR will be reported unless function f is a primitive scalar dyadic function with an identity element shown in Identity Elements.

Examples

      1 2 3+.×10 12 14
76

      1 2 3 PLUS.TIMES 10 12 14
76

      +/1 2 3×10 12 14
76

      NAMES
HENRY
WILLIAM
JAMES
SEBASTIAN

      NAMES^.='WILLIAM  '
0 1 0 0


Outer Product

Outer Product: {R}←X∘.gY

g may be any dyadic function. The left operand of the operator is the symbol ∘. X and Y may be any arrays whose elements are appropriate to the function g.

Function g is applied to all combinations of the elements of X and Y. If function g returns a result, the shape of R is (⍴X),⍴Y. Each element of R is the item returned by function g when applied to the particular combination of elements of X and Y.

Examples

      1 2 3∘.×10 20 30 40
10 20 30  40
20 40 60  80
30 60 90 120

      1 2 3∘.⍴'AB'
 A    B
 AA   BB
 AAA  BBB

      1 2∘.,1 2 3
 1 1  1 2  1 3
 2 1  2 2  2 3

      (⍳3)∘.=⍳3
1 0 0
0 1 0
0 0 1

If X or Y is empty, the result R is a conformable empty array, and the operand function is applied once between the first items of X and Y to determine the prototype of R.


Power Operator

Power Operator: {R}←{X}(f⍣g)Y

If right operand g is a numeric integer scalar, power applies its left operand function f cumulatively g times to its argument. In particular, g may be Boolean 0 or 1 for conditional function application.

If right operand g is a scalar-returning-returning dyadic function, then left operand function f is applied repeatedly until ((f Y) g Y) or until a strong interrupt occurs. In particular, if g is = or ≡, the result is sometimes termed a fixpoint of f.

If a left argument X is present, it is bound as left argument to left operand function f:

X (f ⍣ g) Y → (X∘f ⍣ g) Y

A negative right operand g applies the inverse of the operand function f,(|g)times. In this case, f may be a primitive function or an expression of primitive functions combined with primitive operators:

∘ | compose
¨ | each
∘. | outer product
⍨ | commute
\ | scan
[] | axis
⍣ | power

Defined, dynamic and some primitive functions do not have an inverse. In this case, a negative argument g generates DOMAIN ERROR.

Examples

    (,∘⊂∘,⍣(1=≡,vec))vec    ⍝ ravel-enclose if simple.

    a b c←1 0 1{(⊂⍣⍺)⍵}¨abc ⍝ enclose first and last.

    cap←{(⍺⍺⍣⍺)⍵}           ⍝ conditional application.

    a b c←1 0 1⊂cap¨abc     ⍝ enclose first and last.

    succ←1∘+                ⍝ successor function.

    (succ⍣4)10              ⍝ fourth successor of 10.
14
    (succ⍣¯3)10             ⍝ third predecessor of 10.
7
    1+∘÷⍣=1                 ⍝ fixpoint: golden mean.
1.618033989

    f←(32∘+)∘(×∘1.8)        ⍝ Fahrenheit from Celsius.
    f 0 100
32 212

    c←f⍣¯1                  ⍝ c is Inverse of f.
    c 32 212                ⍝ Celsius from Fahrenheit.
0 100

    invs←{(⍺⍺⍣¯1)⍵}         ⍝ inverse operator.

    +\invs 1 3 6 10         ⍝ scan inverse.
1 2 3 4

    2∘⊥invs 9               ⍝ decode inverse.
1 0 0 1

    dual←{⍵⍵⍣¯1 ⍺⍺ ⍵⍵ ⍵}    ⍝ dual operator.

    mean←{(+/⍵)÷⍴⍵}         ⍝ mean function.

    mean dual⍟ 1 2 3 4 5    ⍝ geometric mean.
2.605171085

    +/dual÷ 1 2 3 4 5       ⍝ parallel resistance.
0.4379562044

    mean dual(×⍨)1 2 3 4 5  ⍝ root-mean-square.
3.31662479

    ⍉dual↑ 'hello' 'world'  ⍝ vector transpose.
 hw  eo  lr  ll  od

Warning

Some expressions, such as the following, will cause an infinite internal loop and APL will appear to hang. In most cases this can be resolved by issuing a hard INTERRUPT.

      !⍣-1
      !⍣-2


Reduce

Reduce: R←f/[K]Y

f must be a dyadic function. Y may be any array whose items in the sub-arrays along the Kth axis are appropriate to function f.

The axis specification is optional. If present, K must identify an axis of Y. If absent, the last axis of Y is implied. The form R←f⌿Y implies the first axis of Y.

R is an array formed by applying function f between items of the vectors along the Kth (or implied) axis of Y.

Table 14: Identity Elements

Function |  | Identity
Add | + | 0
Subtract | - | 0
Multiply | × | 1
Divide | ÷ | 1
Residue | | | 0
Minimum | ⌊ | M(1)
Maximum | ⌈ | -M(1)
Power | * | 1
Binomial | ! | 1
And | ∧ | 1
Or | ∨ | 0
Less | < | 0
Less or Equal | ≤ | 1
Equal | = | 1
Greater | > | 0
Greater or Equal | ≥ | 1
Not Equal | ≠ | 0
Encode | ⊤ | 0
Union | ∪ | ⍬
Replicate | /⌿ | 1
Expand | \⍀ | 1
Rotate | ⌽⊖ | 0

Notes:

1. M represents the largest representable value: typically this is 1.7E308, unless ⎕FR is 1287, when the value is 1E6145.

For a typical vector Y, the result is:

      ⊂(1⊃Y)f(2⊃Y)f......f(n⊃Y)

The shape of R is the shape of Y excluding the Kth axis. If Y is a scalar then R is a scalar. If the length of the Kth axis is 1, then R is the same as Y. If the length of the Kth axis is 0, then DOMAIN ERROR is reported unless function f occurs in Table 1, in which case its identity element is returned in each element of the result.

Examples

      ∨/0 0 1 0 0 1 0
1

      MAT
1 2 3
4 5 6

      +/MAT
6 15

      +⌿MAT
5 7 9

      +/[1]MAT
5 7 9

      +/(1 2 3)(4 5 6)(7 8 9)
 12 15 18

      ,/'ONE' 'NESS'
 ONENESS

      +/⍳0
0

      ,/''
DOMAIN ERROR
      ,/''
      ^


Reduce First

Reduce First: R←f⌿Y

The form R←f⌿Y implies reduction along the first axis of Y. See Reduce:.


Reduce N Wise

Reduce N-Wise: R←Xf/[K]Y

f must be a dyadic function. X must be a simple scalar or one-item integer array. Y may be any array whose sub-arrays along the Kth axis are appropriate to function f.

The axis specification is optional. If present, K must identify an axis of Y. If absent, the last axis of Y is implied. The form R←Xf⌿Y implies the first axis of Y.

R is an array formed by applying function f between items of sub-vectors of length X taken from vectors along the Kth (or implied) axis of Y.

X can be thought of as the width of a ‘window’ which moves along vectors drawn from the Kth axis of Y.

If X is zero, the result is a (⍴Y)+(⍴⍴Y)=⍳⍴⍴Y array of identity elements for the function f. See Identity Elements.

If X is negative, each sub-vector is reversed before being reduced.

Examples

      ⍳4
1 2 3 4

      3+/⍳4⍝ (1+2+3) (2+3+4)
6 9
      2+/⍳4⍝ (1+2) (2+3) (3+4)
3 5 7
      1+/⍳4⍝ (1) (2) (3) (4)
1 2 3 4

      0+/⍳4⍝ Identity element for +
0 0 0 0 0
      0×/⍳4⍝ Identity element for ×
1 1 1 1 1

      2,/⍳4⍝ (1,2) (2,3) (3,4)
 1 2  2 3  3 4
      ¯2,/⍳4⍝ (2,1) (3,2) (4,3)
 2 1  3 2  4 3


Scan

Scan: R←f\[K]Y

f may be any dyadic function that returns a result. Y may be any array whose items in the sub-arrays along the Kth axis are appropriate to the function f.

The axis specification is optional. If present, K must identify an axis of Y. If absent, the last axis of Y is implied. The form R←f⍀Y implies the first axis of Y.

R is an array formed by successive reductions along the Kth axis of Y. If V is a typical vector taken from the Kth axis of Y, then the Ith element of the result is determined as f/I↑V.

The shape of R is the same as the shape of Y. If Y is an empty array, then R is the same empty array.

Examples

      ∨\0 0 1 0 0 1 0
0 0 1 1 1 1 1

      ^\1 1 1 0 1 1 1
1 1 1 0 0 0 0

      +\1 2 3 4 5
1 3 6 10 15

      +\(1 2 3)(4 5 6)(7 8 9)
 1 2 3  5 7 9  12 15 18

      M
1 2 3
4 5 6

      +\M
1 3  6
4 9 15

      +⍀M
1 2 3
5 7 9

      +\[1]M
1 2 3
5 7 9

      ,\'ABC'
A AB  ABC

      T←'ONE(TWO) BOOK(S)'

      ≠\T∊'()'
0 0 0 1 1 1 1 0 0 0 0 0 0 1 1 0

      ((T∊'()')⍱≠\T∊'()')/T
ONE BOOK


Scan First

Scan First: R←f⍀Y

The form R←f⍀Y implies scan along the first axis of Y. See Scan:.


Spawn

Spawn: {R}←{X}f&Y

& is a monadic operator with an ambivalent derived function. & spawns a new thread in which f is applied to its argument Y (monadic case) or between its arguments X and Y (dyadic case). The shy result of this application is the number of the newly created thread.

When function f terminates, its result (if any), the thread result, is returned. If the thread number is the subject of an active ⎕TSYNC, the thread result appears as the result of ⎕TSYNC. If no ⎕TSYNC is in effect, the thread result is displayed in the session in the normal fashion.

Note that & can be used in conjunction with the each operator ¨ to launch many threads in parallel.

Examples

      ÷&4         ⍝ Reciprocal in background
0.25

      ⎕←÷&4       ⍝ Show thread number
1
0.25

      FOO&88      ⍝ Spawn monadic function.

      2 FOO&3     ⍝ dyadic

      {NIL}&0     ⍝ niladic

      ⍎&'NIL'     ⍝ ..

      X.GOO&99    ⍝ thread in remote space.

      ⍎&'⎕dl 2'   ⍝ Execute async expression.

      'NS'⍎&'FOO' ⍝ .. remote .. .. ..

      PRT&¨↓⎕nl 9 ⍝ PRT spaces in parallel.


Variant

Variant: {R}←{X}(f ⍠ B)Y

The Variant operator ⍠ specifies the value of an option to be used by its left operand function f. An option is a named property of a function whose value in some way affects the operation of that function.

For example, the Search and Replace operators include options named IC and Modewhich respectively determine whether or not case is ignored and in what manner the input document is processed.

One of the set of options may be designated as the Principal option whose value may be set using a short-cut form of syntax as described below. For example, the Principal option for the Search and Replace operators is IC.

⍠ and ⎕OPT are synonymous though only the latter is available in the Classic Edition.

Currently, the Variant operator is used solely to specify options for the ⎕S and ⎕R operators but it is anticipated that its use will become more widespread in later versions.

For the operand function with right argument Y and optional left argument X, the right operand B specifies the values of one or more options that are applicable to that function. B may be a scalar, a 2-element vector, or a vector of 2-element vectors which specifies values for one or more options as follows:

  • If B is a 2-element vector and the first element is a character vector, it specifies an option name in the first element and the option value (which may be any suitable array) in the second element.
  • If B is a vector of 2-element vectors, each item of B is interpreted as above.
  • If B is a scalar (a rank-0 array of any depth), it specifies the value of the Principal option,

Option names and their values must be appropriate for the left operand function, otherwise an OPTION ERROR (error code 13) will be reported.

The following illustrations and examples apply to functions derived from the Search and Replace operators.

Examples of operand B

The following expression sets the IC option to 1, the Mode option to 'D' and the EOL option to 'LF'.

      ⍠('Mode' 'D')('IC' 1)('EOL' 'LF')

The following expression sets just the EOL property to 'CR'.

      ⍠'EOL' 'CR'

The following expression sets just the Principal option (which for the Search and Replace operators is IC) to 1.

      ⍠ 1

The order in which options are specified is typically irrelevant but if the same option is specified more than once, the rightmost one dominates. The following expression sets the option IC to 1:

      ⍠('IC' 0) ('IC' 1)

The Variant operator generates a derived function f⍠B and may be assigned to a name. The derived function is effectively function f bound with the option values specified by B.

The derived function may itself be used as a left operand to Variant to produce a second derived function whose options are further modified by the second application of the operator. The following sets the same options as the first example above:

      ⍠'Mode' 'D'⍠'IC' 1⍠'EOL' 'LF'

When the same option is specified more than once in this way, the outermost (rightmost) one dominates. The following expression also sets the option IC to 1:

      ⍠'IC' 0⍠'IC' 1

Further Examples

The following derived function returns the location of the word 'variant' within its right argument using default values for all the options.

      f1 ← 'variant' ⎕S 0
      f1 'The variant Variant operator'
4

It may be modified to perform a case-insensitive search:

      (f1 ⍠ 1) 'The variant Variant operator'
4 12

This modified function may be named:

      f2 ← f1 ⍠ 1
      f2 'The variant Variant operator'
4 12

The modified function may itself be modified, in this case to revert to a case sensitive search:

      f3 ← f2 ⍠ 0
      f3 'The variant Variant operator'
4

This is equivalent to:

      (f1 ⍠ 1 ⍠ 0) 'The variant Variant operator'
4


I Beam

I-Beam: R←{X}(A⌶)Y

I-Beam is a monadic operator that provides a range of system related services.

WARNING: Although documentation is provided for I-Beam functions, any service provided using I-Beam should be considered as “experimental” and subject to change – without notice - from one release to the next. Any use of I-Beams in applications should therefore be carefully isolated in cover-functions that can be adjusted if necessary.

A is an integer that specifies the type of operation to be performed as shown in the table below. Y is an array that supplies further information about what is to be done.

X is currently unused.

R is the result of the derived function.

A | Derived Function
200 | Syntax Colouring
685 | Core to APLCore
1111 | Number of Threads
1112 | Parallel Execution Threshold
1113 | Thread Synchronisation Mechanism
2000 | Memory Manager Statistics
2010 | Update DataTable
2011 | Read DataTable
2100 | Export to Memory
3002 | Component Checksum Validation
4000 | Fork New Task
4001 | Change User
4002 | Reap Forked Tasks
4007 | Signal Counts
16807 | Random Number Generator


Syntax Colouring

Syntax Colouring: R←200⌶Y

This function obtains syntax colouring information for a function.

Y is a vector of character vectors containing the ⎕NR representation of a function or operator.

R is a vector of integer vectors with the same shape and structure of Y in which each number identifies the syntax colour element associated with the corresponding character in Y.

      {(↑⍵),↑ 200⌶⍵}  'foo; local' 'global' 'local←⍴⍴''hello'''

foo; local      21 21 21 19  3 31 31 31 31 31 0 0 0 0 0
global           7  7  7  7  7  7  0  0  0  0 0 0 0 0 0
local←⍴⍴'hello' 31 31 31 31 31 19 23 23  4  4 4 4 4 4 4

In this example:

21 | is the syntax identifier for “function name”
19 | is the syntax identifier for “primitive”
3 | is the syntax identifier for “white space”
31 | is the syntax identifier for “local name”
7 | is the syntax identifier for “global name”
23 | is the syntax identifier for “idiom”


Core To APLCore

Core to APLCore: (UNIX only) X (685⌶)Y

This function is used to extract a workspace from a core file and convert it to an aplcore file. It may then be possible to recover objects from the aplcore file. For further assistance in this matter, please contact support@dyalog.com.

X and Y are character vectors that specify the names of the core file and aplcore file respectively.

Core files differ between AIX and Linux, thus the APL used must be for the same Unix.

A 64-bit APL can be used to extract a 32 bit core file but a 32-bit APL cannot be used to extract a 64-bit core file. The process maps the core file into memory so a low value of MAXWS may be appropriate if a 32-bit APL is being used; mapped files use a separate area of the process's address space from that occupied by the workspace.

This function relies on certain markers being present in the workspace, and will operate only on core files generated by Version 12.1 or higher dated after 4th July 2011.


Number of Threads

Number of Threads: R←1111⌶Y

Specifies how many threads are to be used for parallel execution.

Y is an integer that specifies the number of threads that are to be used henceforth for parallel execution. Prior to this call, the default number of threads is specified by an environment variable named APL_MAX_THREADS. If this variable is not set, the default is the number of CPUs that the machine is configured to have.

R is the previous value

Note that (unless APL_MAX_THREADS is set), the number of CPUs for which the machine is configured is returned by the first execution of 1111⌶. The following expression obtains and resets the number of threads back to this value.

      {}1111⌶ ncpu←1111⌶1


Parallel Execution Threshold

Parallel Execution Threshold: R←1112⌶Y

Y is an integer that specifies the array size threshold at which parallel execution takes place. If a parallel-enabled function is invoked on an array whose number of elements is equal to or greater than this threshold, execution takes place in parallel. If not, it doesn’t.

Prior to this call, the default value of the threshold is specified by an environment variable named APL_MIN_PARALLEL. If this variable is not set, the default is 32768.

R is the previous value


Memory Manager Statistics

Memory Manager Statistics: R←{X}(2000⌶)Y

This function returns information about the state of the workspace and provides a means to reset certain statistics and to control workspace allocation. This I-Beam is provided for performance tuning and is VERY LIKELY to change in the next release.

Y is a simple integer scalar or vector containing values listed in the table below.

If X is omitted, the result R is an array with the same structure as Y, but with values in Y replaced by the following statistics. For any value in Y outside those listed below, the result is undefined.

Value | Description
0 | Workspace available (a "quick" ⎕WA)
1 | Workspace used
2 | Number of compactions since the workspace was loaded
3 | Number of garbage collections that found garbage
4 | Current number of garbage pockets in the workspace
12 | Sediment size
13 | Current workspace allocation, i.e. the amount of memory that is actually being used
14 | Workspace allocation high-water mark, i.e. the maximum amount of memory that has been used since the workspace was loaded or since this count was reset
15 | Limit on minimum workspace allocation
16 | Limit on maximum workspace allocation

Note that while all other operations are relatively fast, the operation to count the number of garbage pockets (4) may take a noticeable amount of time, depending upon the size and state of the workspace.

Examples

      2000⌶0
55414796
      2000⌶0 1 2 3 4 12 13 14 15 16
55414796 10121204 5 0 0 2120524 34489168 34489168 0 65536000

If X is specified,it must be either a simple integer scalar, or a vector of the same length as Y, and the result R is ⍬. In this case, the value in Y specifies the item to be set and and X its new value according to the table below.

Value | Description
2 | 0 resets the compaction count; no other values allowed
3 | 0 resets the count of garbage collections that found garbage; no other values allowed
14 | 0 resets the workspace allocation high-water mark; no other values allowed
15 | Sets the minimum workspace allocation to the corresponding value in X; must be between 0 and the current workspace allocation
16 | Sets the maximum workspace allocation to the corresponding value in X; 0 implies MAXWS otherwise must be between the current workspace allocation and MAXWS.

Notes:

  • Note that the workspace allocation high-water mark indicates a minimum value for MAXWS.
  • Limitting the maximum workspace allocation can be used to prevent code which grabs as much workspace as it can from skewing the peak usage result.
  • Limitting the minimum workspace allocation can avoid repeatedly committing and releasing memory to the Operating System when memory usage is fluctuating.

Examples

      2000⌶2 3
6 0 33216252
      0 (2000⌶)2 3 14 ⍝ Reset compaction count

      2000⌶2 3
0 0
      30000000 40000000(2000⌶)15 16 ⍝ Restrict min/max ws

      (2000⌶)15 16
30000000 40000000

      0 (2000⌶)15 16 ⍝ Reset min/max ws

      (2000⌶)15 16
0 65536000

      (2000⌶)13 14 ⍝ Current, peak WS allocation
4072532 4072532

      a←10e6⍴'x' ⍝ Increase WS allocation

      (2000⌶)13 14 ⍝ Current, peak WS allocation
15108580 15108580

      ⎕ex 'a' ⋄ {}⎕wa ⍝ Decrease current WS allocation

      (2000⌶)13 14 ⍝ Current, peak WS allocation
1962856 15108580

      0 (2000⌶) 14 ⍝ Reset High-water mark

      (2000⌶)13 14 ⍝ Current, peak WS allocation
1962856 1962856


Update DataTable

Update DataTable: R←{X}2010⌶Y

This function performs a block update of an instance of the ADO.NET object System.Data.DataTable. This object may only be updated using an explicit row-wise loop, which is slow at the APL level. 2010⌶ implements an internal row-wise loop which is much faster on large arrays. Furthermore, the function handles NULL values and the conversion of internal APL data to the appropriate .Net datatype in a more efficient manner than can be otherwise achieved. These 3 factors together mean that the function provides a significant improvement in performance compared to calling the row-wise programming interface directly at the APL level.

Y is a 2, 3 or 4-item array containing dtRef, Data, NullValues and Rows as described in the table below.

The optional argument X is the Boolean vector ParseFlags as described in the table below.

Argument | Description
dtRef | A reference to an instance of System.Data.DataTable.
Data | A matrix with the same number of columns as the table.
NullValues | An optional vector with one element per column, containing the value which should be mapped to DBNull when this column is written to the DataTable.
Rows | Row indices (zero origin) of the rows to be updated. If not provided, data will be appended to the DataTable.
ParseFlags | A Boolean vector, where a 1 indicates that the corresponding element of Data is a string which needs to be passed to the Parse method of the data type of column in question.

Example

Shown firstly for comparison is the type of code that is required to update a DataTable by looping:

      ⎕USING←'System' 'System.Data,system.data.dll'
      dt←⎕NEW DataTable
      ac←{dt.Columns.Add ⍺ ⍵}
      'S1' 'S2' 'I1' 'D1' ac¨String String Int32 DateTime
 S1  S2  I1  D1

      NextYear←DateTime.Now+{⎕NEW TimeSpan (4↑⍵)}¨⍳n←365
      data←(⍕¨⍳n),(n⍴'odd' 'even'),(10|⍳n),⍪NextYear
      ¯2 4↑data
 364  even  4  18-01-2011 14:03:29
 365  odd   5  19-01-2011 14:03:29

      ar←{(row←dt.NewRow).ItemArray←⍵ ⋄ dt.Rows.Add row}
      t←3⊃⎕ai ⋄ ar¨↓data ⋄ (3⊃⎕ai)-t
449

This result shows that this code can only insert roughly 100 rows per second (3⊃⎕AI returns elapsed time in milliseconds), because of the need to loop on each row and perform a noticeable amount of work each time around the loop.

2010⌶ does all the looping in compiled code:

      dt.Rows.Clear ⍝ Delete the rows inserted above
      SetDT←2010⌶
      t←3⊃⎕AI ⋄ SetDT dt data ⋄ (3⊃⎕AI)-t4

So in this case, using 2010⌶ achieves something like 10,000 rows per second.

Using ParseFlags

Sometimes it is more convenient to handle .Net datatypes in the workspace as strings rather than as the appropriate APL array equivalent. The System.DateTime datatype (which by default is represented in the workspace as a 6-element numeric vector) is one such example. 2010⌶ will accept such character data and convert it to the appropriate .Net datatype internally.

If specified, the optional left argument X(ParseFlags) instructs the system to pass the corresponding columns of Data to the Parse() method of the data type in question prior to performing the update.

      NextYear←⍕¨DateTime.Now+{⎕NEW TimeSpan (4↑⍵)}¨⍳n←365

      data←(⍕¨⍳n),(n⍴'odd' 'even'),(10|⍳n),NextYear
      ¯2 4↑data
 364  even  4  18-01-2011 14:03:29
 365  odd   5  19-01-2011 14:03:29

      SetDT←2010⌶      0 0 0 1 SetDT dt data

Handling Nulls

If applicable, NullValues is a vector with as many elements as the DataTable has columns, indicating the value that should be converted to System.DBNull as data is written. For example, using the same DataTable as above:

      t
 <null>  odd    1  21-01-2010 14:50:19
 two     even   2  22-01-2010 14:50:19
 three   odd   99  23-01-2010 14:50:19

      dt.Rows.Clear ⍝ Clear the contents of dt
      SetDT dt t ('<null>' 'even' 99 '')

Above, we have declares that the string '<null>' should be considered to be a null value in the first column, 'even' in the second column, and the integer 99 in the third.

Updating Selected Rows

Sometimes, you may have read a very large number of rows from a DataTable, but only want to update a single row, or a very small number of rows. Row indices can be provided as the fourth element of the argument to 2010⌶. If you are not using NullValues, you can just use an empty vector as a placeholder. Continuing from the example above, we could replace the first row in our DataTable using:

      SetDT←2010⌶
      SetDT dt (1 4⍴'one' 'odd' 1 DateTime.Now) ⍬ 0

Note

  • the values must be provided as a matrix, even if you only want to update a single row,
  • row indices are zero origin (the first row has number 0).

Warning

If you are experimenting with writing to a DataTable, note that you should call dt.Rows.Clear each time to clear the current contents of the table. Otherwise you will end up with a very large number of rows after a while.


Read DataTable

Read DataTable: R←{X}2011⌶Y

This function performs a block read from an instance of the ADO.NET object System.Data.DataTable. This object may only be read using an explicit row-wise loop, which is slow at the APL level. 2011⌶ implements an internal row-wise loop which is much faster on large arrays. Furthermore, the function handles NULL values and the conversion of .Net datatypes to the appropriate internal APL form in a more efficient manner than can be otherwise achieved. These 3 factors together mean that the function provides a significant improvement in performance compared to calling the row-wise programming interface directly at the APL level.

Y is a scalar or a 2-item array containing dtRef, and NullValues as described in the table below.

The optional argument X is the Boolean vector ParseFlags as described in the table below.

The result R is the array Data as described in the table below.

Argument | Description
dtRef | A reference to an instance of System.Data.DataTable.
Data | A matrix with the same number of columns as the table.
NullValues | An optional vector with one element per column, containing the value to which a DBNull in the corresponding column of the DataTable should be mapped in the result array Data.
ParseFlags | A Boolean vector, where a 1 indicates that the corresponding element of Data should be converted to a string using the ToString() method of the data type of column in question. It is envisaged that this argument may be extended in the future, to allow other conversions – for example converting Dates to a floating-point format.

First for comparison is shown the type of code that is required to read a DataTable by looping:

      t←3⊃⎕AI ⋄ data1←↑(⌷dt.Rows).ItemArray ⋄ (3⊃⎕AI)-t
191

The above expression turns the dt.Rows collection into an array using ⌷, and mixes the ItemArray properties to produce the result. Although here there is no explicit loop, involved, there is an implicit loop required to reference each item of the collection in succession. This operation performs at about 200 rows/sec.

2011⌶ does the looping entirely in compiled code and is significantly faster:

      GetDT←2011⌶
      t←3⊃⎕AI ⋄ data2←GetDT dt ⋄ (3⊃⎕AI)-t
25

ParseFlags Example

In the example shown above, 2011⌶ created 365 instances of System.DateTime objects in the workspace. If we are willing to receive the timestamps in the form of strings, we can read the data almost an order of magnitude faster:

      t←3⊃⎕AI ⋄ data3←0 0 0 1 GetDT dt ⋄ (3⊃⎕AI)-t
3

The left argument to 2011⌶ allows you to flag columns which should be returned as the ToString() value of each object in the flagged columns. Although the resulting array looks identical to the original, it is not: The fourth column contains character vectors:

      ¯2 4↑data3
 364  even  4  18-01-2011 14:03:29
 365  odd   5  19-01-2011 14:03:29

Depending on your application, you may need to process the text in the fourth column in some way – but the overall performance will probably still be very much better than it would be if DateTime objects were used.

Handling Nulls

Using the DataTable produced by the corresponding example shown for 2010⌶ it can be shown that by default null values will be read back into the APL workspace as instances of System.DBNull.

      GetDT←2011⌶>

      ⎕←z←GetDT dt

        odd  1  21-01-2010 14:50:19
 two         2  22-01-2010 14:50:19
 three  odd     23-01-2010 14:50:19

      (1 1⍉z).GetType

 System.DBNull  System.DBNull  System.DBNull

However, by supplying a NullValues argument to 2011⌶, we can request that nulls in each column are mapped to a corresponding value of our choice; in this case, '<null>', 'even', and 99 respectively.

      GetDT dt ('<null>' 'even' 99 '')
<null>  odd    1  21-01-2010 14:50:19
 two     even   2  22-01-2010 14:50:19
 three   odd   99  23-01-2010 14:50:19


Export To Memory

Export To Memory: R←2100⌶Y

This function exports the current active workspace as an in-memory .NET.Assembly.

Y may be any array and is ignored.

The result R is 1 if the operation succeeded or 0 if it failed.


Component Checksum Validation

Component Checksum Validation: {R}←3002⌶Y

Checksums allow component files to be validated and repaired using ⎕FCHK.

From Version 13.1 onwards, components which contain checksums are also validated on every component read.

Although not recommended, applications which favour performance over security may disable checksum validation by ⎕FREAD using this function.

Y is an integer defined as follows:

Value | Description
0 | ⎕FREAD will not validate checksums.
1 | ⎕FREAD will validate checksums when they are present. This is the default.

The shy result R is the previous value of this setting.


Fork New Task

Fork New Task: (UNIX only) R←4000⌶Y

Y must be is a simple empty vector but is ignored.

This function forks the current APL task. This means that it initiates a new separate copy of the APL program, with exactly the same APL execution stack.

Following the execution of this function, there will be two identical APL processes running on the machine, each with the same execution stack and set of APL objects and values. However, none of the external interfaces and resources in the parent process will exist in the newly forked child process.

The function will return a result in both processes.

  • In the parent process, R is the process id of the child (forked) process.
  • In the child process, R is a scalar zero.

The following external interfaces and resources that may be present in the parent process are not replicated in the child process:

  • Component file ties
  • Native file ties
  • Mapped file associations
  • Auxiliary Processors
  • .NET objects
  • Edit windows
  • Clipboard entries
  • GUI objects (all children of '.')
  • I/O to the current terminal

Note that External Functions established using ⎕NA are replicated in the child process.

The function will fail with a DOMAIN ERROR if there is more than one APL thread running.

The function will fail with a FILE ERROR 11 Resource temporarily unavailable if an attempt is made to exceed the maximum number of processes allowed per user.


Change User

Change User: (UNIX only) R←4001⌶Y

Yis a character vector that specifies a valid UNIX user name. The function changes the userid (uid) and groupid (gid) of the process to values that correspond to the specified user name.

Note that it is only possible to change the user name if the current user name is root (uid=0).

This call is intended to be made in the child process after a fork (4000⌶⍬) in a process with an effective user id of root. It can however be used in any APL process with an effective user id of root.

If the operation is successful, R is the user name specified in Y.

If the operation fails, the function generates a FILE ERROR 1 Not Owner error.

If the argument to 4001⌶ is other than a non-empty simple character vector, the function generates a DOMAIN ERROR.

If the argument is not the name of a valid user the function generates a FILE ERROR 3 No such process.

If the argument is the same name as the current effective user, then the function returns that name, but has no effect.

If the argument is a valid name other than the name of the effective user id of the current process, and that effective user id is not root the function generates a FILE ERROR 1 Not owner.


Reap Forked Tasks

Reap Forked Tasks: (UNIX only) R←4002⌶Y

Under UNIX, when a child process terminates, it signals to its parent that it has terminated and waits for the parent to acknowledge that signal. 4002⌶ is the mechanism to allow the APL programmer to issue such acknowledgements.

Y must be a simple empty vector but is ignored.

The result R is a matrix containing the list of the newly-terminated processes which have been terminated as a result of receiving the acknowledgement, along with information about each of those processes as described below.

R[;1] is the process ID (PID) of the terminated child

R[;2] is ¯1 if the child process terminated normally, otherwise it is the signal number which caused the child process to terminate.

R[;3] is ¯1 if the child process terminated as the result of a signal, otherwise it is the exit code of the child process

The remaining 15 columns are the contents of the rusage structure returned by the underlying wait3() system call. Note that the two timevalstructs are each returned as a floating point number.

The current rusage structure contains:

struct rusage {
    struct timeval ru_utime; /* user time used */
    struct timeval ru_stime; /* system time used */
    long   ru_maxrss;        /* maximum resident set size */
    long   ru_ixrss;         /* integral shared memory size */
    long   ru_idrss;         /* integral unshared data size */
    long   ru_isrss;         /* integral unshared stack size */
    long   ru_minflt;        /* page reclaims */
    long   ru_majflt;        /* page faults */
    long   ru_nswap;         /* swaps */
    long   ru_inblock;       /* block input operations */
    long   ru_oublock;       /* block output operations */
    long   ru_msgsnd;        /* messages sent */
    long   ru_msgrcv;        /* messages received */
    long   ru_nsignals;      /* signals received */
    long   ru_nvcsw;         /* voluntary context switches */
    long   ru_nivcsw;        /* involuntary context switches */
};

4002⌶ may return the PID of an abnormally terminated Auxiliary Processor; APL code should check that the list of processes that have been reaped is a superset of the list of processes that have been started.

Example

     ∇ tryforks;pid;fpid;rpid
[1]    rpids←fpids←⍬
[2]    :For i :In ⍳5
[3]        fpid←4000⌶'' ⍝ fork() a process
[4]   ⍝ if the child, hang around for a while
[5]        :If fpid=0
[6]            ⎕DL 2×i
[7]            ⎕OFF
[8]        :Else
[9]   ⍝ if the parent, save child's pid
[10]           +fpids,←fpid
[11]       :EndIf
[12]   :EndFor
[13]
[14]   :For i :In ⍳20
[15]       ⎕DL 3
[16]  ⍝ get list of newly terminated child processes
[17]       rpid←4002⌶''
[18]  ⍝ and if not empty, make note of their pids
[19]       :If 0≠⊃⍴rpid
[20]           +rpids,←rpid[;1]
[21]       :EndIf
[22]  ⍝ if all fork()'d child processes accounted for
[23]       :If fpids≡fpids∩rpids
[24]           :Leave  ⍝ quit
[25]       :EndIf
[26]   :EndFor
     ∇


Signal Counts

Signal Counts: (UNIX only) R←4007⌶Y

Y must be a simple empty vector but is ignored.

The result R is an integer vector of signal counts. The length of the vector is system dependent. On AIX 32-bit it is 63 on AIX 64-bit it is 256 but code should not rely on the length.

Each element is a count of the number of signals that have been generated since the last call to this function, or since the start of the process. R[1] is the number of occurrences of signal 1 (SIGHUP), R[2] the number of occurrences of signal 2, and so forth.

Each time the function is called it zeros the counts; it is therefore inadvisable to call it in more than one APL thread.

Currently, only SIGHUP, SIGINT, SIGQUIT, SIGTERM and SIGWINCH are counted and all other corresponding elements of R are 0.


Thread Synchronisation Mechanism

Thread Synchronisation Mechanism: R←1113⌶Y

Y is Boolean and specifies whether or not the main thread does a busy wait for the others to complete or uses a semaphore when a function is executed in parallel.

The default and recommended value is 0 (use a semaphore). This function is provided only for Operating Systems that do not support semaphores.

A value of 1 must be set if you are running AIX Version 5.2 which does not support Posix semaphores. Later versions of AIX do not have this restriction.

R is the previous value


Random Number Generator

Random Number Generator: R←16807⌶Y

Specifies the random number generator that is to be used by Roll and Deal.

Y is an integer that specifies which random number generator is to be enabled and must be one of the numbers listed in the first column of the table below.

R is an integer that identifies the previous random number generator in use.

The 3 random number generators are as follows :

Id | Algorithm
0 | Lehmer linear congruential generator.
1 | Mersenne Twister.
2 | Operating System random number generator.

Under Windows, the Operating System random number generator uses the CryptGenRandom() function. Under Unix/Linux it uses /dev/urandom[3].

The default random number generator in a CLEAR WS is 0 (Lehmer linear congruential). The default will change to 1 (Mersenne Twister) in Dyalog APL Version 14.0. In preparation for this change, avoid writing code which assumes that ⎕RL will be a scalar integer. The change to the default will only impact applications if they are rebuilt from a clear ws. Saved workspaces will continue to use the same generator as before.

The Lehmer linear congruential generator RNG0 was the only random number generator provided in versions of Dyalog APL prior to Version 13.1. The implementation of this algorithm has several limitations including limited value range (2*31), short period and non-uniform distribution (some values may appear more frequently than others). It is retained for backwards compatibility.

The Mersenne Twister algortithm RNG1 produces 64-bit values with good distribution.

The Operating System algorithm RNG2 does not support a user modifiable random number seed, so when using this scheme, it is not possible to obtain a repeatable random number series.

For further information, see Random Link: .


Namespaces

Namespace is a (class 9) object in Dyalog APL. Namespaces are analogous to nested workspaces.

'Flat' APL Workspace      Workspace with Namespaces
.OLD-------------------.   .NEW-------------------.
|                      |   | FOO MAT VEC          |
| DISPLAY              |   | .Util----------.     |
|                      |   | |DISPLAY       |     |
|   FOO MAT VEC        |   | |...           |     |
|                      |   | '--------------'     |
|   WsDoc_Init         |   | .WsDoc-------------. |
|   WsDoc_Xref         |   | |Init .prt-..fmt--.| |
|   WsDoc_Tree         |   | |     |Init||line || |
|   WsDoc_prt_init     |   | |Tree |    ||     || |
|   WsDoc_current_page |   | |Xref |page||     || |
|   ...                |   | |     '----''-----'| |
|                      |   | '------------------' |
'----------------------'   '----------------------'

They provide the same sort of facility for workspaces as directories do for filesystems. The analogy might prove helpful:

Operation | Windows | Namespace
Create | MKDIR"apl""Dyalog" | )NS or ⎕NS
Change | CD | )CS or ⎕CS
Relative name | DIR1\DIR2\FILE | NS1.NS2.OBJ
Absolute name | \DIR\FILE | #.NS.OBJ
Name separator | \ | .
Top (root) object | \ | #
Parent object | .. | ##

Namespaces bring a number of major benefits:

They provide static (as opposed to dynamic) local names. This means that a defined function can use local variables and functions which persist when it exits and which are available next time it is called.

Just as with the provision of directories in a filing system, namespaces allow us to organise the workspace in a tidy fashion. This helps to promote an object oriented programming style.

APL's traditional name-clash problem is ameliorated in several ways:

  • Workspaces can be arranged so that there are many fewer names at each namespace level. This means that when copying objects from saved workspaces there is a much reduced chance of a clash with existing names.
  • Utility functions in a saved workspace may be coded as a single namespace and therefore on being copied into the active workspace consume only a single name. This avoids the complexity and expense of a solution which is sometimes used in 'flat' workspaces, where such utilities dynamically fix local functions on each call.
  • In flat APL, workspace administration functions such as WSDOC must share names with their subject namespace. This leads to techniques for trying to avoid name clashes such as using obscure name prefixes like '⍙⍙L1' This problem is now virtually eliminated because such a utility can operate exclusively in its own namespace.

The programming of GUI objects is considerably simplified.

  • An object’s callback functions may be localised in the namespace of the object itself.
  • Static variables used by callback functions to maintain information between calls may be localised within the object.

This means that the object need use only a single name in its namespace.


Namespace Syntax

Names within namespaces may be referenced explicitly or implicitly. An explicit reference requires that you identify the object by its full or relative pathname using a '.' syntax; for example:

      X.NUMB ← 88

sets the variable NUMB in namespace X to 88.

      88 UTIL.FOO 99

calls dyadic function FOO in namespace UTIL with left and right arguments of 88 and 99 respectively. The interpreter can distinguish between this use of '.' and its use as the inner product operator, because the leftmost name: UTIL is a (class 9) namespace, rather than a (class 3) function.

The general namespace reference syntax is:

  SPACE . SPACE . (...) EXPR

Where SPACE is an expression which resolves to a namespace reference, and EXPR is any APL expression to be resolved in the resulting namespace.

There are two special space names:

# is the top level or 'Root' namespace.

## is the parent or space containing the current namespace.

⎕SE is a system namespace which is preserved across workspace load and clear.

Examples

      WSDOC.PAGE.NO +← 1     ⍝ Increment WSDOC page count

      #.⎕NL 2                   ⍝ Variables in root space

      UTIL.⎕FX 'Z←DUP A' 'Z←A A'    ⍝ Fix remote function

      ##.⎕ED'FOO'         ⍝ Edit function in parent space

      ⎕SE.RECORD ← PERS.RECORD    ⍝ Copy from PERS to ⎕SE

      UTIL.(⎕EX ⎕NL 2)        ⍝ Expunge variables in UTIL

      (⊃⎕SE #).(⍎⊃↓⎕NL 9).(⎕NL 2)     ⍝ Vars in first ⎕SE
                                      ⍝ namespace.

      UTIL.⍎STRING         ⍝ Execute STRING in UTIL space

You may also reference a function or operator in a namespace implicitly using the mechanism provided by ⎕EXPORT (See Export Object:) and ⎕PATH. If you reference a name that is undefined in the current space, the system searches for it in the list of exported names defined for the namespaces specified by ⎕PATH. See Search Path: for further details.

Notice that the expression to the right of a dot may be arbitrarily complex and will be executed within the namespace or ref to the left of the dot.

      X.(C←A×B)
      X.C
10 12 14
16 18 20
      NS1.C
10 12 14
16 18 20

Summary

Apart from its use as a decimal separator (3.14), ‘.’ is interpreted by looking at the type or class of the expression to its left:

Template | Interpretation | Example
∘. | Outer product | 2 3 ∘.× 4 5
function. | Inner product | 2 3 +.× 4 5
ref. | Namespace reference | 2 3 x.foo 4 5
array. | Reference array expansion | (x y).⎕nc⊂'foo'


Namespace Reference Evaluation

When the interpreter encounters a namespace reference, it:

  1. Switches to the namespace.
  2. Evaluates the name.
  3. Switches back to the original namespace.

If for example, in the following, the current namespace is #.W, the interpreter evaluates the line:

      A ← X.Y.DUP MAT

in the following way:

  1. Evaluate array MAT in current namespace W to produce argument for function.
  2. Switch to namespace X.Y within W.
  3. Evaluate function DUP in namespace W.X.Y with argument.
  4. Switch back to namespace W.
  5. Assign variable A in namespace W.


Namespaces and Localisation

The rules for name resolution have been generalised for namespaces.

In flat APL, the interpreter searches the state indicator to resolve names referenced by a defined function or operator. If the name does not appear in the state indicator, then the workspace-global name is assumed.

With namespaces, a defined function or operator is evaluated in its 'home' namespace. When a name is referenced, the interpreter searches only those lines of the state indicator which belong to the home namespace. If the name does not appear in any of these lines, the home namespace-global value is assumed.

For example, if #.FN1 calls XX.FN2 calls #.FN3 calls XX.FN4, then:

FN1:
is evaluated in #
can see its own dynamic local names
can see global names in #
FN2:
is evaluated in XX
can see its own dynamic local names
can see global names in XX
FN3:
is evaluated in #
can see its own dynamic local names
can see dynamic local names in FN1
can see global names in #
FN4:
is evaluated in XX
can see its own dynamic local names
can see dynamic local names in FN2
can see global names in XX


Namespace References

A namespace reference, or ref for short, is a unique data type that is distinct from and in addition to number and character.

Any expression may result in a ref, but the simplest one is the namespace itself:

      )NS NS1          ⍝ Make a namespace called NS1
      NS1.A←1          ⍝ and populate it with variables A
      NS1.B←2 3⍴⍳6     ⍝ and B

      NS1              ⍝ expression results in a ref
#.NS1

You may assign a ref; for example:

      X←NS1
      X
#.NS1

In this case, the display of X informs you that X refers to the named namespace #.NS1.

You may also supply a ref as an argument to a defined or dynamic function:

     ∇ FOO ARG
[1]    ARG
     ∇
      FOO NS1
#.NS1

The name class of a ref is 9.

      ⎕NC 'X'
9

You may use a ref to a namespace anywhere that you would use the namespace itself. For example:

      X.A
1
      X.B
1 2 3
4 5 6

Notice that refs are references to namespaces, so that if you make a copy, it is the reference that is copied, not the namespace itself. This is sometimes referred to as a shallow as opposed to a deep copy. It means that if you change a ref, you actually change the namespace that it refers to.

      X.A+←1
      X.A
2
      NS1.A
2

Similarly, a ref passed to a defined function is call-by-reference, so that modifications to the content or properties of the argument namespace using the passed reference persist after the function exits. For example:

     ∇ FOO nsref
[1]    nsref.B+←nsref.A
     ∇

      FOO NS1
      NS1.B
3 4 5
6 7 8
      FOO X
      NS1.B
5 6  7
8 9 10

Notice that the expression to the right of a dot may be arbitrarily complex and will be executed within the namespace or ref to the left of the dot.

      X.(C←A×B)
      X.C
10 12 14
16 18 20
      NS1.C
10 12 14
16 18 20


Unnamed Namespaces

The monadic form of ⎕NS makes a new (and unique) unnamed namespace and returns a ref to it.

One use of unnamed namespaces is to represent hierarchical data structures; for example, a simple employee database:

The first record is represented by JOHN which is a ref to an unnamed namespace:

      JOHN←⎕NS ''
      JOHN
#.[Namespace]

      JOHN.FirstName←'John'
      JOHN.FirstName
John

      JOHN.LastName←'Smith'
      JOHN.Age←50

Data variables for the second record, PAUL, can be established using strand, or vector, assignment:

      PAUL←⎕NS ''
      PAUL.(FirstName LastName Age←'Paul' 'Brown' 44)

The function SHOW can be used to display the data in each record (the function is split into 2 lines only to fit on the printed page). Notice that its argument is a ref.

     ∇ R←SHOW PERSON
[1]    R←PERSON.FirstName,' ',PERSON.LastName
[2]    R, ←' is ',⍕PERSON.Age
     ∇

      SHOW JOHN
John Smith is 50

      SHOW PAUL
Paul Brown is 44

An alternative version of the function illustrates the use of the :With :EndWith control structure to execute an expression, or block of expressions, within a namespace:

     ∇ R←SHOW1 PERSON
[1]    :With PERSON
[2]        R←FirstName,' ',LastName,' is ',(⍕Age)
[3]    :EndWith
     ∇

      SHOW1 JOHN
John Smith is 50

In this case, as only a single expression is involved, it can be expressed more simply using parentheses.

     ∇ R←SHOW2 PERSON
[1]    R←PERSON.(FirstName,' ',LastName,' is ',(⍕Age))
     ∇
      SHOW2 PAUL
Paul Brown is 44

Dynamic functions also accept refs as arguments:

      SHOW3←{
        ⍵.(FirstName,' ',LastName,' is ',⍕Age)
      }

      SHOW3 JOHN
John Smith is 50


Arrays of Namespace References

You may construct arrays of refs using strand notation, catenate (,) and reshape (⍴).

      EMP←JOHN PAUL
      ⍴EMP

2

      EMP
 #.[Namespace]  #.[Namespace]

Like any other array, an array of refs has name class 2:

      ⎕NC 'EMP'
2

Expressions such as indexing and pick return refs that may in turn be used as follows:

      EMP[1].FirstName
John
      (2⊃EMP).Age
44

The each (¨) operator may be used to apply a function to an array of refs:

      SHOW¨EMP
 John Smith is 50  Paul Brown is 44

An array of namespace references (refs) to the left of a ‘.’ is expanded according to the following rule, where x and y are refs, and exp is an arbitrary expression:

      (x y).exp → (x.exp)(y.exp)

If exp evaluates to a function, the items of its argument array(s) are distributed to each referenced function. In the dyadic case, there is a 3-way distribution among: left argument, referenced functions and right argument.

Monadic function f:

      (x y).f d e → (x.f d)(y.f e)

Dyadic function g:

      a b (x y).g  d e → (a x.g d)(b y.g e)

An array of refs to the left of an assignment arrow is expanded thus:

      (x y).a←c d   →  (x.a←c)(y.a←d)

Note that the array of refs can be of any rank. In the limiting case of a simple scalar array, the array construct: refs.exp is identical to the scalar construct: ref.exp.

Note that the expression to the right of the ‘.’ pervades a nested array of refs to its left:

      ((u v)(x y)).exp → ((u.exp)(v.exp))((x.exp)(y.exp))

Note also that with successive expansions (u v).(x y z). ..., the final number of ‘leaf’ terms is the product of the number of refs at each level.

Examples:

      JOHN.Children←⎕NS¨'' ''
      ⍴JOHN.Children
2
      JOHN.Children[1].FirstName←'Andy'
      JOHN.Children[1].Age←23

      JOHN.Children[2].FirstName←'Katherine'
      JOHN.Children[2].Age←19

      PAUL.Children←⎕NS¨'' ''
      PAUL.Children[1].(FirstName Age←'Tom' 25)
      PAUL.Children[2].(FirstName Age←'Jamie' 22)

      ⍴EMP
2
      (⊃EMP).Children.(FirstName Age)
  Andy  23   Katherine  19

      ]display (2⊃EMP).Children.(FirstName Age)
.→----------------------------.
| .→---------. .→-----------. |
| | .→--.    | | .→----.    | |
| | |Tom| 25 | | |Jamie| 22 | |
| | '---'    | | '-----'    | |
| '∊---------' '∊-----------' |
'∊----------------------------'

      EMP.Children ⍝ Is an array of refs
  #.[Namespace]  #.[Namespace]    #.[Namespace]  ...

      EMP.Children.(FirstName Age)
   Andy  23   Katherine  19     Tom  25   Jamie  22


Distributed Assignment

Assignment pervades nested strands of names to the left of the arrow. The conformability rules are the same as for scalar (pervasive) dyadic primitive functions such as ‘+’. The mechanism can be viewed as a way of naming the parts of a structure.

Examples:

      EMP.(FirstName Age)
  JOHN  43   PAUL  44

      EMP.(FirstName Age)←('Jonathan' 21)('Pauline' 22)

      EMP.(FirstName Age)
  Johnathan  21   Pauline  22

⍝ Distributed assignment is pervasive
      JOHN.Children.(FirstName Age)
  Andy  23   Katherine  19

      JOHN.Children.(FirstName Age)←('Andrew' 21)('Kate' 9)

      JOHN.Children.(FirstName Age)
  Andrew  21   Kate  9

More Examples:

      ((a b)(c d))←(1 2)(3 4)   ⍝ a←1 ⋄ b←2 ⋄ c←3 ⋄ d←4

      ((⎕io ⎕ml)vec)←0 ⎕av      ⍝ ⎕io←0 ⋄ ⎕ml←0 ⋄ vec←⎕av

      (i (j k))+←1 2            ⍝ i+←1 ⋄ j+←2 ⋄ k+←2

⍝ Naming of parts:

      ((first last) sex (street city state))←n⊃pvec

⍝ Distributed assignment in :For loop:

      :For (i j)(k l) :In array

⍝ Ref array expansion:

      (x y).(first last)←('John' 'Doe')('Joe' 'Blow')
      (f1 f2).(b1 b2).Caption←⊂'OK' 'Cancel'

⍝ Structure rearrangement:
      rotate1←{       ⍝ Simple binary tree rotation.
           (a b c)d e←⍵
           a b(c d e)
      }
      rotate3←{       ⍝ Compound binary tree rotation.
           (a b(c d e))f g←⍵
           (a b c)d(e f g)
      }


Namespaces and Operators

A function passed as operand to a primitive or defined operator, carries its namespace context with it. This means that if subsequently, the function operand is applied to an argument, it executes in its home namespace, irrespective of the namespace from which the operator was invoked or defined.

Examples

      VAR←99                     ⍝ #.VAR

      )NS X
#.X
      X.VAR←77                   ⍝ X.VAR
      X.⎕FX'Z←FN R' 'Z←R,VAR'

      )NS Y
#.Y
      Y.VAR←88                   ⍝ Y.VAR
      Y.⎕FX'Z←(F OP)R' 'Z←F R'

      X.FN¨⍳3
 1 77  2 77  3 77

      X.FN 'VAR:'
 VAR: 77

      X.FN Y.OP 'VAR:'
 VAR: 77
      ⍎ Y.OP'VAR'
99


Workspaces

APL expressions are evaluated within a workspace. The workspace may contain objects, namely operators, functions and variables defined by the user. APL expressions may include references to operators, functions and variables provided by APL. These objects do not reside in the workspace, but space is required for the actual process of evaluation to accommodate temporary data. During execution, APL records the state of execution through the STATE INDICATOR which is dynamically maintained until the process is complete. Space is also required to identify objects in the workspace in the SYMBOL TABLE. Maintenance of the symbol table is entirely dynamic. It grows and contracts according to the current workspace contents.

Workspaces may be explicitly saved with an identifying name. The workspace may subsequently be loaded, or objects may be selectively copied from a saved workspace into the current workspace.

Under UNIX, workspace names must be valid file names, but are otherwise unrestricted. See your UNIX documentation for details.

Under Windows, Dyalog APL workspaces are stored in files with the suffix ".DWS". However, they are referred to from within APL by only the first part of the file name which must conform to Windows file naming rules.


Expressions

An expression is a sequence of one or more syntactic tokens which may be symbols or constants or names representing arrays (variables) or functions. An expression which produces an array is called an ARRAY EXPRESSION. An expression which produces a function is called a FUNCTION EXPRESSION. Some expressions do not produce a result.

An expression may be enclosed within parentheses.

Evaluation of an expression proceeds from right to left, unless modified by parentheses. If an entire expression results in an array that is not assigned to a name, then that array value is displayed. (Some system functions and defined functions return an array result only if the result is assigned to a name or if the result is the argument of a function or operator.)

Examples

      X←2×3-1

      2×3-1
4
      (2×3)-1
5

Either blanks or parentheses are required to separate constants, the names of variables, and the names of defined functions which are adjacent. Excessive blanks or sets of parentheses are redundant, but permitted. If F is a function, then:

      F 2←→ F(2) ←→ (F)2 ←→ (F) (2) ←→ F  (2) ←→ F ((2))

Blanks or parentheses are not needed to separate primitive functions from names or constants, but they are permitted:

      -2 ←→ (-)(2) ←→ (-) 2

Blanks or parentheses are not needed to separate operators from primitive functions, names or constants. They are permitted with the single exception that a dyadic operator must have its right argument available when encountered. The following syntactical forms are accepted:

      (+.×) ←→ (+).× ←→ +.(×)

The use of parentheses in the following examples is not accepted:

      +(.)×  or     (+.)×


Statements

A statement is a line of characters understood by APL. It may be composed of:

  1. a LABEL (which must be followed by a colon :), or a CONTROL STATEMENT (which is preceded by a colon), or both,
  2. an EXPRESSION (see Expressions),
  3. a SEPARATOR (consisting of the diamond character ⋄ which must separate adjacent expressions),
  4. a COMMENT (which must start with the character ⍝).

Each of the four parts is optional, but if present they must occur in the given order except that successive expressions must be separated by ⋄. Any characters occurring to the right of the first comment symbol (⍝) that is not within quotes is a comment.

Comments are not executed by APL. Expressions in a line separated by ⋄ are taken in left-to-right order as they occur in the line. For output display purposes, each separated expression is treated as a separate statement.

Examples

      5×10
50

      MULT: 5×10
50

      MULT: 5×10 ⋄ 2×4
50
8

      MULT: 5×10 ⋄ 2×4  ⍝ MULTIPLICATION
50
8


Functions

A function is an operation which is performed on zero, one or two array arguments and may produce an array result. Three forms are permitted:

  • NILADIC defined for no arguments
  • MONADIC defined for a right but not a left argument
  • DYADIC defined for a left and a right argument

The number of arguments is referred to as its VALENCE.

The name of a non-niladic function is AMBIVALENT; that is, it potentially represents both a monadic and a dyadic function, though it might not be defined for both. The usage in an expression is determined by syntactical context. If the usage is not defined an error results.

Functions have long SCOPE on the right; that is, the right argument of the function is the result of the entire expression to its right which must be an array. A dyadic function has short scope on the left; that is, the left argument of the function is the array immediately to its left. Left scope may be extended by enclosing an expression in parentheses whence the result must be an array.

For some functions, the explicit result is suppressed if it would otherwise be displayed on completion of evaluation of the expression. This applies on assignment to a variable name. It applies for certain system functions, and may also apply for defined functions.

Examples

      10×5-2×4
¯30
      2×4
8
      5-8
¯3
      10×¯3
¯30
      (10×5)-2×4
42

Defined Functions

Functions may be defined with the system function ⎕FX, or with the function editor. A function consists of a HEADER which identifies the syntax of the function, and a BODY in which one or more APL statements are specified.

The header syntax identifies the function name, its (optional) result and its (optional) arguments. If a function is ambivalent, it is defined with two arguments but with the left argument within braces ({}). If an ambivalent function is called monadically, the left argument has no value inside the function. If the explicit result is to be suppressed for display purposes, the result is shown within braces. A function need not produce an explicit result. Refer to Chapter 2 for further details.

Example

     ∇ R←{A} FOO B
[1]    R←⊃'MONADIC' 'DYADIC'[⎕IO+0≠⎕NC'A']
[2]  ∇

      FOO 1
MONADIC

      'X' FOO 'Y'
DYADIC

Functions may also be created by using assignment (←).

Function Assignment & Display

The result of a function-expression may be given a name. This is known as FUNCTION ASSIGNMENT (see also Dynamic Functions & Operators). If the result of a function-expression is not given a name, its value is displayed. This is termed FUNCTION DISPLAY.

Examples

      PLUS←+
      PLUS
+
      SUM←+/
      SUM
+/

Function expressions may include defined functions and operators. These are displayed as a ∇ followed by their name.

Example

      ∇ R←MEAN X    ⍝ Arithmetic mean
[1]     R←(+/X)÷⍴X
      ∇

      MEAN
 ∇MEAN

      AVERAGE←MEAN
      AVERAGE
 ∇MEAN

      AVG←MEAN∘,
      AVG
 ∇MEAN ∘,


Operators

An operator is an operation on one or two operands which produces a function called a DERIVED FUNCTION. An operand may be a function or an array. Operators are not ambivalent. They require either one or two operands as applicable to the particular operator. However, the derived function may be ambivalent. The derived function need not return a result. Operators have higher precedence than functions. Operators have long scope on the left. That is, the left operand is the longest function or array expression on its left. The left operand may be terminated by:

  1. the end of the expression
  2. the right-most of two consecutive functions
  3. a function with an array to its left
  4. an array with a function to its left

an array or function to the right of a monadic operator.

A dyadic operator has short scope on the right. That is, the right operand of an operator is the single function or array on its right. Right scope may be extended by enclosing an expression in parentheses.

Examples

      ⍴¨X←'WILLIAM' 'MARY' 'BELLE'
 7  4  5

      ⍴∘⍴¨X
 1  1  1

      (⍴∘⍴)¨X
 1  1  1

      ⎕∘←∘⎕VR¨'PLUS' 'MINUS'
     ∇ R←A PLUS B
[1]    R←A+B
     ∇
     ∇ R←A MINUS B
[1]    R←A-B
     ∇

      PLUS/1 2 3 4
10

Defined Operators

Operators may be defined with the system function ⎕FX, or with the function editor. A defined operator consists of a HEADER which identifies the syntax of the operator, and a BODY in which one or more APL statements are specified.

A defined operator may have one or two operands; and its derived function may have one or two arguments, and may or may not produce a result. The header syntax defines the operator name, its operand(s), the argument(s) to its derived function, and the result (if any) of its derived function. The names of the operator and its operand(s) are separated from the name(s) of the argument(s) to its derived function by parentheses.

Example

      ∇ R←A(F AND G)B
[1]     R←(A F B)(A G B)
      ∇

The above example shows a dyadic operator called AND with two operands (F and G). The operator produces a derived function which takes two arguments (A and B), and produces a result (R).

      12 +AND÷ 4
16 3

Operands passed to an operator may be either functions or arrays.

      12 (3 AND 5) 4
12 3 4  12 5 4

      12 (× AND 5) 4
48  12 5 4


Global & Local Names

The following names, if present, are local to the defined operation:

  1. the result,
  2. the argument(s) and operand(s),
  3. additional names in the header line following the model, each name preceded by a semi-colon character,
  4. labels,
  5. the argument list of the system function ⎕SHADOW when executed,
  6. a name assigned within a Dynamic Function.

All names in a defined operation must be valid APL names. The same name may be repeated in the header line, including the operation name (whence the name is localised). Normally, the operation name is not a local name.

The same name may not be given to both arguments or operands of a dyadic operation. The name of a label may be the same as a name in the header line. More than one label may have the same name. When the operation is executed, local names in the header line after the model are initially undefined; labels are assigned the values of line numbers on which they occur, taken in order from the last line to the first; the result (if any) is initially undefined.

In the case of a defined function, the left argument (if any) takes the value of the array to the left of the function when called; and the right argument (if any) takes the value of the array to the right of the function when called. In the case of a defined operator, the left operand takes the value of the function or array to the left of the operator when called; and the right operand (if any) takes the value of the function or array to the right of the operator when called.

During execution, a local name temporarily excludes from use an object of the same name with an active definition. This is known as LOCALISATION or SHADOWING. A value or meaning given to a local name will persist only for the duration of execution of the defined operation (including any time whilst the operation is halted). A name which is not local to the operation is said to be GLOBAL. A global name could itself be local to a pendent operation. A global name can be made local to a defined operation during execution by use of the system function ⎕SHADOW. An object is said to be VISIBLE if there is a definition associated with its name in the active environment.

Examples

      A←1

     ∇ F
[1]    A←10
[2]  ∇

      F ⍝ <A> NOT LOCALISED IN <F>, GLOBAL VALUE REPLACED
      A
10
      A←1
      )ERASE F

     ∇ F;A
[1]    A←10
[2]  ∇

      F  ⍝ <A> LOCALISED IN <F>, GLOBAL VALUE RETAINED
      A
1

Any statement line in the body of a defined operation may begin with a LABEL. A label is followed by a colon (:). A label is a constant whose value is the number of the line in the operation defined by system function ⎕FX or on closing definition mode.

The value of a label is available on entering an operation when executed, and it may be used but not altered in any expression.

Example

      ⎕VR'PLUS'
    ∇ R←{A} PLUS B
[1]   →DYADIC ⍴⍨2=⎕NC'A' ⋄ R←B ⋄ →END
[2]  DYADIC: R←A+B
[3]  END:
    ∇

      1 ⎕STOP'PLUS'

      2 PLUS 2

PLUS[1]
      DYADIC
2

      END
3


Namelists

The right argument and the result of a function may be specified in the function header by a single name or by a Namelist. In this context, a Namelist is a blank-delimited list of names surrounded by a single set of parentheses.

Names specified in a Namelist are automatically local to the function; there is no need to localise them explicitly using semi-colons.

If the right argument of a function is declared as a Namelist, the function will only accept a right argument that is a vector whose length is the same as the number of names in the Namelist. Calling the function with any other argument will result in a LENGTH ERROR in the calling statement. Otherwise, the elements of the argument are assigned to the names in the Namelist in the specified order.

Example:

     ∇ IDN←Date2IDN(Year Month Day)
[1]    'Year is ',⍕Year
[2]    'Month is ',⍕Month
[3]    'Day is ',⍕Day
[4] ...
     ∇

      Date2IDN 2004 4 30
Year is 2004
Month is 4
Day is 30

      Date2IDN 2004 4
LENGTH ERROR
      Date2IDN 2004 4
     ^

Note that if you specify a single name in the Namelist, the function may be called only with a 1-element vector or a scalar right argument.

If the result of a function is declared as a Namelist, the values of the names will automatically be stranded together in the specified order and returned as the result of the function when the function terminates.

Example:

     ∇ (Year Month Day)←Birthday age
[1]    Year←1949+age
[2]    Month←4
[3]    Day←30
     ∇
      Birthday 50
1999 4 30


Locked Functions & Operators

A defined operation may be locked by the system function ⎕LOCK. A locked operation may not be displayed or edited. The system function ⎕CR returns an empty matrix of shape 0 0 and the system functions ⎕NR and ⎕VR return an empty vector for a locked operation.

Stop, trace and monitor settings may be established by the system functions ⎕STOP, ⎕TRACE and ⎕MONITOR respectively. Existing stop, trace and monitor settings are cancelled when an operation is locked.

A locked operation may not be suspended, nor may a locked operation remain pendent when execution is suspended. The state indicator is cut back as described below.


Search Functions and Hash Tables

Primitive dyadic search functions, such as ⍳ (index of) and ∊ (membership) have a principal argument in which items of the other subject argument are located.

In the case of ⍳, the principal argument is the one on the left and in the case of ∊, it is the one on the right. The following table shows the principal (P) and subject (s) arguments for each of the functions.

P ⍳ s | Index of
s ∊ P | Membership
s ∩ P | Intersection
P ∪ s | Union
s ~ P | Without
P {(↓⍺)⍳↓⍵} s | Matrix Iota (idiom)
P∘⍋ and P∘⍒ | Sort

The Dyalog APL implementation of these functions already uses a technique known as hashing to improve performance over a simple linear search. (Note that ⍷ (find) does not employ the same hashing technique, and is excluded from this discussion.)

Building a hash table for the principal argument takes a significant time but is rewarded by a considerably quicker search for each item in the subject. Unfortunately, the hash table is discarded each time the function completes and must be reconstructed for a subsequent call (even if its principal argument is identical to that in the previous one).

For optimal performance of repeated search operations, the hash table may be retained between calls, by binding the function with its principal argument using the primitive ∘ (compose) operator. The retained hash table is then used directly whenever this monadic derived function is applied to a subject argument.

Notice that retaining the hash table pays off only on a second or subsequent application of the derived function. This usually occurs in one of two ways: either the derived function is named for later (and repeated) use, as in the first example below or it is applied repeatedly as the operand of a primitive or defined operator, as in the second example.

Example: naming a derived function.

      words←'red' 'ylo' 'grn' 'brn' 'blu' 'pnk' 'blk'

      find←words∘⍳                 ⍝ monadic find function
      find'blk' 'blu' 'grn' 'ylo'  ⍝
7 5 3 2
      find'grn' 'brn' 'ylo' 'red'  ⍝ fast find
3 4 2 1

Example: repeated application by (¨) each operator.

      ∊∘⎕A¨'This' 'And' 'That'
 1 0 0 0  1 0 0  1 0 0 0


Idiom Recognition

Idioms are commonly used expressions that are recognised and evaluated internally, providing a significant performance improvement.

For example, the idiom BV/⍳⍴A (where BV is a Boolean vector and A is an array) would (in earlier Versions of Dyalog APL) have been evaluated in 3 steps as follows:

  1. Evaluate ⍴A and store result in temporary variable temp1 (temp1 is just an arbitrary name for the purposes of this explanation)
  2. Evaluate ⍳temp1 and store result in temporary variable temp2.
  3. Evaluate BV/temp2
  4. Discard temporary variables

In the current Version of Dyalog APL, the expression is recognised in its entirety and processed in a single step as if it were a single primitive function. In this case, the resultant improvement in performance is between 2 and 4.5.

Idiom recognition is precise; an expression that is almost identical but not exactly identical to an expression given in the Idiom List table will not be recognised.

For example, ⎕AV⍳ will be recognised as an idiom, but (⎕AV)⍳ will not. Similarly, (,)/ would not be recognized as the Join idiom.


Idiom List

In the following table, arguments to the idiom have types and ranks as follows:

Type | Description | Rank | Description
C | Character | S | Scalar or 1-item vector
B | Boolean | V | Vector
N | Numeric | M | Matrix
P | Nested | A | Array of any rank
X | any type |  |

For example: NV: numeric vector, CM: character matrix, PV: nested vector.

Idiom | Description
⍴⍴XA | The rank of XA
BV/⍳NS | The subset of NS corresponding to the 1s in BV
BV/⍳⍴XV | The positions in XV corresponding to the 1s in BV
NA⊃¨⊂XV | The subset of XV in the index positions defined by NA (equivalent to XV[NA])
XA1{}XA2 | XA1 and XA2 are ignored (no result produced)
XA1{⍺}XA2 | XA1 (XA2 is ignored)
XA1{⍵}XA2 | XA2 (XA1 is ignored)
XA1{⍺ ⍵}XA2 | XA1 and XA2 as a two item vector (XA1 XA2)
{0}XA | 0 irrespective of XA
{0}¨XA | 0 corresponding to each item of XA
,/PV | The enclose of the items of PV (which must be of depth 2) catenated along their last axes
⍪/PV | The enclose of the items of PV (which must be of depth 2) catenated along their first axes
⊃⌽XA | The item in the top right of XA (⎕ML<2)
↑⌽XA | The item in the top right of XA (⎕ML≥2)
⊃⌽,XA | The item in the bottom right of XA (⎕ML<2)
↑⌽,A | The item in the bottom right of XA (⎕ML≥2)
0=⍴XV | 1 if XV has a shape of zero, 0 otherwise
0=⍴⍴XA | 1 if XA has a rank of zero (scalar), 0 otherwise
0=≡XA | 1 if XA has a depth of zero (simple scalar), 0 otherwise
XM1{(↓⍺)⍳↓X⍵}M2 | A simple vector comprising as many items as there are rows in XM2, where each item is the number of the first row in XM1 that matches each row in XM2.
↓⍉↑PV | A nested vector comprising vectors that each correspond to a position in the original vectors of PV – the first vector contains the first item from each vector in PV, padded to be the same length as the largest vector, and so on (⎕ML<2)
↓⍉⊃PV | A nested vector comprising vectors that each correspond to a position in the original vectors of PV – the first vector contains the first item from each vector in PV, padded to be the same length as the largest vector, and so on (⎕ML≥2)
^\' '=CA | A Boolean mask indicating the leading blank spaces in each row of CA
+/^\' '=CA | The number of leading blank spaces in each row of CA
+/^\BA | The number of leading 1s in each row of BA
{(∨\' '≠⍵)/⍵}CV | CV without any leading blank spaces
{(+/^\' '=⍵)↓⍵}CV | CV without any leading blank spaces
~∘' '¨↓CA | A nested vector comprising simple character vectors constructed from the rows of CA (which must be of depth 1) with all blank spaces removed
{(+/∨\' '≠⌽⍵)↑¨↓⍵}CA | A nested vector comprising simple character vectors constructed from the rows of CA (which must be of depth 1) with trailing blank spaces removed
⊃∘⍴¨XA | The length of the first axis of each item in XA (⎕ML<2)
↑∘⍴¨XA | The length of the first axis of each item in XA (⎕ML≥2)
XA1,←XA2 | XA1 redefined to be XA1 with XA2 catenated along its last axis
XA1⍪←XA2 | XA1 redefined to be XA1 with XA2 catenated along its first axis
{⍵[⍋⍵]}XV | XV sorted into numerical or alphabetical order
{⍵[⍒⍵]}XV | XV sorted into reverse numerical or alphabetical order
{⍵[⍋⍵;]}XM | XM with the rows sorted into numerical or alphabetical order
{⍵[⍒⍵;]}XM | XM with the rows sorted into reverse numerical or alphabetical order
1=≡XA | 1 if XA has a depth of 1 (simple array), 0 otherwise
1=≡,XA | 1 if XA has a depth of 0 or 1 (simple scalar, vector, etc.), 0 otherwise
0∊⍴XA | 1 if XA is empty, 0 otherwise
~0∊⍴XA | 1 if XA is not empty, 0 otherwise
⊣⌿XA | The first sub-array along the first axis of XA
⊣/XA | The first sub-array along the last axis of XA
⊢⌿XA | The last sub-array along the first axis of XA
⊢/XA | The last sub-array along the last axis of XA
*○NA | Euler's idiom (accurate when NA is a multiple of 0J0.5)
0=⊃⍴ | 1 if XA has an empty first dimension, 0 otherwise (⎕ML<2)
0≠⊃⍴ | 1 if XA does not have an empty first dimension, 0 otherwise (⎕ML<2)
⎕AV⍳CA | Classic version only: The character numbers (atomic vector index) corresponding to the characters in CA

Notes

/⍳ and /⍳⍴, as well as providing an execution time advantage, reduce intermediate workspace usage and, consequently, the incidence of memory compactions and the likelihood of a WS FULL.

NA⊃¨⊂XV is implemented as XV[NA], which is significantly faster. The two are equivalent but the former now has no performance penalty.

,/ is special-cased only for vectors of vectors or scalars. Otherwise, the expression is evaluated as a series of concatenations. Recognition of this idiom turns join from an n-squared algorithm into a linear one. In other words, the improvement factor is proportional to the size of the argument vector.

⊃⌽ and ⊃⌽, now take constant time. Without idiom recognition, the time taken depends linearly on the number of items in the argument.

0=≡ takes a small constant time. Without idiom recognition, the time taken would depend on the size and depth of the argument, which in the case of a deeply nested array could be significant.

↓⍉↑ is special-cased only for a vector of nested vectors, each of whose items is of the same length.

{(↓⍺)⍳↓⍵} can accommodate much larger matrices than its constituent primitives. It is particularly effective when bound with a left argument using the compose operator:

      find←mat∘{(↓⍺)⍳↓⍵}     ⍝ find rows in mat table

In this case, the internal hash table for mat is retained so that it does not need to be generated each time the monadic derived function find is applied to a matrix argument.

{(∨\' '≠⍵)/⍵} and {(+/^\' '=⍵)↓⍵} are two codings of the same idiom. Both use the same C code for evaluation.

~∘' '¨↓ typically takes a character matrix argument and returns a vector of character vectors from which all blanks have been removed. An example might be the character matrix of names returned by the system function ⎕NL. In general, this idiom accommodates character arrays of any rank.

{(+/∨\' '≠⌽⍵)↑¨↓⍵} typically takes a character matrix argument and returns a vector of character vectors. Any embedded blanks in each row are preserved but trailing blanks are removed. In general, this idiom accommodates character arrays of any rank.

⊃∘⍴¨A (⎕ML<2) and ↑∘⍴¨A (⎕ML>2) avoid having to create an intermediate nested array of shape vectors.

For an array of vectors, this idiom quickly returns a simple array of the length of each vector.

      ⊃∘⍴¨ 'Hi' 'Pete' ⍝ Vector Lengths
2 4

For an array of matrices, it returns a simple array of the number of rows in each matrix.

      ⊃∘⍴¨⎕CR¨↓⎕NL 3   ⍝ Lines in functions
5 21...

A,←A and A⍪←Aoptimise the catenation of an array to another array along the last and first dimension respectively.

Among other examples, this idiom optimises repeated catenation of a scalar or vector to an existing vector.

      props,←⊂ 'Posn' 0 0
      props,←⊂'Size' 50 50
      vector,←2+4

Note that the idiom is not applied if the value of vector V is shared with another symbol in the workspace, as illustrated in the following examples:

Example 1: the idiom is used to perform the catenation to V1.

      V1←⍳10
      V1,←11

Example 2: the idiom is not used to perform the catenation to V1, because its value is at that point shared with V2.

      V1←⍳10
      V2←V1
      V1,←11

Example 3: the idiom is not used to perform the catenation to V in Join[1] because its value is, at that point, shared with the array used to call the function.

     ∇ V←V Join A
[1]    V,←A
     ∇
      (⍳10) Join 11
1 2 3 4 5 6 7 8 9 10 11

⊢⌿XA, ⊢/XA, ⊣⌿XA, and ⊣/XA return the first/last rank (0⌈¯1+⍴⍴A) sub-array along the first/last axis of XA. For example, if V is a vector, then:

⊣/V | First item of vector
⊢/V | Last item of vector

Similarly, if M is a matrix, then:

⊣⌿M | First row of matrix
⊣/M | First column of matrix
⊢⌿M | Last row of matrix
⊢/M | Last column of matrix

The idiom generalises uniformly to higher-rank arrays.

Euler's idiom*○NA produces accurate results for right argument values that are a multiple of 0J0.5. This is so that Euler's famous identity 0=1+*○0J1 holds, despite pi being represented as a floating point number.


Function Declaration Statements

Function Declaration statements are used to identify the characteristics of a function in some way.

The following declarative statements are provided.

  • :Access
  • :Attribute
  • :Implements
  • :Signature

With one exception, these statements are not executable statements and may theoretically appear anywhere in the body of the function. However, it is recommended that you place them at the beginning before any executable statements. The exception is:

:Implements Constructor <[:Base expr]>

In addition to being declarative (declaring the function to be a Constructor) this statement also executes the Constructor in the Base Class whether or not it includes :Base expr. Its position in the code is therefore significant.


Access Statement :Access
:Access <Private|Public><Instance|Shared>
:Access <WebMethod>

The :Access statement is used to specify characteristics for functions that represent Methods in classes (see Methods). It is also applicable to Classes and Properties.

Element | Description
Private|Public | Specifies whether or not the method is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies whether the method runs in the Class or Instance. The default is Instance.
WebMethod | Specifies that the method is exported as a web method. This applies only to a Class that implements a Web Service.
Overridable | Applies only to an Instance Method and specifies that the Method may be overridden by a Method in a higher Class. See below.
Override | Applies only to an Instance Method and specifies that the Method overrides the corresponding Overridable Method defined in the Base Class. See below

Overridable/Override

Normally, a Method defined in a higher Class replaces a Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class.

However, a Method declared as being Overridable is replaced in-situ (i.e. within its own Class) by a Method of the same name in a higher Class if that Method is itself declared with the Override keyword. For further information, see Superseding Base Class Methods.

WebMethod

Note that :Access WebMethod is equivalent to:

:Access Public
:Attribute System.Web.Services.WebMethodAttribute


Attribute Statement :Attribute
:Attribute <Name> [ConstructorArgs]

The :Attribute statement is used to attach .Net Attributes to a Method (or Class).

Attributes are descriptive tags that provide additional information about programming elements. Attributes are not used by Dyalog APL but other applications can refer to the extra information in attributes to determine how these items can be used. Attributes are saved with the metadata of Dyalog APL .NET assemblies.

Element | Description
Name | The name of a .Net attribute
ConstructorArgs | Optional arguments for the Attribute constructor

Examples

      :Attribute ObsoleteAttribute
      :Attribute ObsoleteAttribute 'Don''t use' 1


Implements Statement :Implements

The :Implements statement identifies the function to be one of the following types.

:Implements Constructor <[:Base expr]>
:Implements Destructor
:Implements Method <InterfaceName.MethodName>
:Implements Trigger <name1><,name2,name3,...>

Element | Description
Constructor | Specifies that the function is a Class Constructor.
:Base expr | Specifies that the Base Constructor be called with the result of the expression expr as its argument.
Destructor | Specifies that the function is a Class Destructor.
Method | Specifies that the function implements the Method MethodName whose syntax is specified by Interface InterfaceName.
Trigger | Identifies the function as a Trigger Function which is activated by changes to variable name1, name2, etc.


Signature Statement :Signature
:Signature <rslttype←><name><arg1type arg1name>,...

This statement identifies the name and signature by which a function is exported as a method to be called from outside Dyalog APL. Several :Signature statements may be specified to allow the method to be called with different arguments and/or to specify a different result type.

Element | Description
rslttype | Specifies the data type for the result of the method
name | Specifies the name of the exported method.
argntype | Specifies the data type of the nth parameter
argnname | Specifies the name of the nth parameter

Argument and result data types are identified by the names of .Net Types which are defined in the .Net Assemblies specified by ⎕USING or by a :USING statement.

Examples

In the following examples, it is assumed that the .Net Search Path (defined by :Using or ⎕USING includes 'System'.

The following statement specifies that the function is exported as a method named Format which takes a single parameter of type System.Object named Array. The data type of the result of the method is an array (vector) of type System.String.

      :Signature String[]←Format Object Array

The next statement specifies that the function is exported as a method named Catenate whose result is of type System.Object and which takes 3 parameters. The first parameter is of type System.Double and is named Dimension. The second is of type System.Object and is named Arg1. The third is of type System.Object and is named Arg2.

      :Signature Object←Catenate Double Dimension,...
                              ...Object Arg1, Object Arg2

The next statement specifies that the function is exported as a method named IndexGen whose result is an array of type System.Int32 and which takes 2 parameters. The first parameter is of type System.Int32 and is named N. The second is of type System.Int32 and is named Origin.

      :Signature Int32[]←IndexGen Int32 N, Int32 Origin

The next block of statements specifies that the function is exported as a method named Mix. The method has 4 different signatures; i.e. it may be called with 4 different parameter/result combinations.

      :Signature Int32[,]←Mix Double Dimension, ...
            ...Int32[] Vec1, Int32[] Vec2
      :Signature Int32[,]←Mix Double Dimension,...
            ... Int32[] Vec1, Int32[] Vec2, Int32 Vec3
      :Signature Double[,]←Mix Double Dimension, ...
            ... Double[] Vec1, Double[] Vec2
      :Signature Double[,]←Mix Double Dimension, ...
            ... Double[] Vec1, Double[] Vec2, Double[] Vec3


Control Structures

Control structures provide a means to control the flow of execution in your APL programs.

Traditionally, lines of APL code are executed one by one from top to bottom and the only way to alter the flow of execution is using the branch arrow. So how do you handle logical operations of the form “If this, do that; otherwise do the other”?

In APL this is often not a problem because many logical operations are easily performed using the standard array handling facilities that are absent in other languages. For example, the expression:

      STATUS←(1+AGE<16)⊃'Adult' 'Minor'

sets STATUS to 'Adult' if AGE is 16 or more; otherwise sets STATUS to 'Minor'.

Things become trickier if, depending upon some condition, you wish to execute one set of code instead of another, especially when the code fragments cannot conveniently be packaged as functions. Nevertheless, careful use of array logic, defined operators, the execute primitive function and the branch arrow can produce high quality maintainable and comprehensible APL systems.

Control structures provide an additional mechanism for handling logical operations and decisions. Apart from providing greater affinity with more traditional languages, Control structures may enhance comprehension and reduce programming errors, especially when the logic is complex. Control structures are not, however, a replacement for the standard logical array operations that are so much a part of the APL language.


Control Structures

Introduction

Control Structures are blocks of code in which the execution of APL statements follows certain rules and conditions. Control structures are implemented using a set of control words that all start with the colon symbol (:). Control Words are case-insensitive.

There are eight different types of control structures defined by the control words, :If, :While, :Repeat, :For, :Select, :With, :Trap and :Hold . Each one of these control words may occur only at the beginning of an APL statement and indicates the start of a particular type of control structure.

Within a control structure, certain other control words are used as qualifiers. These are :Else, :ElseIf, :AndIf, :OrIf, :Until, :Case and :CaseList.

A third set of control words is used to identify the end of a particular control structure. These are :EndIf, :EndWhile, :EndRepeat, :EndFor, :EndSelect, :EndWith, :EndTrap and :EndHold. Although formally distinct, these control words may all be abbreviated to :End.

Finally, the :GoTo, :Return, :Leave and :Continue control words may be used to conditionally alter the flow of execution within a control structure.

Control words, including qualifiers such as :Else and :ElseIf, may occur only at the beginning of a line or expression in a diamond-separated statement. The only exceptions are :In and :InEach which must appear on the same line within a :For expression.

Key to Notation

The following notation is used to describe Control Structures within this section:

aexp | an expression returning an array,
bexp | an expression returning a single Boolean value (0 or 1),
var | loop variable used by :For control structure,
code | 0 or more lines of APL code, including other (nested) control structures,
andor either one or more :AndIf statements, or one or more :OrIf statements.
|
.-----------------------.
|                       |
|<--------------.       |<--------------.
|               |       |               |
code            |       code            |
|               |       |               |
|               |       |               |
:AndIf bexp-----'       :OrIf bexp------'
|                       |
|<----------------------'
|


Access Statement>

Access Statement :Access

The :Access statement may be used to define the characteristics of a Class, the characteristics of a defined function (Method) in a Class, or the characteristics of other Class members.

:Access Statement in a Function/Method.

:Access Statement in a Class or in other members of a Class.


Attribute Statement :Attribute

The :Attribute statement is used to attach .Net Attributes to a Method or a Class.

:Attribute Statement for a Class.

:Attribute statement for a Method.


LangRef_Flare

If Statement :If bexp

Formal Definition

The simplest :If control structure is a single condition of the form:

[1]   :If AGE<21
[2]       expr 1
[3]       expr 2
[5]   :EndIf

If the test condition (in this case AGE<21) is true, the statements between the :If and the :EndIf will be executed. If the condition is false, none of these statements will be run and execution resumes after the :EndIf. Note that the test condition to the right of :If must return a single element Boolean value 1 (true) or 0 (false).

:If control structures may be considerably more complex. For example, the following code will execute the statements on lines [2-3] if AGE<21 is 1 (true), or alternatively, the statement on line [6] if AGE<21 is 0 (false).

[1]   :If AGE<21
[2]       expr 1
[3]       expr 2
[5]   :Else
[6]       expr 3
[7]   :EndIf

Instead of a single condition, it is possible to have multiple conditions using the :ElseIf control word. For example:

[1]   :If WINEAGE<5
[2]       'Too young to drink'
[5]   :ElseIf WINEAGE<10
[6]       'Just Right'
[7]   :ElseIf WINEAGE<15
[8]       'A bit past its prime'
[9]   :Else
[10]     'Definitely over the hill'
[11]  :EndIf

Notice that APL executes the expression(s) associated with the first condition that is true or those following the :Else if none of the conditions are true.

The :AndIf and :OrIf control words may be used to define a block of conditions and so refine the logic still further. You may qualify an :If or an :ElseIf with one or more :AndIf statements or with one or more :OrIf statements. You may not however mix :AndIf and :OrIf in the same conditional block. For example:

[1]   :If WINE.NAME≡'Chateau Lafitte'
[2]   :AndIf WINE.YEAR∊1962 1967 1970
[3]       'The greatest?'
[4]   :ElseIf WINE.NAME≡'Chateau Latour'
[5]   :Orif WINE.NAME≡'Chateau Margaux'
[6]   :Orif WINE.PRICE>100
[7]       'Almost as good'
[8]   :Else
[9]       'Everyday stuff'
[10]  :EndIf

Please note that in a :If control structure, the conditions associated with each of the condition blocks are executed in order until an entire condition block evaluates to true. At that point, the APL statements following this condition block are executed. None of the conditions associated with any other condition block are executed. Furthermore, if an :AndIf condition yields 0 (false), it means that the entire block must evaluate to false so the system moves immediately on to the next block without executing the other conditions following the failing :AndIf. Likewise, if an :OrIf condition yields 1 (true), the entire block is at that point deemed to yield true and none of the following :OrIf conditions in the same block are executed.


While Statement :While bexp

Formal Definition

The simplest :While loop is :

[1]   I←0
[2]   :While I<100
[3]       expr1
[4]       expr2
[5]       I←I+1
[6]   :EndWhile

Unless expr1 or expr2 alter the value of I, the above code will execute lines [3-4] 100 times. This loop has a single condition; the value of I. The purpose of the :EndWhile statement is solely to mark the end of the iteration. It acts the same as if it were a branch statement, branching back to the :While line.

An alternative way to terminate a :While structure is to use a :Until statement. This allows you to add a second condition. The following example reads a native file sequentially as 80-byte records until it finds one starting with the string 'Widget' or reaches the end of the file.

[1]   I←0
[2]   :While I<⎕NSIZE ¯1
[3]       REC←⎕NREAD ¯1 82 80
[4]       I←I+⍴REC
[5]   :Until 'Widget'≡6⍴REC

Instead of single conditions, the tests at the beginning and end of the loop may be defined by more complex ones using :AndIf and :OrIf. For example:

[1]   :While 100>i
[2]   :AndIf 100>j
[3]       i j←foo i j
[4]   :Until 100<i+j
[5]   :OrIf i<0
[6]   :OrIf j<0

In this example, there are complex conditions at both the start and the end of the iteration. Each time around the loop, the system tests that both i and j are less than or equal to 100. If either test fails, the iteration stops. Then, after i and j have been recalculated by foo, the iteration stops if i+j is equal to or greater than 100, or if either i or j is negative.


Repeat Statement :Repeat

Formal Definition

The simplest type of :Repeat loop is as follows. This example executes lines [3-5] 100 times. Notice that as there is no conditional test at the beginning of a :Repeat structure, its code statements are executed at least once.

[1]   I←0
[2]   :Repeat
[3]       expr1
[4]       expr2
[5]       I←I+1
[6]   :Until I=100

You can have multiple conditional tests at the end of the loop by adding :AndIf or :OrIf expressions. The following example will read data from a native file as 80-character records until it reaches one beginning with the text string 'Widget' or reaches the end of the file.

[1]   :Repeat
[2]       REC←⎕NREAD ¯1 82 80
[3]   :Until 'Widget'≡6⍴REC
[4]   :OrIf 0=⍴REC

A :Repeat structure may be terminated by an :EndRepeat (or :End) statement in place of a conditional expression. If so, your code must explicitly jump out of the loop using a :Leave statement or by branching. For example:

[1]   :Repeat
[2]       REC←⎕NREAD ¯1 82 80
[3]      :If 0=⍴REC
[4]      :OrIf 'Widget'≡6⍴REC
[5]         :Leave
[6]      :EndIf
[7]   :EndRepeat


For Statement :For var :In[Each] aexp

Formal Definition

Single Control Variable

The :For loop is used to execute a block of code for a series of values of a particular control variable. For example, the following would execute lines [2-3] successively for values of I from 3 to 5 inclusive:

[1]   :For I :In 3 4 5
[2]       expr1 I
[3]       expr2 I
[4]   :EndFor

The way a :For loop operates is as follows. On encountering the :For, the expression to the right of :In is evaluated and the result stored. This is the control array. The control variable, named to the right of the :For, is then assigned the first value in the control array, and the code between :For and :EndFor is executed. On encountering the :EndFor, the control variable is assigned the next value of the control array and execution of the code is performed again, starting at the first line after the :For. This process is repeated for each value in the control array.

Note that if the control array is empty, the code in the :For structure is not executed. Note too that the control array may be any rank and shape, but that its elements are assigned to the control variable in ravel order.

The control array may contain any type of data. For example, the following code resizes (and compacts) all your component files

[1]   :For FILE :In (↓⎕FLIB '')~¨' '
[2]       FILE ⎕FTIE 1
[3]       ⎕FRESIZE 1
[4]       ⎕FUNTIE 1
[5]   :EndFor

You may also nest :For loops. For example, the following expression finds the timestamp of the most recently updated component in all your component files.

[1]   TS←0
[2]   :For FILE :In (↓⎕FLIB '')~¨' '
[3]       FILE ⎕FTIE 1
[4]       START END←2⍴⎕FSIZE 1
[5]       :For COMP :In (START-1)↓⍳END-1
[6]           TS⌈←¯1↑⎕FREAD FILE COMP
[7]       :EndFor
[8]       ⎕FUNTIE 1
[9]   :EndFor

Multiple Control Variables

The :For control structure can also take multiple variables. This has the effect of doing a strand assignment each time around the loop.

For example :For a b c :in (1 2 3)(4 5 6), sets a b c←1 2 3, first time around the loop and a b c←4 5 6, the second time.

Another example is :For i j :In ⍳⍴Matrix, which sets i and j to each row and column index of Matrix.

:InEach Control Word

      :For var ... :InEach value ...

In a :For control structure, the keyword :InEach is an alternative to :In.

For a single control variable, the effect of the keywords is identical but for multiple control variables the values vector is inverted.

The distinction is best illustrated by the following equivalent examples:

      :For a b c :In (1 2 3)(3 4 5)(5 6 7)(7 8 9)
          ⎕←a b c
      :EndFor

      :For a b c :InEach (1 3 5 7)(2 4 6 8)(3 5 7 9)
           ⎕←a b c
      :EndFor

In each case, the output from the loop is:

1 2 3
3 4 5
5 6 7
7 8 9

Notice that in the second case, the number of items in the values vector is the same as the number of control variables. A more typical example might be.

      :For a b c :InEach avec bvec cvec
          ...
      :EndFor

Here, each time around the loop, control variable a is set to the next item of avec, b to the next item of bvec and c to the next item of cvec.


Select Statement :Select aexp

Formal Definition

A :Select structure is used to execute alternative blocks of code depending upon the value of an array. For example, the following displays 'I is 1' if the variable I has the value 1, 'I is 2' if it is 2, or 'I is neither 1 nor 2' if it has some other value.

[1]   :Select I
[2]   :Case 1
[3]       'I is 1'
[4]   :Case 2
[5]       'I is 2'
[6]   :Else
[7]       'I is neither 1 nor 2'
[8]   :EndSelect

In this case, the system compares the value of the array expression to the right of the :Select statement with each of the expressions to the right of the :Case statements and executes the block of code following the one that matches. If none match, it executes the code following the :Else (which is optional). Note that comparisons are performed using the ≡ primitive function, so the arrays must match exactly. Note also that not all of the :Case expressions are necessarily evaluated because the process stops as soon as a matching expression is found.

Instead of a :Case statement, you may also use a :CaseList statement. If so, the enclose of the array expression to the right of :Select is tested for membership of the array expression to the right of the :CaseList using the ∊ primitive function.

Note also that any code placed between the :Select and the first :Case or :CaseList statements are unreachable; future versions of Dyalog APL may generate an error when attempting to fix functions which include such code.

Example

[1]   :Select ?6 6
[2]   :Case 6 6
[3]       'Box Cars'
[4]   :Case 1 1
[5]       'Snake Eyes'
[6]   :CaseList 2⍴¨⍳6
[7]       'Pair'
[8]   :CaseList (⍳6),¨⌽⍳6
[9]       'Seven'
[10]  :Else
[11]      'Unlucky'
[12]  :EndSelect


With Statement :With obj

Formal Definition

:With is a control structure that may be used to simplify a series of references to an object or namespace. :With changes into the specified namespace for the duration of the control structure, and is terminated by :End[With]. For example, you could update several properties of a Grid object F.G as follows:

       :With F.G
            Values←4 3⍴0
            RowTitles←'North' 'South' 'East' 'West'
            ColTitles←'Cakes' 'Buns' 'Biscuits'
       :EndWith

:With is analogous to ⎕CS in the following senses:

  • The namespace argument to :With is interpreted relative to the current space.
  • With the exception of those with name class 9, local names in the containing defined function continue to be visible in the new space.
  • Global references from within the :With control structure are to names in the new space.
  • Exiting the defined function from within a :With control structure causes the space to revert to the one from which the function was called.

On leaving the :With control structure, execution reverts to the original namespace. Notice however that the interpreter does not detect branches (→) out of the control structure. :With control structures can be nested in the normal fashion:

[1]   :With 'x'           ⍝ Change to #.x
[2]       :With 'y'       ⍝ Change to #.x.y
[3]           :With ⎕SE   ⍝ Change to ⎕SE
[4]               ...     ⍝ ... in ⎕SE
[5]           :EndWith    ⍝ Back to #.x.y
[6]       :EndWith        ⍝ Back to #.x
[7]   :EndWith            ⍝ Back to #


Hold Statement Hold tkns

Hold Statement :Hold tkn

Formal Definition

Whenever more than one thread tries to access the same piece of data or shared resource at the same time, you need some type of synchronisation to control access to that data. This is provided by :Hold.

:Hold provides a mechanism to control thread entry into a critical section of code. tkns must be a simple character vector or scalar, or a vector of character vectors. tkns represents a set of ‘tokens’, all of which must be acquired before the thread can continue into the control structure. :Hold is analogous to the component file system ⎕FHOLD.

Within the whole active workspace, a token with a particular value may be held only once. If the hold succeeds, the current thread acquires the tokens and execution continues with the first phrase in the control structure. On exit from the structure, the tokens are released for use by other threads. If the hold fails, because one or more of the tokens is already in use:

  1. If there is no :Else clause in the control structure, execution of the thread is blocked until the requested tokens become available.
  2. Otherwise, acquisition of the tokens is abandoned and execution resumed immediately at the first phrase in the :Else clause.

tkns can be either a single token:

    'a'
    'Red'
    '#.Util'
    ''
    'Program Files'

… or a number of tokens:

    'red' 'green' 'blue'
    'doe' 'a' 'deer'
    ,¨'abc'
    ↓⎕nl 9

Pre-processing removes trailing blanks from each token before comparison, so that, for example, the following two statements are equivalent:

    :Hold 'Red' 'Green'
    :Hold ↓2 5⍴'Red  Green'

Unlike ⎕FHOLD, a thread does not release all existing tokens before attempting to acquire new ones. This enables the nesting of holds, which can be useful when multiple threads are concurrently updating parts of a complex data structure.

In the following example, a thread updates a critical structure in a child namespace, and then updates a structure in its parent space. The holds will allow all ‘sibling’ namespaces to update concurrently, but will constrain updates to the parent structure to be executed one at a time.

    :Hold ⎕cs''          ⍝ Hold child space
        ...              ⍝ Update child space
        :Hold ##.⎕cs''   ⍝ Hold parent space
            ...          ⍝ Update Parent space
        :EndHold
        ...
    :EndHold

However, with the nesting of holds comes the possibility of a ‘deadlock’. For example, consider the two threads:

Thread 1 Thread 2
:Hold 'red'
    ...
    :Hold 'green'
        ...
    :EndHold
:EndHold

:Hold 'green'
    ...
    :Hold 'red'
        ...
    :EndHold
:EndHold

In this case if both threads succeed in acquiring their first hold, they will both block waiting for the other to release its token.

If this deadlock situation is detected acquisition of the tokens is abandoned. Then:

  1. If there is an :Else clause in the control structure, execution jumps to the :Else clause.
  2. Otherwise, APL issues an error (1008) DEADLOCK.

You can avoid deadlock by ensuring that threads always attempt to acquire tokens in the same chronological order, and that threads never attempt to acquire tokens that they already own.

Note that token acquisition for any particular :Hold is atomic, that is, either all of the tokens or none of them are acquired. The following example cannot deadlock:

Thread 1 Thread 2
:Hold 'red'
    ...
    :Hold 'green'
        ...
    :EndHold
:EndHold

:Hold 'green' 'red'
    ...
    :EndHold

Examples

:Hold could be used for example, during the update of a complex data structure that might take several lines of code. In this case, an appropriate value for the token would be the name of the data structure variable itself, although this is just a programming convention: the interpreter does not associate the token value with the data variable.

    :Hold'Struct'
        ...              ⍝ Update Struct
        Struct ← ...
    :EndHold

The next example guarantees exclusive use of the current namespace:

    :Hold ⎕CS''          ⍝ Hold current space
        ...
    :EndHold

The following example shows code that holds two positions in a vector while the contents are exchanged.

    :Hold ⍕¨to fm
        :If >/vec[fm to]
            vec[fm to]←vec[to fm]
        :End
    :End

Between obtaining the next available file tie number and using it:

    :Hold '⎕FNUMS'
        tie←1+⌈/0,⎕FNUMS
        fname ⎕FSTIE tie
    :End

The above hold is not necessary if the code is combined into a single line:

    fname ⎕FSTIE tie←1+⌈/0,⎕FNUMS

or,

    tie←fname ⎕FSTIE 0

Note that :Hold, like its component file system counterpart ⎕FHOLD, is a device to enable co-operating threads to synchronise their operation.

:Hold does not prevent threads from updating the same data structures concurrently, it prevents threads only from :Hold-ing the same tokens.


Trap Statement :Trap ecode

Formal Definition

:Trap is an error trapping mechanism that can be used in conjunction with, or as an alternative to, the ⎕TRAP system variable. It is equivalent to APL2’s ⎕EA, except that the code to be executed is not restricted to a single expression and is not contained within quotes (and so is slightly more efficient).

ecode is an integer scalar or vector containing the list of event codes which are to be handled during execution of the segment of code between the :Trap and :End[Trap] statements. Note that event codes 0 and 1000 are wildcards that means any event code in a given range. See Language Reference.

Operation

The segment of code immediately following the :Trap keyword is executed. On completion of this segment, if no error occurs, control passes to the code following :End[Trap].

If an error occurs which is not specified by ecode, it is processed by outer :Traps, ⎕TRAPs, or by the default system processing in the normal fashion.

If an error occurs, whose event code matches ecode:

  • If the error occurred within a sub-function, the system cuts the execution stack back to the function containing the :Trap keyword. In this respect, :Trap behaves like ⎕TRAP with a 'C' qualifier.
  • If the :Trap segment contains a :Case[List] ecode statement whose ecode matches the event code of the error that has occurred, execution continues from the statement following that :Case[List] ecode.
  • Otherwise, if the :Trap segment contains a :Else statement, execution continues from the first statement following the :Else statement.
  • Otherwise, execution continues from the first statement following the :End[Trap] and no error processing occurs.

Note that the error trapping is in effect only during execution of the initial code segment. When a trapped error occurs, further error trapping is immediately disabled (or surrendered to outer level :Traps or ⎕TRAPs). In particular, the error trap is no longer in effect during processing of :Case[List]’s argument or in the code following the :Case[List] or :Else statement. This avoids the situation sometimes encountered with ⎕TRAP where an infinite ‘trap loop’ occurs.

Note that the statement :Trap ⍬ results in no errors being trapped.

Examples

     ∇ lx
[1]    :Trap 1000        ⍝ Cutback and exit on interrupt
[2]        Main ...
[3]    :EndTrap
     ∇

     ∇ ftie←Fcreate file        ⍝ Create null component file
[1]    :Trap 22                 ⍝ Trap FILE NAME ERROR
[2]        ftie←file ⎕FCREATE 0 ⍝ Try to create file.
[3]    :Else
[4]        ftie←file ⎕FTIE 0    ⍝ Tie the file.
[5]        file ⎕FERASE ftie    ⍝ Drop the file.
[6]        file ⎕FCREATE ftie   ⍝ Create new file.
[7]    :EndTrap
     ∇

     ∇ lx ⍝ Distinguish various cases
[1]    :Trap 0 1000
[2]        Main ...
[3]    :Case 1002
[4]        'Interrupted ...'
[5]    :CaseList 1 10 72 76
[6]        'Not enough resources'
[7]    :CaseList 17+⍳20
[8]        'File System Problem'
[9]    :Else
[10]       'Unexpected Error'
[11]   :EndTrap
     ∇

Note that :Traps can be nested:

     ∇ ntie←Ntie file                    ⍝ Tie native file
[1]    :Trap 22                          ⍝ Trap FILE NAME ERROR
[2]        ntie←file ⎕NTIE 0             ⍝ Try to tie file
[3]    :Else
[4]        :Trap 22                      ⍝ Trap FILE NAME ERROR
[5]            ntie←(file,'.txt')⎕NTIE 0 ⍝ Try with .txt extn
[6]        :Else
[7]            ntie←file ⎕NCREATE 0      ⍝ Create null file.
[8]        :EndTrap
[9]    :EndTrap
     ∇


GoTo Statement :GoTo aexp

A :GoTo statement is a direct alternative to → (branch) and causes execution to jump to the line specified by the first element of aexp.

The following are equivalent. See Branch: for further details.

      →Exit
      :GoTo Exit

      →(N<I←I+1)/End
      :GoTo (N<I←I+1)/End

      →1+⎕LC
      :GoTo 1+⎕LC

      →10
      :GoTo 10


Return Statement :Return

A :Return statement causes a function to terminate and has exactly the same effect as →0.

The :Return control word takes no argument.

A :Return statement may occur anywhere in a function or operator.


Leave Statement :Leave

A :Leave statement is used to explicitly terminate the execution of a block of statements within a :For, :Repeat or :While control structure.

The :Leave control word takes no argument.


Continue Statement :Continue

A :Continue statement starts the next iteration of the immediately surrounding :For, :Repeat or :While control loop.

When executed within a :For loop, the effect is to start the body of the loop with the next value of the iteration variable.

When executed within a :Repeat or :While loop, if there is a trailing test that test is executed and, if the result is true, the loop is terminated. Otherwise the leading test is executed in the normal fashion.


Section Statement

Section Statement :Section

Functions and scripted objects (classes, namespaces etc.) can be subdivided into Sections with :Section and :EndSection statements. Both statements may be followed by an optional and arbitrary name or description. The purpose is to split the function up into sections that you can open and close in the Editor, thereby aiding readability and code management. Sections have no effect on the execution of the code, but must follow the nesting rules of other control structures.

For further information, See User Guide.


Triggers

Triggers provide the ability to have a function called automatically whenever a variable or a Field is assigned. Triggers are actioned by all forms of assignment (←), but only by assignment.

Triggers are designed to allow a class to perform some action when a field is modified – without having to turn the field into a property and use the property setter function to achieve this. Avoiding the use of a property allows the full use of the APL language to manipulate data in a field, without having to copy field data in and out of the class through get and set functions.

Triggers can also be applied to variables outside a class, and there will be situations where this is very useful. However, dynamically attaching and detaching a trigger from a variable is a little tricky at present.

The function that is called when a variable or Field changes is referred to as the Trigger Function. The name of a variable or Field which has an associated Trigger Function is termed a Trigger.

A function is declared as aTrigger function by including the statement:

      :Implements Trigger Name1,Name2,Name3, ...

where Name1, Name2 etc are the Triggers.

When a Trigger function is invoked, it is passed an Instance of the internal Class TriggerArguments. This Class has 3 Fields:

Member | Description
Name | Name of the Trigger whose change in value has caused the Trigger Function to be invoked.
NewValue | The newly assigned value of the Trigger
OldValue | The previous value of the Trigger. If the Trigger was not previously defined, a reference to this Field causes a VALUE ERROR.

A Trigger Function is called as soon as possible after the value of a Trigger was assigned; typically by the end of the currently executing line of APL code. The precise timing is not guaranteed and may not be consistent because internal workspace management operations can occur at any time.

If the value of a Trigger is changed more than once by a line of code, the Trigger Function will be called at least once, but the number of times is not guaranteed.

A Trigger Function is not called when the Trigger is expunged.

Expunging a Trigger disconnects the name from the Trigger Function and the Trigger Function will not be invoked when the Trigger is reassigned. The connection may be re-established by re-fixing the Trigger Function.

A Trigger may have only a single Trigger Function. If the Trigger is named in more than one Trigger Function, the Trigger Function that was last fixed will apply.

In general, it is inadvisable for a Trigger function to modify its own Trigger, as this will potentially cause the Trigger to be invoked repeatedly and forever.

To associate a Trigger function with a local name, it is necessary to dynamically fix the Trigger function in the function in which the Trigger is localised; for example:

     ∇ TRIG arg
[1]    :Implements Trigger A
[2]    ...

     ∇ TEST;A
[1]    ⎕FX ⎕OR'TRIG'
[2]    A←10


Triggers

Trigger Example

The following function displays information when the value of variables A or B changes.

     ∇ TRIG arg
[1]    :Implements Trigger A,B
[2]    arg.Name'is now 'arg.NewValue
[3]    :Trap 6 ⍝ VALUE ERROR
[4]        arg.Name'was    'arg.OldValue
[5]    :Else
[6]        arg.Name' was     [undefined]'
[7]    :EndTrap
     ∇

Note that on the very first assignment to A, when the variable was previously undefined, arg.OldValue is a VALUE ERROR.

      A←10
 A  is now   10
 A   was     [undefined]

      A+←10
 A  is now   20
 A  was      10

      A←'Hello World'
 A  is now   Hello World
 A  was      20

      A[1]←⊂2 3⍴⍳6
 A  is now    1 2 3 ello World
              4 5 6
 A  was      Hello World

      B←⌽¨A
 B  is now    3 2 1 ello World
              6 5 4
 B   was     [undefined]

      A←⎕NEW MyClass
 A  is now   #.[Instance of MyClass]
 A  was       1 2 3 ello World
              4 5 6

      'F'⎕WC'Form'
      A←F
 A  is now   #.F
 A  was      #.[Instance of MyClass]

Note that Trigger functions are actioned only by assignment, so changing A to a Form using ⎕WC does not invoke TRIG.

      'A'⎕WC'FORM' ⍝ Note that Trigger Function is not invoked

However, the connection (between A and TRIG) remains and the Trigger Function will be invoked if and when the Trigger is re-assigned.

      A←99
 A  is now   99
 A  was      #.A

See Trigger Fields for information on how a Field (in a Class) may be used as a Trigger.


Trigger Fields

A field may act as a Trigger so that a function may be invoked whenever the value of the Field is changed.

As an example, it is often useful for the Display Form of an Instance to reflect the value of a certain Field. Naturally, when the Field changes, it is desirable to change the Display Form. This can be achieved by making the Field a Trigger as illustrated by the following example.

Notice that the Trigger function is invoked both by assignments made within the Class (as in the assignment in ctor) and those made from outside the Instance.

:Class MyClass
    :Field Public Name
    :Field Public Country←'England'
    ∇ ctor nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ∇ format
      :Implements Trigger Name,Country
      ⎕DF'My name is ',Name,' and I live in ',Country
    ∇
:EndClass ⍝ MyClass

      me←⎕NEW MyClass 'Pete'
      me
My name is Pete and I live in England

      me.Country←'Greece'
      me
My name is Pete and I live in Greece

      me.Name←'Kostas'
      me
My name is Kostas and I live in Greece


Dynamic Functions & Operators

A Dynamic Function (operator) is an alternative function definition style suitable for defining small to medium sized functions. It bridges the gap between operator expressions: rank←⍴∘⍴ and full ‘header style’ definitions such as:

    ∇ rslt←larg func rarg;local...

In its simplest form, a dynamic function is an APL expression enclosed in curly braces {} possibly including the special characters ⍺ and ⍵ to represent the left and right arguments of the function respectively. For example:

      {(+/⍵)÷⍴⍵} 1 2 3 4    ⍝ Arithmetic Mean (Average)
2.5
      3 {⍵*÷⍺} 64           ⍝ ⍺th root
4

Dynamic functions can be named in the normal fashion:

      mean←{(+/⍵)÷⍴⍵}
      mean¨(2 3)(4 5)
 2.5  4.5

Dynamic Functions can be defined and used in any context where an APL function may be found, in particular:

  • In immediate execution mode as in the examples above.
  • Within a defined function or operator.
  • As the operand of an operator such as each (¨).
  • Within another dynamic function.
  • The last point means that it is easy to define nested local functions.


Multi-Line Dynamic Functions

The single expression which provides the result of the Dynamic Function may be preceded by any number of assignment statements. Each such statement introduces a name which is local to the function.

For example in the following, the expressions sum← and num← create local variables sum and num.

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          sum÷num     ⍝ Mean
      }

Note that Dynamic Functions may be commented in the usual way using ⍝.

When the interpreter encounters a local definition, a new local name is created. The name is shadowed dynamically exactly as if the assignment had been preceded by: ⎕shadow name ⋄.

It is important to note the distinction between the two types of statement above. There can be many assignment statements, each introducing a new local variable, but only a single expression where the result is not assigned. As soon as the interpreter encounters such an expression, it is evaluated and the result returned immediately as the result of the function.

For example, in the following,

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          sum,num     ⍝ Attempt to show sum,num (wrong)!
          sum÷num     ⍝ ... and return result.
      }

... as soon as the interpreter encounters the expression sum,num, the function terminates with the two element result (sum,num) and the following line is not evaluated.

To display arrays to the session from within a Dynamic function, you can use the explicit display forms ⎕← or ⍞← as in:

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          ⎕←sum,num   ⍝ show sum,num.
          sum÷num     ⍝ ... and return result.
      }

Note that local definitions can be used to specify local nested Dynamic Functions:

      rms←{                   ⍝ Root Mean Square
          root←{⍵*0.5}        ⍝ ∇ Square root
          mean←{(+/⍵)÷⍴⍵}     ⍝ ∇ Mean
          square←{⍵×⍵}        ⍝ ∇ Square
          root mean square ⍵
      }


Default Left Argument

The special syntax: ⍺←expr is used to give a default value to the left argument if a Dynamic Function is called monadically. For example:

      root←{      ⍝ ⍺th root
          ⍺←2     ⍝ default to sqrt
          ⍵*÷⍺
      }

The expression to the right of ⍺← is evaluated only if its Dynamic Function is called with no left argument.


Guards

A Guard is a Boolean-single valued expression followed on the right by a ':'. For example:

      0≡≡⍵:         ⍝ Right arg simple scalar
      ⍺<0:          ⍝ Left arg negative

The guard is followed by a single APL expression: the result of the function.

      ⍵≥0: ⍵*0.5    ⍝ Square root if non-negative.

A Dynamic function may contain any number of guarded expressions each on a separate line (or collected on the same line separated by diamonds). Guards are evaluated in turn until one of them yields a 1. The corresponding expression to the right of the guard is then evaluated as the result of the function.

If an expression occurs without a guard, it is evaluated immediately as the default result of the function. For example:

      sign←{
          ⍵>0: '+ve'      ⍝ Positive
          ⍵=0: 'zero'     ⍝ zero
               '-ve'      ⍝ Negative (Default)
      }

Local definitions and guards can be interleaved in any order.

Note again that any code following the first unguarded expression (which terminates the function) could never be executed and would therefore be redundant.

      log←{                   ⍝ Append ⍵ to file ⍺.
          tie←⍺ ⎕fstie 0      ⍝ tie number for file,
          cno←⍵ ⎕fappend tie  ⍝ new component number,
          tie←⎕funtie tie     ⍝ untie file,
          1:rslt←cno          ⍝ comp number as shy result.
      }


Shy Result

Dynamic Functions are usually 'pure' functions that take arguments and return explicit results. Occasionally, however, the main purpose of the function might be a side-effect such as the display of information in the session, or the updating of a file, and the value of a result, a secondary consideration. In such circumstances, you might want to make the result 'shy', so that it is discarded unless the calling context requires it. This can be achieved by assigning a dummy variable after a (true) guard:

      log←{                   ⍝ Append ⍵ to file ⍺.
          tie←⍺ ⎕fstie 0      ⍝ tie number for file,
          cno←⍵ ⎕fappend tie  ⍝ new component number,
          tie←⎕funtie tie     ⍝ untie file,
          1:rslt←cno          ⍝ comp number as shy result.
      }


Static Name Scope

When an inner (nested) Dynamic Function refers to a name, the interpreter searches for it by looking outwards through enclosing Dynamic Functions, rather than searching back along the execution stack. This regime, which is more appropriate for nested functions, is said to employ static scope instead of APL’s usual dynamic scope. This distinction becomes apparent only if a call is made to a function defined at an outer level. For the more usual inward calls, the two systems are indistinguishable.

For example, in the following function, variable type is defined both within which itself and within the inner function fn1. When fn1 calls outward to fn2 and fn2 refers to type, it finds the outer one (with value 'static') rather than the one defined in fn1:

      which←{

          type←'static'

          fn1←{
              type←'dynamic'
              fn2 ⍵
          }

          fn2←{
              type ⍵
          }

          fn1 ⍵
      }

      which'scope'
 static  scope


Tail Calls

A novel feature of the implementation of Dynamic Functions is the way in which tail calls are optimised.

When a Dynamic Function calls a sub-function, the result of the call may or may not be modified by the calling function before being returned. A call where the result is passed back immediately without modification is termed a tail call.

For example in the following, the first call on function fact is a tail call because the result of fact is the result of the whole expression, whereas the second call isn’t because the result is subsequently multiplied by ⍵.

      (⍺×⍵)fact ⍵-1       ⍝ Tail call on fact.
      ⍵×fact ⍵-1          ⍝ Embedded call on fact.

Tail calls occur frequently in Dynamic Functions, and the interpreter optimises them by re-using the current stack frame instead of creating a new one. This gives a significant saving in both time and workspace usage. It is easy to check whether a call is a tail call by tracing it. An embedded call will pop up a new trace window for the called function, whereas a tail call will re-use the current one.

Using tail calls can improve code performance considerably, although at first the technique might appear obscure. A simple way to think of a tail call is as a branch with arguments. The tail call, in effect, branches to the first line of the function after installing new values for ⍵ and ⍺.

Iterative algorithms can almost always be coded using tail calls.

In general, when coding a loop, we use the following steps; possibly in a different order depending on whether we want to test at the ‘top’ or the ‘bottom’ of the loop.

  1. Initialise loop control variable(s).⍝ init
  2. Test loop control variable.⍝ test
  3. Process body of loop.⍝ proc
  4. Modify loop control variable for next iteration.⍝ mod
  5. Branch to step 2.⍝ jump

For example, in classical APL you might find the following:

        ∇ value←limit loop value⍝ init
    [1]  top:→(⎕CT>value-limit)/0⍝ test
    [2]   value←Next value⍝ proc, mod
    [3]   →top⍝ jump
        ∇

Control structures help us to package these steps:

        ∇ value←limit loop value⍝ init
    [1]   :While ⎕CT<value-limit⍝ test
    [2]       value←Next value⍝ proc, mod
    [3]   :EndWhile⍝ jump
        ∇

Using tail calls:

    loop←{⍝ init
        ⎕CT>⍺-⍵:⍵⍝ test
        ⍺ ∇ Next ⍵⍝ proc, mod, jump
    }


Error-Guards

An error-guard is (an expression that evaluates to) a vector of error numbers, followed by the digraph: ::, followed by an expression, the body of the guard, to be evaluated as the result of the function. For example:

      11 5 :: ⍵×0 ⍝ Trap DOMAIN and LENGTH errors.

In common with :Trap and ⎕TRAP, error numbers 0 and 1000 are catchalls for synchronous errors and interrupts respectively.

When an error is generated, the system searches statically upwards and outwards for an error-guard that matches the error. If one is found, the execution environment is unwound to its state immediately prior to the error-guard’s execution and the body of the error-guard is evaluated as the result of the function. This means that, during evaluation of the body, the guard is no longer in effect and so the danger of a hang caused by an infinite ‘trap loop’, is avoided.

Notice that you can provide ‘cascading’ error trapping in the following way:

0::try_2nd
0::try_1st
   expr

In this case, if expr generates an error, its immediately preceding: 0:: catches it and evaluates try_1st leaving the remaining error-guard in scope. If try_1st fails, the environment is unwound once again and try_2nd is evaluated, this time with no error-guards in scope.

Examples:

Open returns a handle for a component file. If the exclusive tie fails, it attempts a share-tie and if this fails, it creates a new file. Finally, if all else fails, a handle of 0 is returned.

open←{                 ⍝ Handle for component file ⍵.
    0::0               ⍝ Fails:: return 0 handle.
    22::⍵ ⎕FCREATE 0   ⍝ FILE NAME:: create new one.
    24 25::⍵ ⎕FSTIE 0  ⍝ FILE TIED:: try share tie.
           ⍵ ⎕FTIE 0   ⍝ Attempt to open file.
}

An error in div causes it to be called recursively with improved arguments.

div←{                  ⍝ Tolerant division:: ⍺÷0 → ⍺.
    ⍺←1                ⍝ default numerator.
    5::↑∇/↓↑⍺ ⍵        ⍝ LENGTH:: stretch to fit.
    11::⍺ ∇ ⍵+⍵=0      ⍝ DOMAIN:: increase divisor.
    ⍺÷⍵                ⍝ attempt division.
}

Notice that some arguments may cause div to recur twice:

       6 4 2 div 3 2
→      6 4 2 div 3 2 0
→      6 4 2 div 3 2 1
→      2 2 2

The final example shows the unwinding of the local environment before the error-guard’s body is evaluated. Local name trap is set to describe the domain of its following error-guard. When an error occurs, the environment is unwound to expose trap’s statically correct value.

      add←{
          trap←'domain' ⋄ 11::trap
          trap←'length' ⋄  5::trap
          ⍺+⍵
      }

      2 add 3         ⍝ Addition succeeds
5

      2 add 'three'   ⍝ DOMAIN ERROR generated.
domain

      2 3 add 4 5 6   ⍝ LENGTH ERROR generated.
length


Dynamic Operators

The operator equivalent of a dynamic function is distinguished by the presence of either of the compound symbols ⍺⍺ or ⍵⍵ anywhere in its definition. ⍺⍺ and ⍵⍵ represent the left and right operand of the operator respectively.

Example

The following monadic each operator applies its function operand only to unique elements of its argument. It then distributes the result to match the original argument. This can deliver a performance improvement over the primitive each (¨) operator if the operand function is costly and the argument contains a significant number of duplicate elements. Note however, that if the operand function causes side effects, the operation of dynamic and primitive versions will be different.

      each←{              ⍝ Fast each:
          shp←⍴⍵          ⍝ Shape and ...
          vec←,⍵          ⍝ ... ravel of arg.
          nub←∪vec        ⍝ Vector of unique elements.
          res←⍺⍺¨nub      ⍝ Result for unique elts.
          idx←nub⍳vec     ⍝ Indices of arg in nub ...
          shp⍴idx⊃¨⊂res   ⍝ ... distribute result.
      }

The dyadic else operator applies its left (else right) operand to its right argument depending on its left argument.

      else←{
          ⍺: ⍺⍺ ⍵     ⍝ True: apply Left operand
             ⍵⍵ ⍵     ⍝ Else,  ..   Right   ..
      }
      0 1 ⌈else⌊¨ 2.5     ⍝ Try both false and true.
2 3


Restrictions

Currently multi-line Dynamic Functions can’t be typed directly into the session. The interpreter attempts to evaluate the first line with its trailing left brace and a SYNTAX ERROR results.

Dynamic Functions need not return a result. However even a non-result-returning expression will terminate the function, so you can’t, for example, call a non-result-returning function from the middle of a Dynamic Function.

You can trace a Dynamic Function only if it is defined on more than one line. Otherwise it is executed atomically in the same way as an execute (⍎) expression. This deliberate restriction is intended to avoid the confusion caused by tracing a line and seeing nothing change on the screen.

Dynamic Functions do not currently support ⎕CS.

Supplied Workspaces

You can find more examples of dynamic functions and operators in workspaces in the samples\dfns directory.

DFNS.DWS - a selection of utility functions.

MIN.DWS - an example application.


Overview

Dyalog APL supports multithreading - the ability to run more than one APL expression at the same time.

This unique capability allows you to perform background processing, such as printing, database retrieval, database update, calculations, and so forth while at the same time perform other interactive tasks.

Multithreading may be used to improve throughput and system responsiveness.

A thread is a strand of execution in the APL workspace.

A thread is created by calling a function asynchronously, using the new primitive operator ‘spawn’: & or by the asynchronous invocation of a callback function.

With a traditional APL synchronous function call, execution of the calling environment is paused, pendent on the return of the called function. With an asynchronous call, both calling environment and called function proceed to execute concurrently.

An asynchronous function call is said to start a new thread of execution. Each thread has a unique thread number, with which, for example, its presence can be monitored or its execution terminated.

Any thread can spawn any number of sub-threads, subject only to workspace availability. This implies a hierarchy in which a thread is said to be a child thread of its parent thread. The base thread at the root of this hierarchy has thread number 0.

With multithreading, APL’s stack or state indicator can be viewed as a branching tree in which the path from the base to each leaf is a thread.

When a parent thread terminates, any of its children which are still running, become the children of (are ‘adopted’ by) the parent’s parent.

Thread numbers are allocated sequentially from 0 to 2147483647. At this point, the sequence ‘wraps around’ and numbers are allocated from 0 again avoiding any still in use. The sequence is reinitialised when a )RESET command is issued, or the active workspace is cleared, or a new workspace is loaded. A workspace may not be saved with threads other than the base thread: 0, running.


Multi-Threading language elements.

The following language elements are provided to support threads.

  • Primitive operator, spawn: &.
  • System functions: ⎕TID, ⎕TCNUMS, ⎕TNUMS, ⎕TKILL, ⎕TSYNC.
  • An extension to the GUI Event syntax to allow asynchronous callbacks.
  • A control structure: :Hold.
  • System commands: )HOLDS, )TID.
  • Extended )SI and )SINL display.

Running CallBack Functions as Threads

A callback function is associated with a particular event via the Event property of the object concerned. A callback function is executed by ⎕DQ when the event occurs, or by ⎕NQ.

If you append the character & to the name of the callback function in the Event specification, the callback function will be executed asynchronously as a thread when the event occurs. If not, it is executed synchronously as before.

For example, the event specification:

      ⎕WS'Event' 'Select' 'DoIt&'

tells ⎕DQ to execute the callback function DoIt asynchronously as a thread when a Select event occurs on the object.


Thread Switching

Programming with threads requires care.

The interpreter may switch between running threads at the following points:

  • Between any two lines of a defined (or dynamic) function or operator.
  • While waiting for a ⎕DL to complete.
  • While waiting for a ⎕FHOLD to complete.
  • While awaiting input from:
    • ⎕DQ
    • ⎕SR
    • ⎕ED
  • The session prompt or ⎕: or ⍞.
  • While awaiting the completion of an external operation:
    • A call on an external (AP) function.
    • A call on a ⎕NA (DLL) function
    • A call on an OLE function.
    • A call on a .Net function.

At any of these points, the interpreter might execute code in other threads. If such threads change the global environment; for example by changing the value of, or expunging a name; then the changes will appear to have happened while the thread in question passes through the switch point. It is the task of the application programmer to organise and contain such behaviour!

You can prevent threads from interacting in critical sections of code by using the :Hold control structure.

High Priority Callback Functions

Note that the interpreter cannot perform thread-switching during the execution of a high-priority callback. This is a callback function that is invoked by a high-priority event which demands that the interpreter must return a result to Windows before it may process any other event. Such high-priority events include Configure, ExitWindows, DateTimeChange, DockStart, DockCancel, DropDown. It is therefore not permitted to use a :Hold control structure in a high-priority callback function.


Name Scope

APL’s name scope rules apply whether a function call is synchronous or asynchronous. For example when a defined function is called, names in the calling environment are visible, unless explicitly shadowed in the function header.

Just as with a synchronous call, a function called asynchronously has its own local environment, but can communicate with its parent and ‘sibling’ functions via local names in the parent.

This point is important. It means that siblings can run in parallel without danger of local name clashes. For example, a GUI application can accommodate multiple concurrent instances of its callback functions.

However, with an asynchronous call, as the calling function continues to execute, both child and parent functions may modify values in the calling environment. Both functions see such changes immediately they occur.

If a parent function terminates while any of its children are still running, those children will thenceforward ‘see’ local names in the environment that called the parent function. In cases where a child function relies on its parent’s environment (the setting of a local value of ⎕IO for example), this would be undesirable, and the parent function would normally execute a ⎕TSYNC in order to wait for its children to complete before itself exiting.

If, on the other hand, after launching an asynchronous child, the parent function calls a new function (either synchronously or asynchronously); names in the new function are beyond the purview of the original child. In other words, a function can only ever see its calling stack decrease in size – never increase. This is in order that the parent may call new defined functions without affecting the environment of its asynchronous children.


Using Threads

Put most simply, multithreading allows you to appear to run more than one APL function at the same time, just as Windows (or UNIX) appears to run more than one application at the same time. In both cases this is something of an illusion, although it does nothing to detract from its usefulness.

Dyalog APL implements an internal timesharing mechanism whereby it shares processing between threads. Although the mechanics are somewhat different, APL multithreading is rather similar to the multitasking provided by Windows. If you are running more than one application, Windows switches from one to another, allocating each one a certain time slice before switching. At any point in time, only one application is actually running; the others are paused, waiting.

If you execute more than one Dyalog APL thread, only one thread is actually running; the others are paused. Each APL thread has its own State Indicator, or SI stack. When APL switches from one thread to another, it saves the current stack (with all its local variables and function calls), restores the new one, and then continues processing.


Stack Considerations

When you start a thread, it begins with the SI stack of the calling function and sees all of the local variables defined in all the functions down the stack. However, unless the calling function specifically waits for the new thread to terminate (see Wait for Threads to Terminate: ), the calling functions will (bit by bit, in their turn) continue to execute. The new thread’s view of its calling environment may then change. Consider the following example:

Suppose that you had the following functions: RUN[3] calls INIT which in turn calls GETDATA but as 3 separate threads with 3 different arguments:

     ∇ RUN;A;B
[1]    A←1
[2]    B←'Hello World'
[3]    INIT
[4]    CALC
[5]    REPORT
     ∇

     ∇ INIT;C;D
[1]    C←D←0
[2]    GETDATA&'Sales'
[3]    GETDATA&'Costs'
[4]    GETDATA&'Expenses'
     ∇

When each GETDATA thread starts, it immediately sees (via ⎕SI) that it was called by INIT which was in turn called by RUN, and it sees local variables A, B, C and D. However, once INIT[4] has been executed, INIT terminates, and execution of the root thread continues by calling CALC. From then on, each GETDATA thread no longer sees INIT (it thinks that it was called directly from RUN) nor can it see the local variables C and D that INIT had defined. However, it does continue to see the locals A and B defined by RUN, until RUN itself terminates.

Note that if CALC were also to define locals A and B, the GETDATA threads would still see the values defined by RUN and not those defined by CALC. However, if CALC were to modify A and B (as globals) without localising them, the GETDATA threads would see the modified values of these variables, whatever they happened to be at the time.


Globals and the Order of Execution

It is important to recognise that any reference or assignment to a global or semi-global object (including GUI objects) is inherently dangerous (i.e. a source of programming error) if more than one thread is running. Worse still, programming errors of this sort may not become apparent during testing because they are dependent upon random timing differences. Consider the following example:

     ∇ BUG;SEMI_GLOBAL
[1]    SEMI_GLOBAL←0
[2]    FOO& 1
[3]    GOO& 1
     ∇

     ∇ FOO
[1]    :If SEMI_GLOBAL=0
[2]        DO_SOMETHING SEMI_GLOBAL
[3]    :Else
[4]        DO_SOMETHING_ELSE SEMI_GLOBAL
[5]    :EndIf
     ∇

     ∇ GOO
[1]    SEMI_GLOBAL←1
     ∇

In this example, it is formally impossible to predict in which order APL will execute statements in BUG, FOO or GOO from BUG[2] onwards. For example, the actual sequence of execution may be:

      BUG[1] → BUG[2] → FOO[1] → FOO[2] →
               DO_SOMETHING[1]

or

      BUG[1] → BUG[2] → BUG[3] → GOO[1] →
               FOO[1] → FOO[2] → FOO[3] →
               FOO[4] → DO_SOMETHING_ELSE[1]

This is because APL may switch from one thread to another between any two lines in a defined function. In practice, because APL gives each thread a significant time-slice, it is likely to execute many lines, maybe even hundreds of lines, in one thread before switching to another. However, you must not rely on this; thread-switching may occur at any time between lines in a defined function.

Secondly, consider the possibility that APL switches from the FOO thread to the GOO thread after FOO[1]. If this happens, the value of SEMI_GLOBAL passed to DO_SOMETHING will be 1 and not 0. Here is another source of error.

In fact, in this case, there are two ways to resolve the problem. To ensure that the value of SEMI_GLOBAL remains the same from FOO[1] to FOO[2], you may use diamonds instead of separate statements, e.g.

      :If SEMI_GLOBAL=0 ⋄ DO_SOMETHING SEMI_GLOBAL

Even better, although less efficient, you may use :Hold to synchronise access to the variable, for example:

      ∇ FOO
[1]    :Hold 'SEMI_GLOBAL'
[2]        :If SEMI_GLOBAL=0
[3]            DO_SOMETHING SEMI_GLOBAL
[4]        :Else
[5]            DO_SOMETHING_ELSE SEMI_GLOBAL
[6]        :EndIf
[7]    :EndHold
     ∇

     ∇ GOO
[1]    :Hold 'SEMI_GLOBAL'
[2]        SEMI_GLOBAL←1
[3]    :EndHold
     ∇

Now, although you still cannot be sure which of FOO and GOO will run first, you can be sure that SEMI_GLOBAL will not change (because GOO cuts in) within FOO.

Note that the string used as the argument to :Hold is completely arbitrary, so long as threads competing for the same resource use the same string.

A Caution

These types of problems are inherent in all multithreading programming languages, and not just with Dyalog APL. If you want to take advantage of the additional power provided by multithreading, it is advisable to think carefully about the potential interaction between different threads.


Threads & Niladic Functions

  • In common with other operators, the spawn operator & may accept monadic or dyadic functions as operands, but not niladic functions. This means that, using spawn, you cannot start a thread that consists only of a niladic function
  • If you wish to invoke a niladic function asynchronously, you have the following choices:
  • Turn your niladic function into a monadic function by giving it a dummy argument which it ignores.
  • Call your niladic function with a dynamic function to which you give an argument that is implicitly ignored. For example, if the function NIL is niladic, you can call it asynchronously using the expression: {NIL}& 0
  • Call your function via a dummy monadic function, e.g.
         ∇ NIL_M DUMMY
[1]    NIL
     ∇
     NIL_M& ''

  • Use execute, e.g.
    ⍎& 'NIL'

Note that niladic functions can be invoked asynchronously as callback functions. For example, the statement:

      ⎕WS'Event' 'Select' 'NIL&'

will execute correctly as a thread, even though NIL is niladic. This is because callback functions are invoked directly by ⎕DQ rather than as an operand to the spawn operator.


Threads & External Functions

External functions in dynamic link libraries (DLLs) defined using the ⎕NA interface may be run in separate C threads. Such threads:

  • take advantage of multiple processors if the operating system permits.
  • allow APL to continue processing in parallel during the execution of a ⎕NA function.

When you define an external function using ⎕NA, you may specify that the function be run in a separate C thread by appending an ampersand (&) to the function name, for example:

      'beep'⎕NA'user32|MessageBeep& i'
      ⍝ MessageBeep will run in a separate C thread

When APL first comes to execute a multi-threaded ⎕NA function, it starts a new C-thread, executes the function within it, and waits for the result. Other APL threads may then run in parallel.

Note that when the ⎕NA call finishes and returns its result, its new C-thread is retained to be re-used by any subsequent multithreaded ⎕NA calls made within the same APL thread. Thus any APL thread that makes any multi-threaded ⎕NA calls maintains a separate C-thread for their execution. This C-thread is discarded when its APL thread finishes.

Note that there is no point in specifying a ⎕NA call to be multi-threaded, unless you wish to execute other APL threads at the same time.

In addition, if your ⎕NA call needs to access an APL GUI object (strictly, a window or other handle) it should normally run within the same C-thread as APL itself, and not in a separate C-thread. This is because Windows associates objects with the C-thread that created them. Although you can use a multi-threaded ⎕NA call to access (say) a Dyalog APL Form via its window handle, the effects may be different than if the ⎕NA call was not multi-threaded. In general, ⎕NA calls that access APL (GUI) objects should not be multi-threaded.

If you wish to run the same ⎕NA call in separate APL threads at the same time, you must ensure that the DLL is thread-safe. Functions in DLLs which are not thread-safe, must be prevented from running concurrently by using the :Hold control structure. Note that all the standard Windows API DLLs are thread safe.

Notice that you may define two separate functions (with different names), one single-threaded and one multi-threaded, associated with the same function in the DLL. This allows you to call it in either way.


Synchronising Threads

Threads may be synchronised using tokens and a token pool.

An application can synchronise its threads by having one thread add tokens into the pool whilst other threads wait for tokens to become available and retrieve them from the pool.

Tokens possess two separate attributes, a type and a value.

The type of a token is a positive or negative integer scalar. The value of a token is any arbitrary array that you might wish to associate with it.

The token pool may contain up to 2*31 tokens; they do not have to be unique neither in terms of their types nor of their values.

The following system functions are used to manage the token pool:

⎕TPUT | Puts tokens into the pool.
⎕TGET | If necessary waits for, and then retrieves some tokens from the pool.
⎕TPOOL | Reports the types of tokens in the pool
⎕TREQ | Reports the token requests from specific threads

A simple example of a thread synchronisation requirement occurs when you want one thread to reach a certain point in processing before a second thread can continue. Perhaps the first thread performs a calculation, and the second thread must wait until the result is available before it can be used.

This can be achieved by having the first thread put a specific type of token into the pool using ⎕TPUT. The second thread waits (if necessary) for the new value to be available by calling ⎕TGET with the same token type.

Notice that when ⎕TGET returns, the specified tokens are removed from the pool. However, negative token types will satisfy an infinite number of requests for their positive equivalents.

The system is designed to cater for more complex forms of synchronisation. For example, a semaphore to control a number of resources can be implemented by keeping that number of tokens in the pool. Each thread will take a token while processing, and return it to the pool when it has finished.

A second complex example is that of a latch which holds back a number of threads until the coast is clear. At a signal from another thread, the latch is opened so that all of the threads are released. The latch may (or may not) then be closed again to hold up subsequently arriving threads. A practical example of a latch is a ferry terminal.


Semaphore Example

A semaphore to control a number of resources can be implemented by keeping that number of tokens in the pool. Each thread will take a token while processing, and return it to the pool when it has finished.

For example, if we want to restrict the number of threads that can have sockets open at any one time.

    sock←99                  ⍝ socket-token
                               any +ive number will do).
    ⎕TPUT 5/sock             ⍝ add 5 socket-tokens to pool.

    ∇ sock_open ...
[1]   :If sock=⎕TGET sock    ⍝ grap a socket token
[.]       ...                ⍝ do stuff.
[.]       ⎕TPUT sock         ⍝ release socket token
[.]   :Else
[.]       error'sockets off' ⍝ sockets switched off by
                               retract (see below).
[.]   :EndIf
    ∇

    0 ⎕TPUT ⎕treq ⎕tnums     ⍝ retract socket "service"
                               with 0 value.


Latch Example

A latch holds back a number of threads until the coast is clear. At a signal from another thread, the latch is opened so that all of the threads are released. The latch may (or may not) then be closed again to hold up subsequently arriving threads.

A visual example of a latch might be a ferry terminal, where cars accumulate in the queue until the ferry arrives. The barrier is then opened and all (up to a maximum number) of the cars are allowed through it and on to the ferry. When the last car is through, the barrier is re-closed.

    tkt←6                         ⍝ 6-token: ferry ticket.

    ∇ car ...
[1]   ⎕TGET tkt                   ⍝ await ferry.
[2]   ...

    ∇ ferry ...
[1]   arrives in port
[2]   ⎕TPUT(↑,/⎕treq ⎕tnums)∩tkt  ⍝ ferry tickets for all.
[3]   ...

Note that it is easy to modify this example to provide a maximum number of ferry places per trip by inserting max_places↑ between ⎕TPUT and its argument. If fewer cars than the ferry capacity are waiting, the ↑ will fill with trailing 0s. This will not cause problems because zero tokens are ignored.

Let us replace the car ferry with a new road bridge. Once the bridge is ready for traffic, the barrier could be opened permanently by putting a negative ticket in the pool.

    ⎕TPUT -tkt      ⍝ open ferry barrier permananently.

Cars could choose to take the last ferry if there are places:

    ∇ car ...
[1]   :Select ⎕TGET tkt
[2]   :Case  tkt ⋄ take the last ferry.
[3]   :Case -tkt ⋄ ferry full: take the new bridge.
[4]   :End

The above :Select works because by default, ⎕TPUT -tkt puts a value of -tkt into the token.


Debugging Threads

If a thread sustains an untrapped error, its execution is suspended in the normal way. If the Pause on Error option (see User Guide) is set, all other threads are paused. If Pause on Error option (see User Guide) is not set, other threads will continue running and it is possible for another thread to encounter an error and suspend.

Using the facilities provided by the Tracer and the Threads Tool (see User Guide) it is possible to interrupt (suspend) and restart individual threads, and to pause and resume individual threads, so any thread may be in one of three states - running, suspended or paused.

The Tracer and the Session may be connected with any suspended thread and you can switch the attention of the Session and the Tracer between suspended threads using )TID or by clicking on the appropriate tab in the Tracer. At this point, you may:

  • Examine and modify local variables for the currently suspended thread.
  • Trace and edit functions in the current thread.
  • Cut back the stack in the currently suspended thread.
  • Restart execution.
  • Start new threads

The error message from a thread other than the base is prefixed with its thread number:

260:DOMAIN ERROR
Div[2] rslt←num÷div
      ^

State indicator displays: )SI and )SINL have been extended to show threads’ tree-like calling structure.

      )SI
·   #.Calc[1]
&5
·   ·   #.DivSub[1]
·   &7
·   ·   #.DivSub[1]
·   &6
·   #.Div[2]*
&4
#.Sub[3]
#.Main[4]

Here, Main has called Sub, which has spawned threads 4 and 5 with functions: Div and Calc. Function Div, after spawning DivSub in each of threads 6 and 7, have been suspended at line [2].

Removing stack frames using Quit from the Tracer or → from the session affects only the current thread. When the final stack frame in a thread (other than the base thread) is removed, the thread is expunged.

)RESET removes all but the base thread.

Note the distinction between a suspended thread and a paused thread.

A suspended thread is stopped at the beginning of a line in a defined function or operator. It may be connected to the Session so that expressions executed in the Session do so in the context of that thread. It may be restarted by executing →line (typically, →⎕LC).

A paused thread is an inactive thread that is currently being ignored by the thread scheduler. A paused thread may be paused within a call to ⎕DQ, a call on an external function, at the beginning of a line, or indeed at any of the thread-switching points described earlier in this chapter.

A paused thread may be resumed only by the action of a menu item or button. A paused thread resumes only in the sense that it ceases to be ignored by the thread scheduler and will therefore be switched back to at some point in the future. It does not actually continue executing until the switch occurs.


Introducing Classes

A Class is a blueprint from which one or more Instances of the Class can be created (instances are sometimes also referred to as Objects).

A Class may optionally derive from another Class, which is referred to as its Base Class.

A Class may contain Methods, Properties and Fields (commonly referred to together as Members) which are defined within the body of the class script or are inherited from other Classes. This version of Dyalog APL does not support Events although it is intended that these will be supported in a future release. However, Classes that are derived from .Net types may generate events using 4 ⎕NQ.

A Class that is defined to derive from another Class automatically acquires the set of Properties, Methods and Fields that are defined by its Base Class. This mechanism is described as inheritance.

A Class may extend the functionality of its Base Class by adding new Properties, Methods and Fields or by substituting those in the Base Class by providing new versions with the same names as those in the Base Class.

Members may be defined to be Private or Public. A Public member may be used or accessed from outside the Class or an Instance of the Class. A Private member is internal to the Class and (in general) may not be referenced from outside.

Although Classes are generally used as blueprints for the creation of instances, a class can have Shared members which can be used without first creating an instance


Defining Classes

A Class is defined by a script that may be entered and changed using the editor. A class script may also be constructed from a vector of character vectors, and fixed using ⎕FIX.

A class script begins with a :Class statement and ends with a :EndClass statement.

For example, using the editor:

      )CLEAR
clear ws
      )ED ○Animal

[an edit window opens containing the following skeleton Class script ...]

:Class Animal
:EndClass

[the user edits and fixes the Class script]

      )CLASSES
Animal
      ⎕NC⊂'Animal'
9.4


Editing Classes

Between the :Class and :EndClass statements, you may insert any number of function bodies, Property definitions, and other elements. When you fix the Class Script from the editor, these items will be fixed inside the Class namespace.

Note that the contents of the Class Script defines the Class in its entirety. You may not add or alter functions by editing them independently and you may not add variables by assignment or remove objects with ⎕EX.

When you re-fix a Class Script using the Editor or with ⎕FIX, the original Class is discarded and the new definition, as specified by the Script, replaces the old one in its entirety.

Note:

Associated with a Class (or an instance of a class) there is a completely separate namespace which surrounds the class and can contain functions, variables and so forth that are created by actions external to the class.

For example, if X is not a public member of the class MyClass, then the following expression will insert a variable X into the namespace which surrounds the class:

      MyClass.X←99

The namespace is analogous to the namespace associated with a GUI object and will be re-initialised (emptied) whenever the Class is re-fixed. Objects in this parallel namespace are not visible from inside the Class or an Instance of the Class.


Inheritance

If you want a Class to derive from another Class, you simply add the name of that Class to the :Class statement using colon+space as a separator.

The following example specifies that CLASS2 derives from CLASS1.

:Class CLASS2: CLASS1
:EndClass

Note that CLASS1 is referred to as the Base Class of CLASS2.

If a Class has a Base Class, it automatically acquires all of the Public Properties, Methods and Fields defined for its Base Class unless it replaces them with its own members of the same name. This principle of inheritance applies throughout the Class hierarchy. Note that Private members are not subject to inheritance.

Warning: When a class is fixed, it keeps a reference (a pointer) to its base class. If the global name of the base class is expunged, the derived class will still have the base class reference, and the base class will therefore be kept alive in the workspace. The derived class will be fully functional, but attempts to edit it will fail when it attempts to locate the base class as the new definition is fixed.

At this point, if a new class with the original base class name is created, the derived class has no way of detecting this, and it will continue to use the old and invisible version of the base class. Only when the derived class is re-fixed, will the new base class be detected.

If you edit, re-fix or copy an existing base class, APL will take care to patch up the references, but if the base class is expunged first and recreated later, APL is unable to detect the substitution. You can recover from this situation by editing or re-fixing the derived class(es) after the base class has been substituted.

Classes that derive from .Net Types

You may define a Class that derives from any of the .Net Types by specifying the name of the .Net Type and including a :USING statement that provides a path to the .Net Assembly in which the .Net Type is located.

Example

:Class APLGreg: GregorianCalendar
:Using System.Globalization
...
:EndClass

Classes that derive from the Dyalog GUI

You may define a Class that derives from any of the Dyalog APL GUI objects by specifying the name of the Dyalog APL GUI Class in quotes.

For example, to define a Class named Duck that derives from a Poly object, the Class specification would be:

:Class Duck:'Poly'
:EndClass

The Base Constructor for such a Class is the ⎕WC system function.

For further details see Dyalog GUI Classes.


Instances

A Class is generally used as a blueprint or model from which one or more Instances of the Class are constructed. Note however that a class can have Shared members which can be used directly without first creating an instance.

You create an instance of a Class using the ⎕NEW system function which is monadic.

The 1-or 2-item argument to ⎕NEW contains a reference to the Class and, optionally, arguments for its Constructor function.

When ⎕NEW executes, it creates a regular APL namespace to contain the Instance, and within that it creates an Instance space, which is populated with any Instance Fields defined by the class (with default values if specified), and pointers to the Instance Method and Property definitions specified by the Class.

If a monadic Constructor is defined, it is called with the arguments specified in the second item of the argument to ⎕NEW. If ⎕NEW was called without Constructor arguments, and the class has a niladic Constructor, this is called instead.

The Constructor function is typically used to initialise the instance and may establish variables in the instance namespace.

The result of ⎕NEW is a reference to the instance namespace. Instances of Classes exhibit the same set of Properties, Methods and Fields that are defined for the Class.


Constructors

A Constructor is a special function defined in the Class script that is to be run when an Instance of the Class is created by ⎕NEW. Typically, the job of a Constructor is to initialise the new Instance in some way.

A Constructor is identified by a :Implements Constructor statement. This statement may appear anywhere in the body of the function after the function header. The significance of this is discussed below.

Note that it is also essential to define the Constructor to be Public, with a :Access Public statement, because like all Class members, Constructors default to being Private. Private Constructors currently have no use or purpose, but it is intended that they will be supported in a future release of Dyalog APL.

A Constructor function may be niladic or monadic and must not return a result.

A Class may specify any number of different Constructors of which one (and only one) may be niladic. This is also referred to as the default Constructor.

There may be any number of monadic Constructors, but each must have a differently defined argument list which specifies the number of items expected in the Constructor argument. See Constructor Overloading for details.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class. The only way a Constructor function may be invoked is by ⎕NEW. See Base Constructors for further details.

When ⎕NEW is executed with a 2-item argument, the appropriate monadic Constructor is called with the second item of the ⎕NEW argument.

The niladic (default) Constructor is called when ⎕NEW is executed with a 1-item argument, a Class reference alone, or whenever APL needs to create a fill item for the Class.

Note that ⎕NEW first creates a new instance of the specified Class, and then executes the Constructor inside the instance.

Example

The DomesticParrot Class defines a Constructor function egg that initialises the Instance by storing its name (supplied as the 2nd item of the argument to ⎕NEW) in a Public Field called Name.

:Class DomesticParrot:Parrot
    :Field Public Name

    ∇ egg name
      :Implements Constructor
      :Access Public
      Name←name
    ∇
    ...
:EndClass ⍝ DomesticParrot

      pol←⎕NEW DomesticParrot 'Polly'
      pol.Name
Polly


Constructor Overloading

NameList header syntax is used to define different versions of a Constructor each with a different number of parameters, referred to as its signature. SeeNamelists for details. The Clover Class illustrates this principle.

In deciding which Constructor to call, APL matches the shape of the Constructor argument with the signature of each of the Constructors that are defined. If a constructor with the same number of arguments exists (remembering that 0 arguments will match a niladic Constructor), it is called. If there is no exact match, and there is a Constructor with a general signature (an un-parenthesised right argument), it is called. If no suitable constructor is found, a LENGTH ERROR is reported.

There may be one and only one constructor with a particular signature.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class. The only way a Constructor function may be invoked is by ⎕NEW. See Base Constructors for further details.

In the Clover Class example Class, the following Constructors are defined:

Constructor | Implied argument
Make1 | 1-item vector
Make2 | 2-item vector
Make3 | 3-item vector
Make0 | No argument
MakeAny | Any array accepted

In the following examples, the Make function (see Clover Class for details) displays:

<shape of argument> <name of Constructor called><argument>
(see function make)

Creating a new Instance of Clover with a 1-element vector as the Constructor argument, causes the system to choose the Make1 Constructor. Note that, although the argument to Make1 is a 1-element vector, this is disclosed as the list of arguments is unpacked into the (single) variable arg1.

      (⎕NEW Clover(,1)).Con
   Make1  1

Creating a new Instance of Clover with a 2- or 3-element vector as the Constructor argument causes the system to choose Make2, or Make3 respectively.

      (⎕NEW Clover(1 2)).Con
 2  Make2  1 2
      (⎕NEW Clover(1 2 3)).Con
 3  Make3  1 2 3

Creating an Instance with any other Constructor argument causes the system to choose MakeAny.

      (⎕NEW Clover(⍳10)).Con
 10  MakeAny  1 2 3 4 5 6 7 8 9 10
      (⎕NEW Clover(2 2⍴⍳4)).Con
 2 2  MakeAny  1 2
               3 4

Note that a scalar argument will call MakeAny and not Make1.

      (⎕NEW Clover 1).Con
   MakeAny  1

and finally, creating an Instance without a Constructor argument causes the system to choose Make0.

      (⎕NEW Clover).Con
   Make0  0


Niladic (Default) Constructors

A Class may define a niladic Constructor and/or one or more Monadic Constructors. The niladic Constructor acts as the default Constructor that is used when ⎕NEW is invoked without arguments and when APL needs a fill item.

:Class Bird
    :Field Public Species

    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      Species←spec
    ∇
    ∇ default
      :Access Public Instance
      :Implements Constructor
      Species←'Default Bird'
    ∇
    ∇ R←Speak
      :Access Public
      R←'Tweet, tweet!'
    ∇

:EndClass ⍝ Bird

The niladic Constructor (in this example, the function default) is invoked when ⎕NEW is called without Constructor arguments. In this case, the Instance created is no different to one created by the monadic Constructor egg, except that the value of the Species Field is set to 'Default Bird'.

      Birdy←⎕NEW Bird
      Birdy.Species
Default Bird

The niladic Constructor is also used when APL needs to make a fill item of the Class. For example, in the expression (3↑Birdy), APL has to create two fill items of Birdy (one for each of the elements required to pad the array to length 3) and will in fact call the niladic Constructor twice.

In the following statement:

      TweetyPie←3⊃10↑Birdy

The 10↑ (temporarily) creates a 10-element array comprising the single entity Birdy padded with 9 fill-elements of Class Bird. To obtain the 9 fill-elements, APL calls the niladic Constructor 9 times, one for each separate prototypical Instance that it is required to make.

      TweetyPie.Species
Default Bird


Empty Arrays of Instances: Why ?

In APL it is natural to use arrays of Instances. For example, consider the following example.

:Class Cheese
    :Field Public Name←''
    :Field Public Strength←⍬
    ∇ make2(name strength)
      :Access Public
      :Implements Constructor
      Name Strength←name strength
    ∇
    ∇ make1 name
      :Access Public
      :Implements Constructor
      Name Strength←name 1
    ∇
    ∇ make_excuse
      :Access Public
      :Implements Constructor
      ⎕←'The cat ate the last one!'
    ∇
:EndClass

We might create an array of Instances of the Cheese Class as follows:

      cdata←('Camembert' 5)('Caephilly' 2) 'Mild Cheddar'
      cheeses←{⎕NEW Cheese ⍵}¨cdata

Suppose we want a range of medium-strength cheese for our cheese board.

      board←(cheeses.Strength<3)/cheeses
      board.Name
 Caephilly  Mild Cheddar

But look what happens when we try to select really strong cheese:

      board←(cheeses.Strength>5)/cheeses
      board.Name
The cat ate the last one!

Note that this message is not the result of the expression, but was explicitly displayed by the make_excuse function. The clue to this behaviour is the shape of board; it is empty!

      ⍴board
0

When a reference is made to an empty array of Instances (strictly speaking, a reference that requires a prototype), APL creates a new Instance by calling the niladic (default) Constructor, uses the new Instance to satisfy the reference, and then discards it. Hence, in this example, the reference:

      board.Name

caused APL to run the niladic Constructor make_excuse, which displayed:

The cat ate the last one!

Notice that the behaviour of empty arrays of Instances is modelled VERY closely after the behaviour of empty arrays in general. In particular, the Class designer is given the task of deciding what the types of the members of the prototype are.

The full explanation is given in the next topic.


Empty Arrays of Instances: How?

To cater for the need to handle empty arrays of Instances as easily as non-empty arrays, a reference to an empty array of Class Instances is handled in a special way.

Whenever a reference or an assignment is made to the content of an empty array of Instances, the following steps are performed:

  1. APL creates a new Instance of the same Class of which the empty Instance belongs.
  2. the default (niladic) Constructor is run in the new Instance
  3. the appropriate value is obtained or assigned:
    • if it is a reference is to a Field, the value of the Field is obtained
    • if it is a reference is to a Property, the PropertyGet function is run
    • if it is a reference is to a Method, the method is executed
    • if it is an assignment, the assignment is performed or the PropertySet function is run
  4. if it is a reference, the result of step 3 is used to generate an empty result array with a suitable prototype by the application of the function {0⍴⊂⍵} to it
  5. the Class Destructor (if any) is run in the new Instance
  6. the New Instance is deleted

Example

:Class Bird
    :Field Public Species

    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      ⎕DF Species←spec
    ∇
    ∇ default
      :Access Public Instance
      :Implements Constructor
      ⎕DF Species←'Default Bird'
      #.DISPLAY Species
    ∇
    ∇ R←Speak
      :Access Public
      #.DISPLAY R←'Tweet, Tweet, Tweet'
    ∇

:EndClass ⍝ Bird

First, we can create an empty array of Instances of Bird using 0⍴.

      Empty←0⍴⎕NEW Bird 'Robin'

A reference to Empty.Species causes APL to create a new Instance and invoke the niladic Constructor default. This function sets Species to 'Default Bird'and calls #.DISPLAY which displays output to the Session.

      DISPLAY Empty.Species
.→-----------.
|Default Bird|
'------------'

APL then retrieves the value of Species ('Default Bird'), applies the function {0⍴⊂⍵} to it and returns this as the result of the expression.

.⊖---------------.
| .→-----------. |
| |            | |
| '------------' |
'∊---------------'

A reference to Empty.Speak causes APL to create a new Instance and invoke the niladic Constructor default. This function sets Species to 'Default Bird'and calls #.DISPLAY which displays output to the Session.

      DISPLAY Empty.Speak
.→-----------.
|Default Bird|
'------------'

APL then invokes function Speak which displays 'Tweet, Tweet, Tweet' and returns this as the result of the function.

.→------------------.
|Tweet, Tweet, Tweet|
'-------------------'

APL then applies the function {0⍴⊂⍵} to it and returns this as the result of the expression.

.⊖----------------------.
| .→------------------. |
| |                   | |
| '-------------------' |
'∊----------------------'


Base Constructors

Constructors in a Class hierarchy are not inherited in the same way as other members. However, there is a mechanism for all the Classes in the Class inheritance tree to participate in the initialisation of an Instance.

Every Constructor function contains a:Implements Constructor statement which may appear anywhere in the function body. The statement may optionally be followed by the :Base control word and an arbitrary expression.

The statement:

      :Implements Constructor :Base expr

calls a monadic Constructor in the Base Class. The choice of Constructor depends upon the rank and shape of the result of expr (see Constructor Overloading for details).

Whereas, the statement:

      :Implements Constructor

or

      :Implements Constructor :Base

calls the niladic Constructor in the Base Class.

Note that during the instantiation of an Instance, these calls potentially take place in every Class in the Class hierarchy.

If, anywhere down the hierarchy, there is a monadic call and there is no matching monadic Constructor, the operation fails with a LENGTH ERROR.

If there is a niladic call on a Class that defines no Constructors, the niladic call is simply repeated in the next Class along the hierarchy.

However, if a Class defines a monadic Constructor and no niladic Constructor it implies that that Class cannot be instantiated without Constructor arguments. Therefore, if there is a call to a niladic Constructor in such a Class, the operation fails with a LENGTH ERROR. Note that it is therefore impossible for APL to instantiate a fill item or process a reference to an empty array for such a Class or any Class that is based upon it.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class or Instance. The only way a Constructor function may be invoked is by ⎕NEW. The fundamental reason for these restrictions is that there must be one and only one call on the Base Constructor when a new Instance is instantiated. If Constructor functions were allowed to call one another, there would be several calls on the Base Constructor. Similarly, if a Constructor could be called directly it would potentially duplicate the Base Constructor call.


Niladic Example

In the following example, DomesticParrot is derived from Parrot which is derived from Bird. They all share the Field Desc (inherited from Bird). Each of the 3 Classes has its own niladic Constructor called egg0.

:Class Bird
    :Field Public Desc
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc←'Bird'
    ∇
:EndClass ⍝ Bird

:Class Parrot: Bird
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc,←'→Parrot'
    ∇
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc,←'→DomesticParrot'
    ∇
:EndClass ⍝ DomesticParrot

      (⎕NEW DomesticParrot).Desc
Bird→Parrot→DomesticParrot

Explanation

⎕NEW creates the new instance and runs the niladic Constructor DomesticParrot.egg0. As soon as the line:

:Implements Constructor

is encountered, ⎕NEW calls the niladic constructor in the Base Class Parrot.egg0

Parrot.egg0 starts to execute and as soon as the line:

:Implements Constructor

is encountered, ⎕NEW calls the niladic constructor in the Base Class Bird.egg0.

When the line:

:Implements Constructor

is encountered, ⎕NEW cannot call the niladic constructor in the Base Class (there is none) so the chain of Constructors ends. Then, as the State Indicator unwinds ...

Bird.egg0 | executes | Desc←'Bird''
Parrot.egg0 | executes | Desc,←'→Parrot''
DomesticParrot.egg0 | execute | Desc,←'→DomesticParrot''


Monadic Example

In the following example, DomesticParrot is derived from Parrot which is derived from Bird. They all share the Field Species (inherited from Bird) but only a DomesticParrot has a Field Name. Each of the 3 Classes has its own Constructor called egg.

:Class Bird
    :Field Public Species
    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      Species←spec
    ∇
    ...
:EndClass ⍝ Bird

:Class Parrot: Bird
    ∇ egg species
      :Access Public Instance
      :Implements Constructor :Base 'Parrot: ',species
    ∇
    ...
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    :Field Public Name
    ∇ egg(name species)
      :Access Public Instance
      :Implements Constructor :Base species
      ⎕DF Name←name
    ∇
    ...
:EndClass ⍝ DomesticParrot

      pol←⎕NEW DomesticParrot('Polly' 'Scarlet Macaw')
      pol.Name
Polly
      pol.Species
Parrot: Scarlet Macaw

Explanation

⎕NEW creates the new instance and runs the Constructor DomesticParrot.egg. The egg header splits the argument into two items name and species. As soon as the line:

:Implements Constructor :Base species

is encountered, ⎕NEW calls the Base Class constructor Parrot.egg, passing it the result of the expression to the right, which in this case is simply the value in species.

Parrot.egg starts to execute and as soon as the line:

:Implements Constructor :Base 'Parrot: ',species

is encountered, ⎕NEW calls its Base Class constructor Bird.egg, passing it the result of the expression to the right, which in this case is the character vector 'Parrot: ' catenated with the value in species.

Bird.egg assigns its argument to the Public Field Species.

At this point, the State Indicator would be:

       )SI
[#.[Instance of DomesticParrot]] #.Bird.egg[3]*
[constructor]
:base
[#.[Instance of DomesticParrot]] #.Parrot.egg[2]
[constructor]
:base
[#.[Instance of DomesticParrot]] #.DomesticParrot.egg[2]
[constructor]

Bird.egg then returns to Parrot.egg which returns to DomesticParrot.egg.

Finally, DomesticParrot.egg[3] is executed, which establishes Field Name and the Display Format (⎕DF) for the instance.


Destructors

A Destructor is a function that is called just before an Instance of a Class ceases to exist and is typically used to close files or release external resources associated with an Instance.

An Instance of a Class is destroyed when:

  • The Instance is expunged using ⎕EX or )ERASE.
  • A function, in which the Instance is localised, exits.

But be aware that a destructor will also be called if:

  • The Instance is re-assigned (see below)
  • The result of ⎕NEW is not assigned (the instance gets created then immediately destroyed).
  • APL creates (and then destroys) a new Instance as a result of a reference to a member of an empty Instance. The destructor is called after APL has obtained the appropriate value from the instance and no longer needs it.
  • The constructor function fails. Note that the Instance is actually created before the constructor is run (inside it), and if the constructor fails, the fledgling Instance is discarded. Note too that this means a destructor may need to deal with a partially constructed instance, so the code may need to check that resources were actually acquired, before releasing them.
  • On the execution of )CLEAR, )LOAD, ⎕LOAD, )OFF or ⎕OFF.

Note that an Instance of a Class only disappears when the last reference to it disappears. For example, the sequence:

      I1←⎕NEW MyClass
      I2←I1
      )ERASE I1

will not cause the Instance of MyClass to disappear because it is still referenced by I2.

A Destructor is identified by the statement :Implements Destructor which must appear immediately after the function header in the Class script.

:Class Parrot
    ...
    ∇ kill
      :Implements Destructor
      'This Parrot is dead'
    ∇
    ...
:EndClass ⍝ Parrot

       pol←⎕NEW Parrot 'Scarlet Macaw'
      )ERASE pol
This Parrot is dead

Note that reassignment to pol causes the Instance referenced by pol to be destroyed and the Destructor invoked:

      pol←⎕NEW Parrot 'Scarlet Macaw'
      pol←⎕NEW Parrot 'Scarlet Macaw'
This Parrot is dead

If a Class inherits from another Class, the Destructor in its Base Class is automatically called after the Destructor in the Class itself.

So, if we have a Class structure:

      DomesticParrot => Parrot => Bird

containing the following Destructors:

:Class DomesticParrot: Parrot
    ...
    ∇ kill
      :Implements Destructor
      'This ',(⍕⎕THIS),' is dead'
    ∇
     ...
:EndClass ⍝ DomesticParrot

:Class Parrot: Bird
    ...
    ∇ kill
      :Implements Destructor
      'This Parrot is dead'
    ∇
    ...
:EndClass ⍝ Parrot

:Class Bird
    ...
    ∇ kill
      :Implements Destructor
      'This Bird is dead'
    ∇
    ...
:EndClass ⍝ Bird

Destroying an Instance of DomesticParrot will run the Destructors in DomesticParrot, Parrot and Bird and in that order.

      pol←⎕NEW DomesticParrot

      )CLEAR
This Polly is dead
This Parrot is dead
This Bird is dead
clear ws


Class Members

A Class may contain Methods, Fields and Properties (commonly referred to together as Members) which are defined within the body of the Class script or are inherited from other Classes.

Methods are regular APL defined functions, but with some special characteristics that control how they are called and where they are executed. D-fns may not be used as Methods.

Fields are just like APL variables. To get the Field value, you reference its name; to set the Field value, you assign to its name, and the Field value is stored in the Field. However, Fields differ from variables in that they possess characteristics that control their accessibility.

Properties are similar to APL variables. To get the Property value, you reference its name; to set the Property value, you assign to its name. However, Property values are actually accessed via PropertyGet and PropertySet functions that may perform all sorts of operations. In particular, the value of a Property is not stored in the Property and may be entirely dynamic.

All three types of member may be declared as Public or Private and as Instance or Shared.

Public members are visible from outside the Class and Instances of the Class, whereas Private members are only accessible from within.

Instance Members are unique to every Instance of the Class, whereas Shared Members are common to all Instances and Shared Members may be referenced directly on the Class itself.


Fields

A Field behaves just like an APL variable.

To get the value of a Field, you reference its name; to set the value of a Field, you assign to its name. Conceptually, the Field value is stored in the Field. However, Fields differ from variables in that they possess characteristics that control their accessibility.

A Field may be declared anywhere in a Class script by a :Field statement. This specifies:

  • the name of the Field
  • whether the Field is Public or Private
  • whether the Field is Instance or Shared
  • whether or not the Field is ReadOnly
  • optionally, an initial value for the Field.

Note that Triggers may be associated with Fields. See Trigger Fields for details.


Public Fields

A Public Field may be accessed from outside an Instance or a Class. Note that the default is Private.

Class DomesticParrot has a Name Field which is defined to be Public and Instance (by default).

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ...
:EndClass ⍝ DomesticParrot

The Name field is initialised by the Class constructor.

      pet←⎕NEW DomesticParrot'Polly'
      pet.Name
Polly

The Name field may also be modified directly:

      pet.Name←⌽pet.Name
      pet.Name
ylloP


Initialising Fields

A Field may be assigned an initial value. This can be specified by an arbitrary expression that is executed when the Class is fixed by the Editor or by ⎕FIX.

:Class DomesticParrot: Parrot
    :Field Public Name
        :Field Public Talks←1

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ...
:EndClass ⍝ DomesticParrot

Field Talks will be initialised to 1 in every instance of the Class.

      pet←⎕NEW DomesticParrot 'Dicky'

      pet.Talks
1
      pet.Name
Dicky

Note that if a Field is ReadOnly, this is the only way that it may be assigned a value.

See also: Shared Fields.


Private Fields

A Private Field may only be referenced by code running inside the Class or an Instance of the Class. Furthermore, Private Fields are not inherited.

The ComponentFile Class has a Private Instance Field named tie that is used to store the file tie number in each Instance of the Class.

:Class ComponentFile
    :Field Private Instance tie

    ∇ Open filename
      :Implements Constructor
      :Access Public Instance
      :Trap 0
          tie←filename ⎕FTIE 0
      :Else
          tie←filename ⎕FCREATE 0
      :EndTrap
      ⎕DF filename,'(Component File)'
    ∇

As the field is declared to be Private, it is not accessible from outside an Instance of the Class, but is only visible to code running inside.

      F1←⎕NEW ComponentFile 'test1'
      F1.tie
VALUE ERROR
      F1.tie
     ^


Shared Fields

If a Field is declared to be Shared, it has the same value for every Instance of the Class. Moreover, the Field may be accessed from the Class itself; an Instance is not required.

The following example establishes a Shared Field called Months that contains abbreviated month names which are appropriate for the user's current International settings. It also shows that an arbitrarily complex statement may be used to initialise a Field.

:Class Example
    :Using System.Globalization
    :Field Public Shared ReadOnly Months←12↑(⎕NEW DateTimeFormatInfo).AbbreviatedMonthNames
:EndClass ⍝ Example

A Shared Field is not only accessible from an instance...

      EG←⎕NEW Example
      EG.Months
 Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov...

... but also, directly from the Class itself.

      Example.Months
Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov...

Notice that in this case it is necessary to insert a :Using statement (or the equivalent assignment to ⎕USING) in order to specify the .Net search path for the DateTimeFormatInfo type. Without this, the Class would fail to fix.

You can see how the assignment works by executing the same statements in the Session:

      ⎕USING←'System.Globalization'
    12↑(⎕NEW DateTimeFormatInfo).AbbreviatedMonthNames
 Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov...


Methods

Methods are implemented as regular defined functions, but with some special attributes that control how they are called and where they are executed.

A Method is defined by a contiguous block of statements in a Class Script. A Method begins with a line that contains a ∇, followed by a valid APL defined function header. The method definition is terminated by a closing ∇.

The behaviour of a Method is defined by an :Access control statement.

Public or Private

Methods may be defined to be Private (the default) or Public.

A Private method may only be invoked by another function that is running inside the Class namespace or inside an Instance namespace. The name of a Private method is not visible from outside the Class or an Instance of the Class.

A Public method may be called from outside the Class or an Instance of the Class.

Instance or Shared

Methods may be defined to be Instance (the default) or Shared.

An Instance method runs in the Instance namespace and may only be called via the instance itself. An Instance method has direct access to Fields and Properties, both Private and Public, in the Instance in which it runs.

A Shared method runs in the Class namespace and may be called via an Instance or via the Class. However, a Shared method that is called via an Instance does not have direct access to the Fields and Properties of that Instance.

Shared methods are typically used to manipulate Shared Properties and Fields or to provide general services for all Instances that are not Instance specific.

Overridable Methods

Instance Methods may be declared with :Access Overridable.

A Method declared as being Overridable is replaced in situ (i.e. within its own Class) by a Method of the same name that is defined in a higher Class which itself is declared with the Override keyword. See Superseding Base Class Methods.


Shared Methods

A Shared method runs in the Class namespace and may be called via an Instance or via the Class. However, a Shared method that is called via an Instance does not have direct access to the Fields and Properties of that Instance.

Class Parrot has a Speak method that does not require any information about the current Instance, so may be declared as Shared.

:Class Parrot:Bird

    ∇ R←Speak times
      :Access Public Shared
      R←⍕times⍴⊂'Squark!'
    ∇

:EndClass ⍝ Parrot

      wild←⎕NEW Parrot
      wild.Speak 2
 Squark!  Squark!

Note that Parrot.Speak may be executed directly from the Class and does not in fact require an Instance.

      Parrot.Speak 3
 Squark!  Squark!  Squark!


Instance Methods

An Instance method runs in the Instance namespace and may only be called via the instance itself. An Instance method has direct access to Fields and Properties, both Private and Public, in the Instance in which it runs.

Class DomesticParrot has a Speak method defined to be Public and Instance. Where Speak refers to Name, it obtains the value of Name in the current Instance.

Note too that DomesticParrot.Speak supersedes the inherited Parrot.Speak.

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇

    ∇ R←Speak times
      :Access Public Instance
      R←⊂Name,', ',Name
      R←↑R,times⍴⊂' Who''s a pretty boy, then!'
    ∇

:EndClass ⍝ DomesticParrot

      pet←⎕NEW DomesticParrot'Polly'
      pet.Speak  3
Polly, Polly
 Who's a pretty boy, then!
 Who's a pretty boy, then!
 Who's a pretty boy, then!

      bil←⎕NEW  DomesticParrot'Billy'
      bil.Speak  1
Billy, Billy
 Who's a pretty boy, then!


Superseding Base Class Methods

Normally, a Method defined in a higher Class supersedes the Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class. This behaviour can be altered using the Overridable and Override key words in the :Access statement but only applies to Instance Methods.

If a Public Instance method in a Class is marked as Overridable, this allows a Class which derives from the Class with the Overridable method to supersede the Base Class method in the Base Class, by providing a method which is marked Override. The typical use of this is to replace code in the Base Class which handles an event, with a method provided by the derived Class.

For example, the base class might have a method which is called if any error occurs in the base class:

     ∇ ErrorHandler
[1]    :Access Public Overridable
[2]    ⎕←↑⎕DM
     ∇

In your derived class, you might supersede this by a more sophisticated error handler, which logs the error to a file:

     ∇ ErrorHandler;TN
[1]    :Access Public Override
[2]    ⎕←↑⎕DM
[3]    TN←'ErrorLog'⎕FSTIE 0
[4]    ⎕DM ⎕FAPPEND TN
[5]    ⎕FUNTIE TN
     ∇

If the derived class had a function which was not marked Override, then function in the derived class which called ErrorHandler would call the function as defined in the derived class, but if a function in the base class called ErrorHandler, it would still see the base class version of this function. With Override specified, the new function supersedes the function as seen by code in the base class. Note that different derived classes can specify different Overrides.

In C#, Java and some other compiled languages, the term Virtual is used in place of Overridable, which is the term used by Visual Basic and Dyalog APL.


Properties

A Property behaves in a very similar way to an ordinary APL variable. To obtain the value of a Property, you simply reference its name. To change the value of a Property, you assign a new value to the name.

However, under the covers, a Property is accessed via a PropertyGet function and its value is changed via a PropertySet function. Furthermore, Properties may be defined to allow partial (indexed) retrieval and assignment to occur.

There are three types of Property, namely Simple, Numbered and Keyed.

A Simple Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety.

A Numbered Property behaves like an array (conceptually a vector) which is only ever partially accessed and set (one element at a time) via indices. The Numbered Property is designed to allow APL to perform selections and structural operations on the Property.

A Keyed Property is similar to a Numbered Property except that its elements are accessed via arbitrary keys instead of indices.

The following cases illustrate the difference between Simple and Numbered Properties.

If Instance MyInst has a Simple Property Sprop and a Numbered Property Nprop, the expressions

      X←MyInst.SProp
      X←MyInst.SProp[2]

both cause APL to call the PropertyGet function to retrieve the entire value of Sprop. The second statement subsequently uses indexing to extract just the second element of the value.

Whereas, the expression:

      X←MyInst.NProp[2]

causes APL to call the PropertyGet function with an additional argument which specifies that only the second element of the Property is required. Moreover, the expression:

      X←MyInst.NProp

causes APL to call the PropertyGet function successively, for every element of the Property.

A Property is defined by a :Property ... :EndProperty section in a Class Script.

Within the body of a Property Section there may be:

  • one or more :Access statements which must appear first in the body of the Property.
  • a single PropertyGet function.
  • a single PropertySet function
  • a single PropertyShape function


Simple Instance Properties

A Simple Instance Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety. The following examples are taken from the ComponentFile Class .

The Simple Property Count returns the number of components on a file.

    :Property Count
    :Access Public Instance
        ∇ r←get
          r←¯1+2⊃⎕FSIZE tie
        ∇
    :EndProperty ⍝ Count

      F1←⎕NEW ComponentFile 'test1'
      F1.Append'Hello World'
1
      F1.Count
1
      F1.Append 42
2
      F1.Count
2

Because there is no set function defined, the Property is read-only and attempting to change it causes SYNTAX ERROR.

      F1.Count←99
SYNTAX ERROR
      F1.Count←99
     ^

The Access Property has both get and set functions which are used, in this simple example, to get and set the component file access matrix.

    :Property Access
    :Access Public Instance
        ∇ r←get
          r←⎕FRDAC tie
        ∇
        ∇ set am;mat;OK
          mat←am.NewValue
          :Trap 0
              OK←(2=⍴⍴mat)^(3=2⊃⍴mat)^^/,mat=⌊mat
          :Else
              OK←0
          :EndTrap
          'bad arg'⎕SIGNAL(~OK)/11
          mat ⎕FSTAC tie
        ∇
    :EndProperty ⍝ Access

Note that the set function must be monadic. Its argument, supplied by APL, will be an Instance of PropertyArguments. This is an internal Class whose NewValue field contains the value that was assigned to the Property.

Note that the set function does not have to accept the new value that has been assigned. The function may validate the value reject or accept it (as in this example), or perform whatever processing is appropriate.

      F1←⎕NEW ComponentFile 'test1'
      ⍴F1.Access
0 3
        F1.Access←3 3⍴28 2105 16385 0 2073 16385 31 ¯1 0
      F1.Access
28 2105 16385
 0 2073 16385
31   ¯1     0

      F1.Access←'junk'
bad arg
      F1.Access←'junk'
     ^

      F1.Access←1 2⍴10
bad arg
      F1.Access←1 2⍴10
     ^


Simple Shared Properties

The ComponentFile Class specifies a Simple Shared Property named Files which returns the names of all the Component Files in the current directory.

The previous examples have illustrated the use of Instance Properties. It is also possible to define Shared properties.

A Shared property may be used to handle information that is relevant to the Class as a whole, and which is not specific to any a particular Instance.

    :Property Files
    :Access Public Shared
        ∇ r←get
          r←⎕FLIB''
        ∇
    :EndProperty

Note that ⎕FLIB (invoked by the Files get function) does not report the names of tied files.

      F1←⎕NEW ComponentFile 'test1'
      ⎕EX'F1'
      F2←⎕NEW ComponentFile 'test2'
      F2.Files ⍝ NB ⎕FLIB does not report tied files
test1
      ⎕EX'F2'

Note that a Shared Property may be accessed from the Class itself. It is not necessary to create an Instance first.

      ComponentFile.Files
test1
test2


Numbered Properties

A Numbered Property behaves like an array (conceptually a vector) which is only ever partially accessed and set (one element at a time) via indices.

To implement a Numbered Property, you must specify a PropertyShape function and either or both a PropertyGet and PropertySet function.

When an expression references or makes an assignment to a Numbered Property, APL first calls its PropertyShape function which returns the dimensions of the Property. Note that the shape of the result of this function determines the rank of the Property.

If the expression uses indexing, APL checks that the index or indices are within the bounds of these dimensions, and then calls the PropertyGet or PropertySet function. If the expression specifies a single index, APL calls the PropertyGet or PropertySet function once. If the expression specifies multiple indices, APL calls the function successively.

If the expression references or assigns the entire Property (without indexing) APL generates a set of indices for every element of the Property and calls the PropertyGet or PropertySet function successively for every element in the Property.

Note that APL generates a RANK ERROR if an index contains the wrong number of elements or an INDEX ERROR if an index is out of bounds.

When APL calls a monadic PropertyGet or PropertySet function, it supplies an argument of type PropertyArguments.


Example

The ComponentFile Class specifies a Numbered Property named Component which represents the contents of a specified component on the file.

    :Property Numbered Component
    :Access Public Instance
        ∇ r←shape
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⎕FREAD tie arg.Indexers
        ∇
        ∇ set arg
          arg.NewValue ⎕FREPLACE tie,arg.Indexers
        ∇
    :EndProperty

      F1←⎕NEW ComponentFile 'test1'

      F1.Append¨(⍳5)×⊂⍳4
1 2 3 4 5

      F1.Count
5

      F1.Component[4]
 4 8 12 16

      4⊃F1.Component
4 8 12 16

      (⊂4 3)⌷F1.Component
 4 8 12 16  3 6 9 12

Referencing a Numbered Property in its entirety causes APL to call the get function successively for every element.

      F1.Component
 1 2 3 4  2 4 6 8  3 6 9 12  4 8 12 16  5 10 15 20

      ((⊂4 3)⌷F1.Component)←'Hello' 'World'

      F1.Component[3]
 World

Attempting to access a Numbered Property with inappropriate indices generates an error:

      F1.Component[6]
INDEX ERROR
      F1.Component[6]
     ^
      F1.Component[1;2]
RANK ERROR
      F1.Component[1;2]
     ^


The Default Property

A single Numbered Property may be identified as the Default Property for the Class. If a Class has a Default Property, indexing with the ⌷ primitive function and [...] indexing may be applied to the Property directly via a reference to the Class or Instance.

The Numbered Property example of the ComponentFile Class can be extended by adding the control word Default to the :Property statement for the Component Property.

Indexing may now be applied directly to the Instance F1. In essence, F1[n] is simply shorthand for F1.Component[n] and n⌷F1 is shorthand for n⌷F1.Component

    :Property Numbered Default Component
    :Access Public Instance
        ∇ r←shape
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⎕FREAD tie arg.Indexers
        ∇
        ∇ set arg
          arg.NewValue ⎕FREPLACE tie,arg.Indexers
        ∇
    :EndProperty

      F1←⎕NEW ComponentFile 'test1'
      F1.Append¨(⍳5)×⊂⍳4
1 2 3 4 5
      F1.Count
5

      F1[4]
 4 8 12 16
      (⊂4 3)⌷F1
 4 8 12 16  3 6 9 12
      ((⊂4 3)⌷F1)←'Hello' 'World'
      F1[3]
 World

Note however that this feature applies only to indexing.

      4⊃F1
DOMAIN ERROR
      4⊃F1
     ^


ComponentFile Class

:Class ComponentFile
    :Field Private Instance tie

    ∇ Open filename
      :Implements Constructor
      :Access Public Instance
      :Trap 0
          tie←filename ⎕FTIE 0
      :Else
          tie←filename ⎕FCREATE 0
      :EndTrap
      ⎕DF filename,'(Component File)'
    ∇

    ∇ Close
      :Access Public Instance
      ⎕FUNTIE tie
    ∇

    ∇ r←Append data
      :Access Public Instance
      r←data ⎕FAPPEND tie
    ∇

    ∇ Replace(comp data)
      :Access Public Instance
      data ⎕FREPLACE tie,comp
    ∇

    :Property Count
    :Access Public Instance
        ∇ r←get
          r←¯1+2⊃⎕FSIZE tie
        ∇
    :EndProperty ⍝ Count

:Property Access
    :Access Public Instance
        ∇ r←get arg
          r←⎕FRDAC tie
        ∇
        ∇ set am;mat;OK
          mat←am.NewValue
          :Trap 0
              OK←(2=⍴⍴mat)^(3=2⊃⍴mat)^^/,mat=⌊mat
          :Else
              OK←0
          :EndTrap
          'bad arg'⎕SIGNAL(~OK)/11
          mat ⎕FSTAC tie
        ∇
    :EndProperty ⍝ Access

    :Property Files
    :Access Public Shared
        ∇ r←get
          r←⎕FLIB''
        ∇
    :EndProperty

    :Property Numbered Default Component
    :Access Public Instance
        ∇ r←shape args
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⊂⎕FREAD tie,arg.Indexers
        ∇
        ∇ set arg
          (⊃arg.NewValue)⎕FREPLACE tie,arg.Indexers
        ∇
    :EndProperty

    ∇ Delete file;tie
      :Access Public Shared
      tie←file ⎕FTIE 0
      file ⎕FERASE tie
    ∇
:EndClass ⍝ Class ComponentFile


Keyed Properties

A Keyed Property is similar to a Numbered Property except that it may only be accessed by indexing (so-called square-bracket indexing) and indices are not restricted to integers but may be arbitrary arrays.

To implement a Keyed Property, only a get and/or a set function are required. APL does not attempt to validate or resolve the specified indices in any way, so does not require the presence of a shape function for the Property.

However, APL does check that the rank and lengths of the indices correspond to the rank and lengths of the array to the right of the assignment (for an indexed assignment) and the array returned by the get function (for an indexed reference). If the rank or shape of these arrays fails to conform to the rank or shape of the indices, APL will issue a RANK ERROR or LENGTH ERROR.

Note too that indices may be elided. If KProp is a Keyed Property of Instance I1, the following expressions are all valid.

      I1.KProp
      I1.KProp[]←10
      I1.KProp[;]←10
      I1.KProp['One' 'Two';]←10
      I1.KProp[;'One' 'Two']←10

When APL calls a monadic get or a set function, it supplies an argument of type PropertyArguments, which identifies which dimensions and indices were specified. See PropertyArguments Class.


Keyed Properties Example 1

The Sparse2 Class illustrates the implementation and use of a Keyed Property.

Sparse2 represents a 2-dimensional sparse array each of whose dimensions are indexed by arbitrary character keys. The sparse array is implemented as a Keyed Property named Values. The following expressions show how it might be used.

      SA1←⎕NEW Sparse2
      SA1.Values[⊂'Widgets';⊂'Jan']←100
      SA1.Values[⊂'Widgets';⊂'Jan']
100
      SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']←10×2 3⍴⍳6
      SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']
10 20 30
40 50 60
      SA1.Values[⊂'Widgets';'Jan' 'Oct']
10 30
      SA1.Values['Grommets' 'Widgets';⊂'Oct']
60
30

Sparse2 Class Example

:Class Sparse2  ⍝ 2D Sparse Array
    :Field Private keys
    :Field Private values
    ∇ make
      :Access Public
      :Implements Constructor
      keys←0⍴⊂'' ''
      values←⍬
    ∇
    :Property Keyed Values
    :Access Public Instance
        ∇ v←get arg;k
          k←arg.Indexers
          ⎕SIGNAL(2≠⍴k)/4
          k←fixkeys k
          v←(values,0)[keys⍳k]
        ∇
        ∇ set arg;new;k;v;n
          v←arg.NewValue
          k←arg.Indexers
          ⎕SIGNAL(2≠⍴k)/4
          k←fixkeys k
          v←(⍴k)(⍴⍣(⊃1=⍴,v))v
          ⎕SIGNAL((⍴k)≠⍴v)/5
          k v←,¨k v
          :If ∨/new←~k∊keys
              values,←new/v
              keys,←new/k
              k v/⍨←⊂~new
          :EndIf
          :If 0<⍴k
              values[keys⍳k]←v
          :EndIf
        ∇
    :EndProperty

    ∇ k←fixkeys k
      k←(2≠≡¨k){,(⊂⍣⍺)⍵}¨k
      k←⊃(∘.{⊃,/⊂¨⍺ ⍵})/k
    ∇
:EndClass ⍝ 2D Sparse Array

Internally, Sparse2 maintains a list of keys and a list of values which are initialised to empty arrays by its constructor.

When an indexed assignment is made, the set function receives a list of keys (indices) in arg.Indexer and values in arg.NewValue. The function updates the values of existing keys, and adds new keys and their values to the internal lists.

When an indexed reference is made, the get function receives a list of keys (indices) in arg.Indexer. The function uses these keys to retrieve the corresponding values, inserting 0s for non-existent keys.

Note that in the expression:

 SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']

the structure of arg.Indexer is:

.→-----------------------------------------------.
| .→---------------------. .→------------------. |
| | .→------. .→-------. | | .→--. .→--. .→--. | |
| | |Widgets| |Grommets| | | |Jan| |Mar| |Oct| | |
| | '-------' '--------' | | '---' '---' '---' | |
| '∊---------------------' '∊------------------' |
'∊-----------------------------------------------'


Example

A second example of a Keyed Property is provided by the KeyedFile Class which is based upon the ComponentFile Class used previously.

:Class KeyedFile: ComponentFile
    :Field Public Keys
    ⎕ML←0

    ∇ Open filename
      :Implements Constructor :Base filename
      :Access Public Instance
      :If Count>0
          Keys←{⊃⍵⊃⎕BASE.Component}¨⍳Count
      :Else
          Keys←0⍴⊂''
      :EndIf
    ∇

    :Property Keyed Component
    :Access Public Instance
        ∇ r←get arg;keys;sink
          keys←⊃arg.Indexers
          ⎕SIGNAL(~^/keys∊Keys)/3
          r←{2⊃⍵⊃⎕BASE.Component}¨Keys⍳keys
        ∇
        ∇ set arg;new;keys;vals
          vals←arg.NewValue
          keys←⊃arg.Indexers
          ⎕SIGNAL((⍴,keys)≠⍴,vals)/5
          :If ∨/new←~keys∊Keys
              sink←Append¨↓⍉↑(⊂new)/¨keys vals
              Keys,←new/keys
              keys vals/⍨←⊂~new
          :EndIf
          :If 0<⍴,keys
              Replace¨↓⍉↑(Keys⍳keys)(↓⍉↑keys vals)
          :EndIf
        ∇
    :EndProperty

:EndClass ⍝ Class KeyedFile

      K1←⎕NEW KeyedFile 'ktest'
      K1.Count
0
      K1.Component[⊂'Pete']←42
      K1.Count
1
      K1.Component['John' 'Geoff']←(⍳10)(3 4⍴⍳12)
      K1.Count
3
      K1.Component['Geoff' 'Pete']
 1  2  3  4  42
 5  6  7  8
 9 10 11 12
      K1.Component['Pete' 'Morten']←(3 4⍴'∘')(⍳⍳3)
      K1.Count
4
      K1.Component['Morten' 'Pete' 'John']
  1 1 1  1 1 2  1 1 3   ∘∘∘∘  1 2 3 4 5 6 7 8 9 10
  1 2 1  1 2 2  1 2 3   ∘∘∘∘
                        ∘∘∘∘


Interfaces

An Interface is defined by a Script that contains skeleton declarations of Properties and/or Methods. These members are only place-holders; they have no specific implementation; this is provided by each of the Classes that support the Interface.

An Interface contains a collection of methods and properties that together represents a protocol that an application must follow in order to manipulate a Class in a particular way.

An example might be an Interface called Icompare that provides a single method (Compare) which compares two Instances of a Class, returning a value to indicate which of the two is greater than the other. A Class that implements Icompare must provide an appropriate Compare method, but every Class will have its own individual version of Compare. An application can then be written that sorts Instances of any Class that supports the ICompare Interface.

An Interface is implemented by a Class if it includes the name of the Interface in its :Class statement, and defines a corresponding set of the Methods and Properties that are declared in the Interface.

To implement a Method, a function defined in the Class must include a :Implements Method statement that maps it to the corresponding Method defined in the Interface:

      :Implements Method <InterfaceName.MethodName>

Furthermore, the syntax of the function (whether it be result returning, monadic or niladic) must exactly match that of the method described in the Interface. The function name, however, need not be the same as that described in the Interface.

Similarly, to implement a Property the type (Simple, Numbered or Keyed) and syntax (defined by the presence or absence of a PropertyGet and PropertySet functions) must exactly match that of the property described in the Interface. The Property name, however, need not be the same as that described in the Interface.


Interfaces

Penguin Class Example

The Penguin Class example illustrates the use of Interfaces to implement multiple inheritance.

FishBehaviour Interface

BirdBehaviour Interface

Penguin Class

In this case, the Penguin Class derives from Animal but additionally supports the BirdBehaviour and FishBehaviour Interfaces, thereby inheriting members from both.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
  #.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal

      (FishBehaviour ⎕CLASS Pingo).Swim
I can dive and swim like a fish
      (BirdBehaviour ⎕CLASS Pingo).Fly
Although I am a bird, I cannot fly
      (BirdBehaviour ⎕CLASS Pingo).Lay
I lay one egg every year
      (BirdBehaviour ⎕CLASS Pingo).Sing
Croak, Croak!


Including Namespaces in Classes

A Class may import methods from one or more plain Namespaces. This allows several Classes to share a common set of methods, and provides a degree of multiple inheritance.

To import methods from a Namespace NS, the Class Script must include a statement:

:Include NS

When the Class is fixed by the editor or by ⎕FIX, all the defined functions and operators in Namespace NS are included as methods in the Class. The functions and operators which are brought in as methods from the namespace NS are treated exactly as if the source of each function/operator had been included in the class script at the point of the :Include statement. For example, if a function contains :Signature or :Access statements, these will be taken into account. Note that such declarations have no effect on a function/operator which is in an ordinary namespace.

D-fns and D-ops in NS are also included in the Class but as Private members, because D-fns and D-ops may not contain :Signature or :Access statements. Variables and Sub-namespaces in NS are not included.

Note that objects imported in this way are not actually copied, so there is no penalty incurred in using this feature. Additions, deletions and changes to the functions in NS are immediately reflected in the Class.

If there is a member in the Class with the same name as a function in NS, the Class member takes precedence and supersedes the function in NS.

Conversely, functions in NS will supersede members of the same name that are inherited from the Base Class, so the precedence is:

Class supersedes

Included Namespace, supersedes

Base Class

Any number of Namespaces may be included in a Class and the :Include statements may occur anywhere in the Class script. However, for the sake of readability, it is recommended that you have :Include statements at the top, given that any definitions in the script will supersede included functions and operators.


Including Namespaces

Example

In this example, Class Penguin inherits from Animal and includes functions from the plain Namespaces BirdStuff and FishStuff.

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
:EndClass ⍝ Penguin

Namespace BirdStuff contains 2 functions, both declared as Public methods.

:Namespace BirdStuff
    ∇ R←Fly
      :Access Public Instance
      R←'Fly, Fly ...'
    ∇
    ∇ R←Lay
      :Access Public Instance
      R←'Lay, Lay ...'
    ∇
:EndNamespace ⍝ BirdStuff

Namespace FishStuff contains a single function, also declared as a Public method.

:Namespace FishStuff
    ∇ R←Swim
      :Access Public Instance
      R←'Swim, Swim ...'
    ∇
:EndNamespace ⍝ FishStuff

      Pingo←⎕NEW Penguin
      Pingo.Swim
Swim, Swim ...
      Pingo.Lay
Lay, Lay ...
      Pingo.Fly
Fly, Fly ...

This is getting silly - we all know that Penguin's can't fly. This problem is simply resolved by overriding the BirdStuff.Fly method with Penguin.Fly. We can hide BirdStuff.Fly with a Private method in Penguin that does nothing. For example:

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
    ∇ Fly ⍝ Override BirdStuff.Fly
    ∇
:EndClass ⍝ Penguin

      Pingo←⎕NEW Penguin
      Pingo.Fly
VALUE ERROR
      Pingo.Fly
     ^

or we can supersede it with a different Public method, as follows:

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
    ∇ R←Fly ⍝ Override BirdStuff.Fly
      :Access Public Instance
      R←'Sadly, I cannot fly'
    ∇
:EndClass ⍝ Penguin

      Pingo←⎕NEW Penguin
      Pingo.Fly
Sadly, I cannot fly


Nested Classes

It is possible to define Classes within Classes (Nested Classes).

A Nested Class may be either Private or Public. This is specified by a :Access Statement, which must precede the definition of any Class contents. The default is Private.

A Public Nested Class is visible from outside its containing Class and may be used directly in its own right, whereas a Private Nested Class is not and may only be used by code inside the containing Class.

However, methods in the containing Class may return instances of Private Nested Classes and in that way expose them to the calling environment.


GolfService Example

The GolfService Example Class illustrates the use of nested classes. GolfService was originally developed as a Web Service for Dyalog.Net and is one of the samples distributed in samples\asp.net\webservices. This version has been reconstructed as a stand-alone APL Class.

GolfService contains the following nested classes, all of which are Private.

GolfCourse | A Class that represents a Golf Course, having Fields Code and Name.
Slot | A Class that represents a tee-time or match, having Fields Time and Players. Up to 4 players may play together in a match.
Booking | A Class that represents a reservation for a particular tee-time at a particular golf course. This has Fields OK, Course, TeeTime and Message. The value of TeeTime is an Instance of a Slot Class.
StartingSheet | A Class that represents a day's starting-sheet at a particular golf course. It has Fields OK, Course, Date, Slots, Message. Slots is an array of Instances of Slot Class.

The GolfService constructor takes the name of a file in which all the data is stored. This file is initialised by method InitFile if it doesn't already exist.

      G←⎕NEW GolfService 'F:\HELP11.0\GOLFDATA'
      G
#.[Instance of GolfService]

The GetCourses method returns an array of Instances of the internal (nested) Class GolfCourse. Notice how the display form of each Instance is established by the GolfCourse constructor, to obtain the output display shown below.

      G.GetCourses
 St Andrews(1)  Hindhead(2)  Basingstoke(3)

All of the dates and times employ instances of the .Net type System.DateTime, and the following statements just set up some temporary variables for convenience later.

      ⎕←Tomorrow←(⎕NEW DateTime(3↑⎕TS)).AddDays 1
31/03/2006 00:00:00
      ⎕←TomorrowAt7←Tomorrow.AddHours 7
31/03/2006 07:00:00

The MakeBooking method takes between 4 and 7 parameters viz.

  • the code for the golf course at which the reservation is required
  • the date and time of the reservation
  • a flag to indicate whether or not the nearest available time will do
  • a list of up to 4 players who wish to book that time.

The result is an Instance of the internal Class Booking. Once again, ⎕DF is used to make the default display of these Instances meaningful. In this case, the reservation is successful.

      G.MakeBooking 2 TomorrowAt7 1 'Pete' 'Tiger'
  Hindhead(2)   31/03/2006 07:00:00   Pete  Tiger    OK

Bob, Arnie and Jack also ask to play at 7:00 but are given the 7:10 tee-time instead (4-player restriction).

      G.MakeBooking 2 TomorrowAt7 1 'Bob' 'Arnie' 'Jack'
 Hindhead(2)   31/03/2006 07:10:00   Bob  Arnie  Jack    OK

However, Pete and Tiger are joined at 7:00 by Dave and Al.

       G.MakeBooking 2 TomorrowAt7 1 'Dave' 'Al'
  Hindhead(2)   31/03/2006 07:00:00   Pete  Tiger  Dave  Al    OK

Up to now, all bookings have been made with the tee-time flexibility flag set to 1. Inflexible Jim is only interested in playing at 7:00...

      G.MakeBooking 2 TomorrowAt7 0 'Jim'
 Hindhead(2)  31/03/2006 07:00:00  Not available

... so his reservation fails (4-player restriction).

Finally the GetStartingSheet method is used to obtain an Instance of the internal Class StartingSheet for the given course and day.

      G.GetStartingSheet 2 Tomorrow
  Hindhead(2)  31/03/2006 00:00:00
  31/03/2006 07:00:00   Pete  Tiger  Dave  Al
  31/03/2006 07:10:00   Bob  Arnie  Jack
  31/03/2006 07:20:00
  ....


Namespace Scripts

A Namespace Script is a script that begins with a :Namespace statement and ends with a :EndNamespace statement. When a Namespace Script is fixed, it establishes an entire namespace that may contain other namespaces, functions, variables and classes.

The names of Classes defined within a Namespace Script which are parents, children, or siblings are visible both to one another and to code and expressions defined in the same script, regardless of the namespace hierarchy within it. Names of Classes which are nieces or nephews and their descendants are however not visible.

For example:

:Namespace a

    d←⎕NEW a1
    e←⎕NEW bb2

    :Class a1
        ∇ r←foo
          :Access Shared Public
          r←⎕NEW¨b1 b2
        ∇
    :EndClass ⍝ a1

    ∇ r←goo
      r←a1.foo
    ∇

    ∇ r←foo
      r←⎕NEW¨b1 b2
    ∇

    :Namespace b
        :Class b1
        :EndClass ⍝ b1
        :Class b2
            :Class bb2
            :EndClass ⍝ bb2
        :EndClass ⍝ b2
    :EndNamespace ⍝ b

:EndNamespace ⍝ a

      a.d
#.a.[a1]
      a.e
#.a.[bb2]
      a.foo
 #.a.[b1]  #.a.[b2]

Note that the names of Classes b1 (a.b.b1) and b2 (a.b.b2) are not visible from their “uncle” a1 (a.a1).

      a.goo
VALUE ERROR
foo[2] r←⎕NEW¨b1 b2

Notice that Classes in a Namespace Script are fixed before other objects (hence the assignments to d and e are evaluated after Classes a1 and bb2 are fixed), although the order in which Classes themselves are defined is still important if they reference one another during initialisation.

Warning: If you introduce new objects of any type (functions, variables, or classes) into a namespace defined by a script by any other means than editing the script, then these objects will be lost the next time the script is edited and fixed. Also, if you modify a variable which is defined in a script, the script will not be updated.

A practical example using :Namespace is given in the next topic.


Namespace Script Example

The DiaryStuff example illustrates the manner in which classes may be defined and used in a Namespace script.

DiaryStuff defines two Classes named Diary and DiaryEntry.

Diary contains a (private) Field named entries, which is simply a vector of instances of DiaryEntry. These are 2-element vectors containing a .NET DateTime object and a description.

The entries Field is initialised to an empty vector of DiaryEntry instances which causes the invocation of the default constructor DiaryEntry.Make0 when Diary is fixed. See Empty Arrays of Instances: Why ? for further explanation.

The entries Field is referenced through the Entry Property, which is defined as the Default Property. This allows individual entries to be referenced and changed using indexing on a Diary Instance.

Note that DiaryEntry is defined in the script first (before Diary) because it is referenced by the initialisation of the Diaries.entries Field

Create a new instance of Diary.

      D←⎕NEW DiaryStuff.Diary

Add a new entry "meeting with John at 09:00 on April 30th"

      D.Add(2006 4 30 9 0)'Meeting with John'
 30/04/2006 09:00:00  Meeting with John

Add another diary entry "Dentist at 10:00 on April 30th".

      D.Add(2006 4 30 10 0)'Dentist'
 30/04/2006 10:00:00  Dentist

One of the benefits of the Namespace Script is that Classes defined within it (which are typically related) may be used independently, so we can create a stand-alone instance of DiaryEntry; "Doctor at 11:00"...

  Doc←⎕NEW DiaryStuff.DiaryEntry((2006 4 30 11 0)'Doctor')
      Doc
 30/04/2006 11:00:00  Doctor

... and then use it to replace the second Diary entry with indexing:

      D[2]←Doc

and just to confirm it is there...

      D[2]
 30/04/2006 11:00:00  Doctor

What am I doing on the 30th?

      D.DoingOn 2006 4 30
  30/04/2006 09:00:00  Meeting with John    ...
  ... 30/04/2006 11:00:00  Doctor

Remove the 11:00 appointment...

      D.Remove 2006 4 30 11 0
1

and the complete Diary is...

      ⌷D
  30/04/2006 09:00:00  Meeting with John


:Access Statement

:Access <Private|Public><Instance|Shared><Overridable>
                                         <Override>
:Access <WebMethod>

The :Access statement is used to specify characteristics for Classes, Properties and Methods.

Element | Description
Private|Public | Specifies whether or not the (nested) Class, Property or Method is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | For a Field, specifies if there is a separate value of the Field in each Instance of the Class, or if there is only a single value that is shared between all Instances.For a Property or Method, specifies whether the code associated with the Property or Method runs in the Class or Instance.
WebMethod | Applies only to a Method and specifies that the method is exported as a web method. This applies only to a Class that implements a Web Service.
Overridable | Applies only to an Instance Method and specifies that the Method may be overridden by a Method in a higher Class. See below.
Override | Applies only to an Instance Method and specifies that the Method overrides the corresponding Overridable Method defined in the Base Class. See below.

Overridable/Override

Normally, a Method defined in a higher Class replaces a Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class.

However, a Method declared as being Overridable is replaced in situ (i.e. within its own Class) by a Method of the same name in a higher Class if that Method is itself declared with the Override keyword. For further information, see Superseding Base Class Methods.

Nested Classes

The :Access statement is also used to control the visibility of one Class that is defined within another (a nested Class). A Nested Class may be either Private or Public. Note that the :Access Statement must precede the definition of any Class contents.

A Public Nested Class is visible from outside its containing Class and may be used directly in its own right, whereas a Private Nested Class is not and may only be used by code inside the containing Class.

However, methods in the containing Class may return instances of Private Nested Classes and in that way expose them to the calling environment.

WebMethod

Note that :Access WebMethod is equivalent to:

:Access Public
:Attribute System.Web.Services.WebMethodAttribute


:Interface Statement

:Interface <interface name>
...
:EndInterface

An Interface is defined by a Script containing skeleton declarations of Properties and/or Methods. The script must begin with a :Interface Statement and end with a :EndInterface Statement.

An Interface may not contain Fields.

Properties and Methods defined in an Interface, and the Class functions that implement the Interface, may not contain :Access Statements.


:Class Statement

:Class <class name><:base class name> <,interface name...>

:Include <namespace>
...
:EndClass

A class script begins with a :Class statement and ends with a :EndClass statement. The elements that comprise the :Class statement are as follows:

Element | Description
class name | Optionally, specifies the name of the Class, which must conform to the rules governing APL names.
base class name | Optionally specifies the name of a Class from which this Class is derived and whose members this Class inherits.
interface name | The names of one or more Interfaces which this Class supports.

A Class may import methods defined in separate plain Namespaces with one or more :Include statements. For further details, see Including Namespaces in Classes.

Examples:

The following statements define a Class named Penguin that derives from (is based upon) a Class named Animal and which supports two Interfaces named BirdBehaviour and FishBehaviour.

:Class Penguin: Animal,BirdBehaviour,FishBehaviour
...
:EndClass

The following statements define a Class named Penguin that derives from (is based upon) a Class named Animal and includes methods defined in two separate Namespaces named BirdStuff and FishStuff.

:Class Penguin: Animal
:Include BirdStuff
:Include FishStuff
...
:EndClass


:Namespace Statement

:Namespace <namespace name>
...
:EndNamespace

A Namespace Script may be used to define an entire namespace containing other namespaces, functions, variables and Classes.

A Namespace script must begin with a :Namespace statement and end with a :EndNamespace statement.

Sub-namespaces, which may be nested, are defined by pairs of :Namespace and :EndNamespace statements within the Namespace script.

Classes are defined by pairs of :Class and :EndClass statements within the Namespace script, and these too may be nested.

The names of Classes defined within a Namespace Script are visible both to one another and to code and expressions defined in the same script, regardless of the namespace hierarchy within it.

A Namespace script is therefore particularly useful to group together Classes that refer to one another where the use of nested classes is inappropriate.


:Implements Statement

The :Implements statement identifies the function to be one of the following types.

:Implements Constructor <[:Base expr]>
:Implements Destructor
:Implements Method <InterfaceName.MethodName>
:Implements Trigger <name1><,name2,name3,...>

Element | Description
Constructor | Specifies that the function is a Class Constructor.
:Base expr | Specifies that the Base Constructor be called with the result of the expression expr as its argument.
Destructor | Specifies that the function is a Class Destructor.
Method | Specifies that the function implements the Method MethodName whose syntax is specified by Interface InterfaceName.
Trigger | Identifies the function as a Trigger Function which is activated by changes to variable name1, name2, etc.


:Using Statement

:Using <NameSpace[,Assembly]>

This statement specifies a .NET namespace that is to be searched to resolve unqualified names of .NET types referenced by expressions in the Class.

Element | Description
NameSpace | Specifies a .NET namespace.
Assembly | Specifies the Assembly in which NameSpace is located. If the Assembly is defined in the global assembly cache, you need only specify its name. If not, you must specify a full or relative pathname.

If the Microsoft .Net Framework is installed, the System namespace inmscorlib.dll is automatically loaded when Dyalog APL starts. To access this namespace, it is not necessary to specify the name of the Assembly.

When the class is fixed, ⎕USING is inherited from the surrounding space. Each :Using statement appends an element to ⎕USING, with the exception of :Using with no argument:

If you omit <Namespace>, this is equivalent to clearing ⎕USING, which means that no .NET namespaces will be searched (unless you follow this statement with additional :Using statements, each of which will append to ⎕USING).

To set ⎕USING, to a single empty character vector, which only allows references to fully qualified names of classes in mscorlib.dll, you must write:

:Using , (note the presence of the comma)

or

:Using ,mscorlib.dll

i.e. specify an empty namespace name followed by no assembly, or followed by the default assembly, which is always loaded.


:Attribute Statement

:Attribute <Name> [ConstructorArgs]

The :Attribute statement is used to attach .Net Attributes to a Class or a Method.

Attributes are descriptive tags that provide additional information about programming elements. Attributes are not used by Dyalog APL but other applications can refer to the extra information in attributes to determine how these items can be used. Attributes are saved with the metadata of Dyalog APL .NET assemblies.

Element | Description
Name | The name of a .Net attribute
ConstructorArgs | Optional arguments for the Attribute constructor

Example

The following Class has SerializableAttribute and CLSCompliantAttribute attributes attached to the Class as a whole, and ObsoleteAttribute attributes attached to Methods foo and goo within it.

:Class c1
:using System
    :attribute SerializableAttribute
    :attribute CLSCompliantAttribute 1

    ∇ foo(p1 p2)
      :Access public instance
      :Signature foo Object,Object
      :Attribute ObsoleteAttribute
    ∇

    ∇ goo(p1 p2)
      :Access public instance
      :Signature foo Object,Object
      :Attribute ObsoleteAttribute 'Don''t use this' 1

    ∇

:EndClass ⍝ c1

When this Class is exported as a .Net Class, the attributes are saved in its metadata. For example, Visual Studio will warn developers if they make use of a member which has the ObsoleteAttribute.


Field Statement

:Field <Private|Public> <Instance|Shared> <ReadOnly>...
       ... FieldName <← expr>

A :Field statement is a single statement whose elements are as follows:

Element | Description
Private|Public | Specifies whether or not the Field is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies if there is a separate value of the Field in each Instance of the Class, or if there is only a single value that is shared between all Instances.
ReadOnly | If specified, this keyword prevents the value in the Field from being changed after initialisation.
FieldName | Specifies the name of the Field (mandatory).
← expr | Specifies an initial value for the Field.

Examples:

The following statement defines a Field called Name. It is (by default), an Instance Field so every Instance of the Class has a separate value. It is a Public Field and so may be accessed (set or retrieved) from outside an Instance.

:Field Public Name

The following statement defines a Field called Months.

:Field Shared ReadOnly Months←12↑(⎕NEW DateTimeFormatInfo)
                                 .AbbreviatedMonthNames

Months is a Shared Field so there is just a single value that is the same for every Instance of the Class. It is (by default), a Private Field and may only be referenced by code running in an Instance or in the Class itself. Furthermore, it is ReadOnly and may not be altered after initialisation. Its initial value is calculated by an expression that obtains the short month names that are appropriate for the current locale using the .Net Type DateTimeFormatInfo.

Notes

Note that Fields are initialised when a Class script is fixed by the editor or by ⎕FIX. If the evaluation of expr causes an error (for example, a VALUE ERROR), an appropriate message will be displayed in the Status Window and ⎕FIX will fail with a DOMAIN ERROR. Note that a ReadOnly Field may only be assigned a value by its :Field statement.

In the second example above, the expression will only succeed if ⎕USING is set to the appropriate path, in this case System.Globalization.

You may not define a Field with the name of one of the permissable keywords (such as public). Otherwise the Class not be fixed and the editor will display an error message in the Status Windows. For example:

error AC0541: a field must have a name "    :Field Public public"


Property Section

A Property is defined by a :Property ... :EndProperty section in a Class Script. The syntax of the :Property Statement, and its optional :Access statement is as follows:

:Property <Simple|Numbered|Keyed> <Default> Name<,Name>...
:Access <Private|Public><Instance|Shared>
...
:EndProperty

Element | Description
Name | Specifies the name of the Property by which it is accessed. Additional Properties, sharing the same PropertyGet and/or PropertySet functions, and the same access behaviour may be specified by a comma-separated list of names.
Simple|Numbered|Keyed | Specifies the type of Property (see below). The default is Simple.
Default | Specifies that this Property acts as the default property for the Class when indexing is applied directly to an Instance of the Class.
Private|Public | Specifies whether or not the Property is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies if there is a separate value of the Property in each Instance of the Class, or if there is only a single value that is shared between all Instances.

A Simple Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety.

A Numbered Property behaves like an array (conceptually a vector) which is only ever partially accessed and set (one element at a time) via indices.

A Keyed Property is similar to a Numbered Property except that its elements are accessed via arbitrary keys instead of indices.

Numbered and Keyed Properties are designed to allow APL to perform selections and structural operations on the Property.

Within the body of a Property Section there may be:

  • one or more :Access statements
  • a single PropertyGet function.
  • a single PropertySet function
  • a single PropertyShape function

The three functions are identified by case-independent names Get, Set and Shape.

Errors

When a Class is fixed by the Editor or by ⎕FIX, APL checks the validity of each Property section and the syntax of PropertyGet, PropertySet and PropertyShape functions within them.

  • You may not specify a name which is the same as one of the keywords.
  • There must be at least a PropertyGet, or a PropertySet or a PropertyShape function defined.
  • You may only define a PropertyShape function if the Property is Numbered.

If anything is wrong, the Class is not fixed and an error message is displayed in the Status Window. For example:

error AC0545: invalid or empty property declaration
error AC0595: this property type should not implement a "shape" function


PropertyArguments Class

Where appropriate, APL supplies the PropertyGet and PropertySet functions with an argument that is an instance of the internal class PropertyArguments.

PropertyArguments has just 3 read-only Fields which are as follows:

Name | The name of the property. This is useful when one function is handling several properties.
NewValue | Array containing the new value for the Property or for selected element(s) of the property as specified by Indexers.
IndexersSpecified | A Boolean vector that identifies which dimensions of the Property are to be referenced or assigned.
Indexers | A vector that identifies the elements of the Property that are to be referenced or assigned.


PropertyGet Function Syntax

PropertyGet Function R←Get {ipa}

The name of the PropertyGet function must be Get, but is case-independent. For example, get, Get, gEt and GET are all valid names for the PropertyGet function

The PropertyGet function must be result returning. For a Simple Property, it may be monadic or niladic. For a Numbered or Keyed Property it must be monadic.

The result R may be any array. However, for a Keyed Property, R must conform to the rank and shape specified by ipa.Indexers or be scalar.

If monadic, ipa is an instance of the internal class PropertyArguments.

In all cases, ipa.Name contains the name of the Property being referenced and NewValue is undefined (VALUE ERROR).

If the Property is Simple, ipa.Indexers is undefined (VALUE ERROR).

If the Property is Numbered, ipa.Indexers is an integer vector of the same length as the rank of the property (as implied by the result of the Shape function) that identifies a single element of the Property whose value is to be obtained. In this case, R must be scalar.

If the Property is Keyed, ipa.IndexersSpecified is a Boolean vector with the same length as the rank of the property (as implied by the result of the Shape function). A value of 1 means that an indexing array for the corresponding dimension of the Property was specified, while a value of 0 means that the corresponding dimension was elided. ipa.Indexers is a vector of the same length containing the arrays that were specified within the square brackets in the reference expression. Specifically, ipa.Indexers will contain one fewer elements than, the number of semi-colon (;) separators. If any index was elided, the corresponding element of ipa.Indexers is ⎕NULL


PropertySet Function Syntax

PropertySet Function Set ipa

The name of the PropertySet function must be Set, but is case-independent. For example, set, Set, sEt and SET are all valid names for the PropertySet function.

The PropertySet function must be monadic and may not return a result.

ipa is an instance of the internal class PropertyArguments.

In all cases, ipa.Name contains the name of the Property being referenced and NewValue contains the new value(s) for the element(s) of the Property being assigned.

If the Property is Simple, ipa.Indexers is undefined (VALUE ERROR).

If the Property is Numbered, ipa.Indexers is an integer vector of the same length as the rank of the property (as implied by the result of the Shape function) that identifies a single element of the Property whose value is to be set.

If the Property is Keyed, ipa.IndexersSpecified is a Boolean vector with the same length as the rank of the property (as implied by the result of the Shape function). A value of 1 means that an indexing array for the corresponding dimension of the Property was specified, while a value of 0 means that the corresponding dimension was elided.ipa.Indexers is a vector containing the arrays that were specified within the square brackets in the assignment expression. Specifically, ipa.Indexers will contain one fewer elements than, the number of semi-colon (;) separators. If any index was elided, the corresponding element of ipa.Indexers is ⎕NULL. However, if the Keyed Property is being assigned in its entirety, without square-bracket indexing, ipa.Indexers is undefined (VALUE ERROR).


PropertyShape Function Syntax

PropertyShape Function R←Shape {ipa}

The name of the PropertyShape function must be Shape, but is case-independent. For example, shape, Shape, sHape and SHAPE are all valid names for the PropertyShape function.

A PropertyShape function is only called if the Property is a Numbered Property.

The PropertyShape function must be niladic or monadic and must return a result.

If monadic, ipa is an instance of the internal class PropertyArguments. ipa.Name contains the name of the Property being referenced and NewValue and Indexers are undefined (VALUE ERROR).

The result R must be an integer vector or scalar that specifies the rank of the Property. Each element of R specifies the length of the corresponding dimension of the Property. Otherwise, the reference or assignment to the Property will fail with DOMAIN ERROR.

Note that the result R is used by APL to check that the number of indices corresponds to the rank of the Property and that the indices are within the bounds of its dimensions. If not, the reference or assignment to the Property will fail with RANK ERROR or LENGTH ERROR.


Using the Dyalog GUI

You may manipulate Dyalog GUI objects as Instances of built-in (GUI) Classes. This approach supplements (but does not replace) the use of ⎕WC, ⎕WS and so forth.

To create a GUI object using ⎕NEW, the Class is given as the GUI Object name and the Constructor Argument as a vector of (Property Name / Property Value) pairs. For example, to create a Form:

      F1←⎕NEW 'Form' (⊂'Caption' 'Hello World')

Notice however that only perfectly formed name/value pairs are accepted. The highly flexible syntax for specifying Properties by position and omitting levels of enclosure, that is supported by ⎕WC and ⎕WS, is not provided with ⎕NEW.

Naturally, you may reference and assign Properties as before:

      F1.Size
50 50
      F1.Size←20 30

Callbacks (to regular defined functions in the Root or in another space, work exactly as before. If function FOO merely displays its argument:

     ∇ FOO M
[1]    ⎕←M
     ∇

      F1.onMouseUp←'#.FOO'
#.[Form]  MouseUp  78.57142639 44.62540817 1 0

Note that the first item in the event message is a ref to the Instance of the Form.

To create a control such as a Button, it is only necessary to run ⎕NEW inside a ref to the appropriate parent object. For example:

      B1←F1.⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10)))

As illustrated in this example, it is not necessary to assign the resulting Button Instance to a name inside the Form (F1 in this case). However, it is a good idea to do so, so that refs to Instances of controls are expunged when the parent object is expunged. In the example above, expunging F1 will not remove the Form from the screen because B1 still exists as a ref to the Button. So, the following is safer:

       F1.B1←F1.⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10)))

Or perhaps better still,

       F1.(B1←⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10))))

The next topic describes the Temperature Converter (see Interface Guide) implemented in this manner.


Using the Dyalog GUI (Example)

The following function illustrates this approach to manipulating the Dyalog APL GUI using the Temperature Converter example that is described in Chapter 2 of the Dyalog APL Interface Guide manual.

     ∇ TempConv;TITLE;TEMP
[1]    TITLE←'Temperature Converter'
[2]    TEMP←⎕NEW'Form'(('Caption'TITLE)('Posn'(10 10))('Size'(30 40)))
[3]
[4]    TEMP.(MB←⎕NEW⊂'MenuBar')
[5]    TEMP.MB.(M←⎕NEW'Menu'(,⊂'Caption' '&Scale'))
[6]    TEMP.MB.M.(C←⎕NEW'MenuItem'(('Caption' '&Centigrade')('Checked' 1)))
[7]    TEMP.MB.M.(F←⎕NEW'MenuItem'(,⊂('Caption' '&Fahrenheit')))
[8]
[9]    TEMP.(LF←⎕NEW'Label'(('Caption' 'Fahrenheit')('Posn'(10 10))))
[10]   TEMP.(F←⎕NEW'Edit'(('Posn'(10 40))('Size'(⍬ 20))('FieldType' 'Numeric')))
[11]
[12]   TEMP.(LC←⎕NEW'Label'(('Caption' 'Centigrade')('Posn'(40 10))))
[13]   TEMP.(C←⎕NEW'Edit'(('Posn'(40 40))('Size'(⍬ 20))('FieldType' 'Numeric')))
[14]
[15]   TEMP.(F2C←⎕NEW'Button'(('Caption' 'F->C')('Posn'(10 70))('Default' 1)))
[16]   TEMP.(C2F←⎕NEW'Button'(('Caption' 'C->F')('Posn'(40 70))))
[17]   TEMP.(Q←⎕NEW'Button'(('Caption' '&Quit')('Posn'(70 30))('Size'(⍬ 40))('Cancel' 1)))
[18]
[19]   TEMP.(S←⎕NEW'Scroll'(⊂('Range' 101)))
[20]
[21]   TEMP.MB.M.C.onSelect←'SET_C'
[22]   TEMP.MB.M.F.onSelect←'SET_F'
[23]   TEMP.F2C.onSelect←'f2c'
[24]   TEMP.F.onGotFocus←'SET_DEF'
[25]   TEMP.C2F.onSelect←'c2f'
[26]   TEMP.C.onGotFocus←'SET_DEF'
[27]   TEMP.onClose←'QUIT'
[28]   TEMP.Q.onSelect←'QUIT'
[29]   TEMP.S.onScroll←'c2f_scroll'
[30]
[31]   ⎕DQ'TEMP'
     ∇

For brevity, only a couple of the callback functions are shown here.

     ∇ f2c
[1]    TEMP.C.Value←(TEMP.F.Value-32)×5÷9
     ∇
     ∇ c2f_scroll MSG
[1]   ⍝ Callback for Centigrade input via scrollbar
[2]    TEMP.C.Value←101-4⊃MSG
[3]    c2f
     ∇


Writing Classes based on the Dyalog GUI

Dyalog GUI Classes

You may create user-defined Classes based upon Dyalog GUI objects. The Temperature Converter Class and Dual Class illustrate how this can be done.

To base a Class on a Dyalog GUI object, you specify the name of the object as its Base Class. For example, the Temperature Converter is based upon a Form:

:Class Temp: 'Form'

and the Dual Control is based upon a SubForm:

:Class Dual: 'SubForm'

Being based upon a top-level GUI object, the Temperature Converter may be used as follows:

      T1←⎕NEW Temp(⊂'Posn'(68 50))

Notice that the :Implements Constructor statement of its Constructor Make:

:Implements Constructor :Base (⊂'Caption' TITLE),pv,⊂('Size' (30 40))

passes on the application-specific property list (pv) given as its argument, but (in this case) specifies Caption and Size as well. The order in which the properties are specified in the :Base call ensures that the former will act as a default (and be overridden by an application-specific Caption requested in pv), whereas the specified Size of(30 40) will override whatever value of Size is requested by the host application in pv.

Other Instances can co-exist with the first:

      T2←⎕NEW Temp(('Caption' 'My Application')('Posn'(10 10))

The Dual Control requires a GUI parent but several Instances can co-exist, quite independently, in the same parent.

For example, function RUN creates a Form and 3 Instances of Dual; one to convert Centigrade to Fahrenheit, one to convert Fahrenheit to Centigrade, and the third to convert centimetres to inches.

     ∇ RUN;F;D1PROPS;D2PROPS;D3PROPS
[1]
[2]    F←⎕NEW'Form'(('Caption' 'Dual Instances')('Coord' 'Pixel')('Size'(320 320)))
[3]
[4]    D1PROPS←('Caption1' 'Centigrade')('Caption2' 'Fahrenheit')
[5]    D1PROPS,←('Intercept' 32)('Gradient'(9÷5))('Value1' 0)('Range'(0 100))
[6]    F.D1←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(10 10))('Size'(100 300)),D1PROPS)
[7]
[8]    D2PROPS←('Caption1' 'Fahrenheit')('Caption2' 'Centigrade')
[9]    D2PROPS,←('Intercept'(-32×5÷9))('Gradient'(5÷9))('Value1' 0)('Range'(0 212))
[10]   F.D2←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(110 10))('Size'(100 300)),D2PROPS)
[11]
[12]   D3PROPS←('Caption1' 'Centimetres')('Caption2' 'Inches')
[13]   D3PROPS,←('Intercept' 0)('Gradient'(÷2.54))('Value1' 0)('Range'(0 100))
[14]   F.D3←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(210 10))('Size'(100 300)),D3PROPS)
[15]
[16]   ⎕DQ'F'
     ∇

Dual's Constructor Make first splits its constructor arguments into those that apply to the Dual Class itself and those that apply to the SubForm. Its :Implements Constructor statement then passes these on to the Base Constructor, together with an appropriate setting for EdgeStyle.

      :Implements Constructor :Base BaseArgs,⊂'EdgeStyle' 'Dialog'


Writing Classes based on .Net Types

From Version 11.0 onwards you may create user-defined Classes based upon .Net Classes. This feature supercedes the NetType object through which this was achieved in previous Versions of Dyalog APL.

To base a Class on a .Net Type, you simply specify the .Net Type as its Base Class. However, you must also specify the .Net search path with one or more :Using statements.

For example, the following Class called APLGreg derives from the .Net Type GregorianCalendar which is located in the System.Globalization .Net namespace.

:Class APLGreg: GregorianCalendar
:Using System.Globalization
...
:EndClass

Exporting the Class

Unlike other Classes, a Class that derives from a .Net Type must be exported to a .Net Assembly before it can be used. It must be turned into a fully fledged .Net Type before you can access it through .Net.

You may either export your Class (or Classes) to a named Assembly file (DLL) on disk, or you may take advantage of the new Version 11.0 feature and export it to memory. This is done using the Export to Memory menu item on the Session File menu. Export to Memory builds a temporary in-memory .Net Assembly and is intended to speed the development cycle. Note however that in order to use the Class in a live application, it will be necessary to save it to file.

Using the Class

An APL Class that derives from a .Net Class is used in the same way as any other .Net Class. In particular, you must specify the correct .Net search path by setting ⎕USING.

To use a Class that you have just exported to memory, ⎕USING (or an element of ⎕USING) must be set to an empty vector (''). To use a Class that you have exported to a file, ⎕USING must include the path to the file.


Writing Classes based on .Net Types (Example)

Example of a Class based on a .Net Type

The following example illustrates an APL Class that is based upon the .Net Type MailMessage.

:Class MultiMail : MailMessage
:Using System
:Using System.Web.Mail,system.web.dll
⍝ Adds "MultiSend" method to System.Web.Mail.MailMessage
⍝ "MultiSend" sends one message to each To address (separated by ";")
⍝ So that each recipient sees self as sole addressee

    ⎕ML←0

    ∇ r←MultiSend;to;all;t
      :Access Public
      :Signature Int32←MultiSend
      r←⍴to←1↓¨(';'=to)⊂to←';',all←To
      :For t :In to
          To←t
          SmtpMail.Send ⎕THIS
      :EndFor
      To←all
    ∇

:EndClass

The MultiMail Class adds a MultiSend method to the basic System.Web.Mail.MailMessage Type. MultiSend sends a separate message to each of the recipients in the semi-colon separated address list. The result is the number of recipients.

To use the Class, you must first export it as a .Net Assembly (in this case, using the Export to Memory menu item on the Session File menu) and set ⎕USING.

[Export to Memory]

      ⎕USING←''
      z←⎕NEW MultiMail
      z.To←'mkrom@dyalog.com;mkrom@insight.dk'
      z.Subject←'hello'
      z.From←'mkrom@dyalog.com'
      z.Body←'????'
      z.MultiSend
2

The following points are noteworthy:

  • The :Signature statement in function MultiSend defines the signature of the method. It specifies that MultiSend takes no argument and returns a result of Type Int32 (which will be resolved to System.Int32 via ⎕USING)
  • Of the two :Using statements, the first one is required to resolve the reference to Int32 to System.Int32.
  • The second :Using statement is required to resolve the references to MailMessage (in the :Class statement) and SmtpMail (in MultiSend).


System Functions and Variables

System Functions, Variables, Constants and Namespaces provide information and services within the APL environment. Their case-insensitive names begin with ⎕.

⍞ | ⎕ | ⎕Á | ⎕A | ⎕AI
⎕AN | ⎕ARBIN | ⎕ARBOUT | ⎕AT | ⎕AV
⎕AVU | ⎕BASE | ⎕CLASS | ⎕CLEAR | ⎕CMD
⎕CR | ⎕CS | ⎕CT | ⎕CY | ⎕D
⎕DCT | ⎕DF | ⎕DIV | ⎕DL | ⎕DM
⎕DMX | ⎕DQ | ⎕DR | ⎕ED | ⎕EM
⎕EN | ⎕EX | ⎕EXCEPTION | ⎕EXPORT | ⎕FAPPEND
⎕FAVAIL | ⎕FCHK | ⎕FCOPY | ⎕FCREATE | ⎕FDROP
⎕FERASE | ⎕FHIST | ⎕FHOLD | ⎕FIX | ⎕FLIB
⎕FMT | ⎕FNAMES | ⎕FNUMS | ⎕FPROPS | ⎕FR
⎕FRDAC | ⎕FRDCI | ⎕FREAD | ⎕FRENAME | ⎕FREPLACE
⎕FRESIZE | ⎕FSIZE | ⎕FSTAC | ⎕FSTIE | ⎕FTIE
⎕FUNTIE | ⎕FX | ⎕INSTANCES | ⎕IO | ⎕KL
⎕LC | ⎕LOAD | ⎕LOCK | ⎕LX | ⎕MAP
⎕ML | ⎕MONITOR | ⎕NA | ⎕NAPPEND | ⎕NC
⎕NCREATE | ⎕NERASE | ⎕NEW | ⎕NL | ⎕NLOCK
⎕NNAMES | ⎕NNUMS | ⎕NQ | ⎕NR | ⎕NREAD
⎕NRENAME | ⎕NREPLACE | ⎕NRESIZE | ⎕NS | ⎕NSI
⎕NSIZE | ⎕NTIE | ⎕NULL | ⎕NUNTIE | ⎕NXLATE
⎕OFF | ⎕OPT | ⎕OR | ⎕PATH | ⎕PFKEY
⎕PP | ⎕PROFILE | ⎕PW | ⎕R | ⎕REFS
⎕RL | ⎕RSI | ⎕RTL | ⎕S | ⎕SAVE
⎕SD | ⎕SE | ⎕SH | ⎕SHADOW | ⎕SI
⎕SIGNAL | ⎕SIZE | ⎕SM | ⎕SR | ⎕SRC
⎕STACK | ⎕STATE | ⎕STOP | ⎕SVC | ⎕SVO
⎕SVQ | ⎕SVR | ⎕SVS | ⎕TC | ⎕TCNUMS
⎕TGET | ⎕THIS | ⎕TID | ⎕TKILL | ⎕TNAME
⎕TNUMS | ⎕TPOOL | ⎕TPUT | ⎕TRACE | ⎕TRAP
⎕TREQ | ⎕TS | ⎕TSYNC | ⎕UCS | ⎕USING
⎕VFI | ⎕VR | ⎕WA | ⎕WC | ⎕WG
⎕WN | ⎕WS | ⎕WSID | ⎕WX | ⎕XML
⎕XSI | ⎕XT |  |  |


System Variables

System variables retain information used by the system in some way, usually as implicit arguments to functions.

The characteristics of an array assigned to a system variable must be appropriate; otherwise an error will be reported immediately.

Example

      ⎕IO←3
DOMAIN ERROR
      ⎕IO←3
      ^

System variables may be localised by inclusion in the header line of a defined function or in the argument list of the system function ⎕SHADOW. When a system variable is localised, it retains its previous value until it is assigned a new one. This feature is known as “pass-through localisation”. The exception to this rule is ⎕TRAP.

A system variable can never be undefined. Default values are assigned to all system variables in a clear workspace.

Name | Description | Scope
⍞ | Character Input/Output | Session
⎕ | Evaluated Input/Output | Session
⎕AVU | Atomic Vector – Unicode | Namespace
⎕CT | Comparison Tolerance | Namespace
⎕DCT | Decimal Comp Tolerance | Namespace
⎕DIV | Division Method | Namespace
⎕FR | Floating-Point Representation | Workspace
⎕IO | Index Origin | Namespace
⎕LX | Latent Expression | Workspace
⎕ML | Migration Level | Namespace
⎕PATH | Search Path | Session
⎕PP | Print Precision | Namespace
⎕PW | Print Width | Session
⎕RL | Random Link | Namespace
⎕RTL | Response Time Limit | Namespace
⎕SM | Screen Map | Workspace
⎕TRAP | Event Trap | Workspace
⎕USING | Microsoft .Net Search Path | Namespace
⎕WSID | Workspace Identification | Workspace
⎕WX | Window Expose | Namespace

In other words, ⎕, ⍞, ⎕SE, ⎕PATH and ⎕PW relate to the session. ⎕LX, ⎕SM, ⎕TRAP and ⎕WSID relate to the active workspace. All the other system variables relate to the current namespace.

Session | Workspace | Namespace
⍞ | ⎕FR | ⎕AVU
⎕ | ⎕LX | ⎕CT
⎕PATH | ⎕SM | ⎕DCT
⎕PW | ⎕TRAP | ⎕DIV
 | ⎕WSID | ⎕IO
 |  | ⎕ML
 |  | ⎕PP
 |  | ⎕RL
 |  | ⎕RTL
 |  | ⎕USING
 |  | ⎕WX


System Namespaces

⎕SE is currently the only system namespace.


System Constants

System constants, which can be regarded as niladic system functions, return information from the system. They have distinguished names, beginning with the quad symbol, ⎕. A system constant may not be assigned a value. System constants may not be localised or erased. System constants are summarised in the following table:

Name | Description
⎕Á | Underscored Alphabetic upper case characters
⎕A | Alphabetic upper case characters
⎕AI | Account Information
⎕AN | Account Name
⎕AV | Atomic Vector
⎕D | Digits
⎕DM | Diagnostic Message
⎕DMX | Extended Diagnostic Message
⎕EN | Event Number
⎕EXCEPTION | Reports the most recent Microsoft .Net Exception
⎕LC | Line Count
⎕NULL | Null Item
⎕SD | Screen (or window) Dimensions
⎕TC | Terminal Control (backspace, linefeed, newline)
⎕TS | Time Stamp
⎕WA | Workspace Available


System Functions

System functions provide various services related to both the APL and the external environment. System functions have distinguished names beginning with the ⎕ symbol. They are implicitly available in a clear workspace.

The following Figure identifies system functions divided into relevant categories. Each function is described in alphabetical order in this chapter

System Commands

These functions closely emulate system commands (see System Commands)

Name | Description
⎕CLEAR | Clear workspace (WS)
⎕CY | Copy objects into active WS
⎕EX | Expunge objects
⎕LOAD | Load a saved WS
⎕NL | Name List
⎕OFF | End the session
⎕SAVE | Save the active WS

External Environment

These functions provide access to the external environment, such as file systems, Operating System facilities, and input/output devices.

Name | Description
⎕ARBIN | Arbitrary Input
⎕ARBOUT | Arbitrary Output
⎕CMD | Execute the Windows Command Processor or another program
⎕CMD | Start a Windows AP
⎕MAP | Map a file
⎕NA | Declare a DLL function
⎕SH | Execute a UNIX command or another program
⎕SH | Start a UNIX AP

Defined Functions and Operators

These functions provide services related to defined functions and operators.

Name | Description
⎕AT | Object Attributes
⎕CR | Canonical Representation
⎕CS | Change Space
⎕ED | Edit one or more objects
⎕EXPORT | Export objects
⎕FX | Fix definition
⎕LOCK | Lock a function
⎕MONITOR | Monitor set
⎕MONITOR | Monitor query
⎕NR | Nested Representation
⎕NS | Create Namespace
⎕OR | Object Representation
⎕PATH | Search Path
⎕PROFILE | Profile Application
⎕REFS | Local References
⎕SHADOW | Shadow names
⎕STOP | Set Stop vector
⎕STOP | Query Stop vector
⎕THIS | This Space
⎕TRACE | Set Trace vector
⎕TRACE | Query Trace vector
⎕VR | Vector Representation

Error Trapping

These functions are associated with event trapping and the system variable ⎕TRAP.

Name | Description
⎕EM | Event Messages
⎕SIGNAL | Signal event

Shared Variables

These functions provide the means to communicate between APL tasks and with other applications.

Name | Description
⎕SVC | Set access Control
⎕SVC | Query access Control
⎕SVO | Shared Variable Offer
⎕SVO | Query degree of coupling
⎕SVQ | Shared Variable Query
⎕SVR | Retract offer
⎕SVS | Query Shared Variable State

Object Oriented Programming

These functions provide object oriented programming features.

Name | Description
⎕BASE | Base Class
⎕CLASS | Class
⎕DF | Display Format
⎕FIX | Fix
⎕INSTANCES | Instances
⎕NEW | New Instance
⎕SRC | Source
⎕THIS | This

Graphical User Interface

These functions provide access to GUI components.

Name | Description
⎕DQ | Await and process events
⎕NQ | Place an event on the Queue
⎕WC | Create GUI object
⎕WG | Get GUI object properties
⎕WN | Query GUI object Names
⎕WS | Set GUI object properties
⎕WX | Expose GUI property names

External Variables

These functions are associated with using external variables.

Name | Description
⎕XT | Associate External variable
⎕XT | Query External variable
⎕FHOLD | External variable Hold

Component Files

The functions provide the means to store and retrieve data on APL Component Files. See User Guide for further details.

Name | Description
⎕FAPPEND | Append a component to File
⎕FAVAIL | File system Availability
⎕FCHK | File Check and Repair
⎕FCOPY | Copy a File
⎕FCREATE | Create a File
⎕FDROP | Drop a block of components
⎕FERASE | Erase a File
⎕FHIST | File History
⎕FHOLD | File Hold
⎕FLIB | List File Library
⎕FNAMES | Names of tied Files
⎕FNUMS | Tie Numbers of tied Files
⎕FPROPS | File Properties
⎕FRDAC | Read File Access matrix
⎕FRDCI | Read Component Information
⎕FREAD | Read a component from File
⎕FRENAME | Rename a File
⎕FREPLACE | Replace a component on File
⎕FRESIZE | File Resize
⎕FSIZE | File Size
⎕FSTAC | Set File Access matrix
⎕FSTIE | Share-Tie a File
⎕FTIE | Tie a File exclusively
⎕FUNTIE | Untie Files

Native Files

The functions provide the means to store and retrieve data on native files.

Name | Description
⎕NAPPEND | Append to File
⎕NCREATE | Create a File
⎕NERASE | Erase a File
⎕NLOCK | Lock a region of a file
⎕NNAMES | Names of tied Files
⎕NNUMS | Tie Numbers of tied Files
⎕NREAD | Read from File
⎕NRENAME | Rename a File
⎕NREPLACE | Replace data on File
⎕NRESIZE | File Resize
⎕NSIZE | File Size
⎕NTIE | Tie a File exclusively
⎕NUNTIE | Untie Files
⎕NXLATE | Specify Translation Table

Threads

These functions are associated with threads created using the Spawn operator (&).

Name | Description
⎕TCNUMS | Thread Child Numbers
⎕TGET | Get Tokens
⎕TID | Current Thread Identity
⎕TKILL | Kill Threads
⎕TNAME | Current Thread Name
⎕TNUMS | Thread Numbers
⎕TPOOL | Token Pool
⎕TPUT | Put Tokens
⎕TREQ | Token Requests
⎕TSYNC | Wait for Threads to Terminate

Search and Replace

These operators implement Search and Replace functionality utilising the open-source regular-expression search engine PCRE.

Name | Description
⎕R | Replace
⎕S | Search
⎕OPT | Variant Operator

Miscellaneous

These functions provide various miscellaneous services.

Name | Description
⎕AVU | Atomic Vector - Unicode
⎕DL | Delay execution
⎕DR | Data Representation (Monadic)
⎕DR | Data Representation (Dyadic)
⎕FMT | Resolve display
⎕FMT | Format array
⎕KL | Key Labels
⎕NC | Name Classification
⎕NSI | Namespace Indicator
⎕PFKEY | Programmable Function Keys
⎕RSI | Space Indicator
⎕SI | State Indicator
⎕SIZE | Size of objects
⎕SR | Screen Read
⎕STACK | Report Stack
⎕STATE | Return State of an object
⎕UCS | Unicode Convert
⎕VFI | Verify and Fix numeric
⎕XSI | Extended State Indicator


Fix Definition

Fix Definition: {R}←⎕FX Y

Y is the representation form of a function or operator which may be:

  • its canonical representation form similar to that produced by ⎕CR except that redundant blanks are permitted other than within names and constants.
  • its nested representation form similar to that produced by ⎕NR except that redundant blanks are permitted other than within names and constants.
  • its object representation form produced by ⎕OR.
  • its vector representation form similar to that produced by ⎕VR except that additional blanks are permitted other than within names and constants.

⎕FX attempts to create (fix) a function or operator in the workspace or current namespace from the definition given by Y. ⎕IO is an implicit argument of ⎕FX.

If the function or operator is successfully fixed, R is a simple character vector containing its name and the result is shy. Otherwise R is an integer scalar containing the (⎕IO dependent) index of the row of the canonical representation form in which the first error preventing its definition is detected. In this case the result R is not shy.

Functions and operators which are pendent, that is, in the State Indicator without a suspension mark (*), retain their original definition until they complete, or are cleared from the State Indicator. All other occurrences of the function or operator assume the new definition. The function or operator will fail to fix if it has the same name as an existing variable, or a visible label.


Canonical Representation

Canonical Representation: R←⎕CR Y

Y must be a simple character scalar or vector which represents the name of a defined function or operator.

If Y is a name of a defined function or operator, R is a simple character matrix. The first row of R is the function or operator header. Subsequent rows are lines of the function or operator. R contains no unnecessary blanks, except for leading indentation of control structures, trailing blanks that pad each row, and the blanks in comments. If Y is the name of a variable, a locked function or operator, an external function, or is undefined, R is an empty matrix whose shape is 0 0.

Example

      ∇R←MEAN X    ⍝ Arithmetic mean
[1]  R←(+/X)÷⍴X
[2]  ∇
      +F←⎕CR'MEAN'
R←MEAN X    ⍝ Arithmetic mean
R←(+/X)÷⍴X

      ⍴F
2 30

The definition of ⎕CR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators.

If Y is a name assigned to a primitive function, R is a one-element vector containing the corresponding function symbol. If Y is a name assigned to a system function, R is a one element nested array containing the name of the system function.

Examples

      PLUS←+
      +F←⎕CR'PLUS'
+
      ⍴F
1
      C←⎕CR
      C'C'
 ⎕CR
      ⍴C'C'
1

      ∇R←CONDITION (FN1 ELSE FN2) X
[1]   →CONDITION/L1
[2]   R←FN2 X ⋄ →0
[3]  L1:R←FN1 X
[4]   ∇

      2 ⎕STOP 'ELSE'
      (X≥0) ⌊ ELSE ⌈ X←¯2.5

ELSE[2]
       X
¯2.5
       ⎕CR'FN2'
⌈
       →⎕LC
¯2

If Y is a name assigned to a derived function, R is a vector whose elements represent the arrays, functions, and operators from which Y was constructed. Constituent functions are represented by their own ⎕CRs, so in this respect the definition of ⎕CR is recursive. Primitive operators are treated like primitive functions, and are represented by their corresponding symbols. Arrays are represented by themselves.

Example

      BOX←2 2∘⍴
      +F←⎕CR'BOX'
 2 2 ∘⍴
      ⍴F
3
      ]display F
.→----------.
| .→--.     |
| |2 2| ∘ ⍴ |
| '~--' - - |
'∊----------'

If Y is a name assigned to a defined function, R is the ⎕CR of the defined function. In particular, the name that appears in the function header is the name of the original defined function, not the assigned name Y.

Example

      AVERAGE←MEAN
      ⎕CR'AVERAGE'
R←MEAN X    ⍝ Arithmetic mean
R←(+/X)÷⍴X


Nested Representation

Nested Representation: R←⎕NR Y

Y must be a simple character scalar or vector which represents the name of a function or a defined operator.

If Y is a name of a defined function or defined operator, R is a vector of text vectors. The first element of R contains the text of the function or operator header. Subsequent elements contain lines of the function or operator. Elements of R contain no unnecessary blanks, except for leading indentation of control structures and the blanks which precede comments.

If Y is the name of a variable, a locked function or operator, an external function or a namespace, or is undefined, R is an empty vector.

Example

      ∇R←MEAN X    ⍝ Average
[1]   R←(+/X)÷⍴X
      ∇

      +F←⎕NR'MEAN'
  R←MEAN X    ⍝Average   R←(+/X)÷⍴X

      ⍴F
2
      ]display F
.→----------------------------------------.
| .→---------------------.  .→----------. |
| | R←MEAN X    ⍝ Average|  | R←(+/X)÷⍴X| |
| '----------------------'  '-----------' |
'∊----------------------------------------'

The definition of ⎕NR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators. In these cases, the result of ⎕NR is identical to that of ⎕CR except that the representation of defined functions and operators is as described above.

Example

      AVG←MEAN∘,

      +F←⎕NR'AVG'
   R←MEAN X    ⍝ Average   R←(+/X)÷⍴X  ∘,

      ⍴F
3
      ]display F
.→------------------------------------------------.
| .→----------------------------------------.     |
| | .→---------------------.  .→----------. | ∘ , |
| | | R←MEAN X    ⍝ Average|  | R←(+/X)÷⍴X| | - - |
| | '----------------------'  '-----------' |     |
| '∊----------------------------------------'     |
'∊------------------------------------------------'


Vector Representation

Vector Representation: R←⎕VR Y

Y must be a simple character scalar or vector which represents the name of a function or defined operator.

If Y is the name of a defined function or defined operator, R is a simple character vector containing a character representation of the function or operator with each line except the last terminated by the newline character (⎕TC[3]). Its display form is as follows:

  1. the header line starts at column 8 with the ∇ symbol in column 6,
  2. the line number for each line of the function starts in column 1,
  3. the statement contained in each line starts at column 8 except for labelled lines or lines beginning with ⍝ which start at column 7,
  4. the header line and statements contain no redundant blanks beyond column 7 except that the ⋄ separator is surrounded by single blanks, control structure indentation is preserved and comments retain embedded blanks as originally defined,
  5. the last line shows only the ∇ character in column 6.

If Y is the name of a variable, a locked function or operator, an external function, or is undefined, R is an empty vector.

Example

      ⍴V←⎕VR'PLUS'
128

      V
     ∇ R←{A}PLUS B
[1]   ⍝ MONADIC OR DYADIC +
[2]    →DYADIC⍴⍨2=⎕NC'A' ⋄ R←B ⋄ →END
[3]   DYADIC:R←A+B ⋄ →END
[4]   END:
     ∇

The definition of ⎕VR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators. In these cases, the result of ⎕VR is identical to that of ⎕CR except that the representation of defined functions and operators is as described above.

Example

      AVG←MEAN∘,

      +F←⎕VR'AVG'
      ∇ R←MEAN X    ⍝ Arithmetic mean
[1]    R←(+/X)÷⍴X
     ∇ ∘,

      ⍴F
3

      ]display F
.→-------------------------------------------.
| .→-----------------------------------.     |
| |     ∇ R←MEAN X    ⍝ Arithmetic mean| ∘ , |
| |[1]    R←(+/X)÷⍴X                   | - - |
| |     ∇                              |     |
| '------------------------------------'     |
'∊-------------------------------------------'


Object Representation

Object Representation: R←⎕OR Y

⎕OR converts a function, operator or namespace to a special form, described as its object representation, that may be assigned to a variable and/or stored on a component file. Classes and Instances are however outside the domain of ⎕OR.

Taking the ⎕OR of a function or operator is an extremely fast operation as it simply changes the type information in the object’s header, leaving its internal structure unaltered. Converting the object representation back to an executable function or operator using ⎕FX is also very fast. ⎕OR is therefore the recommended form for storing functions and operators on component files and is significantly faster than using ⎕CR, ⎕VR or ⎕NR.

However, the saved results of ⎕OR which were produced on a different hardware platform or using an older Version of Dyalog APL may require a significant amount of processing when re-constituted using ⎕FX. For optimum performance, it is strongly recommended that you save ⎕ORs using the same Version of Dyalog APL and on the same hardware platform that you will use to ⎕FX them.

⎕OR may also be used to convert a namespace (either a plain namespace or a named GUI object created by ⎕WC) into a form that can be stored in a variable or on a component file. The namespace may be reconstructed using ⎕NS or ⎕WC with its original name or with a new one. ⎕OR may therefore be used to clone a namespace or GUI object.

Y must be a simple character scalar or vector which contains the name of an APL object.

If Y is the name of a variable, the result R is its value. In this case, R←⎕OR Y is identical to R←⍎Y.

Otherwise, R is a special form of the name Y, re-classified as a variable. The rank of R is 0 (R is scalar), and the depth of R is 1. These unique characteristics distinguish the result of ⎕OR from any other object. The type of R (∊R) is itself. Note that although R is scalar, it may not be index assigned to an element of an array unless it is enclosed.

If Y is the name of a function or operator, R is in the domain of the monadic functions Depth (≡), Disclose (⊃), Enclose (⊂), Rotate (⌽), Transpose (⍉), Indexing ([]), Format (⍕), Identity (+), Shape (⍴), Type (∊) and Unique (∪), of the dyadic functions Assignment (←), Without (~), Index Of (⍳), Intersection (∩), Match (≡), Membership (∊), Not Match (≠) and Union (∪), and of the monadic system functions Canonical Representation (⎕CR), Cross-Reference (⎕REFS), Fix (⎕FX), Format (⎕FMT), Nested Representation (⎕NR) and Vector Representation (⎕VR).

Nested arrays which include the object representations of functions and operators are in the domain of many mixed functions which do not use the values of items of the arrays.

Note that a ⎕OR object can be transmitted through an 'APL-style' TCP socket. This technique may be used to transfer objects including namespaces between APL sessions.

The object representation forms of namespaces produced by ⎕OR may not be used as arguments to any primitive functions. The only operations permitted for such objects (or arrays containing such objects) are ⎕EX, ⎕FAPPEND, ⎕FREPLACE, ⎕NS, and ⎕WC.

Example

      F←⎕OR ⎕FX'R←FOO' 'R←10'

      ⍴F

      ⍴⍴F
0
      ≡F
1
      F≡∊F
1

The display of the ⎕OR form of a function or operator is a listing of the function or operator. If the ⎕OR form of a function or operator has been enclosed, then the result will display as the operator name preceded by the symbol ∇. It is permitted to apply ⎕OR to a locked function or operator. In this instance the result will display as for the enclosed form.

Examples

       F
      ∇ R←FOO
[1]     R←10
      ∇

      ⊂F
 ∇FOO

      ⎕LOCK'FOO'

      ⎕OR'FOO'
∇FOO
      A←⍳5

      A[3]←⊂F

      A
1 2  ∇FOO  4 5

For the ⎕OR forms of two functions or operators to be considered identical, their unlocked display forms must be the same, they must either both be locked or unlocked, and any monitors, trace and stop vectors must be the same.

Example

      F←⎕OR ⎕FX 'R←A PLUS B' 'R←A+B'

      F≡⎕OR 'PLUS'
1

      1 ⎕STOP 'PLUS'

      F≡⎕OR 'PLUS'
0

Namespace Examples

The following example sets up a namespace called UTILS, copies into it the contents of the UTIL workspace, then writes it to a component file:

      )CLEAR
clear ws
      )NS UTILS
#.UTILS
      )CS UTILS
#.UTILS
      )COPY UTIL
C:\WDYALOG\WS\UTIL saved Fri Mar 17 12:48:06 1995
      )CS
#
      'ORTEST' ⎕FCREATE 1
      (⎕OR'UTILS')⎕FAPPEND 1

The namespace can be restored with ⎕NS, using either the original name or a new one:

      )CLEAR
clear ws
      'UTILS' ⎕NS ⎕FREAD 1 1
#.UTILS
      )CLEAR
clear ws
      'NEWUTILS' ⎕NS ⎕FREAD 1 1
#.NEWUTILS

This example illustrates how ⎕OR can be used to clone a GUI object; in this case a Group containing some Button objects. Note that ⎕WC will accept only a ⎕OR object as its argument (or preceded by the “Type” keyword). You may not specify any other properties in the same ⎕WC statement, but you must instead use ⎕WS to reset them afterwards.

    'F'⎕WC'Form'
    'F.G1' ⎕WC 'Group' '&One' (10 10)(80 30)
    'F.G1.B2'⎕WC'Button' '&Blue' (40 10)('Style' 'Radio')
    'F.G1.B3'⎕WC'Button' '&Green' (60 10)('Style' 'Radio')
    'F.G1.B1'⎕WC'Button' '&Red' (20 10)('Style' 'Radio')
    'F.G2' ⎕WC ⎕OR 'F.G1'
    'F.G2' ⎕WS ('Caption' 'Two')('Posn' 10 60)

Note too that ⎕WC and ⎕NS may be used interchangeably to rebuild pure namespaces or GUI namespaces from a ⎕OR object. You may therefore use ⎕NS to rebuild a Form or use ⎕WC to rebuild a pure namespace that has no GUI components.


Attributes

Attributes: R←{X} ⎕AT Y

Y can be a simple character scalar, vector or matrix, or a vector of character vectors representing the names of 0 or more defined functions or operators. Used dyadically, this function closely emulates the APL2 implementation. Used monadically, it returns information that is more appropriate for Dyalog APL.

Y specifies one or more names. If Y specifies a single name as a character scalar, a character vector, or as a scalar enclosed character vector, the result R is a vector. If Y specifies one or more names as a character matrix or as a vector of character vectors R is a matrix with one row per name in Y.

Monadic Use

If X is omitted, R is a 4-element vector or a 4 column matrix with the same number of rows as names in Y containing the following attribute information:

R[1] or R[;1]: Each item is a 3-element integer vector representing the function header syntax:

1 | Function result | 0 if the function has no result 1 if the function has an explicit result ¯1 if the function has a shy result
2 | Function valence | 0 if the object is a niladic function or not a function 1 if the object is a monadic function 2 if the object is a dyadic function ¯2 if the object is an ambivalent function
3 | Operator valence | 0 if the object is not an operator 1 if the object is a monadic operator 2 if the object is a dyadic operator

The following values correspond to the syntax shown alongside:

        0  0  0     ∇ FOO
        1  0  0     ∇ Z←FOO
       ¯1  0  0     ∇ {Z}←FOO
        0 ¯2  0     ∇ {A} FOO B
       ¯1  1  2     ∇ {Z}←(F OP G)B

R[2] or R[;2]: Each item is the (⎕TS form) timestamp of the time the function was last fixed.

R[3] or R[;3]: Each item is an integer reporting the current ⎕LOCK state of the function:

0 | Not locked
1 | Cannot display function
2 | Cannot suspend function
3 | Cannot display or suspend

R[4] or R[;4]: Each item is a character vector - the network ID of the user who last fixed (edited) the function.

Example

    ∇ {z}←{l}(fn myop)r
[1]   ...

    ∇ z←foo
[1]   ...

    ∇ z←{larg}util rarg
[1]   ...

      ⎕LOCK'foo'

      util2←util

      ]display ⎕AT 'myop' 'foo' 'util' 'util2'
.→--------------------------------------------.
↓ .→------. .→-----------------.     .→---.   |
| |¯1 ¯2 1| |1996 8 2 2 13 56 0|   0 |john|   |
| '~------' '~-----------------'     '----'   |
| .→----.   .→------------.          .⊖.      |
| |1 0 0|   |0 0 0 0 0 0 0|        3 | |      |
| '~----'   '~------------'          '-'      |
| .→-----.  .→------------------.    .→---.   |
| |1 ¯2 0|  |1996 3 1 14 12 10 0|  0 |pete|   |
| '~-----'  '~------------------'    '----'   |
| .→-----.  .→-------------------.   .→-----. |
| |1 ¯2 0|  |1998 8 26 16 16 42 0| 0 |graeme| |
| '~-----'  '~-------------------'   '------' |
'∊--------------------------------------------'

Dyadic Use

The dyadic form of ⎕AT emulates APL2. It returns the same rank and shape result containing information that matches the APL2 implementation as closely as possible.

The number of elements or columns in R and their meaning depends upon the value of X which may be 1, 2, 3 or 4.

If X is 1, R specifies valences and contains 3 elements (or columns) whose meaning is as follows:

1 | Explicit result | 1 if the object has an explicit result or is a variable 0 otherwise
2 | Function valence | 0 if the object is a niladic function or not a function 1 if the object is a monadic function 2 if the object is an ambivalent function
3 | Operator valence | 0 if the object is not an operator 1 if the object is a monadic operator 2 if the object is a dyadic operator

If X is 2, R specifies fix times (the time the object was last updated) for functions and operators named in Y. The time is reported as 7 integer elements (or columns) whose meaning is as follows. The fix time reported for names in Y which are not defined functions or operators is 0.

1 | Year
2 | Month
3 | Day
4 | Hour
5 | Minute
6 | Second
7 | Milliseconds (this is always reported as 0)

If X is 3, R specifies execution properties and contains 4 elements (or columns) whose meaning is as follows:

1 | Displayable | 0 if the object is displayable 1 if the object is not displayable
2 | Suspendable | 0 if execution will suspend in the object 1 if execution will not suspend in the object
3 | Weak Interrupt behaviour | 0 if the object responds to interrupt 1 if the object ignores interrupt
4 |  | (always 0)

If X is 4, R specifies object size and contains 2 elements (or columns) which both report the ⎕SIZE of the object.


Size of Object

Size of Object: R←⎕SIZE Y

Y must be a simple character scalar, vector or matrix, or a vector of character vectors containing a list of names. R is a simple integer vector of non-negative elements with the same length as the number of names in Y.

If the name in Y identifies an object with an active referent, the workspace required in bytes by that object is returned in the corresponding element of R. Otherwise, 0 is returned in that element of R.

The result returned for an external variable is the space required to store the external array. The result for a system constant, variable or function is 0. The result returned for a GUI object gives the amount of workspace needed to store it, but excludes the space required for its children.

Note: Wherever possible, Dyalog APL shares the whole or part of a workspace object rather than generates a separate copy; however ⎕SIZE reports the size as though nothing is shared. ⎕SIZE also includes the space required for the interpreter's internal information about the object in question.

Examples

      ⎕VR 'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      A←⍳10

      'EXT/ARRAY' ⎕XT'E' ⋄ E←⍳20

      ⎕SIZE 'A' 'FOO' 'E' 'UND'
28 76 120 0


Create Namespace

Create Namespace: {R}←{X}⎕NS Y

If specified, X must be a simple character scalar or vector identifying the name of a namespace.

Y is either a character array which represents a list of names of objects to be copied into the namespace, or is an array produced by the ⎕OR of a namespace.

In the first case, Y must be a simple character scalar, vector, matrix or a nested vector of character vectors identifying zero or more workspace objects to be copied into the namespace X. The identifiers in X and Y may be simple names or compound names separated by '.' and including the names of the special namespaces '#', '##' and '⎕SE'.

The namespace X is created if it doesn't already exist. If the name is already in use for an object other than a namespace, APL issues a DOMAIN ERROR.

If X is omitted, an unnamed namespace is created.

The objects identified in the list Y are copied into the namespace X.

If X is specified, the result R is the full name (starting with #. or ⎕SE.) of the namespace X. If X is omitted, the result R is a namespace reference, or ref, to an unnamed namespace.

Examples

      +'X'⎕NS''               ⍝ Create namespace X.
#.X
      ⊢'X'⎕NS'VEC' 'UTIL.DISP'⍝ Copy VEC and DISP to X.
#.X
      )CS X                   ⍝ Change to namespace X.
#.X
      ⊢'Y'⎕NS'#.MAT' '##.VEC' ⍝ Create #.X.Y &copy in
#.X.Y
      ⊢'#.UTIL'⎕NS'Y.MAT'     ⍝ Copy MAT from Y to UTIL #.UTIL.
#.UTIL
      ⊢'#'⎕NS'Y'              ⍝ Copy namespace Y to root.
#
      ⊢''⎕NS'#.MAT'           ⍝ Copy MAT to currentspace.
#.X
      ⊢''⎕NS''                ⍝ Display current space.
#.X
      ⊢'Z'⎕NS ⎕OR'Y'          ⍝ Create nspace from ⎕OR.
#.X.Z
      NONAME←⎕NS ''           ⍝ Create unnamed nspace
      NONAME
#.[Namespace]
      DATA←⎕NS¨3⍴⊂''         ⍝ Create 3-element vector of
                             ⍝ distinct unnamed nspaces
      DATA
 #.[Namespace]  #.[Namespace]  #.[Namespace]

The second case is where Y is the ⎕OR of a namespace.

If Y is the ⎕OR of a GUI object, #.Z must be a valid parent for the GUI object represented by Y, or the operation will fail with a DOMAIN ERROR.

Otherwise, the result of the operation depends upon the existence of Z.

  • If Z does not currently exist (name class is 0), Z is created as a complete copy (clone) of the original namespace represented by Y. If Y is the ⎕OR of a GUI object or of a namespace containing GUI objects, the corresponding GUI components of Y will be instantiated in Z.
  • If Z is the name of an existing namespace (name class 9), the contents of Y, including any GUI components, are merged into Z. Any items in Z with corresponding names in Y (names with the same path in both Y and Z) will be replaced by the names in Y, unless they have a conflicting name class in which case the existing items in Z will remain unchanged. However, all GUI spaces in Z will be stripped of their GUI components prior to the merge operation.


Change Space

Change Space: {R}←{X}⎕CS Y

Y must be namespace reference (ref) or a simple character scalar or vector identifying the name of a namespace.

If specified, X is a simple character scalar, vector, matrix or a nested vector of character vectors identifying zero or more workspace objects to be exported into the namespace Y.

The identifiers in X and Y may be simple names or compound names separated by '.' and including the names of the special namespaces '⎕SE', '#', and '##'.

The result R is the full name (starting #.) of the space in which the function or operator was executing prior to the ⎕CS.

⎕CS changes the space in which the current function or operator is running to the namespace Y and returns the original space, in which the function was previously running, as a shy result. After the ⎕CS, references to global names (with the exception of those specified in X) are taken to be references to global names in Y. References to local names (i.e. those local to the current function or operator) are, with the exception of those with name class 9, unaffected. Local names with name class 9 are however no longer visible.

When the function or operator terminates, the calling function resumes execution in its original space.

The names listed in X are temporarily exported to the namespace Y. If objects with the same name exist in Y, these objects are effectively shadowed and are inaccessible. Note that Dyadic ⎕CS may be used only if there is a traditional function in the state indicator (stack). Otherwise there would be no way to retract the export. In this case (for example in a clear workspace) DOMAIN ERROR is reported.

Note that calling ⎕CS with an empty argument Y obtains the namespace in which a function is currently executing.

Example

This simple example illustrates how ⎕CS may be used to avoid typing long pathnames when building a tree of GUI objects. Note that the objects NEW and OPEN are created as children of the FILE menu as a result of using ⎕CS to change into the F.MB.FILE namespace.

     ∇ MAKE_FORM;F;OLD
[1]    'F'⎕WC'Form'
[2]    'F.MB'⎕WC'MenuBar'
[3]    'F.MB.FILE'⎕WC'Menu' '&File'
[4]
[5]    OLD←⎕CS'F.MB.FILE'
[6]    'NEW'⎕WC'MenuItem' '&New'
[7]    'OPEN'⎕WC'MenuItem' '&Open'
[8]    ⎕CS OLD
[9]
[10]   'F.MB.EDIT'⎕WC'Menu' '&Edit'
[11]
[12]   OLD←⎕CS'F.MB.EDIT'
[13]   'UNDO'⎕WC'MenuItem' '&Undo'
[14]   'REDO'⎕WC'MenuItem' '&Redo'
[15]   ⎕CS OLD
[16]   ...
     ∇

Example

Suppose a form F1 contains buttons B1 and B2. Each button maintains a count of the number of times it has been pressed, and the form maintains a count of the total number of button presses. The single callback function PRESS and its subfunction FMT can reside in the form itself

      )CS F1
#.F1
      ⍝ Note that both instances reference
      ⍝ the same callback function
      'B1'⎕WS'Event' 'Select' 'PRESS'
      'B2'⎕WS'Event' 'Select' 'PRESS'

      ⍝ Initialise total and instance counts.
      TOTAL ← B1.COUNT ← B2.COUNT ← 0

    ∇ PRESS MSG
[1]   'FMT' 'TOTAL'⎕CS⊃MSG ⍝     Switch to instance space
[2]   (TOTAL COUNT)+←1   ⍝    Incr total & instance count
[3]   ⎕WS'Caption'(COUNT FMT TOTAL)⍝ Set instance caption
    ∇

    ∇ CAPT←INST FMT TOTL      ⍝ Format button caption.
[1]   CAPT←(⍕INST),'/',⍕TOTL  ⍝ E.g. 40/100.
    ∇

Example

This example uses ⎕CS to explore a namespace tree and display the structure. Note that it must export its own name (tree) each time it changes space, because the name tree is global.

      ∇ tabs tree space;subs     ⍝ Display namespace tree
[1]    tabs,space
[2]    'tree'⎕CS space
[3]    →(⍴subs←↓⎕NL 9)↓0
[4]    (tabs,'.   ')∘tree¨subs
     ∇

      )ns x.y
#.x.y
      )ns z
#.z
      ''tree '#'
#
.   x
.   .   y
.   z


Copy Workspace

Copy Workspace: {X}⎕CY Y

Y must be a simple character scalar or vector identifying a saved workspace. X is optional. If present, it must be a simple character scalar, vector or matrix. A scalar or vector is treated as a single row matrix. Each (implied) row of X is interpreted as an APL name.

Each (implied) row of X is taken to be the name of an active object in the workspace identified by Y. If X is omitted, the names of all defined active objects in that workspace are implied (defined functions and operators, variables, labels and namespaces).

Each object named in X (or implied) is copied from the workspace identified by Y to become the active object referenced by that name in the active workspace if the object can be copied. A copied label is re-defined to be a variable of numeric type. If the name of the copied object has an active referent in the active workspace, the name is disassociated from its value and the copied object becomes the active referent to that name. In particular, a function in the state indicator which is disassociated may be executed whilst it remains in the state indicator, but it ceases to exist for other purposes, such as editing.

You may copy an object from a namespace by specifying its full pathname. The object will be copied to the current namespace in the active workspace, losing its original parent and gaining a new one in the process. You may only copy a GUI object into a namespace that is a suitable parent for that object. For example, you could only copy a Group object from a saved workspace if the current namespace in the active workspace is itself a Form, SubForm or Group.

See Copy Workspace: for further information and, in particular, the manner in which dependant objects are copied.

A DOMAIN ERROR is reported in any of the following cases:

  • Y is ill-formed, or is not the name of a workspace with access authorised for the active user account.
  • Any name in X is ill-formed.
  • An object named in X does not exist as an active object in workspace named in Y.

An object being copied has the same name as an active label.

When copying data between Classic and Unicode Editions, ⎕CY will fail and a TRANSLATION ERROR will be reported if any object in workspace Y fails conversion between Unicode and ⎕AV indices, whether or not that object is specified by X. See Atomic Vector - Unicode: for further details.

A WS FULL is reported if the active workspace becomes full during the copying process.

Example

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇
      'FOO' ⎕CY 'BACKUP'
      ⎕VR'FOO'
     ∇ R←FOO X
[1]    R←10×X
     ∇

System variables are copied if explicitly included in the left argument, but not if the left argument is omitted.

Example

      ⎕LX

      (2 3⍴'⎕LX  X')⎕CY'WS/CRASH'
      ⎕LX
→RESTART

A copied object may have the same name as an object being executed. If so, the name is disassociated from the existing object, but the existing object remains defined in the workspace until its execution is completed.

Example

      )SI
#.FOO[1]*

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      'FOO'⎕CY'WS/MYWORK'

      FOO
1 2 3
      )SI
#.FOO[1]*
      →⎕LC
10


Edit Object

Edit Object: {R}←{X}⎕ED Y

⎕ED invokes the Editor. Y is a simple character vector, a simple character matrix, or a vector of character vectors, containing the name(s) of objects to be edited. The optional left argument X is a character scalar or character vector with as many elements as there are names in Y. Each element of X specifies the type of the corresponding (new) object named in Y, where:

∇ | function/operator
→ | simple character vector
∊ | vector of character vectors
- | character matrix
⍟ | Namespace script
○ | Class script
∘ | Interface

If an object named in Y already exists, the corresponding type specification in X is ignored.

If ⎕ED is called from the Session, it opens Edit windows for the object(s) named in Y and returns a null result. The cursor is positioned in the first of the Edit windows opened by ⎕ED, but may be moved to the Session or to any other window which is currently open. The effect is almost identical to using )ED.

If ⎕ED is called from a defined function or operator, its behaviour is different. On asynchronous terminals, the Edit windows are automatically displayed in "full-screen" mode (ZOOMED). In all implementations, the user is restricted to those windows named in Y. The user may not skip to the Session even though the Session may be visible

⎕ED terminates and returns a result ONLY when the user explicitly closes all the windows for the named objects. In this case the result contains the names of any objects which have been changed, and has the same structure as Y.


Expunge Object

Expunge Object: {R}←⎕EX Y

Y must be a simple character scalar, vector or matrix, or a vector of character vectors containing a list of names. R is a simple Boolean vector with one element per name in Y.

Each name in Y is disassociated from its value if the active referent for the name is a defined function, operator, variable or namespace.

The value of an element of R is 1 if the corresponding name in Y is now available for use. This does not necessarily mean that the existing value was erased for that name. A value of 0 is returned for an ill-formed name or for a distinguished name in Y. The result is suppressed if not used or assigned.

Examples

      ⎕EX'VAR'
      +⎕EX'FOO' '⎕IO' 'X' '123'
1 0 1 0

If a named object is being executed the existing value will continue to be used until its execution is completed. However, the name becomes available immediately for other use.

Examples

      )SI
#.FOO[1]*

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇
      +⎕EX'FOO'
1
      )SI
#.FOO[1]*

     ∇FOO[⎕]
defn error

      FOO←1 2 3
      →⎕LC
10
      FOO
1 2 3

If a named object is an external variable, the external array is disassociated from the name:

      ⎕XT'F'
FILES/COSTS
      ⎕EX'F' ⋄ ⎕XT'F'

If the named object is a GUI object, the object and all its children are deleted and removed from the screen. The expression ⎕EX'.' deletes all objects owned by the current thread except for the Root object itself. In addition, if this expression is executed by thread 0, it resets all the properties of '.' to their default values. Furthermore, any unprocessed events in the event queue are discarded.

If the named object is a shared variable, the variable is retracted.

If the named object is the last remaining external function of an auxiliary process, the AP is terminated.

If the named object is the last reference into a dynamic link library, the DLL is freed.


Export Object

Export Object: {R}←{X}⎕EXPORT Y

⎕EXPORT is used to set or query the export type of a defined function (or operator) referenced by the ⎕PATH mechanism.

Y is a character matrix or vector-of-vectors representing the names of functions and operators whose export type is to be set or queried.

X is an integer scalar or vector (one per name in the namelist) indicating the export type. X can currently be one of the values:

  • 0 - not exported.
  • 1 - exported (default).

A scalar or 1-element-vector type is replicated to conform with a multi-name list.

The result R is a vector that reports the export type of the functions and operators named in Y. When used dyadically to set export type, the result is shy.

When the path mechanism locates a referenced function (or operator) in the list of namespaces in the ⎕PATH system variable, it examines the function’s export type:

0 | This instance of the function is ignored and the search is resumed at the next namespace in the ⎕PATH list. Type-0 is typically used for functions residing in a utility namespace which are not themselves utilities, for example the private sub-function of a utility function.
1 | This instance of the function is executed in the namespace in which is was found and the search terminated. The effect is exactly as if the function had been referenced by its full path name.

Warning: The left domain of ⎕EXPORT may be extended in future to include extra types 2, 3,... (for example, to change the behaviour of the function). This means that, while ⎕EXPORT returns a Boolean result in the first version, this may not be the case in the future. If you need a Boolean result, use 0≠ or an equivalent.

   (0≠⎕EXPORT ⎕nl 3 4)⌿⎕nl 3 4  ⍝ list of exported
                                ⍝ functions and ops.


Search Path

Search Path: ⎕PATH

⎕PATH is a simple character vector representing a blank-separated list of namespaces. It is approximately analogous to the PATH variable in Windows or UNIX

The ⎕PATH variable can be used to identify a namespace in which commonly used utility functions reside. Functions or operators (NOT variables) which are copied into this namespace and exported (see Export Object:) can then be used directly from anywhere in the workspace without giving their full path names.

Example

To make the DISPLAY function available directly from within any namespace.

      ⍝ Create and reference utility namespace.
      ⎕PATH←'⎕se.util'⎕ns''
      ⍝ Copy DISPLAY function from UTIL into it.
      'DISPLAY'⎕se.util.⎕cy'UTIL'
      ⍝ (Remember to save the session to file).

In detail, ⎕PATH works as follows:

When a reference to a name cannot be found in the current namespace, the system searches for it from left to right in the list of namespaces indicated by ⎕PATH. In each namespace, if the name references a defined function (or operator) and the export type of that function is non-zero (see Export Object: ), then it is used to satisfy the reference. If the search exhausts all the namespaces in ⎕PATH without finding a qualifying reference, the system issues a VALUE ERROR in the normal manner.

The special character ↑ stands for the list of namespace ancestors:

       ## ##.## ##.##.## ...

In other words, the search is conducted upwards through enclosing namespaces, emulating the static scope rule inherent in modern block-structured languages.

Note that the ⎕PATH mechanism is used ONLY if the function reference cannot be satisfied in the current namespace. This is analogous to the case when the Windows or UNIX PATH variable begins with a '.'.

Examples

   ⎕PATH               Search in ...

1. '⎕se.util'          Current space,   then
                       ⎕se.util,        then
                       VALUE ERROR

2. '↑'                 Current space
                       Parent space: ##
                       Parent's parent space:  ##.##
                       ...
                       Root: # (or ⎕se if current space
                                was inside ⎕se)
                       VALUE ERROR

3. 'util ↑ ⎕se.util'   Current space
                       util (relative to current space)
                       Parent space: ##
                       ...
                       Root: # or ⎕se
                       ⎕se.util
                       VALUE ERROR

Note that ⎕PATH is a session variable. This means that it is workspace-wide and survives )LOAD and )CLEAR. It can of course, be localised by a defined function or operator.


Profile Application

Profile Application: R←{X}⎕PROFILE Y

⎕PROFILE facilitates the profiling of either CPU consumption or elapsed time for a workspace. It does so by retaining time measurements collected for APL functions/operators and function/operator lines. ⎕PROFILE is used to both control the state of profiling and retrieve the collected profiling data.

Y specifies the action to perform and any options for that action, if applicable. Y is case-insensitive.

Use | Description
state←⎕PROFILE 'start' {timer} | Turn profiling on using the specified timer or resume if profiling was stopped
state←⎕PROFILE 'stop' | Suspend the collection of profiling data
state←⎕PROFILE 'clear' | Turn profiling off, if active, and discard any collected profiling data
state←⎕PROFILE 'calibrate' | Calibrate the profiling timer
state←⎕PROFILE 'state' | Query profiling state
data←⎕PROFILE 'data' | Retrieve profiling data in flat form
data←⎕PROFILE 'tree' | Retrieve profiling data in tree form

⎕PROFILE has 2 states:

  • active – the profiler is running and profiling data is being collected.
  • inactive – the profiler is not running.

For most actions, the result of ⎕PROFILE is its current state and contains:

[1] | character vector indicating the ⎕PROFILE state having one of the values 'active' or 'inactive'
[2] | character vector indicating the timer being used having one of the values 'CPU' or 'elapsed'
[3] | call time bias in milliseconds. This is the amount of time, in milliseconds, that is consumed for the system to take a time measurement.
[4] | timer granularity in milliseconds. This is the resolution of the timer being used.

state←⎕PROFILE 'start' {timer}

Turn profiling on; timer is an optional case-independent character vector containing 'CPU' or 'elapsed' or 'none'. If omitted, it defaults to 'CPU'. If timer is 'none', ⎕PROFILE can be used to record which lines of code are executed without incurring the timing overhead.

The first time a particular timer is chosen, ⎕PROFILE will spend 1000 milliseconds (1 second) to approximate the call time bias and granularity for that timer.

      ⎕PROFILE 'start' 'CPU'
 active  CPU  0.0001037499999 0.0001037499999

state←⎕PROFILE 'stop'

Suspends the collection of profiling data.

      ⎕PROFILE 'stop'
 inactive  CPU  0.0001037499999 0.0001037499999

state←⎕PROFILE 'clear'

Clears any collected profiling data and, if profiling is active, places profiling in an inactive state.

      ⎕PROFILE 'clear'
 inactive    0 0

state←⎕PROFILE 'calibrate'

Causes ⎕PROFILE to perform a 1000 millisecond calibration to approximate the call time bias and granularity for the current timer. Note, a timer must have been previously selected by using ⎕PROFILE 'start'.

⎕PROFILE will retain the lesser of the current timer values compared to the new values computed by the calibration. The rationale for this is to use the smallest possible values of which we can be certain.

      ⎕PROFILE'calibrate'
 active  CPU  0.0001037499997 0.0001037499997

state←⎕PROFILE 'state'

Returns the current profiling state.

      )clear
clear ws
      ⎕PROFILE 'state'
 inactive    0 0

      ⎕PROFILE 'start' 'CPU'
 active  CPU  0.0001037499997 0.0001037499997
      ⎕PROFILE 'state'
 active  CPU  0.0001037499997 0.0001037499997

data←{X} ⎕PROFILE 'data'

Retrieves the collected profiling data. If the optional left argument X is omitted, the result is a matrix with the following columns:

[;1] | function name
[;2] | function line number or ⍬ for a whole function entry
[;3] | number of times the line or function was executed
[;4] | accumulated time (ms) for this entry exclusive of items called by this entry
[;5] | accumulated time (ms) for this entry inclusive of items called by this entry
[;6] | number of times the timer function was called for the exclusive time
[;7] | number of times the timer function was called for the inclusive time

Example: (numbers have been truncated for formatting)

      ⎕PROFILE 'data'
#.foo             1  1.04406  39347.64945   503 4080803
#.foo      1      1  0.12488     0.124887     1       1
#.foo      2    100  0.58851 39347.193900   200 4080500
#.foo      3    100  0.21340     0.213406   100     100
#.NS1.goo       100 99.44404   39346.6053 50300 4080300
#.NS1.goo  1    100  0.61679     0.616793   100     100
#.NS1.goo  2  10000 67.80292   39314.9642 20000 4050000
#.NS1.goo  3  10000 19.60274      19.6027 10000   10000

If X is specified it must be a simple vector of column indices. In this case, the result has the same shape as X and is a vector of the specified column vectors:

X ⎕PROFILE 'data' ←→ ↓[⎕IO](⎕PROFILE 'data')[;X]

If column 2 is included in the result, the value ¯1 is used instead of ⍬ to indicate a whole-function entry.

data←{X} ⎕PROFILE 'tree'

Retrieve the collected profiling data in tree format:

[;1] | depth level
[;2] | function name
[;3] | function line number or ⍬ for a whole function entry
[;4] | number of times the line or function was executed
[;5] | accumulated time (ms) for this entry exclusive of items called by this entry
[;6] | accumulated time (ms) for this entry inclusive of items called by this entry
[;7] | number of times the timer function was called for the exclusive time
[;8] | number of times the timer function was called for the inclusive time

The optional left argument is treated in exactly the same way as for X ⎕PROFILE 'data'.

Example:

      ⎕PROFILE 'tree'
0  #.foo               1     1.04406 39347.64945     503 4080803
1  #.foo      1        1     0.12488     0.12488       1       1
1  #.foo      2      100     0.58851 39347.19390     200 4080500
2  #.NS1.goo         100    99.44404 39346.60538   50300 4080300
3  #.NS1.goo  1      100     0.61679     0.61679     100     100
3  #.NS1.goo  2    10000    67.80292 39314.96426   20000 4050000
4  #.NS2.moo       10000 39247.16133 39247.16133 4030000 4030000
5  #.NS2.moo  1    10000    39.28315    39.28315   10000   10000
5  #.NS2.moo  2  1000000 36430.65236 36430.65236 1000000 1000000
5  #.NS2.moo  3  1000000  1645.36214  1645.36214 1000000 1000000
3  #.NS1.goo  3    10000    19.60274    19.60274   10000   10000
1  #.foo      3      100     0.21340     0.21340     100     100

Note that rows with an even depth level in column [;1] represent function summary entries and odd depth level rows are function line entries. Recursive functions will generate separate rows for each level of recursion.

Notes

Profile Data Entry Types

The results of ⎕PROFILE 'data' and ⎕PROFILE 'tree' have two types of entries; function summary entries and function line entries. Function summary entries contain ⍬ in the line number column, whereas function line entries contain the line number. Dynamic functions line entries begin with 0 as they do not have a header line like traditional functions. The timer data and timer call counts in function summary entries represent the aggregate of the function line entries plus any time spent that cannot be directly attributed to a function line entry. This could include time spent during function initialisation, etc.

Example:

 #.foo         1  1.04406 39347.649450   503 4080803
 #.foo    1    1  0.12488     0.124887     1       1
 #.foo    2  100  0.58851 39347.193900   200 4080500
 #.foo    3  100  0.21340     0.213406   100     100

Timer Data Persistence

The profiling data collected is stored outside the workspace and will not impact workspace availability. The data is cleared upon workspace load, clear workspace, ⎕PROFILE 'clear', or interpreter sign off.

The PROFILE User Command

]PROFILE is a utility which implements a high-level interface to ⎕PROFILE and provides reporting and analysis tools that act upon the profiling data. For further information, see Tuning Applications using the Profile User Command.

Using ⎕PROFILE Directly

If you choose to use ⎕PROFILE directly, the following guidelines and information may be of use to you.

Note: Running your application with ⎕PROFILE turned on incurs a significant processing overhead and will slow your application down.

Decide which timer to use

⎕PROFILE supports profiling of either CPU or elapsed time. CPU time is generally of more interest in profiling application performance.

Simple Profiling

To get a quick handle on the top CPU time consumers in an application, use the following procedure:

  • Make sure the application runs long enough to collect enough data to overcome the timer granularity – a reasonable rule of thumb is to make sure the application runs for at least (4000×4⊃⎕PROFILE 'state') milliseconds.
  • Turn profiling on with ⎕PROFILE 'start' CPU
  • Run your application.
  • Pause the profiler with ⎕PROFILE 'stop'
  • Examine the profiling data from ⎕PROFILE 'data' or ⎕PROFILE 'tree' for entries that consume large amounts of resource.

This should identify any items that take more than 10% of the run time.

To find finer time consumers, or to focus on elapsed time rather than CPU time, take the following additional steps prior to running the profiler:

Turn off as much hardware as possible. This would include peripherals, network connections, etc.

  • Turn off as many other tasks and processes as possible. These include anti-virus software, firewalls, internet services, background tasks.
  • Raise the priority on the Dyalog APL task to higher than normal, but in general avoid giving it the highest priority.
  • Run the profiler as described above.

Doing this should help identify items that take more than 1% of the run time.

Advanced Profiling

The timing data collected by ⎕PROFILE is not adjusted for the timer’s call time bias; in other words, the times reported by ⎕PROFILE include the time spent calling the timer function. One effect of this can be to make “cheap” lines that are called many times seem to consume more resource. If you desire more accurate profiling measurements, or if your application takes a short amount of time to run, you will probably want to adjust for the timer call time bias. To do so, subtract from the timing data the timer’s call time bias multiplied by the number of times the timer was called.

Example:

      CallTimeBias←3⊃⎕PROFILE 'state'
      RawTimes←⎕PROFILE 'data'
      Adjusted←RawTimes[;4 5]-RawTimes[;6 7]×CallTimeBias


Name Classification

Name Classification: R←⎕NC Y

Y must be a simple character scalar, vector, matrix, or vector of vectors that specifies a list of names. R is a simple numeric vector containing one element per name in Y.

Each element of R is the name class of the active referent to the object named in Y.

If Y is simple, a name class may be:

Name Class | Description
¯1 | invalid name
0 | unused name
1 | Label
2 | Variable
3 | Function
4 | Operator
9 | Object (GUI, namespace, COM, .Net)

If Y is nested a more precise analysis of name class is obtained whereby different types of functions (primitive, traditional defined functions, D-fns) are identified by a decimal extension. For example, defined functions have name class 3.1, D-fns have name class 3.2, and so forth. The complete set of name classification is as follows:

 | Array (2) | Functions (3) | Operators (4) | Namespaces (9)
n.1 | Variable | Traditional | Traditional | Created by ⎕NS
n.2 | Field | D-fns | D-ops | Instance
n.3 | Property | Derived Primitive |  |
n.4 |  |  |  | Class
n.5 |  | N/A |  | Interface
n.6 | External Shared | External |  | External Class
n.7 |  |  |  | External Interface

In addition, values in R are negative to identify names of methods, properties and events that are inherited through the class hierarchy of the current class or instance.

Variable (Name-Class 2.1)

Conventional APL arrays have name-class 2.1.

      NUM←88
      CHAR←'Hello World'

      ⎕NC ↑'NUM' 'CHAR'
2 2

      ⎕NC 'NUM' 'CHAR'
2.1 2.1

      'MYSPACE'⎕NS ''
      MYSPACE.VAR←10
      MYSPACE.⎕NC'VAR'
2
      MYSPACE.⎕NC⊂'VAR'
2.1

Field (Name-Class 2.2)

Fields defined by APL Classes have name-class 2.2.

:Class nctest
    :Field Public pubFld
    :Field pvtFld

    ∇ r←NameClass x
      :Access Public
      r←⎕NC x
    ∇
...
:EndClass ⍝ nctest

      ncinst←⎕NEW nctest

The name-class of a Field, whether Public or Private, viewed from a Method that is executing within the Instance Space, is 2.2.

      ncinst.NameClass'pubFld' 'pvtFld'
2.2 2.2

Note that an internal Method sees both Public and Private Fields in the Class Instance. However, when viewed from outside the instance, only public fields are visible

      ⎕NC 'ncinst.pubFld' 'ncinst.pvtFld'
¯2.2 0

In this case, the name-class is negative to indicate that the name has been exposed by the class hierarchy, rather than existing in the associated namespace which APL has created to contain the instance. The same result is returned if ⎕NC is executed inside this space:

      ncinst.⎕NC'pubFld' 'pvtFld'
¯2.2 0

Note that the names of Fields are reported as being unused if the argument to ⎕NC is simple.

      ncinst.⎕NC 2 6⍴'pubFldpvtFld'
0 0

Property (Name-Class 2.3)

Properties defined by APL Classes have name-class 2.3.

:Class nctest
    :Field pvtFld←99

    :Property pubProp
    :Access Public
        ∇ r←get
          r←pvtFld
        ∇
    :EndProperty

    :Property pvtProp
        ∇ r←get
          r←pvtFld
        ∇
    :EndProperty

    ∇ r←NameClass x
      :Access Public
      r←⎕NC x
    ∇
...
:EndClass ⍝ nctest

      ncinst←⎕NEW nctest

The name-class of a Property, whether Public or Private, viewed from a Method that is executing within the Instance Space, is 2.3.

      ncinst.NameClass'pubProp' 'pvtProp'
2.3 2.3

Note that an internal Method sees both Public and Private Properties in the Class Instance. However, when viewed from outside the instance, only Public Properties are visible

      ⎕NC 'ncinst.pubProp' 'ncinst.pvtProp'
¯2.3 0

In this case, the name-class is negative to indicate that the name has been exposed by the class hierarchy, rather than existing in the associated namespace which APL has created to contain the instance. The same result is returned if ⎕NC is executed inside this space:

      ncinst.⎕NC 'pubProp' 'pvtProp'
¯2.3 0

Note that the names of Properties are reported as being unused if the argument to ⎕NC is simple.

      ncinst.⎕NC 2 6⍴'pubProppvtProp'
0 0

External Properties (Name-Class 2.6)

Properties exposed by external objects (.Net and COM and the APL GUI) have name-class ¯2.6.

      ⎕USING←'System'
      dt←⎕NEW DateTime (2006 1 1)
      dt.⎕NC 'Day' 'Month' 'Year'
¯2.6 ¯2.6 ¯2.6

      'ex' ⎕WC 'OLEClient' 'Excel.Application'
      ex.⎕NC 'Caption' 'Version' 'Visible'
¯2.6 ¯2.6 ¯2.6

     'f'⎕WC'Form'
      f.⎕NC'Caption' 'Size'
¯2.6 ¯2.6

Note that the names of such Properties are reported as being unused if the argument to ⎕NC is simple.

      f.⎕NC 2 7⍴'CaptionSize   '
0 0

Defined Functions (Name-Class 3.1)

Traditional APL defined functions have name-class 3.1.

     ∇ R←AVG X
[1]    R←(+/X)÷⍴X
     ∇
      AVG ⍳100
50.5

      ⎕NC'AVG'
3
      ⎕NC⊂'AVG'
3.1

      'MYSPACE'⎕NS 'AVG'
       MYSPACE.AVG ⍳100
50.5

      MYSPACE.⎕NC'AVG'
3
      ⎕NC⊂'MYSPACE.AVG'
3.1

Note that a function that is simply cloned from a defined function by assignment retains its name-class.

      MEAN←AVG
      ⎕NC'AVG' 'MEAN'
3.1 3.1

Whereas, the name of a function that amalgamates a defined function with any other functions has the name-class of a Derived Function, i.e. 3.3.

      VMEAN←AVG∘,
      ⎕NC'AVG' 'VMEAN'
3.1 3.3

D-Fns (Name-Class 3.2)

D-Fns (Dynamic Functions) have name-class 3.2

      Avg←{(+/⍵)÷⍴⍵}

      ⎕NC'Avg'
3
      ⎕NC⊂'Avg'
3.2

Derived Functions (Name-Class 3.3)

Derived Functions and functions created by naming a Primitive function have name-class 3.3.

      PLUS←+
      SUM←+/
      CUM←PLUS\
      ⎕NC'PLUS' 'SUM' 'CUM'
3.3 3.3 3.3
      ⎕NC 3 4⍴'PLUSSUM CUM '
3 3 3

Note that a function that is simply cloned from a defined function by assignment retains its name-class. Whereas, the name of a function that amalgamates a defined function with any other functions has the name-class of a Derived Function, i.e. 3.3.

     ∇ R←AVG X
[1]    R←(+/X)÷⍴X
     ∇

      MEAN←AVG
      VMEAN←AVG∘,
      ⎕NC'AVG' 'MEAN' 'VMEAN'
3.1 3.1 3.3

External Functions (Name-Class 3.6)

Methods exposed by the Dyalog APL GUI and COM and .NET objects have name-class ¯3.6. Methods exposed by External Functions created using ⎕NA and ⎕SH all have name-class 3.6.

      'F'⎕WC'Form'

      F.⎕NC'GetTextSize' 'GetFocus'
¯3.6 ¯3.6

      'EX'⎕WC'OLEClient' 'Excel.Application'
      EX.⎕NC 'Wait' 'Save' 'Quit'
¯3.6 ¯3.6 ¯3.6

      ⎕USING←'System'
      dt←⎕NEW DateTime (2006 1 1)
      dt.⎕NC 'AddDays' 'AddHours'
¯3.6 ¯3.6

      'beep'⎕NA'user32|MessageBeep i'

      ⎕NC'beep'
3
      ⎕NC⊂'beep'
3.6
      'xutils'⎕SH''
      )FNS
avx     box     dbr     getenv  hex     ltom    ltov    mtol    ss      vtol
      ⎕NC'hex' 'ss'
3.6 3.6

Operators (Name-Class 4.1)

Traditional Defined Operators have name-class 4.1.

      ∇FILTER∇
     ∇ VEC←(P FILTER)VEC  ⍝ Select from VEC those elts ..
[1]    VEC←(P¨VEC)/VEC    ⍝ for which BOOL fn P is true.
     ∇

      ⎕NC'FILTER'
4
      ⎕NC⊂'FILTER'
4.1

D-Ops (Name-Class 4.2

D-Ops (Dynamic Operators) have name-class 4.2.

     pred←{⎕IO ⎕ML←1 3   ⍝ Partitioned reduction.
     ⊃⍺⍺/¨(⍺/⍳⍴⍺)⊂⍵
     }

      2 3 3 2 +pred ⍳10
3 12 21 19

      ⎕NC'pred'
4
      ⎕NC⊂'pred'
4.2

External Events (Name-Class 8.6)

Events exposed by Dyalog APL GUI objects, COM and .NET objects have name-class ¯8.6.

      f←⎕NEW'Form'('Caption' 'Dyalog GUI Form')
      f.⎕NC'Close' 'Configure' 'MouseDown'
¯8.6 ¯8.6 ¯8.6

      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')
      xl.⎕NL -8
 NewWorkbook  SheetActivate  SheetBeforeDoubleClick ...

      xl.⎕NC 'SheetActivate' 'SheetCalculate'
¯8.6 ¯8.6

    ⎕USING←'System.Windows.Forms,system.windows.forms.dll'
    ⎕NC,⊂'Form'
9.6
    Form.⎕NL -8
 Activated  BackgroundImageChanged  BackColorChanged ...

Namespaces (Name-Class 9.1)

Plain namespaces created using ⎕NS, or fixed from a :Namespace script, have name-class 9.1.

      'MYSPACE' ⎕NS ''
      ⎕NC'MYSPACE'
9
      ⎕NC⊂'MYSPACE'
9.1

Note however that a namespace created by cloning, where the right argument to ⎕NS is a ⎕OR of a namespace, retains the name-class of the original space.

      'CopyMYSPACE'⎕NS ⎕OR 'MYSPACE'
      'CopyF'⎕NS ⎕OR 'F'⎕WC'Form'

      ⎕NC'MYSPACE' 'F'
9.1 9.2
      ⎕NC'CopyMYSPACE' 'CopyF'
9.1 9.2

The Name-Class of .Net namespaces (visible through ⎕USING) is also 9.1

      ⎕USING←''
      ⎕NC 'System' 'System.IO'
9.1 9.1

Instances (Name-Class 9.2)

Instances of Classes created using ⎕NEW, and GUI objects created using ⎕WC all have name-class 9.2.

      MyInst←⎕NEW MyClass
      ⎕NC'MyInst'
9
      ⎕NC⊂'MyInst'
9.2
      UrInst←⎕NEW ⎕FIX ':Class'  ':EndClass'
      ⎕NC 'MyInst' 'UrInst'
9.2 9.2

      'F'⎕WC 'Form'
      'F.B' ⎕WC 'Button'
      ⎕NC 2 3⍴'F  F.B'
9 9
      ⎕NC'F' 'F.B'
9.2 9.2
      F.⎕NC'B'
9
      F.⎕NC⊂,'B'
9.2

Instances of COM Objects whether created using ⎕WC or ⎕NEW also have name-class 9.2.

      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')
      'XL'⎕WC'OLEClient' 'Excel.Application'
      ⎕NC'xl' 'XL'
9.2 9.2

The same is true of Instances of .Net Classes (Types) whether created using ⎕NEW or .New.

      ⎕USING←'System'
      dt←⎕NEW DateTime (3↑⎕TS)
      DT←DateTime.New 3↑⎕TS
      ⎕NC 'dt' 'DT'
9.2 9.2

Note that if you remove the GUI component of a GUI object, using the Detach method, it reverts to a plain namespace.

      F.Detach
      ⎕NC⊂,'F'
9.1

Correspondingly, if you attach a GUI component to a plain namespace using the monadic form of ⎕WC, it morphs into a GUI object

      F.⎕WC 'PropertySheet'
      ⎕NC⊂,'F'
9.2

Classes (Name-Class 9.4)

Classes created using the editor or ⎕FIX have name-class 9.4.

      )ED ○MyClass

:Class MyClass
    ∇ r←NameClass x
      :Access Public Shared
      r←⎕NC x
    ∇
:EndClass ⍝ MyClass

      ⎕NC 'MyClass'
9
      ⎕NC⊂'MyClass'
9.4

      ⎕FIX ':Class UrClass'  ':EndClass'
      ⎕NC 'MyClass' 'UrClass'
9.4 9.4

Note that the name of the Class is visible to a Public Method in that Class, or an Instance of that Class.

      MyClass.NameClass'MyClass'
9
      MyClass.NameClass⊂'MyClass'
9.4

Interfaces (Name-Class 9.5)

Interfaces, defined by :Interface ... :EndInterface clauses, have name-class 9.5.

:Interface IGolfClub
:Property Club
    ∇ r←get
    ∇
    ∇ set
    ∇
:EndProperty

∇ Shank←Swing Params
∇

:EndInterface ⍝ IGolfClub

      ⎕NC 'IGolfClub'
9
      ⎕NC ⊂'IGolfClub'
9.5

External Classes (Name-Class 9.6)

External Classes (Types) exposed by .Net have name-class 9.6.

      ⎕USING←'System' 'System.IO'

      ⎕NC 'DateTime' 'File' 'DirectoryInfo'
9.6 9.6 9.6

Note that referencing a .Net class (type) with ⎕NC, fixes the name of that class in the workspace and obviates the need for APL to repeat the task of searching for and loading the class when the name is next used.

External Interfaces (Name-Class 9.7)

External Interfaces exposed by .Net have name-class 9.7.

      ⎕USING←'System.Web.UI,system.web.dll'

      ⎕NC 'IPostBackDataHandler' 'IPostBackEventHandler'
9.7 9.7

Note that referencing a .Net Interface with ⎕NC, fixes the name of that Interface in the workspace and obviates the need for APL to repeat the task of searching for and loading the Interface when the name is next used.


Name List

Name List: R←{X}⎕NL Y

Y must be a simple numeric scalar or vector containing one or more of the values for name-class. See alsoName Classification: .

X is optional. If present, it must be a simple character scalar or vector. R is a list of the names of active objects whose name-class is included in Y in standard sorted order.

If any element of Y is negative, positive values in Y are treated as if they were negative, and R is a vector of character vectors. Otherwise, R is simple character matrix.

Furthermore, if ⎕NL is being evaluated inside the namespace associated with a Class or an Instance of a Class, and any element of Y is negative, R includes the Public names exposed by the Base Class (if any) and all other Classes in the Class hierarchy.

If X is supplied, R contains only those names which begin with any character of X. Standard sorted order is in Unicode point order for Unicode editions, and in the collation order of ⎕AV for Classic editions.

If an element of Y is an integer, the names of all of the corresponding sub-name-classes are included in R. For example, if Y contains the value 2, the names of all variables (name-class 2.1), fields (2.2), properties (2.3) and external or shared variables (2.6) are obtained. Otherwise, only the names of members of the corresponding sub-name-class are obtained.

Examples:

      ⎕NL 2 3
A
FAST
FIND
FOO
V

      'AV' ⎕NL 2 3
A
V

      ⎕NL ¯9
 Animal  Bird  BirdBehaviour  Coin  Cylinder  DomesticParrot  Eeyore  FishBehaviour  Nickel  Parrot  Penguin  Polly  Robin
      ⎕NL ¯9.3 ⍝ Instances
 Eeyore  Nickel  Polly  Robin
      ⎕NL ¯9.4 ⍝ Classes
 Animal  Bird  Coin  Cylinder  DomesticParrot  Parrot  Penguin
      ⎕NL ¯9.5 ⍝ Interfaces
 BirdBehaviour  FishBehaviour

⎕NL can also be used to explore Dyalog GUI Objects, .Net types and COM objects.

Dyalog GUI Objects

⎕NL may be used to obtain lists of the Methods, Properties and Events provided by Dyalog APL GUI Objects.

     'F' ⎕WC 'Form'
      F.⎕NL -2 ⍝ Properties
 Accelerator  AcceptFiles  Active  AlphaBlend  AutoConf  Border  BCol  Caption ...

      F.⎕NL -3 ⍝ Methods
 Animate  ChooseFont  Detach  GetFocus  GetTextSize  ShowSIP  Wait

      F.⎕NL -8 ⍝ Events
Close  Create  DragDrop  Configure  ContextMenu  DropFiles  DropObjects  Expose  Help ...

.Net Classes (Types)

⎕NL can be used to explore .Net types.

When a reference is made to an undefined name, and ⎕USING is set, APL attempts to load the Type from the appropriate .Net Assemblies. If successful, the name is entered into the symbol table with name-class 9.6.

      ⎕USING←'System'
      DateTime
(System.DateTime)
      ⎕NL -9
 DateTime
      ⎕NC,⊂'DateTime'
9.6

The names of the Properties and Methods of a .Net Type may then be obtained using ⎕NL.

      DateTime.⎕NL -2 ⍝ Properties
  MaxValue  MinValue  Now  Today  UtcNow

      DateTime.⎕NL -3 ⍝ Methods
 get_Now  get_Today  get_UtcNow  op_Addition  op_Equality  ...

In fact it is not necessary to make a separate reference first, because the expression Type.⎕NL (where Type is a .Net Type) is itself a reference to Type. So, (with ⎕USING still set to 'System'):

      Array.⎕NL -3
 BinarySearch  Clear  Copy  CreateInstance  IndexOf  LastIndexOf  Reverse  Sort

      ⎕NL -9
 Array  DateTime

Another use for ⎕NL is to examine .Net enumerations. For example:

      ⎕USING←'System.Windows.Forms,system.windows.forms.dll'

      FormBorderStyle.⎕NL -2
Fixed3D  FixedDialog  FixedSingle  FixedToolWindow  None  Sizable  SizableToolWindow

      FormBorderStyle.FixedDialog.value__
3

      FormBorderStyle.({⍵,[1.5]⍎¨⍵,¨⊂'.value__'}⎕NL -2)
 Fixed3D            2
 FixedDialog        3
 FixedSingle        1
 FixedToolWindow    5
 None               0
 Sizable            4
 SizableToolWindow  6

COM Objects

Once a reference to a COM object has been obtained, ⎕NL may be used to obtain lists of its Methods, Properties and Events.

      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')

      xl.⎕NL -2 ⍝ Properties
 _Default  ActiveCell  ActiveChart  ActiveDialog  ActiveMenuBar  ActivePrinter  ActiveSheet  ActiveWindow ...

      xl.⎕NL -3 ⍝ Methods
 _Evaluate  _FindFile  _Run2  _Wait  _WSFunction  ActivateMicrosoftApp  AddChartAutoFormat  AddCustomList  Browse  Calculate ...

      ⎕NL -9
 xl


Lock Definition

Lock Definition: {X}⎕LOCK Y

Y must be a simple character scalar, or vector which is taken to be the name of a defined function or operator in the active workspace.

The active referent to the name in the workspace is locked. Stop, trace and monitor settings, established by the ⎕STOP, ⎕TRACEand ⎕MONITORfunctions, are cancelled.

The optional left argument X specifies to what extent the function code is hidden. X may be 1, 2 or 3 (the default) with the following meaning:

  1. The object may not be displayed and you may not obtain its character form using ⎕CR, ⎕VR or ⎕NR.
  2. Execution cannot be suspended with the locked function or operator in the state indicator. On suspension of execution the state indicator is cut back to the statement containing the call to the locked function or operator.
  3. Both 1 and 2 apply. You can neither display the locked object nor suspend execution within it.

Locks are additive, so that the following are equivalent:

      1 ⎕LOCK'FOO'
      2 ⎕LOCK'FOO'
      3 ⎕LOCK'FOO'

DOMAIN ERROR is reported if:

  • Y is ill-formed.
  • The name in Y is not the name of a visible defined function or operator which is not locked.

Examples

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      ⎕LOCK'FOO'
      ⎕VR'FOO'

      ⎕LOCK'FOO'
DOMAIN ERROR
      ⎕LOCK'FOO'
      ^


Migration Level

Migration Level: ⎕ML

⎕ML determines the degree of migration of the Dyalog APL language towards IBM's APL2. Setting this variable to other than its default value of 0 changes the interpretation of certain symbols and language constructs.

⎕ML←0 |  | Native Dyalog (Default)
⎕ML←1 | Z←∊R | Monadic '∊' is interpreted as 'enlist' rather than 'type'.
⎕ML←2 | Z←↑R | Monadic '↑' is interpreted as 'first' rather than 'mix'.
 | Z←⊃R | Monadic '⊃' is interpreted as 'mix' rather than 'first'.
 | Z←≡R | Monadic '≡' returns a positive rather than a negative value, if its argument has non-uniform depth.
⎕ML←3 | R←X⊂[K]Y | Dyadic '⊂' follows the APL2 (rather than the original Dyalog APL) convention.
 | ⎕TC | The order of the elements of ⎕TC is the same as in APL2.

Subsequent versions of Dyalog APL may provide further migration levels.

Examples

      X←2(3 4)

      ⎕ML←0
      ∊X
0  0 0
      ↑X
2 0
3 4
      ⊃X
2
      ≡X
¯2

      ⎕ML←1
      ∊X
2 3 4
      ↑X
2 0
3 4
      ⊃X
2
      ≡X
¯2

      ⎕ML←2
      ∊X
2 3 4
      ↑X
2
      ⊃X
2 0
3 4
      ≡X
2


Using Microsoft Net Search Path

Using (Microsoft .Net Search Path): ⎕USING

⎕USING specifies a list of Microsoft .Net Namespaces that are to be searched for a reference to a .Net class.

⎕USING is a vector of character vectors, each element of which specifies the name of a .Net Namespace followed optionally by a comma (,) and the Assembly in which it is to be found.

If a pathname is specified, the file is loaded from that location. Otherwise the system will attempt to load the assembly first from the directory in which the Dyalog program (or host application) is located, and then from the .Net installation directory.

If the Microsoft .Net Framework is installed, the System namespace in mscorlib.dll is automatically loaded when Dyalog APL starts. To access this namespace, it is not necessary to specify the name of the Assembly.

⎕USING has namespace scope. If the local value of ⎕USING is anything other than empty, and you reference a name that would otherwise generate a VALUE ERROR, APL searches the list of .Net Namespaces and Assemblies specified by ⎕USING for a class of that name. If it is found, an entry for the class is added to the symbol table in the current space and the class is used as specified. Note that subsequent references to that class in the current space will be identified immediately.

If ⎕USING is empty (its default value in a CLEAR WS) no such search is performed.

Note that when you assign a value to ⎕USING, you may specify a simple character vector or a vector of character vectors. If you specify a simple character vector (including an empty vector ''), this is equivalent to specifying a 1-element enclosed vector containing the specified characters. Thus to clear ⎕USING, you must set it to 0⍴⊂'' and not ''.

Examples:

  ⎕USING←'System'
  ]display ⎕USING
.→---------.
| .→-----. |
| |System| |
| '------' |
'∊---------'

⎕USING,←⊂'System.Windows.Forms,System.Windows.Forms.dll'
⎕USING,←⊂'System.Drawing,System.Drawing.dll'

An Assembly may contain top-level classes which are not packaged into .Net Namespaces. In this case, you omit the Namespace name. For example:

  ⎕USING←,⊂',.\LoanService.dll'


Verify Fix Input

Verify & Fix Input: R←{X}⎕VFI Y

Y must be a simple character scalar or vector. X is optional. If present, X must be a simple character scalar or vector. R is a nested vector of length two whose first item is a simple logical vector and whose second item is a simple numeric vector of the same length as the first item of R.

Y is the character representation of a series of numeric constants. If X is omitted, adjacent numeric strings are separated by one or more blanks. Leading and trailing blanks and separating blanks in excess of one are redundant and ignored. If X is present, X specifies one or more alternative separating characters. Blanks in leading and trailing positions in Y and between numeric strings separated also by the character(s) in X are redundant and ignored. Leading, trailing and adjacent occurrences of the character(s) in X are not redundant. The character 0 is implied in Y before a leading character, after a trailing character, and between each adjacent pair of characters specified by X.

The length of the items of R is the same as the number of identifiable strings (or implied strings) in Y separated by blank or the value of X. An element of the first item of R is 1 where the corresponding string in Y is a valid numeric representation, or 0 otherwise. An element of the second item of R is the numeric value of the corresponding string in Y if it is a valid numeric representation, or 0 otherwise.

Examples

      ⎕VFI '2 -2 ¯2'
 1 0 1  2 0 ¯2

      ⎕VFI '12.1 1E1 1A1 ¯10'
 1 1 0 1  12.1 10 0 ¯10

      ⊃(//⎕VFI'12.1 1E1 1A1 ¯10')
12.1 10 ¯10

      ','⎕VFI'3.9,2.4,,76,'
 1 1 1 1 1  3.9 2.4 0 76 0

      '⋄'⎕VFI'1 ⋄ 2 3 ⋄ 4 '
 1 0 1  1 0 4
      ⍬≡⎕VFI''
1


Character Input/Output: ⍞

⍞ is a variable which communicates between the user's terminal and APL. Its behaviour depends on whether it is being assigned or referenced.

When ⍞ is assigned with a vector or a scalar, the array is displayed without the normal ending new-line character. Successive assignments of vectors or scalars to ⍞ without any intervening input or output cause the arrays to be displayed on the same output line.

Example

      ⍞←'2+2' ⋄ ⍞←'=' ⋄ ⍞←4
2+2=4

Output through ⍞ is independent of the print width in ⎕PW. The way in which lines exceeding the print width of the terminal are treated is dependent on the characteristics of the terminal. Numeric output is formatted in the same manner as direct output (see Display of Arrays).

When ⍞ is assigned with a higher-order array, the output is displayed in the same manner as for direct output except that the print width ⎕PW is ignored.

When ⍞ is referenced, terminal input is expected without any specific prompt, and the response is returned as a character vector.

If the ⍞ request was preceded by one or more assignments to ⍞ without any intervening input or output, the last (or only) line of the output characters are returned as part of the response.

Example

      mat←↑⌽⍞⍞⍞⍞⍞

Examples

      ⍞←'OPTION : ' ⋄ R←⍞
OPTION : INPUT

      R
OPTION : INPUT

      ⍴R
14

The output of simple arrays of rank greater than 1 through ⍞ includes a new-line character at the end of each line. Input through ⍞ includes the preceding output through ⍞ since the last new-line character. The result from ⍞, including the prior output, is limited to 256 characters.

A soft interrupt causes an INPUT INTERRUPT error if entered while ⍞ is awaiting input, and execution is then suspended (unless the interrupt is trapped):

      R←⍞

(Interrupt)

INPUT INTERRUPT

A time limit is imposed on input through ⍞ if ⎕RTL is set to a non-zero value:

      ⎕RTL←5 ⋄ ⍞←'PASSWORD ? ' ⋄ R←⍞
PASSWORD ?
TIMEOUT
      ⎕RTL←5 ⋄ ⍞←'PASSWORD : ' ⋄ R←⍞
                                   ^

The TIMEOUT interrupt is a trappable event.


Evaluated Input/Output: ⎕

⎕ is a variable which communicates between the user’s terminal and APL. Its behaviour depends on whether it is being assigned or referenced.

When ⎕ is assigned an array, the array is displayed at the terminal in exactly the same form as is direct output (see Display of Arrays).

Example

      ⎕←2+⍳5
3 4 5 6 7

      ⎕←2 4⍴'WINEMART'
WINE
MART

When ⎕ is referenced, a prompt (⎕:) is displayed at the terminal, and input is requested. The response is evaluated and an array is returned if the result is valid. If an error occurs in the evaluation, the error is reported as normal (unless trapped by a ⎕TRAP definition) and the prompt (⎕:) is again displayed for input. An EOF interrupt reports INPUT INTERRUPT and the prompt (⎕:) is again displayed for input. A soft interrupt is ignored and a hard interrupt reports INTERRUPT and the prompt (⎕:) is redisplayed for input.

Examples

      10×⎕+2
⎕:
      ⍳3
30 40 50

      2+⎕
⎕:
      X
VALUE ERROR
      X
     ^
⎕:
      2+⍳3
5 6 7

A system command may be entered. The system command is effected and the prompt is displayed again (unless the system command changes the environment):

      ⍴3,⎕
⎕:
      )WSID
WS/MYWORK
⎕:
      )SI
⎕
⎕:
      )CLEAR
CLEAR WS

If the response to a ⎕: prompt is an abort statement (→), the execution will be aborted:

      1 2 3 = ⎕
⎕:
      →

A trap definition on interrupt events set for the system variable ⎕TRAP in the range 1000-1008 has no effect whilst awaiting input in response to a ⎕: prompt.

Example

      ⎕TRAP←(11 'C' '''ERROR''')(1000 'C' '''STOP''')

      2+⎕
⎕:
      (Interrupt Signal)
INTERRUPT
⎕:
      'C'+2
ERROR

A time limit set in system variable ⎕RTL has no effect whilst awaiting input in response to a ⎕: prompt.


Digits

Digits: R←⎕D

This is a simple character vector of the digits from 0 to 9.

Example

      ⎕D
0123456789


Alphabetic Characters

Alphabetic Characters: R←⎕A

This is a simple character vector, composed of the letters of the alphabet.

Example

      ⎕A
ABCDEFGHIJKLMNOPQRSTUVWXYZ


Underscored Alphabetic Characters

Underscored Alphabetic Characters: R←⎕Ⓐ

⎕Ⓐ is a deprecated feature. Dyalog strongly recommends that you move away from the use of ⎕Ⓐand of the underscored alphabet itself, as these symbols now constitute the sole remaining non-standard use of characters in Dyalog applications.

In Versions of Dyalog APL prior to Version 11.0, ⎕Ⓐ was a simple character vector, composed of the letters of the alphabet with underscores. If the Dyalog Alt font was in use, these symbols displayed as additional National Language characters.

Version 10.1 and Earlier

      ⎕Ⓐ
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

For compatibility with previous versions of Dyalog APL, functions that contain references to ⎕Ⓐ will continue to return characters with the same index in ⎕AV as before. However, the display of ⎕Ⓐ is now ⎕Á, and the old underscored symbols appear as they did in previous Versions when the Dyalog Alt font was in use.

Current Version

      ⎕Á
ÁÂÃÇÈÊËÌÍÎÏÐÒÓÔÕÙÚÛÝþãìðòõ


Atomic Vector

Atomic Vector: R←⎕AV

⎕AV is a deprecated feature and is replaced by ⎕UCS.

This is a simple character vector of all 256 characters in the Classic Dyalog APL character.

In the Classic Edition the contents of ⎕AV are defined by the Output Translate Table.

In the Unicode Edition, the contents of ⎕AV are defined by the system variable ⎕AVU.

Examples

      ⎕AV[48+⍳10]
0123456789

      5 52⍴12↓⎕av
%'⍺⍵_abcdefghijklmnopqrstuvwxyz__¯.⍬0123456789_¤¥$£¢
∆ABCDEFGHIJKLMNOPQRSTUVWXYZ__ý·⍙ÁÂÃÇÈÊËÌÍÎÏÐÒÓÔÕÙÚÛ
ÝÞãìðòõ{€}⊣⌷¨ÀÄÅÆ⍨ÉÑÖØÜßàáâäåæçèéêëíîïñ[/⌿\⍀<≤=≥>≠∨^
-+÷×?∊⍴~↑↓⍳○*⌈⌊∇∘(⊂⊃∩∪⊥⊤|;,⍱⍲⍒⍋⍉⌽⊖⍟⌹!⍕⍎⍫⍪≡≢óôöø"#_&'
___________@ùúû^ü`⌷¶:⍷¿¡⋄←→⍝)]§⎕⍞⍣%'⍺⍵_abcdefghijk


Atomic Vector Unicode

Atomic Vector - Unicode: ⎕AVU

⎕AVU specifies the contents of the atomic vector, ⎕AV, and is used to translate data between Unicode and non-Unicode character formats when required, for example when:

  • Unicode Edition loads or copies a Classic Edition workspace or a workspace saved by a Version prior to Version 12.0.
  • Unicode Edition reads character data from a non-Unicode component file, or receives data type 82 from a TCP socket.
  • Unicode Edition writes data to a non-Unicode component file
  • Unicode Edition reads or writes data from or to a Native File using conversion code 82.
  • Classic Edition loads or copies a Unicode Edition workspace
  • Classic Edition reads character data from a Unicode component file, or receives data type 80, 160, or 320 from a TCP socket.
  • Classic Edition writes data to a Unicode component file.

⎕AVU is an integer vector with 256 elements, containing the Unicode code points which define the characters in ⎕AV.

Note

In Versions of Dyalog prior to Version 12.0 and in the Classic Edition, a character is stored internally as an index into the atomic vector, ⎕AV. When a character is displayed or printed, the index in ⎕AV is translated to a number in the range 0-255 which represents the index of the character in an Extended ASCII font. This mapping is done by the Output Translate Table which is user-configurable. Note that although ASCII fonts typically all contain the same symbols in the range 0-127, there are a number of different Extended ASCII font layouts, including proprietary APL fonts, which provide different symbols in positions 128-255. The actual symbol that appears on the screen or on the printed page is therefore a function of the Output Translate Table and the font in use. Classic Edition provides two different fonts (and thus two different ⎕AV layouts) for use with the Development Environment, named Dyalog Std (with APL underscores) and Dyalog Alt (without APL underscores

The default value of ⎕AVU corresponds to the use of the Dyalog Alt Output Translate Table and font in the Classic Edition or in earlier versions of Dyalog APL.

      2 13⍴⎕AVU[97+⍳26]
193 194 195 199 200 202 203 204 205 206 207 208 210
211 212 213 217 218 219 221 254 227 236 240 242 245
      ⎕UCS 2 13⍴⎕AVU[97+⍳26]
ÁÂÃÇÈÊËÌÍÎÏÐÒ
ÓÔÕÙÚÛÝþãìðòõ

⎕AVU has namespace scope and can be localised, in order to make it straightforward to write access functions which receive or read data from systems with varying atomic vectors. If you have been using Dyalog Alt for most things but have some older code which uses underscores, you can bring this code together in the same workspace and have it all look “as it should” by using the Alt and Std definitions for ⎕AVU as you copy each part of the code into the same Unicode Edition workspace.

      )COPY avu.dws Std.⎕AVU
C:\Program Files\Dyalog\Dyalog APL 12.0 Unicode\ws\avu saved Thu Dec 06 11:24:32 2007

      2 13⍴⎕AVU[97+⍳26]
9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410
9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423
       ⎕UCS 2 13⍴⎕AVU[97+⍳26]
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂ
ⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

Rules for Conversion on Import

When the Unicode Edition imports APL objects from a non-Unicode source, function comments and character data of type 82 are converted to Unicode. When the Classic Edition imports APL objects from a Unicode source, this translation is performed in reverse.

If the objects are imported from a Version 12.0 (or later) workspace (i.e. from a workspace that contains its own value of ⎕AVU) the value of #.⎕AVU (the value of ⎕AVU in the root) in the source workspace is used. Otherwise, such as when APL objects are imported from a pre-Version 12 workspace, from a component file, or from a TCP socket, the local value of ⎕AVU in the target workspace is used.

Rules for Conversion on Export

When the Unicode Edition exports APL objects to a non-Unicode destination, such as a non-Unicode Component File or non-Unicode TCPSocket Object, function comments (in ⎕ORs) and character data of type 82 are converted to ⎕AV indices using the local value of ⎕AVU.

When the Classic Edition exports APL objects to a Unicode destination, such as a Unicode Component File or Unicode TCPSocket Object, function comments (in ⎕ORs) and character data of type 82 are converted to Unicode using the local value of ⎕AVU.

In all cases, if a character to be translated is not defined in ⎕AVU, a TRANSLATION ERROR (event number 92) will be signalled.


Unicode Convert

Unicode Convert: R←{X} ⎕UCS Y

⎕UCS converts (Unicode) characters into integers and vice versa.

The optional left argument X is a character vector containing the name of a variable-length Unicode encoding scheme which must be one of:

  • 'UTF-8'
  • 'UTF-16'
  • 'UTF-32'

If not, a DOMAIN ERROR is issued.

If X is omitted, Y is a simple character or integer array, and the result R is a simple integer or character array with the same rank and shape as Y.

If X is specified, Y must be a simple character or integer vector, and the result R is a simple integer or character vector.

Monadic ⎕UCS

Used monadically, ⎕UCS simply converts characters to Unicode code points and vice-versa.

With a few exceptions, the first 256 Unicode code points correspond to the ANSI character set.

      ⎕UCS 'Hello World'
72 101 108 108 111 32 87 111 114 108 100

      ⎕UCS 2 11⍴72 101 108 108 111 32 87 111 114 108 100
Hello World
Hello World

The code points for the Greek alphabet are situated in the 900's:

      ⎕UCS 'καλημέρα ελλάδ'
954 945 955 951 956 941 961 945 32 949 955 955 940 948

Unicode also contains the APL character set. For example:

      ⎕UCS 123 40 43 47 9077 41 247 9076 9077 125
{(+/⍵)÷⍴⍵}

Dyadic ⎕UCS

Dyadic ⎕UCS is used to translate between Unicode characters and one of three standard variable-length Unicode encoding schemes, UTF-8, UTF-16 and UTF-32. These represent a Unicode character string as a vector of 1-byte (UTF-8), 2-byte (UTF-16) and 4-byte (UTF-32) signed integer values respectively.

      'UTF-8' ⎕UCS 'ABC'
65 66 67
      'UTF-8' ⎕UCS 'ABCÆØÅ'
65 66 67 195 134 195 152 195 133
      'UTF-8' ⎕UCS 195 134, 195 152, 195 133
ÆØÅ
      'UTF-8' ⎕UCS 'γεια σου'
206 179 206 181 206 185 206 177 32 207 131 206 191 207 133
      'UTF-16' ⎕UCS 'γεια σου'
947 949 953 945 32 963 959 965
      'UTF-32' ⎕UCS 'γεια σου'
947 949 953 945 32 963 959 965

Because integers are signed, numbers greater than 127 will be represented as 2-byte integers (type 163), and are thus not suitable for writing directly to a native file. To write the above data to file, the easiest solution is to use ⎕UCS to convert the data to 1-byte characters and append this data to the file:

      (⎕UCS 'UTF-8' ⎕UCS 'ABCÆØÅ') ⎕NAPPEND tn

Note regarding UTF-16: For most characters in the first plane of Unicode (0000-FFFF), UTF-16 and UCS-2 are identical. However, UTF-16 has the potential to encode all Unicode characters, by using more than 2 bytes for characters outside plane 1.

      'UTF-16' ⎕UCS 'ABCÆØÅ⍒⍋'
65 66 67 198 216 197 9042 9035
      ⎕←unihan←⎕UCS (2×2*16)+⍳3 ⍝ x20001-x20003

      'UTF-16' ⎕UCS unihan
55360 56321 55360 56322 55360 56323

Translation Error

⎕UCS will generate TRANSLATION ERROR (event number 92) if the argument cannot be converted. In the Classic Edition, a TRANSLATION ERROR is generated if the result is not in ⎕AV or the numeric argument is not in ⎕AVU.


Terminal Control

Terminal Control: (⎕ML) R←⎕TC

⎕TC is a deprecated feature and is replaced by ⎕UCS (see note).

⎕TC is a simple three element vector. If ⎕ML < 3 this is ordered as follows:

⎕TC[1] | Backspace
⎕TC[2] | Linefeed
⎕TC[3] | Newline

Note that ⎕TC≡⎕AV[⎕IO+⍳3] for ⎕ML< 3 .

If ⎕ML ≥ 3 the order of the elements of ⎕TC is instead compatible with IBM's APL2:

⎕TC[1] | Backspace
⎕TC[2] | Newline
⎕TC[3] | Linefeed

Elements of ⎕TC beyond 3 are not defined but are reserved.

Note

With the introduction of ⎕UCS in Version 12.0, the use of ⎕TC is discouraged and it is strongly recommended that you generate control characters using ⎕UCS instead. This recommendation holds true even if you continue to use the Classic Edition.

Control Character | Old | New
Backspace | ⎕TC[1] | ⎕UCS 8
Linefeed | ⎕TC[2] (⎕ML<3) ⎕TC[3] (⎕ML≥3) | ⎕UCS 10
Newline | ⎕TC[3] (⎕ML<3) ⎕TC[2] (⎕ML≥3) | ⎕UCS 13


Null Item

Null Item: R←⎕NULL

This is a reference to a null item, such as may be returned across the COM interface to represent a null value. An example might be the value of an empty cell in a spreadsheet.

⎕NULL may be used in any context that accepts a namespace reference, in particular:

  • As the argument to a defined function
  • As an item of an array.
  • As the argument to those primitive functions that take character data arguments, for example: =, ≠, ≡, ≢, ,, ⍴, ⊃, ⊂

Example

      'EX'⎕WC'OLEClient' 'Excel.Application'
      WB←EX.Workbooks.Open 'simple.xls'

      (WB.Sheets.Item 1).UsedRange.Value2
 [Null]  [Null]  [Null]  [Null]  [Null]
 [Null]    Year  [Null]  [Null]  [Null]
 [Null]    1999    2000    2001    2002
 [Null]  [Null]  [Null]  [Null]  [Null]
 Sales      100      76     120     150
 [Null]  [Null]  [Null]  [Null]  [Null]
 Costs       80      60     100     110
 [Null]  [Null]  [Null]  [Null]  [Null]
 Margin      20      16      20      40

To determine which of the cells are filled, you can compare the array with ⎕NULL.

      ⎕NULL≢¨(WB.Sheets.Item 1).UsedRange.Value2
0 0 0 0 0
0 1 0 0 0
0 1 1 1 1
0 0 0 0 0
1 1 1 1 1
0 0 0 0 0
1 1 1 1 1
0 0 0 0 0
1 1 1 1 1


Delay

Delay: {R}←⎕DL Y

Y must be a simple non-negative numeric scalar or one element vector. A pause of approximately Y seconds is caused.

The shy result R is an integer scalar value indicating the length of the pause in seconds.

The pause may be interrupted by a strong interrupt.


Response Time Limit

Response Time Limit: ⎕RTL

A non-zero value in ⎕RTL places a time limit, in seconds, for input requested via ⍞ , ⎕ARBIN , and ⎕SR. ⎕RTL may be assigned any integer in the range 0 to 32767. The value is a clear workspace is 0.

Example

      ⎕RTL←5 ⋄ ⍞←'FUEL QUANTITY?' ⋄ R←⍞
FUEL QUANTITY?
TIMEOUT
      ⎕RTL←5 ⋄ ⍞←'FUEL QUANTITY?' ⋄ R←⍞


Format

Format ⎕FMT

Monadic ⎕FMT means

Display Form

      ⎕FMT 2 4⍴⍳8
1 2 3 4
5 6 7 8

Dyadic ⎕FMT means

Format

     'I3,F5.2' ⎕FMT 2 4⍴⍳8
  1 2.00  3 4.00
  5 6.00  7 8.00

Language Elements


Format Monadic

Format (Monadic): R←⎕FMT Y

Y may be any array. R is a simple character matrix which appears the same as the default display of Y. If Y contains control characters from ⎕TC, they will be resolved.

Examples

      A←⎕FMT '∩' ,⎕TC[1],'∘'

      ⍴A
1 1
      A
⍝

      A←⎕VR 'FOO'

      A
     ∇ R←FOO
[1]    R←10
     ∇

      ⍴A
31
      B←⎕FMT A

      B
     ∇ R←FOO
[1]    R←10
     ∇

      ⍴B
3 12


Format Dyadic

Format (Dyadic): R←X ⎕FMT Y

Y must be a simple array of rank not exceeding two, or a non-simple scalar or vector whose items are simple arrays of rank not exceeding two. The simple arrays in Y must be homogeneous, either character or numeric. All numeric values in Y must be simple; if Y contains any complex numbers, dyadic ⎕FMT will generate a DOMAIN ERROR. X must be a simple character vector. R is a simple character matrix.

X is a format specification that defines how columns of the simple arrays in Y are to appear. A simple scalar in Y is treated as a one-element matrix. A simple vector in Y is treated as a one-column matrix. Each column of the simple arrays in Y is formatted in left-to-right order according to the format specification in X taken in left-to-right order and used cyclically if necessary.

R has the same number of rows as the longest column (or implied column) in Y, and the number of columns is determined from the format specification.

The format specification consists of a series of control phrases, with adjacent phrases separated by a single comma, selected from the following:

rAw | Alphanumeric format
rEw.s | Scaled format
rqFw.d | Decimal format
rqG⍞pattern⍞ | Pattern
rqIw | Integer format
Tn | Absolute tabulation
Xn | Relative tabulation
⍞t⍞ | Text insertion

(Alternative surrounding pairs for Pattern or Text insertion are < >, ⊂ ⊃, ⎕ ⎕ or ¨ ¨.)

where:

r | is an optional repetition factor indicating that the format phrase is to be applied to r columns of Y
q | is an optional usage of qualifiers or affixtures from those described below.
w | is an integer value specifying the total field width per column of Y, including any affixtures.
s | is an integer value specifying the number of significant digits in Scaled format; s must be less than w-1
d | is an integer value specifying the number of places of decimal in Decimal format; d must be less than w.
n | is an integer value specifying a tab position relative to the notional left margin (for T-format) or relative to the last formatted position (for X-format) at which to begin the next format.
t | is any arbitrary text excluding the surrounding character pair. Double quotes imply a single quote in the result.
pattern | see following section G format

Qualifiers q are as follows:

B | leaves the field blank if the result would otherwise be zero.
C | inserts commas between triads of digits starting from the rightmost digit of the integer part of the result.
Km | scales numeric values by 1Em where m is an integer; negation may be indicated by ¯ or - preceding the number.
L | left justifies the result in the field width.
Ov⍞t⍞ | replaces specific numeric value v with the text t.
S⍞p⍞ | substitutes standard characters. p is a string of pairs of symbols enclosed between any of the Text Insertion delimiters. The first of each pair is the standard symbol and the second is the symbol to be substituted. Standard symbols are: * overflow fill character . decimal point , triad separator for C qualifier 0 fill character for Z qualifier _ loss of precision character
Z | fills unused leading positions in the result with zeros (and commas if C is also specified).
9 | digit selector

Affixtures are as follows:

M⍞t⍞ | prefixes negative results with the text t instead of the negative sign.
N⍞t⍞ | post-fixes negative results with the text t
P⍞t⍞ | prefixes positive or zero results with the text t.
Q⍞t⍞ | post-fixes positive or zero results with the text t.
R⍞t⍞ | presets the field with the text t which is repeated as necessary to fill the field. The text will be replaced in parts of the field filled by the result, including the effects of other qualifiers and affixtures except the B qualifier

The surrounding affixture delimiters may be replaced by the alternative pairs described for Text Insertion.

Examples

A vector is treated as a column:

      'I5' ⎕FMT 10 20 30
   10
   20
   30

The format specification is used cyclically to format the columns of the right argument:

      'I3,F5.2' ⎕FMT 2 4⍴⍳8
  1 2.00  3 4.00
  5 6.00  7 8.00

The columns of the separate arrays in the items of a non-simple right argument are formatted in order. Rows in a formatted column beyond the length of the column are left blank:

      '2I4,F7.1' ⎕FMT (⍳4)(2 2⍴ 0.1×⍳4)
   1   0    0.2
   1   0    0.4
   3
   4

Characters are right justified within the specified field width, unless the L qualifier is specified:

      'A2' ⎕FMT 1 6⍴'SPACED'
 S P A C E D

If the result is too wide to fit within the specified width, the field is filled with asterisks:

      'F5.2' ⎕FMT 0.1×5 1000 ¯100
  0.50
*****
*****

Relative tabulation (X-format) identifies the starting position for the next format phrase relative to the finishing position for the previous format, or the notional left margin if none. Negative values are permitted providing that the starting position is not brought back beyond the left margin. Blanks are inserted in the result, if necessary:

      'I2,X3,3A1' ⎕FMT (⍳3)(2 3⍴'TOPCAT')
 1   TOP
 2   CAT
 3

Absolute tabulation (T-format) specifies the starting position for the next format relative to the notional left margin. If position 0 is specified, the next format starts at the next free position as viewed so far. Blanks are inserted into the result as required. Over-written columns in the result contain the most recently formatted array columns taken in left-to-right order:

      X←'6I1,T5,A1,T1,3A1,T7,F5.1'

      X ⎕FMT (1 6⍴⍳6)('*')(1 3⍴'ABC')(22.2)
ABC4*6 22.2

If the number of specified significant digits exceeds the internal precision, low order digits are replaced by the symbol _:

      'F20.1' ⎕FMT 1E18÷3
3333333333333333__._

The Text Insertion format phrase inserts the given text repeatedly in all rows of the result:

      MEN←3 5⍴'FRED BILL JAMES'
      WOMEN←2 5⍴'MARY JUNE '

      '5A1,<|>' ⎕FMT MEN WOMEN
FRED |MARY |
BILL |JUNE |
JAMES|     |

The last example also illustrates that a Text Insertion phrase is used even though the data is exhausted. The following example illustrates effects of the various qualifiers:

      X←'F5.1,BF6.1,X1,ZF5.1,X1,LF5.1,K3CS<.,,.>F10.1'

      X ⎕FMT ⍉5 3⍴¯1.5 0 25
 ¯1.5  ¯1.5 ¯01.5 ¯1.5   ¯1.500,0
  0.0       000.0 0.0         0,0
 25.0  25.0 025.0 25.0   25.000,0

Affixtures allow text to be included within a field. The field width is not extended by the inclusion of affixtures. N and Q affixtures shift the result to the left by the number of characters in the text specification. Affixtures may be used to enclose negative results in parentheses in accordance with common accounting practice:

      'M<(>N<)>Q< >F9.2' ⎕FMT 150.3 ¯50.25 0 1114.9
  150.30
  (50.25)
    0.00
 1114.90

One or more format phrases may be surrounded by parentheses and preceded by an optional repetition factor. The format phrases within parentheses will be re-used the given number of times before the next format phrase is used. A Text Insertion phrase will not be re-used if the last data format phrase is preceded by a closing parenthesis:

      'I2,2(</>,ZI2)' ⎕FMT 1 3⍴⌽100|3↑⎕TS
20/07/89

G Format

Only the B, K, S and O qualifiers are valid with the G option

⍞pattern⍞ is an arbitrary string of characters, excluding the delimiter characters. Characters '9' and 'Z' (unless altered with the S qualifier) are special and are known as digit selectors.

The result of a G format will have length equal to the length of the pattern.

The data is rounded to the nearest integer (after possible scaling). Each digit of the rounded data replaces one digit selector in the result. If there are fewer data digits than digit selectors, the data digits are padded with leading zeros. If there are more data digits than digit selectors, the result will be filled with asterisks.

A '9' digit selector causes a data digit to be copied to the result.

A 'Z' digit selector causes a non-zero data digit to be copied to the result. A zero data digit is copied if and only if digits appear on either side of it. Otherwise a blank appears. Similarly text between digit selectors appears only if digits appear on either side of the text. Text appearing before the first digit selector or after the last will always appear in the result.

Examples

      'G⊂99/99/99⊃'⎕FMT 0 100 100 ⊥8 7 89
08/07/89

      'G⊂ZZ/ZZ/ZZ⊃'⎕FMT 80789 + 0 1
 8/07/89
 8/07/9

      'G⊂Andy ZZ Pauline ZZ⊃' ⎕FMT 2721.499 2699.5
Andy 27 Pauline 21
Andy 27

      ⍴⎕←'K2G⊂DM Z.ZZZ.ZZ9,99⊃' ⎕FMT 1234567.89 1234.56
DM 1.234.567,89
DM     1.234,56
2 15

An error will be reported if:

  • Numeric data is matched against an A control phrase.
  • Character data is matched against other than an A control phrase.
  • The format specification is ill-formed.
  • For an F control phrase, d>w-2
  • For an E control phrase, s>w-2

O Format Qualifier

The O format qualifier replaces a specific numeric value with a text string and may be used in conjunction with the E, F, I and G format phrases.

An O-qualifier consists of the letter "O" followed by the optional numeric value which is to be substituted (if omitted, the default is 0) and then the text string within pairs of symbols such as "<>". For example:

O - qualifier | Description
O<nil> | Replaces the value 0 with the text "nil"
O42<N/A> | Replaces the value 42 with the text "N/A"
O0.001<1/1000> | Replaces the value 0.001 with the text "1/1000"

The replacement text is inserted into the field in place of the numeric value. The text is normally right-aligned in the field, but will be left-aligned if the L qualifier is also specified.

It is permitted to specify more than one O-qualifier within a single phrase.

The O-qualifier is ⎕CT sensitive.

Examples

      'O<NIL>F7.2'⎕FMT 12.3 0 42.5
  12.30
    NIL
  42.50

      'O<NIL>LF7.2'⎕FMT 12.3 0 42.5
12.30
NIL
42.50

      'O<NIL>O42<N/A>I6'⎕FMT 12 0 42 13
    12
   NIL
   N/A
    13

      'O99<replace>F20.2'⎕fmt 99 100 101
             replace
              100.00
              101.00


Screen Dimensions

Screen Dimensions: R←⎕SD

⎕SD is a 2-element integer vector containing the number of rows and columns on the screen, or in the USER window.

For asynchronous terminals under UNIX, the screen size is taken from the terminal database terminfo or termcap.

In window implementations of Dyalog APL, ⎕SD reports the current size (in characters) of the USER window or the current size of the SM object, whichever is appropriate.


Screen Map

Screen Map: ⎕SM

⎕SM is a system variable that defines a character-based user interface (as opposed to a graphical user interface). In versions of Dyalog APL that support asynchronous terminals, ⎕SM defines a form that is displayed on the USER SCREEN. The implementation of ⎕SM in "window" environments is compatible with these versions. In Dyalog APL/X, ⎕SM occupies its own separate window on the display, but is otherwise equivalent. In versions of Dyalog APL with GUI support, ⎕SM either occupies its own separate window (as in Dyalog APL/X) or, if it exists, uses the window assigned to the SM object. This allows ⎕SM to be used in a GUI application in conjunction with other GUI components.

In general ⎕SM is a nested matrix containing between 3 and 13 columns. Each row of ⎕SM represents a field; each column a field attribute.

The columns have the following meanings:

Column | Description | Default
1 | Field Contents | N/A
2 | Field Position - Top Row | N/A
3 | Field Position - Left Column | N/A
4 | Window Size - Rows | 0
5 | Window Size - Columns | 0
6 | Field Type | 0
7 | Behaviour | 0
8 | Video Attributes | 0
9 | Active Video Attributes | ¯1
10 | Home Element - Row | 1
11 | Home Element - Column | 1
12 | Scrolling Group - Vertical | 0
13 | Scrolling Group - Horizontal | 0

With the exception of columns 1 and 8, all elements in ⎕SM are integer scalar values.

Elements in column 1 (Field Contents) may be:

  • A numeric scalar
  • A numeric vector
  • A 1-column numeric matrix
  • A character scalar
  • A character vector
  • A character matrix (rank 2)
  • A nested matrix defining a sub-form whose structure and contents must conform to that defined for ⎕SM as a whole. This definition is recursive. Note however that a sub-form must be a matrix - a vector is not allowed.

Elements in column 8 (Video Attributes) may be:

  • An integer scalar that specifies the appearance of the entire field.
  • An integer array of the same shape as the field contents. Each element specifies the appearance of the corresponding element in the field contents.

Screen Management (Async Terminals)

Dyalog APL for UNIX systems (Async terminals) manages two screens; the SESSION screen and the USER screen. If the SESSION screen is current, an assignment to ⎕SM causes the display to switch to the USER screen and show the form defined by ⎕SM.

If the USER screen is current, any change in the value of ⎕SM is immediately reflected by a corresponding change in the appearance of the display. However, an assignment to ⎕SM that leaves its value unchanged has no effect.

Dyalog APL automatically switches to the SESSION screen for default output, if it enters immediate input mode (6-space prompt), or through use of ⎕ or ⍞. This means that typing

      ⎕SM ← expression

in the APL session will cause the screen to switch first to the USER screen, display the form defined by ⎕SM, and then switch back to the SESSION screen to issue the 6-space prompt. This normally happens so quickly that all the user sees is a flash on the screen.

To retain the USER screen in view it is necessary to issue a call to ⎕SR or for APL to continue processing. e.g.

      ⎕SM ← expression  ⋄  ⎕SR 1

or

      ⎕SM ← expression  ⋄  ⎕DL 5

Screen Management (Window Versions)

In Dyalog APL/X, and optionally in Dyalog APL/W, ⎕SM is displayed in a separate USER WINDOW on the screen. In an end-user application this may be the only Dyalog APL window. However, during development, there will be a SESSION window, and perhaps EDIT and TRACE windows too.

The USER Window will only accept input during execution of ⎕SR. It is otherwise "output-only". Furthermore, during the execution of ⎕SR it is the only active window, and the SESSION, EDIT and TRACE Windows will not respond to user input.

Screen Management (GUI Versions)

In versions of Dyalog APL that provide GUI support, there is a special SM object that defines the position and size of the window to be associated with ⎕SM. This allows character-mode applications developed for previous versions of Dyalog APL to be migrated to and integrated with GUI environments without the need for a total re-write.

Effect of Localisation

Like all system variables (with the exception of ⎕TRAP) ⎕SM is subject to "pass-through localisation". This means that a localised ⎕SM assumes its value from the calling environment. The localisation of ⎕SM does not, of itself therefore, affect the appearance of the display. However, reassignment of a localised ⎕SM causes the new form to overlay rather than replace whatever forms are defined further down the stack. The localisation of ⎕SM thus provides a simple method of defining pop-up forms, help messages, etc.

The user may edit the form defined by ⎕SM using the system function ⎕SR. Under the control of ⎕SR the user may change the following elements in ⎕SM which may afterwards be referenced to obtain the new values.

Column 1 | Field Contents
Column 10 | Home Element - Row (by scrolling vertically)
Column 11 | Home Element - Column (by scrolling horizontally)


Screen Read

Screen Read: R←{X}⎕SR Y

⎕SR is a system function that allows the user to edit or otherwise interact with the form defined by ⎕SM.

In versions of Dyalog APL that support asynchronous terminals, if the current screen is the SESSION screen, ⎕SR immediately switches to the USER SCREEN and displays the form defined by ⎕SM.

In Dyalog APL/X, ⎕SR causes the input cursor to be positioned in the USER window. During execution of ⎕SR, only the USER Window defined by ⎕SM will accept input and respond to the keyboard or mouse. The SESSION and any EDIT and TRACE Windows that may appear on the display are dormant.

In versions of Dyalog APL with GUI support, a single SM object may be defined. This object defines the size and position of the ⎕SM window, and allows ⎕SM to be used in conjunctions with other GUI components. In these versions, ⎕SR acts as a superset of ⎕DQ (see Dequeue Events: ) but additionally controls the character-based user interface defined by ⎕SM.

Y is an integer vector that specifies the fields which the user may visit. In versions with GUI support, Y may additionally contain the names of GUI objects with which the user may also interact.

If specified, X may be an enclosed vector of character vectors defining EXIT_KEYS or a 2-element nested vector defining EXIT_KEYS and the INITIAL_CONTEXT.

The result R is the EXIT_CONTEXT.

Thus the 3 uses of ⎕SR are:

     EXIT_CONTEXT←⎕SR FIELDS

     EXIT_CONTEXT←(⊂EXIT_KEYS)⎕SR FIELDS

     EXIT_CONTEXT←(EXIT_KEYS)(INITIAL_CONTEXT)⎕SR FIELDS

FIELDS

If an element of Y is an integer scalar, it specifies a field as the index of a row in ⎕SM (if ⎕SM is a vector it is regarded as having 1 row).

If an element of Y is an integer vector, it specifies a sub-field. The first element in Y specifies the top-level field as above. The next element is used to index a row in the form defined by ⊃⎕SM[Y[1];1] and so forth.

If an element of Y is a character scalar or vector, it specifies the name of a top-level GUI object with which the user may also interact. Such an object must be a "top-level" object, i.e. the Root object ('.') or a Form or pop-up Menu. This feature is implemented ONLY in versions of Dyalog APL with GUI support.

EXIT_KEYS

Each element of EXIT_KEYS is a 2-character code from the Input Translate Table for the keyboard. If the user presses one of these keys, ⎕SR will terminate and return a result.

If EXIT_KEYS is not specified, it defaults to:

      'ER' 'EP' 'QT'

which (normally) specifies <Enter>, <Esc> and <Shift+Esc>.

INITIAL_CONTEXT

This is a vector of between 3 and 6 elements with the following meanings and defaults:

Element | Description | Default
1 | Initial Field | N/A
2 | Initial Cursor Position - Row | N/A
3 | Initial Cursor Position - Col | N/A
4 | Initial Keystroke | ''
5 | (ignored) | N/A
6 | Changed Field Flags | 0

Structure of INITIAL_CONTEXT

INITIAL_CONTEXT[1] specifies the field in which the cursor is to be placed. It is an integer scalar or vector, and must be a member of Y. It must not specify a field which has ÂÞÝÝÔÓ behaviour (64), as the cursor is not allowed to enter such a field.

INITIAL_CONTEXT[2 3] are integer scalars which specify the initial cursor position within the field in terms of row and column numbers.

INITIAL_CONTEXT[4] is either empty, or a 2-element character vector specifying the initial keystroke as a code from the Input Translate Table for the keyboard.

INITIAL_CONTEXT[5] is ignored. It is included so that the EXIT_CONTEXT result of one call to ⎕SR can be used as the INITIAL_CONTEXT to a subsequent call.

INITIAL_CONTEXT[6] is a Boolean scalar or vector the same length as Y. It specifies which of the fields in Y has been modified by the user.

EXIT_CONTEXT

The result EXIT_CONTEXT is a 6 or 9-element vector whose first 6 elements have the same structure as the INITIAL_CONTEXT. Elements 7-9 only apply to those versions of Dyalog APL that provide mouse support.

Element | Description
1 | Final Field
2 | Final Cursor Position - Row
3 | Final Cursor Position - Col
4 | Terminating Keystroke
5 | Event Code
6 | Changed Field Flags
7 | Pointer Field
8 | Pointer Position - Row
9 | Pointer Position - Col

Structure of the Result of ⎕SR

EXIT_CONTEXT[1] contains the field in which the cursor was when ⎕SR terminated due to the user pressing an exit key or due to an event occurring. It is an integer scalar or vector, and a member of Y.

EXIT_CONTEXT[2 3] are integer scalars which specify the row and column position of the cursor within the field EXIT_CONTEXT[1] when ⎕SR terminated.

EXIT_CONTEXT[4] is a 2-element character vector specifying the last keystroke pressed by the user before ⎕SR terminated. Unless ⎕SR terminated due to an event, EXIT_CONTEXT[4] will contain one of the exit keys defined by X. The keystroke is defined in terms of an Input Translate Table code.

EXIT_CONTEXT[5] contains the sum of the event codes that caused ⎕SR to terminate. For example, if the user pressed a mouse button on a ÂÞÝÝÔÓ field (event code 64) and the current field has ÒÔÇÍÊÍÈÇ behaviour (event code 2) EXIT_CONTEXT[5] will have the value 66.

EXIT_CONTEXT[6] is a Boolean scalar or vector the same length as Y. It specifies which of the fields in Y has been modified by the user during this ⎕SR, ORed with INITIAL_CONTEXT[6]. Thus if the EXIT_CONTEXT of one call to ⎕SR is fed back as the INITIAL_CONTEXT of the next, EXIT_CONTEXT[6] records the fields changed since the start of the process.

EXIT_CONTEXT (Window Versions)

⎕SR returns a 9-element result ONLY if it is terminated by the user pressing a mouse button. In this case:

EXIT_CONTEXT[7] contains the field over which the mouse pointer was positioned when the user pressed a button. It is an integer scalar or vector, and a member of Y.

EXIT_CONTEXT[8 9] are integer scalars which specify the row and column position of the mouse pointer within the field EXIT_CONTEXT[7] when ⎕SR terminated.


Arbitrary Input

Arbitrary Input: R←{X}⎕ARBIN Y

This transmits the prompt Y to an output device specified by X prior to reading from an input device specified by X.

Under Windows, the use of ⎕ARBIN to the screen is not supported.

Y may be a scalar, a simple vector, or a vector of simple scalars or vectors. The items of the simple arrays of Y must each be a character, or a number in the range 0 to 255. Numbers are sent to the output device without translation. Characters undergo the standard ⎕AV to ASCII translation. If Y is an empty vector, no codes are sent to the output device.

X may take several forms:

terminate (input output) | ⎕ARBIN | prompt
terminate input | ⎕ARBIN | prompt
terminate | ⎕ARBIN | prompt
 | ⎕ARBIN | prompt

Each of these elements is discussed separately.

<terminate>

This defines how the read should be terminated.

If it is omitted, the read terminates on receipt of a Carriage Return (CR) character.

If supplied, it must be a simple numeric scalar or vector.

  • If it is a numeric scalar, it defines the number of characters to be read.
  • If it is a numeric vector, it defines a set of terminating characters.
  • If it is the null vector, the read terminates on CR.

<input>

This defines the input device.

If this is omitted, input is taken from standard input (usually the keyboard).

If supplied, it must be a simple numeric scalar or a simple text vector.

  • If it is a numeric scalar, it must correspond to a Windows device handle or UNIX stream number.
  • If it is a text vector, it must correspond to a valid device or file name.

You must have permission to read from the chosen device.

<output>

This defines the output device.

If this is omitted, output is sent to standard output (usually the screen).

If supplied, it must be a simple numeric scalar or a simple text vector.

  • If it is a numeric scalar, it must correspond to a Windows device handle or UNIX stream number.
  • If it is a text vector, it must correspond to a valid device or file name.

You must have permission to write to the chosen device.

The result R is a simple numeric vector. Each item of R is the numeric representation of an 8-bit code in the range 0 to 255 received from the input device. The meaning of the code is dependent on the characteristics of the input device. If a set of delimiters was defined by <terminate>, the last code returned will belong to that set.

⎕RTL (Response Time Limit) is an implicit argument of ⎕ARBIN. This allows a time limit to be imposed on input. If the time limit is reached, ⎕ARBIN returns with the codes read up to that point.

Examples

Write HELLO on the screen, and read a line of input from the keyboard:

      R ← ⎕ARBIN 'HELLO'

Beep three times, send ARE YOU AWAKE? to the screen and wait for a 1 character answer from the keyboard:

      R ← 1 ⎕ARBIN 7 7 7 'ARE YOU AWAKE (Y/N)'

Read a line from MYFILE:

      R ← '' 'MYFILE' ⎕ARBIN ''

Read MYFILE until a SPACE (code 32):

      R ← (,32) 'MYFILE' ⎕ARBIN ''

Read MYFILE until a SPACE (code 32) or a TAB (code 9):

      R ← (32 9) 'MYFILE' ⎕ARBIN ''

Write HELLO on /dev/tty1 (a UNIX terminal screen), then read a line from /dev/tty1 (a UNIX terminal keyboard):

      R ← '' ('/dev/tty1' '/dev/tty1') ⎕ARBIN 'HELLO'

Write TITLE to LPT1 (a Windows printer device), then read from COM1 (a Windows serial port) up to the first CR character:

      R ← (,13) ('COM1' 'LPT1') ⎕ARBIN 'TITLE'

Read 100 characters from COM1; timeout after 10 secs:

      ⎕RTL←10
      R←100 'COM1' ⎕ARBIN ''
      ⍎(100≠⍴R)/'''Read timed out'''

Read until DELIM from COM1; timeout after 10 secs:

      ⎕RTL←10
      R←(,DELIM) 'COM1' ⎕ARBIN ''
      ⍎(DELIM≠¯1↑R)/'''Read timed out'''


Arbitrary Output

Arbitrary Output: {X}⎕ARBOUT Y

This transmits Y to an output device specified by X.

Under Windows, the use of ⎕ARBOUT to the screen or to RS232 ports is not supported.

Y may be a scalar, a simple vector, or a vector of simple scalars or vectors. The items of the simple arrays of Y must each be a character or a number in the range 0 to 255. Numbers are sent to the output device without translation. Characters undergo the standard ⎕AV to ASCII translation. If Y is an empty vector, no codes are sent to the output device.

X defines the output device. If X is omitted, output is sent to standard output (usually the screen). If X is supplied, it must be a simple numeric scalar or a simple text vector.

If it is a numeric scalar, it must correspond to a Windows device handle or UNIX stream number.

If it is a text vector, it must correspond to a valid device or file name.

You must have permission to write to the chosen device.

Examples

Write ASCII digits '123' to UNIX stream 9:

      9 ⎕ARBOUT 49 50 51

Write ASCII characters 'ABC' to MYFILE:

     'MYFILE' ⎕ARBOUT 'ABC'

Beep 3 times:

     ⎕ARBOUT 7 7 7

Prompt for input:

     ⍞← 'Prompt: ' ⋄ ⎕arbout 12 ⋄ ans←⍞


File System Available

File System Available: R←⎕FAVAIL

This niladic function returns the scalar value 1 unless the component file system is unavailable for some reason, in which case it returns scalar 0. If ⎕FAVAIL does return 0, most of the component file system functions will generate the error message:

FILE SYSTEM NOT AVAILABLE

See User Guide for further details.


File Copy

File Copy: R←X ⎕FCOPY Y

Access Code: 4609

Y must be a simple integer scalar or 1 or 2-element vector containing the file tie number and optional passnumber. The file need not be tied exclusively.

X is a character vector containing the name of a new file to be copied to.

⎕FCOPY creates a copy of the tied file specified by Y, named X. The new file X will be a 64-bit file, but will otherwise be identical to the original file. In particular all component level information, including the user number and update time, will be the same. The operating system file creation, modification and access times will be set to the time at which the copy occurred.

The result R is the file tie number associated with the new file X.

Note that the Access Code is 4609, which is the sum of the Access Codes for ⎕FREAD (1), ⎕FRDCI (512) and ⎕FRDAC (4096).

Example

      told←'oldfile32'⎕FTIE 0
      'S' ⎕FPROPS told
32
      tnew←'newfile64' ⎕FCOPY told

      'S' ⎕FPROPS tnew
64

If X specifies the name of an existing file, the operation fails with a FILE NAME ERROR.

Note: This operation is atomic. If an error occurs during the copy operation (such as disk full) or if a strong interrupt is issued, the copy will be aborted and the new file X will not be created.


File Create

File Create: {R}←X ⎕FCREATE Y

Y must be a simple integer scalar or a 1 or 2 element vector containing the file tie number followed by an optional address size. .

The file tie number must not be the tie number associated with another tied file.

The address size is an integer and may be either 32 or 64. A value of 32 causes the internal component addresses to be represented by 32-bit values which allow a maximum file size of 4GB. A value of 64 (the default) causes the internal component addresses to be represented by 64-bit values which allows file sizes up to operating system limits. Note that 32-bit component files will. See below.

Note:

  • a 32-bit component file may not contain Unicode character data.
  • a 64-bit component file may not be accessed by versions of Dyalog APL prior to Version 10.1.0

X must be either

  1. a simple character scalar or vector which specifies the name of the file to be created. See User Guide for file naming conventions under UNIX and Windows.
  2. a vector of length 1 or 2 whose items are:
  1. a simple character scalar or vector as above.
  2. an integer scalar specifying the file size limit in bytes.

The newly created file is tied for exclusive use.

The shy result of ⎕FCREATE is the tie number of the new file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS    ⍝ With next available number,
      file ⎕FCREATE tie   ⍝ ... create file.

to:

      tie←file ⎕FCREATE 0 ⍝ Create with first available..

Examples

      '..\BUDGET\SALES'    ⎕FCREATE 2    ⍝ Windows
      '../budget/SALES.85' ⎕FCREATE 2    ⍝ UNIX

      'COSTS' 200000 ⎕FCREATE 4          ⍝ max size 200000

      'LARGE' ⎕FCREATE 5 64              ⍝ 64-bit file
      'SMALL' ⎕FCREATE 6 32              ⍝ 32-bit file

Important Note

Dyalog intends to withdraw support for 32-bit component files in future releases.

If you have any existing 32-bit component files, or applications which create and/or use them, Dyalog recommends that you prepare for this in the following ways:

  • Ensure that Dyalog is not started with the command-line option –F32. This option sets the default component file type which is created to 32-bit.
  • Ensure that no ⎕FCREATE within your applications explicitly specifies that 32-bit files are to be created.
  • Make plans to convert any existing 32-bit component files to 64-bit using ⎕FCOPY. ⎕FCOPY will create a 64-bit copy even if the file being copied is 32-bit.

Note: in order to allow the use of legacy files retrieved from backups etc., Dyalog will continue to provide a means to convert 32-bit files to supported formats for a minimum of 10 years after direct support is withdrawn.


File Properties

File Properties: R←X ⎕FPROPS Y

Access Code 1 (to read) or 8192 (to change properties)

⎕FPROPS reports and sets the properties of a component file.

Y must be a simple integer scalar or a 1 or 2-element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted, it is assumed to be 0.

X must be a simple character scalar or vector containing one or more valid Identifiers listed in the table below, or a 2-element nested vector which specifies an Identifier and a (new) value for that property. To set new values for more than one property, X must be is a vector of 2-element vectors, each of which contains an Identifier and a (new) value for that property.

If the left argument is a simple character array, the result R contains the current values for the properties identified by X. If the left argument is nested, the result R contains the previous values for the properties identified by X.

Identifier | Property | Description / Legal Values
S | File Size (read only) | 32 = Small Component Files (<4Gb) 64 = Large Component Files
E | Endian-ness (read only) | 0 = Little-endian 1 = Big-endian
U | Unicode | 0 = Characters must be written as type 82 arrays 1 = Characters may be written as Unicode arrays
J | Journaling | 0 = Disable Journaling 1 = Enable APL crash proof Journaling 2 = Enable System crash proof Journaling; repair needed on recovery 3 = Enable full System crash proof Journaling
C | Checksum | 0 = Disable checksum 1 = Enable checksum

The default properties for a newly created file are as follows:

  • S = 64
  • U = 1 (Unicode Edition and 64-bit file) or 0 (otherwise)
  • J = 1
  • C = 1
  • E depends upon the computer architecture.

Journaling Levels

Level 1 journaling (APL crash-proof) automatically protects a component file from damage in the event of abnormal termination of the APL process. The file state will be implicitly committed between updates and an incomplete update will automatically be rolled forward or back when the file is re-tied. In the event of an operating system crash the file may be more seriously damaged. If checksum was also enabled it may be repaired using ⎕FCHK but some components may be restored to a previous state or not restored at all.

Level 2 journaling (system crash-proof – repair needed on recovery) extends level 1 by ensuring that a component file is fully repairable using ⎕FCHK with no component loss in the event of an operating system failure. If an update was in progress when the system crashed the affected component will be rolled back to the previous state. Tying and modifying such a file without first running ⎕FCHK may however render it un-repairable.

Level 3 journaling (system crash-proof) extends level 1 further by protecting a component file from damage in the event of abnormal termination of the APL process and also the operating system. Rollback of an incomplete update will be automatic and no explicit repair will be needed.

Enabling journaling on a component file will reduce performance of file updates; higher journaling levels have a greater impact.

Journaling levels 2 and 3 cannot be set unless the checksum option is also enabled.

The default level of journaling may be changed using the APL_FCREATE_PROPS_J parameter (see User Guide).

Checksum Option

The checksum option is enabled by default. This enables a damaged file to be repaired using ⎕FCHK. It will however will reduce the performance of file updates slightly and result in larger component files. The default may be changed using the APL_FCREATE_PROPS_C parameter (See User Guide).

Enabling the checksum option on an existing non-empty component file, will mean that all components that had previously been written without a checksum, will be check-summed and converted. This operation which will take place when ⎕FPROPS is changed, may not, therefore, be instantaneous.

Journaling and checksum settings may be changed at any time a file is exclusively tied.

Component files written with Checksum enabled cannot be read by versions of Dyalog APL prior to Version 12.1.

Example

   tn←'myfile64' ⎕FCREATE 0
   'SEUJ' ⎕FPROPS tn
64 0 1 0

   tn←'myfile32' ⎕FCREATE 0 32
   'SEUJ' ⎕FPROPS tn
32 0 0 0

The following expression disables Unicode and switches Journaling on. The function returns the previous settings:

     ('U' 0)('J' 1) ⎕FPROPS tn
1 0

Note that to set the value of just a single property, the following two statements are equivalent:

     'J' 1 ⎕FPROPS tn
     (,⊂'J' 1) ⎕FPROPS tn

The Unicode property applies only to 64-bit component files. 32-bit component files may not contain Unicode character data and the value of the Unicode property is always 0. To convert a 32-bit component file to a 64-bit component file, use ⎕FCOPY.

Properties may be read by a task with ⎕FREAD permission (access code 1), and set by a task with ⎕FSTAC access (8192). To set the value of the Journaling property, the file must be exclusively tied.

If Journaling or Unicode properties are set, the file cannot be tied by Versions prior to Version 12.0. If journaling is set to a value higher than 1, or checksums are enabled, the file cannot be tied by versions prior to 12.1.


File Append Component

File Append Component: {R}←X ⎕FAPPEND Y

Access code 8

Y must be a simple integer scalar or a 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. Subject to a few restrictions, X may be any array.

The shy result R is the number of the component to which X is written, and is 1 greater than the previously highest component number in the file, or 1 if the file is new.

Examples

      (1000?1000) ⎕FAPPEND 1

      ⎕←(2 3⍴⍳6) 'Geoff' (⎕OR'FOO') ⎕FAPPEND 1
12

      ⎕←A B C ⎕FAPPEND¨1
13 14 15

Dump←{
    tie←⍺ ⎕FCREATE 0              ⍝ create file.
    (⎕FUNTIE tie){}⍵ ⎕FAPPEND tie ⍝ append and untie.
}


File Check and Repair

File Check and Repair: R←{X} ⎕FCHK Y

⎕FCHK validates and repairs component files, and validates files associated with external variables, following an abnormal termination of the APL process or operating system.

Y must be a simple character scalar or vector which specifies the name of the file to be exclusively checked or repaired. For component files, the file must be named in accordance with the operating system's conventions, and may be a relative or absolute pathname. The file must exist and must not be tied. For files associated with external variables, any filename extension must be specified even if ⎕XT would not require it. See User Guide for file naming conventions under Windows and UNIX. The file must exist and must not be associated with an external variable.

The optional left-argument X must be a vector of zero or more character vectors from among 'force', 'repair' and 'rebuild', which determine the detailed operation of the function. Note that these options are case-sensitive.

  • If X contains 'force' ⎕FCHK will validate the file even if it appears to have been cleanly untied.
  • If X contains 'repair' ⎕FCHK will repair the file, following validation, if it appears to be damaged. This option may be used in conjunction with 'force'.
  • If X contains 'rebuild' ⎕FCHK will repair the file unconditionally.

If X is omitted, the default behaviour is as follows:

  1. If the file appears to have been cleanly untied previously, return ⍬, i.e. report that the file is OK.
  2. Otherwise, validate the file and return the appropriate result. If the file is corrupt, no attempt is made to repair it.

The result R is a vector of the numbers of missing or damaged components. R may include non-positive numbers of "pseudo components" that indicate damage to parts of the file other than in specific components:

0 | ACCESS MATRIX.
¯1 | Free-block tree.
¯2 | Component index tree.

Other negative numbers represent damage to the file metadata; this set may be extended in the future.

Following a check of the file, a non-null result indicates that the file is damaged.

Following a repair of the file, the result indicates those components that could not be recovered. Un-recovered components will give a FILE COMPONENT DAMAGED error if read but may be replaced without error.

Repair can recover only check-summed components from the file, i.e. only those components that were written with the checksum option enabled (see File Properties: ).

Following an operating system crash, repair may result in one or more individual components being rolled back to a previous version or not recovered at all, unless Journaling levels 2 or 3 were also set when these components were written.


File Drop Component

File Drop Component: {R}←⎕FDROP Y

Access code 32

Y must be a simple integer vector of length 2 or 3 whose elements are:

[1] | a file tie number
[2] | a number specifying the position and number of components to be dropped. A positive value indicates that components are to be removed from the beginning of the file; a negative value indicates that components are to be removed from the end of the file
[3] | an optional passnumber which if omitted is assumed to be zero

The shy result of a ⎕FDROP is a vector of the numbers of the dropped components. This is analogous to ⎕FAPPEND in that the result is potentially useful for updating some sort of dictionary:

      cnos,←vec ⎕FAPPEND¨tie ⍝ Append index to dictionary

      cnos~←⎕FDROP tie,-⍴vec ⍝ Remove index from dict.

Note that the result vector, though potentially large, is generated only on request.

Examples

      ⎕FSIZE 1
1 21 5436 4294967295

      ⎕FDROP 1 3 ⋄ ⎕FSIZE 1
4 21 5436 4294967295

      ⎕FDROP 1 ¯2 ⋄ ⎕FSIZE 1
4 19 5436 4294967295


File Erase

File Erase: {R}←X ⎕FERASE Y

Access code 4

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. X must be a character scalar or vector containing the name of the file associated with the tie number Y. This name must be identical with the name used to tie the file, and the file must be exclusively tied. The file named in X is erased and untied. See User Guide for file naming conventions under UNIX and Windows.

The shy result of ⎕FERASE is the tie number of the erased file.

Examples

      'SALES'⎕FERASE 'SALES' ⎕FTIE 0

      './temp' ⎕FCREATE 1
      'temp' ⎕FERASE 1
FILE NAME ERROR
      'temp'⎕FERASE 1
      ^


File History

File History: R←⎕FHIST Y

Access code 16384

Y must be a simple integer vector of length 1 or 2 containing the file tie number and an optional passnumber. If the passnumber is omitted it is assumed to be zero.

The result is a numeric matrix with shape (5 2) whose rows represent the most recent occurrence of the following events.

  1. File creation (see note)
  2. (Undefined)
  3. Last update of the access matrix
  4. (Undefined)
  5. Last update performed by ⎕FAPPEND, ⎕FCREATE, ⎕FDROP or ⎕FREPLACE

For each event, the first column contain the user number and the second a timestamp. Like the timestamp reported by ⎕FRDCIthis is measured in 60ths of a second since 1st January 1970 (UTC).

Currently, the second and fourth rows of the result (undefined) contain (0 0).

Note: ⎕FHIST collects information only if journaling and/or checksum is in operation. If neither is in use, the collection of data for ⎕FHIST is disabled and its result is entirely 0. If a file has both journaling and checksum disabled, and then either is enabled, the collection of data for ⎕FHIST is enabled too. In this case, the information in row 1 of ⎕FHIST relates to the most recent enabling ⎕FPROPS operation rather than the original ⎕FCREATE.

In the examples that follow, the FHist function is used below to format the result of ⎕FHIST.

     ∇ r←FHist tn;cols;rows;fhist;fmt;ToTS;I2D
[1]    rows←'Created' 'Undefined' 'Last ⎕FSTAC'
[2]    rows,←'Undefined' 'Last Updated'
[3]    cols←'User' 'TimeStamp'
[4]    fmt←'ZI4,2(⊂-⊃,ZI2),⊂ ⊃,ZI2,2(⊂:⊃,ZI2)'|
[5]    I2D←{+2 ⎕NQ'.' 'IDNToDate'⍵}
[6]    ToTS←{d t←1 1 0 0 0⊂⍉⌊0 24 60 60 60⊤⍵
[7]        ↓fmt ⎕FMT(0 ¯1↓↑I2D¨25568+,d),0 ¯1↓t}
[8]    fhist←⎕FHIST tn
[9]    fhist[;2]←ToTS fhist[;2]
[10]   fhist[;1]←⍕¨fhist[;1]
[11]   r←((⊂''),rows),cols⍪fhist
     ∇

Examples

     'c:\temp'⎕FCREATE 1 ⋄ FHist 1
               User  TimeStamp
 Created       0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last ⎕FSTAC   0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last Updated  0     2012-01-14 12:29:53

      (⍳10)⎕FAPPEND 1  ⋄ FHist 1
               User  TimeStamp
 Created       0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last ⎕FSTAC   0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last Updated  0     2012-01-14 12:29:55

      ⎕FUNTIE 1

      'c:\temp'⎕FCREATE 1 ⋄ FHist 1
               User  TimeStamp
 Created       0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last ⎕FSTAC   0     2012-01-14 12:29:53
 Undefined     0     1970-01-01 00:00:00
 Last Updated  0     2012-01-14 12:29:55


File Hold

File Hold: {R}←⎕FHOLD Y

Access code 2048

This function holds component file(s) and/or external variable(s).

If applied to component files, then Y is an integer scalar, vector, or one-row matrix of file tie numbers, or a two-row matrix whose first row contains file tie numbers and whose second row contains passnumbers.

If applied to external variables, then Y is a non-simple scalar or vector of character vectors, each of which is the name of an external variable. (NOT the file names associated with those variables).

If applied to component files and external variables, Y is a vector whose elements are either integer scalars representing tie numbers, or character vectors containing names of external variables.

The effect is as follows:

  1. The user's preceding holds (if any) are released.
  2. Execution is suspended until the designated files are free of holds by any other task.
  3. When all the designated files are free, execution proceeds. Until the hold is released, other tasks using ⎕FHOLD on any of the designated files will wait.

If Y is empty, the user's preceding hold (if any) is released, and execution continues.

A hold is released by any of the following:

  • Another ⎕FHOLD
  • Untying or retying all the designated files. If some but not all are untied or retied, they become free for another task but the hold persists for those that remain tied.
  • Termination of APL.
  • Any untrapped error or interrupt.
  • A return to immediate execution.

Note that a hold is not released by a request for input through ⎕ or ⍞.

Note also that point 5 above implies that ⎕FHOLD is generally useful only when called from a defined function, as holds set in immediate execution (desk calculator) mode are released immediately.

The shy result of ⎕FHOLD is a vector of tie numbers of the files held.

Examples:

      ⎕FHOLD 1

      ⎕FHOLD ⍬

      ⎕FHOLD ⊂'XTVAR'

      ⎕FHOLD 1 2,[0.5]0 16385

      ⎕FHOLD 1 'XTVAR'


Component File Library

Component File Library: R←⎕FLIB Y

Y must be a simple character scalar or vector which specifies the name of the directory whose APL component files are to be listed. If Y is empty, the current working directory is assumed.

The result R is a character matrix containing the names of the component files in the directory with one row per file. The number of columns is given by the longest file name. Each file name is prefixed by Y followed by a directory delimiter character. The ordering of the rows is not defined.

If there are no APL component files accessible to the user in the directory in question, the result is an empty character matrix with 0 rows and 0 columns.

Examples

      ⎕FLIB ''
SALESFILE
COSTS

      ⎕FLIB '.'
./SALESFILE
./COSTS

      ⎕FLIB '../budget'
../budget/SALES.85
../budget/COSTS.85


File Names

File Names: R←⎕FNAMES

The result is a character matrix containing the names of all tied files, with one file name per row. The number of columns is that required by the longest file name.

A file name is returned precisely as it was specified when the file was tied. If no files are tied, the result is a character matrix with 0 rows and 0 columns. The rows of the result are in the order in which the files were tied.

Examples

      '/usr/pete/SALESFILE' ⎕FSTIE 16

      '../budget/COSTFILE' ⎕FSTIE 2

      'PROFIT' ⎕FCREATE 5

       ⎕FNAMES
/usr/pete/SALESFILE
../budget/COSTFILE
PROFIT

      ⍴⎕FNAMES
3 19
      ⎕FNUMS,⎕FNAMES
16 /usr/pete/SALESFILE
 2 ../budget/COSTFILE
 5 PROFIT


File Numbers

File Numbers: R←⎕FNUMS

The result is an integer vector of the tie numbers of all tied files. If no files are tied, the result is empty. The elements of the result are in the order in which the files were tied.

Examples

      '/usr/pete/SALESFILE' ⎕FSTIE 16

      '../budget/COSTFILE' ⎕FSTIE 2

      'PROFIT' ⎕FCREATE 5

      ⎕FNUMS
16 2 5

      ⎕FNUMS,⎕FNAMES
16 /usr/pete/SALESFILE
 2 ../budget/COSTFILE
 5 PROFIT

      ⎕FUNTIE ⎕FNUMS
      ⍴⎕FNUMS
0


File Read Access

File Read Access: R←⎕FRDAC Y

Access code 4096

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. The result is the access matrix for the designated file.

See "File Access Control" in User Guide for further details.

Examples

      ⎕FRDAC 1
28 2105 16385
 0 2073 16385
31   ¯1     0


File Read Component Information

File Read Component Information: R←⎕FRDCI Y

Access code 512

Y must be a simple integer vector of length 2 or 3 containing the file tie number, component number and an optional passnumber. If the passnumber is omitted it is assumed to be zero.

The result is a 3 element numeric vector containing the following information:

  1. the size of the component in bytes (i.e. how much disk space it occupies).
  2. the user number of the user who last updated the component.
  3. the time of the last update in 60ths of a second since 1st January 1970 (UTC).

Example

      ⎕FRDCI 1 13
2200 207 3.702094494E10


File Read Component

File Read Component: R←⎕FREAD Y

Access code 1

Y is a 2 or 3 item vector containing the file tie number, the component number(s), and an optional passnumber. If the passnumber is omitted it is assumed to be zero. All elements of Y must be integers.

The second item in Y may be scalar which specifies a single component number or a vector of component numbers. If it is a scalar, the result is the value of the array that is stored in the specified component on the tied file. If it is a vector, the result is a vector of such arrays.

Note that any invocation of ⎕FREAD is an atomic operation. Thus if compnos is a vector, the statement:

      ⎕FREAD tie compnos passno

will return the same result as:

      {⎕FREAD tie ⍵ passno}¨compnos

However, the first statement will, in the case of a share-tied file, prevent any potential intervening file access from another user (without the need for a ⎕FHOLD). It will also perform slightly faster, especially when reading from a share-tied file..

Examples

      ⍴SALES←⎕FREAD 1 241
3 2 12

GetFile←{⎕io←0                ⍝ Extract contents.
    tie←⍵ ⎕fstie 0            ⍝ new tie number.
    fm to←2↑⎕fsize tie        ⍝ first and next component.
    cnos←fm+⍳to-fm            ⍝ vector of component nos.
    cvec←⎕fread tie cnos      ⍝ vector of components.
    cvec{⍺}⎕funtie tie        ⍝ ... untie and return.
}


File Rename

File Rename: {R}←X ⎕FRENAME Y

Access code 128

Y must be a simple 1 or 2 element integer vector containing a file tie number and an optional passnumber. If the passnumber is omitted it is assumed to be zero.

X must be a simple character scalar or vector containing the new name of the file. This name must be in accordance with the operating system's conventions, and may be specified with a relative or absolute pathname.

The file being renamed must be tied exclusively.

The shy result of ⎕FRENAME is the tie number of the file.

Examples

      'SALES' ⎕FTIE 1
      'PROFIT' ⎕FTIE 2

      ⎕FNAMES
SALES
PROFIT

      'SALES.85' ⎕FRENAME 1
      '../profits/PROFIT.85' ⎕FRENAME 2
      ⎕FNAMES
SALES.85
../profits/PROFITS.85

Rename←{
    fm to←⍵
    ⎕FUNTIE to ⎕FRENAME fm ⎕FTIE 0
}


File Replace Component

File Replace Component: {R}←X ⎕FREPLACE Y

Access code 16

Y must be a simple 2 or 3 element integer vector containing the file tie number, the component number, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The component number specified must lie within the file's component number limits.

X is any array (including, for example, the ⎕OR of a namespace), and overwrites the value of the specified component. The component information (see File Read Component Information: ) is also updated.

The shy result of ⎕FREPLACE is the file index (component number of replaced record).

Example

      SALES←⎕FREAD 1 241

      (SALES×1.1) ⎕FREPLACE 1 241

Define a function to replace (index, value) pairs in a component file JMS.DCF:

Frep←{
    tie←⍺ ⎕FTIE 0
    _←{⍵ ⎕FREPLACE tie ⍺}/¨⍵
    ⎕FUNTIE tie
}

      'jms'Frep(3 'abc')(29 'xxx')(7 'yyy')


File Resize

File Resize: {R}←{X}⎕FRESIZE Y

Access code 1024

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero.

X is an integer that specifies the maximum permitted size of the file in bytes. The value 0 means the maximum possible size of file.

An attempt to update a component file that would cause it to exceed its maximum size will fail with a FILE FULL error (21).A side effect of ⎕FRESIZE is to cause the file to be compacted. Any interrupt entered at the keyboard during the compaction is ignored. Note that if the left argument is omitted, the file is simply compacted and the maximum file size remains unchanged.

During compaction, the file is restructured by reordering the components and by amalgamating the free areas at the end of the file. The file is then truncated and excess disk space is released back to the operating system. For a large file with many components, this process may take a significant time.

The shy result of ⎕FRESIZE is the tie number of the file.

Example

      'test'⎕FCREATE 1 ⋄ ⎕FSIZE 1
1 1 120 1.844674407E19
      (10 1000⍴1.1)⎕FAPPEND 1 ⋄ ⎕FSIZE 1
1 2 80288 1.844674407E19

      100000 ⎕FRESIZE 1 ⍝ Limit size to 100000 bytes

      (10 1000⍴1.1)⎕FAPPEND 1
FILE FULL
      (10 1000⍴1.1)⎕FAPPEND 1
     ∧

      ⎕FRESIZE 1      ⍝ Force file compaction.


File Size

File Size: R←⎕FSIZE Y

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. The result is a 4 element numeric vector containing the following:

Element | Description
1 | the number of first component
2 | 1 + the number of the last component, (i.e. the result of the next ⎕FAPPEND)
3 | the current size of the file in bytes
4 | the file size limit in bytes

Example

      ⎕FSIZE 1
1 21 65271 4294967295


File Set Access

File Set Access: {R}←X ⎕FSTAC Y

Access code 8192

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero.

X must be a valid access matrix, i.e. a 3 column integer matrix with any number of rows.

See "File Access Control" in User Guide for further details.

The shy result of ⎕FSTAC is the tie number of the file.

Examples

      SALES ⎕FCREATE 1
      (3 3⍴28 2105 16385 0 2073 16385 31 ¯1 0) ⎕FSTAC 1
      ((⎕FRDAC 1)⍪21 2105 16385) ⎕FSTAC 1

      (1 3⍴0 ¯1 0)⎕FSTAC 2


File Share Tie

File Share Tie: {R}←X ⎕FSTIE Y

Y must be 0 or a simple 1 or 2 element integer vector containing an available file tie number to be associated with the file for further file operations, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The tie number must not already be associated with a tied file.

X must be a simple character scalar or vector which specifies the name of the file to be tied. The file must be named in accordance with the operating system's conventions, and may be specified with a relative or absolute pathname.

The file must exist and be accessible by the user. If it is already tied by another task, it must not be tied exclusively.

The shy result of ⎕FSTIE is the tie number of the file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create, share tie or exclusive tie operation, allocates the first (closest to zero) available tie number and returns it as an explicit result. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS  ⍝ With next available number,
      file ⎕FSTIE tie   ⍝ ... share tie file.

to:

      tie←file ⎕FSTIE 0 ⍝ Tie with 1st available number.

Example

      'SALES' ⎕FSTIE 1

      '../budget/COSTS' ⎕FSTIE 2


Exclusive File Tie

Exclusive File Tie: {R}←X ⎕FTIE Y

Access code 2

Y must be 0 or a simple 1 or 2 element integer vector containing an available file tie number to be associated with the file for further file operations, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The tie number must not already be associated with a share tied or exclusively tied file.

X must be a simple character scalar or vector which specifies the name of the file to be exclusively tied. The file must be named in accordance with the operating system's conventions, and may be a relative or absolute pathname.

The file must exist and be accessible by the user. It may not already be tied by another user.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create, share tie or exclusive tie operation, allocates the first (closest to zero) available tie number, and returns it as an explicit result. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS ⍝ With next available number,
      file ⎕FTIE tie   ⍝ ... tie file.

to:

      tie←file ⎕FTIE 0 ⍝ Tie with first available number.

The shy result of ⎕FTIE is the tie number of the file.

Examples

      'SALES' ⎕FTIE 1

      '../budget/COSTS' ⎕FTIE  2

      '../budget/expenses' ⎕FTIE 0
3


File Untie

File Untie: {R}←⎕FUNTIE Y

Y must be a simple integer scalar or vector (including Zilde). Files whose tie numbers occur in Y are untied. Other elements of Y have no effect.

If Y is empty, no files are untied, but all the interpreter's internal file buffers are flushed and the operating system is asked to flush all file updates to disk. This special facility allows the programmer to add extra security (at the expense of performance) for application data files.

The shy result of ⎕FUNTIE is a vector of tie numbers of the files actually untied.

Example

      ⎕FUNTIE ⎕FNUMS ⍝ Unties all tied files

      ⎕FUNTIE ⍬      ⍝ Flushes all buffers to disk


External Variables

External Variables ⎕XT

Dyadic ⎕XT means

Set External Variable

      'EXT\ARRAY' ⎕XT 'V'

Monadic ⎕XT means

Query External Variable

      ⎕XT'V'
EXT\ARRAY

Language Elements


Query External Variable

Query External Variable: R←⎕XT Y

Y must be a simple character scalar or vector which is taken to be a variable name. R is a simple character vector containing the file reference of the external array associated with the variable named by Y, or the null vector if there is no associated external array.

Example

      ⎕XT'V'
EXT\ARRAY

      ⍴⎕XT'G'
0


Set External Variable

Set External Variable: X ⎕XT Y

Y must be a simple character scalar or vector which is taken to be a variable name. X must be a simple character scalar or vector which is taken to be a file reference. The name given by Y is identified as an EXTERNAL VARIABLE associated with an EXTERNAL ARRAY whose value may be stored in file identified by X. See User Guide for file naming conventions under Windows and UNIX.

If Y is the name of a defined function or operator, a label or a namespace in the active workspace, a DOMAIN ERROR is reported.

Example

      'EXT\ARRAY' ⎕XT 'V'

If the file reference does not exist, the external variable has no value until a value is assigned:

      V
VALUE ERROR
      V
      ^

A value assigned to an external variable is stored in file space, not within the workspace:

      ⎕WA
2261186

      V←⍳100000

      ⎕WA
2261186

There are no specific restrictions placed on the use of external variables. They must conform to the normal requirements when used as arguments of functions or as operands of operators. The essential difference between a variable and an external variable is that an external variable requires only temporary workspace for an operation to accommodate (usually) a part of its value.

Examples

      V←⍳5
      +/V
15

      V[3]←⊂'ABC'

      V
1 2  ABC  4 5

      ⍴¨V
     3

Assignment allows the structure or the value of an external variable to be changed without fully defining the external array in the workspace.

Examples

      V,←⊂2 4⍴⍳8

      ⍴V
6

      V[6]
1 2 3 4
5 6 7 8

      V[1 2 4 5 6]×←10

      V
10 20  ABC  40 50  10 20 30 40
                   50 60 70 80

An external array is (usually) preserved in file space when the name of the external variable is disassociated from the file. It may be re-associated with any valid variable name.

Example

      ⎕EX'V'

      'EXT\ARRAY'⎕XT'F'

      F
10 20  ABC  40 50  10 20 30 40
                   50 60 70 80

In UNIX versions, if X is an empty vector, the external array is associated with a temporary file which is erased when the array is disassociated.

Example

      ''⎕XT'TEMP'

      TEMP←⍳10

      +/TEMP×TEMP
385

      ⎕EX'TEMP'

An external array may be erased using the native file function: ⎕NERASE.

In a multi-user environment (UNIX or a Windows LAN) a new file associated with an external array is created with access permission for owner read/write. An existing file is opened for exclusive use (by the owner) if the permissions remain at this level. If the access permissions allow any other users to read and write to the file, the file is opened for shared use. In UNIX versions, access permissions may be modified using the appropriate Operating System command, or in Windows using the supplied function XVAR from the UTIL workspace.


Data Representation

Data Representation ⎕DR

Monadic ⎕DR means

Query Data Type

      A←10
      ⎕DR A
83

Dyadic ⎕DR means

Change Data Type

      A←10
      11 ⎕DR A
0 0 0 0 1 0 1 0

Language Elements


Data Representation Monadic

Data Representation (Monadic): R←⎕DR Y

Monadic ⎕DR returns the type of its argument Y. The result R is an integer scalar containing one of the following values. Note that the internal representation and data types for character data differ between the Unicode and Classic Editions.

Table 15: Unicode Edition

Value | Data Type
11 | 1 bit Boolean
80 | 8 bits character
83 | 8 bits signed integer
160 | 16 bits character
163 | 16 bits signed integer
320 | 32 bits character
323 | 32 bits signed integer
326 | Pointer (32-bit or 64-bit as appropriate)
645 | 64 bits Floating
1287 | 128 bits Decimal

Table 16: Classic Edition

Value | Data Type
11 | 1 bit Boolean
82 | 8 bits character
83 | 8 bits signed integer
163 | 16 bits signed integer
323 | 32 bits signed integer
326 | Pointer (32-bit or 64-bit as appropriate)
645 | 64 bits Floating
1287 | 128 bits Decimal

Note that types 80, 160 and 320 and 83 and 163 and 1287 are exclusive to Dyalog APL.


Data Representation Dyadic

Data Representation (Dyadic): R←X ⎕DR Y

Dyadic ⎕DR converts the data type of its argument Y according to the type specification X. See Data Representation (Monadic): for a list of data types but note that 1287 is not a permitted value in X.

Case 1:

X is a single integer value. The bits in the right argument are interpreted as elements of an array of type X. The shape of the resulting new array will typically be changed along the last axis. For example, a character array seen as Boolean will have 8 times as many elements along the last axis.

Case 2:

X is a 2-element integer value. The bits in the right argument are interpreted as type X[1]. The system then attempts to convert the elements of the resulting array to type X[2] without loss of precision. The result R is a two element nested array comprised of:

  1. The converted elements or a fill element (0 or blank) where the conversion failed
  2. A Boolean array of the same shape indicating which elements were successfully converted.

Case 3: Classic Edition Only

X is a 3-element integer value and X[2 3] is 163 82. The bits in the right argument are interpreted as elements of an array of type X[1]. The system then converts them to the character representation of the corresponding 16 bit integers. This case is provided primarily for compatibility with APL*PLUS. For new applications, the use of the [conv] field with ⎕NAPPEND and ⎕NREPLACE is recommended.

Conversion to and from character (data type 82) uses the translate vector given by ⎕NXLATE 0. By default this is the mapping defined by the current output translate table (usually WIN.DOT).

Note. The internal representation of data may be modified during workspace compaction. For example, numeric arrays and (in the Unicode Edition) character arrays will, if possible, be squeezed to occupy the least possible amount of memory. However, the internal representation of the result R is guaranteed to remain unmodified until it is re-assigned (or partially re-assigned) with the result of any function.


Native File Create

Native File Create: {R}←X ⎕NCREATE Y

This function creates a new file. Under Windows the file is opened in compatibility mode. The name of the new file is specified by the left argument X which must be a simple character vector or scalar containing a valid pathname for the file. Y is 0 or a negative integer value that specifies an (unused) tie number by which the file may subsequently be referred.

The shy result of ⎕NCREATE is the tie number of the new file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←¯1+⌊/0,⎕NNUMS   ⍝ With next available number,
      file ⎕NCREATE tie   ⍝ ... create file.

to:

      tie←file ⎕NCREATE 0 ⍝ Create with first available no.

If the specified file already exists, ⎕NCREATE fails with the error (22):

      FILE NAME ERROR: Unable to create file


Native File Append

Native File Append: {R}←X ⎕NAPPEND Y

This function appends the ravel of its left argument X to the end of the designated native file. X must be a simple homogeneous APL array. Y is a 1- or 2-element integer vector. Y[1] is a negative integer that specifies the tie number of a native file. The optional second element Y[2] specifies the data type to which the array X is to be converted before it is written to the file.

The shy file index result returned is the position within the file of the end of the record, which is also the start of the following one.

Unicode Edition

Unless you specify the data type in Y[2], a character array will by default be written using type 80.

If the data will not fit into the specified character width (bytes) ⎕NAPPEND will fail with a DOMAIN ERROR.

As a consequence of these two rules, you must specify the data type (either 160 or 320) in order to write Unicode characters whose code-point are in the range 256-65535 and >65535 respectively.

Example

      n←'test'⎕NCREATE 0

      'abc' ⎕nappend n

      'ταβέρνα'⎕nappend n
DOMAIN ERROR
      'ταβέρνα'⎕NAPPEND n
     ∧

      'ταβέρνα'⎕NAPPEND n 160

      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 7
ταβέρνα

For compatibility with old files, you may specify that the data be converted to type 82 on output. The conversion (to ⎕AV indices) will be determined by the local value of ⎕AVU.


Native File Erase

Native File Erase: {R}←X ⎕NERASE Y

This function erases (deletes) a native file. Y is a negative integer tie number associated with a tied native file. X is a simple character vector or scalar containing the name of the same file and must be identical to the name used when it was opened by ⎕NCREATE or ⎕NTIE.

The shy result of ⎕NERASE is the tie number that the erased file had.

Example

      file ⎕nerase file ⎕ntie 0


Native File Lock

Native File Lock: {R}←X ⎕NLOCK Y

This function assists the controlled update of shared native files by locking a range of bytes.

Locking enables controlled update of native files by co-operating users. A process requesting a lock on a region of a file will be blocked until that region becomes available. A write-lock is exclusive, whereas a read-lock is shared. In other words, any byte in a file may be in one of only three states:

  • Unlocked
  • Write-locked by exactly one process.
  • Read-locked by any number of processes.

Y must be a simple integer scalar or vector containing 1, 2 or 3 items namely:

  1. Tie number
  2. Offset (from 0) of first byte of region. Defaults to 0
  3. Number of bytes to lock. Defaults to maximum possible file size

X must be a simple integer scalar or vector containing 1 or 2 items, namely:

  1. Type: 0: Unlock, 1:Read lock, 2:Write lock.
  2. Timeout: Number of seconds to wait for lock before generating a TIMEOUT error. Defaults to indefinite wait.

The shy result R is Y. To unlock the file, this value should subsequently be supplied in the right argument to 0 ⎕NLOCK.

Examples:

    2 ⎕NLOCK ¯1        ⍝ write-lock whole file
    0 ⎕NLOCK ¯1        ⍝ unlock whole file.
    1 ⎕NLOCK ¯1        ⍝ read (share) lock whole file.
    2 ⎕NLOCK¨⎕NNUMS    ⍝ write-lock all files.
    0 ⎕NLOCK¨⎕NNUMS    ⍝ unlock all files.

    1 ⎕NLOCK ¯1 12 1   ⍝ read-lock byte 12.
    1 ⎕NLOCK ¯1 0 10   ⍝ read-lock first 10 bytes.
    2 ⎕NLOCK ¯1 20     ⍝ write-lock from byte 20 onwards.
    2 ⎕NLOCK ¯1 10 2   ⍝ write-lock 2 bytes from byte 10
    0 ⎕NLOCK ¯1 12 1   ⍝ remove lock from byte 12.

To lock the region immediately beyond the end of the file prior extending it:

   ⎕←region←2 ⎕NLOCK ¯1, ⎕NSIZE ¯1 ⍝ write-lock from EOF.
¯1 1000
   ... ⎕NAPPEND ¯1                 ⍝ append bytes to file
   ... ⎕NAPPEND ¯1                 ⍝ append bytes to file

   0 ⎕NLOCK region                 ⍝ release lock.

The left argument may have a second optional item that specifies a timeout value. If a lock has not been acquired within this number of seconds, the acquisition is abandoned and a TIMEOUT error reported.

    2 10 ⎕nlock ¯1      ⍝ wait up to 10 seconds for lock.

Notes:

There is no per-byte cost associated with region locking. It takes the same time to lock/unlock a region, irrespective of that region’s size.

Different file servers implement locks in slightly different ways. For example on some systems, locks are advisory. This means that a write lock on a region precludes other locks intersecting that region, but doesn't stop reads or writes across the region. On the other hand, mandatory locks block both other locks and read/write operations. ⎕NLOCK will just pass the server's functionality along to the APL programmer without trying to standardise it across different systems.

All locks on a file will be removed by ⎕NUNTIE.

Blocked locking requests can be freed by a strong interrupt. Under Windows, this operation is performed from the Dyalog APL pop-up menu in the system tray.

Errors

In this release, an attempt to unlock a region that contains bytes that have not been locked results in a DOMAIN ERROR.

A LIMIT ERROR results if the operating system lock daemon has insufficient resources to honour the locking request.

Some systems support only write locks. In this case an attempt to set a read lock will generate a DOMAIN ERROR, and it may be appropriate for the APL programmer to trap the error and apply a write lock.

No attempt will be made to detect deadlock. Some servers do this and if such a condition is detected, a DEADLOCK error (1008) will be reported.


Native File Names

Native File Names: R←⎕NNAMES

This niladic function reports the names of all currently open native files. R is a character matrix. Each row contains the name of a tied native file padded if necessary with blanks. The names are identical to those that were given when opening the files with ⎕NCREATE or ⎕NTIE. The rows of the result are in the order in which the files were tied.


Native File Numbers

Native File Numbers: R←⎕NNUMS

This niladic function reports the tie numbers associated with all currently open native files. R is an integer vector of negative tie numbers. The elements of the result are in the order in which the files were tied.


Native File Read

Native File Read: R←⎕NREAD Y

This monadic function reads data from a native file. Y is a 3- or 4-element integer vector whose elements are as follows:

[1] | negative tie number,
[2] | conversion code (see below),
[3] | count,
[4] | start byte, counting from 0.

Y[2] specifies conversion to an APL internal form as follows. Note that the internal formats for character arrays differ between the Unicode and Classic Editions.

Table 17: Unicode Edition : Conversion Codes

Value | Number of bytes read | Result Type | Result shape
11 | count | 1 bit Boolean | 8 × count
80 | count | 8 bits character | count
82Conversion code 82 is permitted in the Unicode Edition for compatibility and causes 1-byte data on file to be translated (according to ⎕NXLATE) from ⎕AV indices into normal (Unicode) characters of type 80, 160 or 320. 1 | count | 8 bits character | count
83 | count | 8 bits integer | count
160 | 2 × count | 16-bits character | count
163 | 2 × count | 16 bits integer | count
320 | 4 × count | 32-bits character | count
323 | 4 × count | 32 bits integer | count
645 | 8 × count | 64bits floating | count

Table 18: Classic Edition : Conversion Codes

Value | Number of bytes read | Result Type | Result shape
11 | count | 1 bit Boolean | 8 × count
82 | count | 8 bits character | count
83 | count | 8 bits integer | count
163 | 2 × count | 16 bits integer | count
323 | 4 × count | 32 bits integer | count
645 | 8 × count | 64bits floating | count

Note that types 80, 160 and 320 and 83 and 163 are exclusive to Dyalog APL.

If Y[4] is omitted, data is read starting from the current position in the file (initially, 0).

Example

      DATA←⎕NREAD ¯1 160 (0.5×⎕NSIZE ¯1) 0 ⍝ Unicode
      DATA←⎕NREAD ¯1 82 (⎕NSIZE ¯1) 0      ⍝ Classic


Native File Rename

Native File Rename: {R}←X ⎕NRENAME Y

⎕NRENAME is used to rename a native file.

Y is a negative integer tie number associated with a tied native file. X is a simple character vector or scalar containing a valid (and unused) file name.

The shy result of ⎕NRENAME is the tie number of the renamed file.


Native File Replace

Native File Replace: {R}←X ⎕NREPLACE Y

⎕NREPLACE is used to write data to a native file, replacing data which is already there.

X must be a simple homogeneous APL array containing the data to be written.

Y is a 2- or 3-element integer vector whose elements are as follows:

[1] | negative tie number,
[2] | start byte, counting from 0, at which the data is to be written,
[3] | conversion code (optional).

See Native File Read: for a list of valid conversion codes.

The shy result is the position within the file of the end of the record, or, equivalently, the start of the following one. Used, for example, in:

      ⍝ Replace sequentially from indx.
      {⍺ ⎕NREPLACE tie ⍵}/vec,indx

Unicode Edition

Unless you specify the data type in Y[2], a character array will by default be written using type 80. .

If the data will not fit into the specified character width (bytes) ⎕NREPLACE will fail with a DOMAIN ERROR.

As a consequence of these two rules, you must specify the data type (either 160 or 320) in order to write Unicode characters whose code-point are in the range 256-65535 and >65535 respectively.

Example

      n←'test'⎕NTIE 0 ⍝ See Example

      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 7
ταβέρνα

      ⎕←'εστιατόριο'⎕NREPLACE n 3
DOMAIN ERROR
      ⎕←'εστιατόριο'⎕NREPLACE n 3
     ∧

      ⎕←'εστιατόριο'⎕NREPLACE n 3 160
23
      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 10
εστιατόριο

For compatibility with old files, you may specify that the data be converted to type 82 on output. The conversion (to ⎕AV indices) will be determined by the local value of ⎕AVU.


Native File Resize

Native File Resize: {R}←X ⎕NRESIZE Y

This function changes the size of a native file.

Y is a negative integer tie number associated with a tied native file.

X is a single integer value that specifies the new size of the file in bytes. If X is smaller than the current file size, the file is truncated. If X is larger than the current file size, the file is extended and the value of additional bytes is undefined.

The shy result of ⎕NRESIZE is the tie number of the resized file.


Native File Size

Native File Size: R←⎕NSIZE Y

This reports the size of a native file.

Y is a negative integer tie number associated with a tied native file. The result R is the size of the file in bytes.


Native File Tie

Native File Tie: {R}←X ⎕NTIE Y

⎕NTIE opens a native file.

X is a simple character vector or scalar containing a valid pathname for an existing native file.

Y is a 1- or 2-element vector. Y[1] is a negative integer value that specifies an (unused) tie number by which the file may subsequently be referred. Y[2] is optional and specifies the mode in which the file is to be opened. This is an integer value calculated as the sum of 2 codes. The first code refers to the type of access needed from users who have already tied the native file. The second code refers to the type of access you wish to grant to users who subsequently try to open the file while you have it open.

Needed from existing users |  | Granted to subsequent users
0 | read access | 0 | compatibility mode
1 | write access | 16 | no access (exclusive)
2 | read and write access | 32 | read access
 |  | 48 | write access
 |  | 64 | read and write access

On Unix systems, the first code (16|mode) is passed to the open(2) call as the access parameter. See include file fcntl.h for details.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←¯1+⌊/0,⎕NNUMS    ⍝ With next available number,
      file ⎕NTIE tie       ⍝ ... tie file.

to:

      tie←file ⎕NTIE 0     ⍝ Tie with first available no.

Example

ntie←{                  ⍝ tie file and return tie no.
    ⍺←2+64              ⍝ default all access.
    ⍵ ⎕ntie 0 ⍺         ⍝ return new tie no.
}


Native File Untie

Native File Untie: {R}←⎕NUNTIE Y

This closes one or more native files. Y is a scalar or vector of negative integer tie numbers. The files associated with elements of Y are closed. Native file untie with a zero length argument (⎕NUNTIE ⍬) flushes all file buffers to disk - see File Untie: for more explanation.

The shy result of ⎕NUNTIE is a vector of tie numbers of the files actually untied.


Native File Translate

Native File Translate: {R}←{X}⎕NXLATE Y

This associates a character translation vector with a native file or, if Y is 0, with the use by ⎕DR.

A translate vector is a 256-element vector of integers from 0-255. Each element maps the corresponding ⎕AV position onto an ANSI character code.

For example, to map ⎕AV[17+⎕IO] onto ANSI 'a' (code 97), element 17 of the translate vector is set to 97.

⎕NXLATE is a non-Unicode (Classic Edition) feature and is retained in the Unicode Edition only for compatibility.

Y is either a negative integer tie number associated with a tied native file or 0. If Y is negative, monadic ⎕NXLATE returns the current translation vector associated with the corresponding native file. If specified, the left argument X is a 256-element vector of integers that specifies a new translate vector. In this case, the old translate vector is returned as a shy result. If Y is 0, it refers to the translate vector used by ⎕DR to convert to and from character data.

The system treats a translate vector with value (⍳256)-⎕IO as meaning no translation and thus provides raw input/output bypassing the whole translation process.

The default translation vector established at ⎕NTIE or ⎕NCREATE time, maps ⎕AV characters to their corresponding ANSI positions and is derived from the mapping defined in the current output translation table (normally WIN.DOT)

Between them, ANSI and RAW translations should cater for most uses.

Unicode Edition

⎕NXLATE is relevant in the Unicode Edition only to process Native Files that contain characters expressed as indices into ⎕AV, such as files written by the Classic Edition.

In the Unicode Edition, when reading data from a Native File using conversion code 82, incoming bytes are translated first to ⎕AV indices using the translation table specified by ⎕NXLATE, and then to type 80, 160 or 320 using ⎕AVU. When writing data to a Native File using conversion code 82, characters are converted using these two translation tables in reverse.


Dequeue Events

Dequeue Events: {R}←⎕DQ Y

⎕DQ awaits and processes events. Y specifies the GUI objects(s) for which events are to be processed. Objects are identified by their names, as character scalars/vectors, or by namespace references. These may be objects of type Root, Form, Locator, Filebox, MsgBox, PropertySheet, TCPSocket, Timer, Clipboard and pop-up Menu. Sub-objects (children) of those named in Y are also included. However, any objects which exist, but are not named in Y, are effectively disabled (do not respond to the user).

If Y is '.', all objects currently owned and subsequently created by the current thread are included in the ⎕DQ. Note that because the Root object is owned by thread 0, events on Root are reported only to thread 0.

If Y is empty it specifies the object associated with the current namespace and is only valid if the current space is one of the objects listed above.

Otherwise, Y contains the name(s) of or reference(s) to the objects for which events are to be processed. Effectively, this is the list of objects with which the user may interact. A DOMAIN ERROR is reported if an element of Y refers to anything other than an existing "top-level" object.

Associated with every object is a set of events. For every event there is defined an "action" which specifies how that event is to be processed by ⎕DQ. The "action" may be a number with the value 0, 1 or ¯1, or a character vector containing the name of a "callback function", or a character vector containing the name of a callback function coupled with an arbitrary array. Actions can be defined in a number of ways, but the following examples will illustrate the different cases.

      OBJ ⎕WS 'Event' 'Select' 0

      OBJ ⎕WS 'Event' 'Select' 1

      OBJ ⎕WS 'Event' 'Select' 'FOO'

      OBJ ⎕WS 'Event' 'Select' 'FOO' 10

      OBJ ⎕WS 'Event' 'Select' 'FOO&'

These are treated as follows:

Action = 0 (the default)

⎕DQ performs "standard" processing appropriate to the object and type of event. For example, the standard processing for a KeyPress event in an Edit object is to action the key press, i.e. to echo the character on the screen.

Action = ¯1

This disables the event. The "standard" processing appropriate to the object and type of event is not performed, or in some cases is reversed. For example, if the "action code" for a KeyPress event (22) is set to ¯1, ⎕DQ simply ignores all keystrokes for the object in question.

Action = 1

⎕DQ terminates and returns information pertaining to the event (the event message in R as a nested vector whose first two elements are the name of the object (that generated the event) and the event code. R may contain additional elements depending upon the type of event that occurred.

Action = fn {larg}

fn is a character vector containing the name of a callback function. This function is automatically invoked by ⎕DQ whenever the event occurs, and prior to the standard processing for the event. The callback is supplied the event message (see above) as its right argument, and, if specified, the array larg as its left argument. If the callback function fails to return a result, or returns the scalar value 1, ⎕DQ then performs the standard processing appropriate to the object and type of event. If the callback function returns a scalar 0, the standard processing is not performed or in some cases is reversed.

If the callback function returns its event message with some of the parameters changed, these changes are incorporated into the standard processing. An example would be the processing of a keystroke message where the callback function substitutes upper case for lower case characters. The exact nature of this processing is described in the reference section on each event type.

Action = ⍎expr

If Action is set to a character vector whose first element is the execute symbol (⍎) the remaining string will be executed automatically whenever the event occurs. The default processing for the event is performed first and may not be changed or inhibited in any way.

Action = fn& {larg}

fn is a character vector containing the name of a callback function. The function is executed in a new thread. The default processing for the event is performed first and may not be changed or inhibited in any way.

The Result of ⎕DQ

⎕DQ terminates, returning the shy result R, in one of four instances.

Firstly, ⎕DQ terminates when an event occurs whose "action code" is 1. In this case, its result is a nested vector containing the event message associated with the event. The structure of an event message varies according to the event type (see Object Reference). However, an event message has at least two elements of which the first is a ref to the object or a character vector containing the name of the object, and the second is a numeric code specifying the event type.

⎕DQ also terminates if all of the objects named in Y have been deleted. In this case, the result is an empty character vector. Objects are deleted either using ⎕EX, or on exit from a defined function or operator if the names are localised in the header, or on closing a form using the system menu.

Thirdly, ⎕DQ terminates if the object named in its right argument is a special modal object, such as a MsgBox, FileBox or Locator, and the user has finished interacting with the object (e.g. by pressing an "OK" button). The return value of ⎕DQ in this case depends on the action code of the event.

Finally, ⎕DQ terminates with a VALUE ERROR if it attempts to execute a callback function that is undefined.


Enqueue Event

Enqueue Event: {R}←{X}⎕NQ Y

This system function generates an event or invokes a method.

While APL is executing, events occur "naturally" as a result of user action or of communication with other applications. These events are added to the event queue as and when they occur, and are subsequently removed and processed one by one by ⎕DQ. ⎕NQ provides an "artificial" means to generate an event and is analogous to ⎕SIGNAL.

If the left argument X is omitted or is 0, ⎕NQ adds the event specified by Y to the bottom of the event queue. The event will subsequently be processed by ⎕DQ when it reaches the top of the queue.

If X is 1, the event is actioned immediately by ⎕NQ itself and is processed in exactly the same way as it would be processed by ⎕DQ. For example, if the event has a callback function attached, ⎕NQ will invoke it directly. See Dequeue Events: for further details.

Note that it is not possible for one thread to use 1 ⎕NQ to send an event to another thread.

If X is 2 and the name supplied is the name of an event, ⎕NQ performs the default processing for the event immediately, but does not invoke a callback function if there is one attached.

If X is 2 and the name supplied is the name of a (Dyalog APL) method, ⎕NQ invokes the method. Its (shy) result is the result produced by the method.

If X is 3, ⎕NQ invokes a method in an OLE Control. The (shy) result of ⎕NQ is the result produced by the method.

If X is 4, ⎕NQ signals an event from an ActiveXControl object to its host application. The (shy) result of ⎕NQ is the result returned by the host application and depends upon the syntax of the event. This case is only applicable to ActiveXControl objects.

Y is a nested vector containing an event message. The first two elements of Y are:

[1] | Object | ref or character vector
[2] | Event | numeric scalar or character vector which specifies an event or method

Y[1] must specify an existing object. If not, ⎕NQ terminates with a VALUE ERROR. If Y[2] specifies a standard event type, subsequent elements must conform to the structure defined for that event type. If not, ⎕NQ terminates with a SYNTAX ERROR. If Y[2] specifies a non-standard event type, Y[3] onwards (if present) may contain arbitrary information. Although any event type not listed herein may be used, numbers in the range 0-1000 are reserved for future extensions.

If ⎕NQ is used monadically, or with a left argument of 0, its (shy) result is always an empty character vector. If a left argument of 1 is specified, ⎕NQ returns Y unchanged or a modified Y if the callback function returns its modified argument as a result.

If the left argument is 2, ⎕NQ returns either the value 1 or a value that is appropriate.

Examples

      ⍝ Send a keystroke ("A") to an Edit Field
      ⎕NQ TEST.ED 'KeyPress' 'A'

      ⍝ Iconify all top-level Forms
      {⎕NQ ⍵ 'StateChange' 1}¨'Form'⎕WN'.'

      ⍝ Set the focus to a particular field
      ⎕NQ TEST.ED3 40

      ⍝ Throw a new page on a printer
      1 ⎕NQ PR1 'NewPage'

      ⍝ Terminate ⎕DQ under program control

      'TEST'⎕WC 'Form' ... ('Event' 1001 1)
      ...
      ⎕DQ 'TEST'
      ...
      ⎕NQ TEST 1001  ⍝ From a callback

      ⍝ Call GetItemState method for a TreeView F.TV
      +2 ⎕NQF.TV 'GetItemState' 6
96

      +2 ⎕NQ'.' 'GetEnvironment' 'Dyalog'
c:\Z\2\dyalog82


Session Namespace

Session Namespace: ⎕SE

⎕SE is a system namespace. Its GUI components (MenuBar, ToolBar, and so forth) define the appearance and behaviour of the APL Session window and may be customised to suit individual requirements.

⎕SE is maintained separately from the active workspace and is not affected by )LOAD or )CLEAR. It is therefore useful for containing utility functions. The contents of ⎕SE may be saved in and loaded from a .DSE file.

See User Guide for further details.


Windows Create Object

Windows Create Object: {R}←{X}⎕WC Y

This system function creates a GUI object. Y is either a vector which specifies properties that determine the new object's appearance and behaviour, or the ⎕OR of a GUI object that exists or previously existed. X is a character vector which specifies the name of the new object, and its position in the object hierarchy.

If X is omitted, ⎕WC attaches a GUI component to the current namespace, retaining any functions, variables and other namespaces that it may contain. Monadic ⎕WC is discussed in detail at the end of this section.

If Y is a nested vector each element specifies a property. The Type property (which specifies the class of the object) must be specified. Most other properties take default values and need not be explicitly stated. Properties (including Type) may be declared either positionally or with a keyword followed by a value. Note that Type must always be the first property specified. Properties are specified positionally by placing their values in Y in the order prescribed for an object of that type.

If Y is a result of ⎕OR, the new object is a complete copy of the one from which the ⎕OR was made, including any child objects, namespaces, functions and variables that it contained at that time.

The shy result R is the full name (starting #. or ⎕SE.) of the namespace X.

An object's name is specified by giving its full pathname in the object hierarchy. At the top of the hierarchy is the Root object whose name is ".". Below "." there may be one or more "top-level" objects. The names of these objects follow the standard rules for other APL objects as described in Chapter 1.

Names for sub-objects follow the same rules except that the character "." is used as a delimiter to indicate parent/child relationships.

The following are examples of legal and illegal names :

Legal | Illegal
FORM1 | FORM 1
form_23 | form#1
Form1.Gp | 11_Form
F1.g2.b34 | Form+1

If X refers to the name of an APL variable, label, function, or operator, a DOMAIN ERROR is reported. If X refers to the name of an existing GUI object or namespace, the existing one is replaced by the new one. The effect is the same as if it were deleted first.

If Y refers to a non-existent property, or to a property that is not defined for the type of object X, a DOMAIN ERROR is reported. A DOMAIN ERROR is also reported if a value is given that is inconsistent with the corresponding property. This can occur for example, if Y specifies values positionally and in the wrong order.

A "top-level" object created by ⎕WC whose name is localised in a function/operator header, is deleted on exit from the function/operator. All objects, including sub-objects, can be deleted using ⎕EX.

GUI objects are named relative to the current namespace, so the following examples are equivalent:

      'F1.B1' ⎕WC 'Button'

is equivalent to :

      )CS F1
#.F1
      'B1' ⎕WC 'Button'
      )CS
#

is equivalent to :

      'B1' F1.⎕WC 'Button'

Examples

⍝ Create a default Form called F1

      'F1' ⎕WC 'Form'

⍝ Create a Form with specified properties (by position)
⍝   Caption = "My Application"  (Title)
⍝   Posn    = 10 30  (10% down, 30% across)
⍝   Size    = 80 60  (80% high, 60% wide)

      'F1' ⎕WC 'Form' 'My Application' (10 30)(80 60)

⍝ Create a Form with specified properties (by keyword)
⍝   Caption = "My Application"  (Title)
⍝   Posn    = 10 30  (10% down, 30% across)
⍝   Size    = 80 60  (80% high, 60% wide)

      PROPS←⊂'Type' 'Form'
      PROPS,←⊂'Caption' 'My Application'
      PROPS,←⊂'Posn' 10 30
      PROPS,←⊂'Size' 80 60
      'F1' ⎕WC PROPS

⍝ Create a default Button (a pushbutton) in the Form F1

      'F1.BTN' ⎕WC 'Button'

⍝ Create a pushbutton labelled "Ôk"
⍝ 10% down and 10% across from the start of the FORM
⍝ with callback function FOO associated with EVENT 30
⍝ (this event occurs when the user presses the button)

      'F1.BTN'⎕WC'Button' '&Ok' (10 10)('Event' 30 'FOO')

Monadic ⎕WC is used to attach a GUI component to an existing object. The existing object must be a pure namespace or a GUI object. The operation may be performed by changing space to the object or by running ⎕WC inside the object using the dot syntax. For example, the following statements are equivalent.

      )CS F
#.F
      ⎕WC 'Form'  ⍝ Attach a Form to this namespace

      )CS
#
      F.⎕WC'Form' ⍝ Attach a Form to namespace F


Windows Get Property

Windows Get Property: R←{X}⎕WG Y

This system function returns property values for a GUI object.

X is a namespace reference or a character vector containing the name of the object. Y is a character vector or a vector of character vectors containing the name(s) of the properties whose values are required. The result R contains the current values of the specified properties. If Y specifies a single property name, a single property value is returned. If Y specifies more than one property, R is a vector with one element per name in Y.

If X refers to a non-existent GUI name, a VALUE ERROR is reported. If Y refers to a non-existent property, or to a property that is not defined for the type of object X, a DOMAIN ERROR is reported.

GUI objects are named relative to the current namespace. A null value of X (referring to the namespace in which the function is being evaluated) may be omitted. The following examples are equivalent:

      'F1.B1' ⎕WG 'Caption'
      'B1' F1.⎕WG 'Caption'
      '' F1.B1.⎕WG 'Caption'
      F1.B1.⎕WG 'Caption'

Examples

      'F1' ⎕WC 'Form' 'TEST'

      'F1' ⎕WG 'Caption'
TEST

      'F1' ⎕WG 'MaxButton'
1

      'F1' ⎕WG 'Size'
50 50

      ]display 'F1' ⎕WG 'Caption' 'MaxButton' 'Size'
.→-----------------.
| .→---.   .→----. |
| |TEST| 1 |50 50| |
| '----'   '~----' |
'∊-----------------'


Windows Child Names

Windows Child Names: R←{X}⎕WN Y

This system function reports the Windows objects whose parent is Y.

If Y is a name (i.e. is a character vector) then the result R is a vector of character vectors containing the names of the named direct Windows children of Y.

If Y is a reference then the result R is a vector of references to the direct Windows children of Y, named or otherwise.

The optional left argument X is a character vector which specifies the Type of Windows object to be reported; if X is not specified, no such filtering is performed.

Names of objects further down the tree are not returned, but can be obtained by recursive use of ⎕WN.

If Y refers to a non-existent GUI name, a VALUE ERROR is reported.

Note that ⎕WN reports only those child objects visible from the current thread.

GUI objects are named relative to the current namespace. The following examples are equivalent:

      ⎕WN 'F1.B1'
      F1.⎕WN 'B1'
      F1.B1.⎕WN ''

Example

      f←⎕NEW⊂'Form'
      f.n←⎕ns''                  ⍝ A non-windows object
      f.l←f.⎕NEW⊂'Label'         ⍝ A reference to a Label
      'f.b1'⎕wc'Button'          ⍝ A named Button
      f.(b2←⎕new ⊂'Button')      ⍝ A reference to a Button
      ⎕wn 'f'
 [Form].b1
      ⎕wn f
 #.[Form].[Label]  #.[Form].b1  #.[Form].[Button]
      'Button' ⎕wn f
 #.[Form].b1  #.[Form].[Button]


Windows Set Property

Windows Set Property: {R}←{X}⎕WS Y

This system function resets property values for a GUI object.

X is a namespace reference or a character vector containing the name of the object. Y defines the property or properties to be changed and the new value or values. If a single property is to be changed, Y is a vector whose first element Y[1] is a character vector containing the property name. If Y is of length 2, Y[2] contains the corresponding property value. However, if the property value is itself a numeric or nested vector, its elements may be specified in Y[2 3 4 ...] instead of as a single nested element in Y[2]. If Y specifies more than one property, they may be declared either positionally or with a keyword followed by a value. Properties are specified positionally by placing their values in Y in the order prescribed for an object of that type. Note that the first property in Y must always be specified with a keyword because the Type property (which is expected first) may not be changed using ⎕WS.

If X refers to a non-existent GUI name, a VALUE ERROR is reported. If Y refers to a non-existent property, or to a property that is not defined for the type of object X, or to a property whose value may not be changed by ⎕WS, a DOMAIN ERROR is reported.

The shy result R contains the previous values of the properties specified in Y.

GUI objects are named relative to the current namespace. A null value of X (referring to the namespace in which the function is being evaluated) may be omitted. The following examples are equivalent:

      'F1.B1' ⎕WS 'Caption' '&Ok'
      'B1' F1.⎕WS 'Caption' '&Ok'
      '' F1.B1.⎕WS 'Caption' '&Ok'
      F1.B1.⎕WS 'Caption' '&Ok'

Examples

      'F1' ⎕WC 'Form'  ⍝ A default Form

      'F1' ⎕WS 'Active' 0

      'F1' ⎕WS 'Caption' 'My Application'

      'F1' ⎕WS 'Posn' 0 0

      'F1' ⎕WS ('Active' 1)('Event' 'Configure' 'FOO')

      'F1' ⎕WS 'Junk' 10
DOMAIN ERROR

      'F1' ⎕WS 'MaxButton' 0
DOMAIN ERROR


Window Expose

Window Expose: ⎕WX

⎕WX is a system variable that determines:

  1. whether or not the names of properties, methods and events provided by a Dyalog APL GUI object are exposed.
  2. certain aspects of behaviour of .Net and COM objects.

The permitted values of ⎕WX are 0, 1, or 3. Considered as a sum of bit flags, the first bit in ⎕WX specifies (a), and the second bit specifies (b).

If ⎕WX is 1 (1st bit is set), the names of properties, methods and events are exposed as reserved names in GUI namespaces and can be accessed directly by name. This means that the same names may not be used for global variables in GUI namespaces.

If ⎕WX is 0, these names are hidden and may only be accessed indirectly using ⎕WG and ⎕WS.

If ⎕WX is 3 (2nd bit is also set) COM and .Net objects adopt the Version 11 behaviour, as opposed to the behaviour in previous versions of Dyalog APL.

Note that it is the value of ⎕WX in the object itself, rather than the value of ⎕WX in the calling environment, that determines its behaviour.

The value of ⎕WX in a clear workspace is defined by the default_wx parameter (see User Guide) which itself defaults to 3.

⎕WX has namespace scope and may be localised in a function header. This allows you to create a utility namespace or utility function in which the exposure of objects is known and determined, regardless of its global value in the workspace.


Diagnostic Message

Diagnostic Message: R←⎕DM

This niladic function returns the last reported APL error as a three-element vector, giving error message, line in error and position of caret pointer.

Example

      2÷0
DOMAIN ERROR
      2÷0
     ^

      ⎕DM
 DOMAIN ERROR        2÷0       ^


Extended Diagnostic Message

Extended Diagnostic Message: R←⎕DMX

⎕DMX is a system object that provides information about the last reported APL error. ⎕DMX has thread scope, i.e. its value differs according to the thread from which it is referenced. In a multi-threaded application therefore, each thread has its own value of ⎕DMX.

⎕DMX contains the following Properties (name class 2.6). Note that this list is likely to change. Your code should not assume that this list will remain unchanged. You should also not assume that the display form of ⎕DMX will remain unchanged.

Category | character vector | The category of the error
DM | nested vector | Diagnostic message. This is the same as ⎕DM, but thread safe
EM | character vector | Event message; this is the same as ⎕EM ⎕EN
EN | integer | Error number. This is the same as ⎕EN, but thread safe
ENX | integer | Sub-error number
HelpURL | character vector | URL of a web page that will provide help for this error. APL identifies and has a handler for URLs starting with http:, https:, mailto: and www. This list may be extended in future
InternalLocation | nested vector | Identifies the line of interpreter source code (file name and line number) which raised the error. This information may be useful to Dyalog support when investigating an issue
Message | character vector | Further information about the error
OSError | see below | If applicable, identifies the error generated by the Operating System
Vendor | character vector | For system generated errors, Vendor will always contain the character vector 'Dyalog'. This value can be set using ⎕SIGNAL

OSError is a 3-element vector whose items are as follows:

1 integer This indicates how the operating system error was retrieved.
0 = by the C-library errno() function
1 = by the Windows GetLastError() function
2 | integer | Error code. The error number returned by the operating system using errno() or GetLastError() as above
3 | character vector | The description of the error returned by the operating system

Example

      1÷0
DOMAIN ERROR
      1÷0
     ∧
      ⎕DMX
 EM       DOMAIN ERROR
 Message  Divide by zero
 HelpURL  http://help.dyalog.com/dmx/13.1/General/1

      ⎕DMX.InternalLocation
 arith_su.c  554

Isolation of Handled Errors

⎕DMX cannot be explicitly localised in the header of a function. However, for all trapped errors, the interpreter creates an environment which effectively makes the current instance of ⎕DMX local to, and available only for the duration of, the trap-handling code.

With the exception of ⎕TRAP with Cutback, ⎕DMX is implicitly localised within:

  • Any function which explicitly localises ⎕TRAP
  • The :Case[List] or :Else clause of a :Trap control structure.
  • The right hand side of a D-function Error-Guard.

and is implicitly un-localised when:

  • A function which has explicitly localised ⎕TRAP terminates (even if the trap definition has been inherited from a function further up the stack).
  • The :EndTrap of the current :Trap control structure is reached.
  • A D-function Error-Guard exists.

During this time, if an error occurs then the localised ⎕DMX is updated to reflect the values generated by the error.

The same is true for ⎕TRAP with Cutback, with the exception that if the cutback trap event is triggered, the updated values for ⎕DMX are preserved until the function that set the cutback trap terminates.

The benefit of the localisation strategy is that code which uses error trapping as a standard operating procedure (such as a file utility which traps FILE NAME ERROR and creates missing files when required) will not pollute the environment with irrelevant error information.

Example

     ∇ tie←NewFile name
[1]    :Trap 22
[2]        tie←name ⎕FCREATE 0
[3]    :Else
[4]        ⎕DMX
[5]        tie←name ⎕FTIE 0
[6]        name ⎕FERASE tie
[7]        tie←name ⎕FCREATE 0
[8]    :EndTrap
[9]    ⎕FUNTIE tie
     ∇

⎕DMX is cleared by )RESET, .

      )reset
      ⍴⎕FMT ⎕DMX
0 0

The first time we run NewFile 'pete', the file doesn't exist and the ⎕FCREATE in NewFile[2] succeeds.

      NewFile 'pete'
1

If we run the function again, the ⎕FCREATE in NewFile[2]generates an error which triggers the :Else clause of the :Trap. On entry to the :Else clause, the values in ⎕DMX reflect the error generated by ⎕FCREATE. The file is then tied, erased and recreated.

 EM       FILE NAME ERROR
 Message  File exists
 HelpURL  http://help.dyalog.com/dmx/13.1/Componentfilesystem/9
1

After exiting the :Trap control structure, the shadowed value of ⎕DMX is discarded, revealing the orignal value that it shadowed.

      ⍴⎕FMT ⎕DMX
0 0

Example

The EraseFile function also uses a :Trap in order to ignore the situation when the file doesn't exist.

     ∇ EraseFile name;tie
[1]    :Trap 22
[2]        tie←name ⎕FTIE 0
[3]        name ⎕FERASE tie
[4]    :Else
[5]        ⎕DMX
[6]    :EndTrap
     ∇

The first time we run the function, it succeeds in tieing and then erasing the file.

      EraseFile 'pete'

The second time, the ⎕FTIE fails. On entry to the :Else clause, the values in ⎕DMX reflect this error.

      EraseFile 'pete'
 EM       FILE NAME ERROR
 Message  Unable to open file
 OSError  1 2  The system cannot find the file specified.
 HelpURL  http://help.dyalog.com/dmx/13.1/Componentfilesystem/11

Once again, the local value of ⎕DMX is discarded on exit from the :Trap, revealing the shadowed value as before.

      ⍴⎕FMT ⎕DMX
0 0

Example

In this example only the error number (EN) propery of ⎕DMX is displayed in order to simplify the output:

     ∇ foo n;⎕TRAP
[1]    'Start foo'⎕DMX.EN
[2]    ⎕TRAP←(2 'E' '→err')(11 'C' '→err')
[3]    goo n
[4]   err:'End foo:'⎕DMX.EN
     ∇

     ∇ goo n;⎕TRAP
[1]    ⎕TRAP←5 'E' '→err'
[2]    ⍎n⊃'÷0' '1 2+1 2 3' '∘'
[3]   err:'goo:'⎕DMX.EN
     ∇

In the first case a DOMAIN ERROR (11) is generated on goo[2]. This error is not included in the definition of ⎕TRAP in goo, but rather the the Cutback ⎕TRAP definition in foo. The error causes the stack to be cut back to foo, and then execution branches to foo[4]. Thus ⎕DMX.EN in foo retains the value set when the error occurred in goo.

      foo 1
 Start foo  0
 End foo:  11

In the second case a LENGTH ERROR (5) is raised on goo[2]. This error is included in the definition of ⎕TRAP in goo so the value ⎕DMX.EN while in goo is 5, but when goo terminates and foo resumes execution the value of ⎕DMX.EN localised in goo is lost.

      foo 2
 Start foo  0
 goo:  5
 End foo:  0

In the third case a SYNTAX ERROR (2) is raised on goo[2]. Since the ⎕TRAP statement is handled within goo (although the applicable ⎕TRAP is defined in foo), the value ⎕DMX.EN while in goo is 2, but when goo terminates and foo resumes execution the value of ⎕DMX.EN localised in goo is lost.

      foo 3
 Start foo  0
 goo:  2
 End foo:  0


Event Message

Event Message: R←⎕EM Y

Y must be a simple non-negative integer scalar or vector of event codes. If Y is a scalar, R is a simple character vector containing the associated event message. If Y is a vector, R is a vector of character vectors containing the corresponding event messages.

If Y refers to an undefined error code "n", the event message returned is "ERROR NUMBER n".

Example

      ⎕EM 11
DOMAIN ERROR


Event Number

Event Number: R←⎕EN

This simple integer scalar reports the identification number for the most recent event which occurred, caused by an APL action or by an interrupt or by the ⎕SIGNAL system function. Its value in a clear workspace is 0.


Exception

Exception: R←⎕EXCEPTION

This is a system object that identifies the most recent Exception thrown by a Microsoft .Net object.

⎕EXCEPTION derives from the Microsoft .Net class System.Exception. Among its properties are the following, all of which are strings:

Source | The name of the .Net namespace in which the exception was generated
StackTrace | The calling stack
Message | The error message
      ⎕USING←'System'
      DT←DateTime.New 100000 0 0
EXCEPTION
      DT←DateTime.New 100000 0 0

      ⎕EN
90
      ⎕EXCEPTION.Message
Specified argument was out of the range of valid values.

Parameter name: Year, Month, and Day parameters describe
an unrepresentable DateTime.

      ⎕EXCEPTION.Source
mscorlib

      ⎕EXCEPTION.StackTrace
   at System.DateTime.DateToTicks(Int32 year,
                                  Int32 month, Int32 day)

   at System.DateTime..ctor(Int32 year,
                            Int32 month, Int32 day)


Signal Event

Signal Event: {X}⎕SIGNAL Y

Y must be a scalar or vector.

If Y is a an empty vector nothing is signalled.

If Y is a vector of more than one element, all but the first element are ignored.

If the first element of Y is a simple integer in the range 1-999 it is taken to be an event number. X is an optional text message. If present, X must be a simple character scalar or vector, or an object reference. If X is omitted or is empty, the standard event message for the corresponding event number is assumed. See APL Error Messages. If there is no standard message, a message of the form ERROR NUMBER n is composed, where n is the event number in Y. Values outside the range 1-999 will result in a DOMAIN ERROR.

If the first element of Y is a 2 column matrix or a vector of 2 element vectors of name/values pairs, then it is considered to be a set of values to be used to override the default values in a new instance of ⎕DMX. Any other value for the first element of Y will result in a DOMAIN ERROR.

The names in the error specification must all appear in a system-generated ⎕DMX, otherwise a DOMAIN ERROR will be issued. For each name specified, the default value in the new instance of ⎕DMX is replaced with the value specified. EN must be one of the names in the error specification. Attempting to specify certain names, including InternalLocation and DM, will result in a DOMAIN ERROR. The value which is to be assigned to a name must be appropriate to the name in question.

Dyalog may enhance ⎕DMX in future, thus potentially altering the list of valid and/or assignable names.

If the first element of Y is an array of name/value pairs then specifying any value for X will result in a DOMAIN ERROR.

The effect of the system function is to interrupt execution. The state indicator is cut back to exit from the function or operator containing the line that invoked ⎕SIGNAL, or is cut back to exit the Execute (⍎) expression that invoked ⎕SIGNAL, and an error is then generated.

An error interrupt may be trapped if the system variable ⎕TRAP is set to intercept the event. Otherwise, the standard system action is taken (which may involve cutting back the state indicator further if there are locked functions or operators in the state indicator). The standard event message is replaced by the text given in X, if present.

Example

      ⎕VR'DIVIDE'
     ∇ R←A DIVIDE B;⎕TRAP
[1]    ⎕TRAP←11 'E' '→ERR'
[2]    R←A÷B ⋄ →0
[3]   ERR:'DIVISION ERROR' ⎕SIGNAL 11
     ∇

      2 4 6 DIVIDE 0
DIVISION ERROR
      2 4 6 DIVIDE 0
     ^

If you are using the Microsoft .Net Framework, you may use ⎕SIGNAL to throw an exception by specifying a value of 90 in Y. In this case, if you specify the optional left argument X, it must be a reference to a .Net object that is or derives from the Microsoft .Net class System.Exception. The following example illustrates a constructor function CTOR that expects to be called with a value for ⎕IO (0 or 1)

     ∇ CTOR IO;EX
[1]    :If IO∊0 1
[2]        ⎕IO←IO
[3]    :Else
[4]        EX←ArgumentException.New'IO must be 0 or 1'
[5]        EX ⎕SIGNAL 90
[6]    :EndIf
     ∇

Further examples

Example 1

      'Hello'⎕SIGNAL 200
Hello
      'Hello'⎕SIGNAL 200
     ∧
      ⎕DMX
 EM       Hello
 Message
 HelpURL

      ⎕DM
 Hello        'Hello'⎕SIGNAL 200       ∧

      ⎕SIGNAL⊂⊂('EN' 200)
ERROR 200
      ⎕SIGNAL⊂⊂('EN' 200)
     ∧

      ⎕DMX
 EM       ERROR 200
 Message
 HelpURL

      ⎕DM
 ERROR 200        ⎕SIGNAL⊂⊂('EN' 200)       ∧

Example 2

      ⎕SIGNAL⊂('EN' 200)('Vendor' 'Andy')('Message' 'My error')
ERROR 200: My error
      ⎕SIGNAL⊂('EN' 200)('Vendor' 'Andy')('Message' 'My error')
     ∧

      ⎕DMX
 EM       ERROR 200
 Message  My error
 HelpURL
      ⍪⎕DMX.(EN EM Vendor)
       200
 ERROR 200
      Andy

Be aware of the following case, in which the argument has not been sufficiently nested:

      ⎕SIGNAL⊂('EN' 200)
DOMAIN ERROR: Unexpected name in signalled ⎕DMX specification
      ⎕SIGNAL⊂('EN' 200)
     ∧


Trap Event

Trap Event: ⎕TRAP

This is a non-simple vector. An item of ⎕TRAP specifies an action to be taken when one of a set of events occurs. An item of ⎕TRAP is a 2 or 3 element vector whose items are simple scalars or vectors in the following order:

  1. an integer vector whose value is one or more event codes selected from the list in the Figure on the following two pages.
  2. a character scalar whose value is an action code selected from the letters C, E, N or S.
  3. if element 2 is the letter C or E, this item is a character vector forming a valid APL expression or series of expressions separated by ⋄. Otherwise, this element is omitted.

An EVENT may be an APL execution error, an interrupt by the user or the system, a control interrupt caused by the ⎕STOP system function, or an event generated by the ⎕SIGNAL system function.

When an event occurs, the system searches for a trap definition for that event. The most local ⎕TRAP value is searched first, followed by successive shadowed values of ⎕TRAP, and finally the global ⎕TRAP value. Separate actions defined in a single ⎕TRAP value are searched from left to right. If a trap definition for the event is found, the defined action is taken. Otherwise, the normal system action is followed.

The ACTION code identifies the nature of the action to be taken when an associated event occurs. Permitted codes are interpreted as follows:

C | Cutback | The state indicator is 'cut back' to the environment in which the ⎕TRAP is locally defined (or to immediate execution level). The APL expression in element 3 of the same ⎕TRAP item is then executed.
E | Execute | The APL expression in element 3 of the same ⎕TRAP item is executed in the environment in which the event occurred.
N | Next | The event is excluded from the current ⎕TRAP definition. The search will continue through further localised definitions of ⎕TRAP
S | Stop | Stops the search and causes the normal APL action to be taken in the environment in which the event occurred.

Table 19: Trappable Event Codes

Code | Event
0 | Any event in range 1-999
1 | WS FULL
2 | SYNTAX ERROR
3 | INDEX ERROR
4 | RANK ERROR
5 | LENGTH ERROR
6 | VALUE ERROR
7 | FORMAT ERROR
10 | LIMIT ERROR
11 | DOMAIN ERROR
12 | HOLD ERROR
13 | OPTION ERROR
16 | NONCE ERROR
18 | FILE TIE ERROR
19 | FILE ACCESS ERROR
20 | FILE INDEX ERROR
21 | FILE FULL
22 | FILE NAME ERROR
23 | FILE DAMAGED
24 | FILE TIED
25 | FILE TIED REMOTELY
26 | FILE SYSTEM ERROR
28 | FILE SYSTEM NOT AVAILABLE
30 | FILE SYSTEM TIES USED UP
31 | FILE TIE QUOTA USED UP
32 | FILE NAME QUOTA USED UP
34 | FILE SYSTEM NO SPACE
35 | FILE ACCESS ERROR - CONVERTING FILE
38 | FILE COMPONENT DAMAGED
52 | FIELD CONTENTS RANK ERROR
53 | FIELD CONTENTS TOO MANY COLUMNS
54 | FIELD POSITION ERROR
55 | FIELD SIZE ERROR
56 | FIELD CONTENTS/TYPE MISMATCH
57 | FIELD TYPE/BEHAVIOUR UNRECOGNISED
58 | FIELD ATTRIBUTES RANK ERROR
59 | FIELD ATTRIBUTES LENGTH ERROR
60 | FULL-SCREEN ERROR
61 | KEY CODE UNRECOGNISED
62 | KEY CODE RANK ERROR
63 | KEY CODE TYPE ERROR
70 | FORMAT FILE ACCESS ERROR
71 | FORMAT FILE ERROR
72 | NO PIPES
76 | PROCESSOR TABLE FULL
84 | TRAP ERROR
90 | EXCEPTION
92 | TRANSLATION ERROR
200-499 | Reserved for distributed auxiliary processors
500-999 | User-defined events
1000 | Any event in range 1001-1008
1001 | Stop vector
1002 | Weak interrupt
1003 | INTERRUPT
1005 | EOF INTERRUPT
1006 | TIMEOUT
1007 | RESIZE (Dyalog APL/X, Dyalog APL/W)
1008 | DEADLOCK

See Trap Statement for an alternative 'control structured' error trapping mechanism.

Examples

      ⎕TRAP←⊂(3 4 5) 'E' 'ERROR' ⋄ ⍴⎕TRAP
1

      ⎕TRAP
  3 4 5 E ERROR

Items may be specified as scalars. If there is only a single trap definition, it need not be enclosed. However, the value of ⎕TRAP will be rigorously correct:

      ⎕TRAP←11 'E' '→LAB'

      ⎕TRAP
  11 E →ERR

      ⍴⎕TRAP
1

The value of ⎕TRAP in a clear workspace is an empty vector whose prototype is

0⍴(⍬ '' ''). A convenient way of cancelling a ⎕TRAP definition is:

      ⎕TRAP←0⍴⎕TRAP

Event codes 0 and 1000 allow all events in the respective ranges 1-999 and 1000-1006 to be trapped. Specific event codes may be excluded by the N action (which must precede the general event action):

      ⎕TRAP←(1 'N')(0 'E' '→GENERR')

The 'stop' action is a useful mechanism for cancelling trap definitions during development of applications.

The 'cut-back' action is useful for returning control to a known point in the application system when errors occur. The following example shows a function that selects and executes an option with a general trap to return control to the function when an untrapped event occurs:

     ∇ SELECT;OPT;⎕TRAP
[1]   ⍝ Option selection and execution
[2]   ⍝ A general cut-back trap
[3]    ⎕TRAP←(0 1000)'C' '→ERR'
[4]   INP:⍞←'OPTION : ' ⋄ OPT←(OPT≠' ')/OPT←9↓⍞
[5]    →EX⍴⍨(⊂OPT)∊Options ⋄ 'INVALID OPTION' ⋄ →INP
[6]   EX:⍎OPT ⋄ →INP
[7]   ERR:ERROR∆ACTION ⋄ →INP
[8]   END:
     ∇

User-defined events may be signalled through the ⎕SIGNAL system function. A user-defined event (in the range 500-999) may be trapped explicitly or implicitly by the event code 0.

Example

      ⎕TRAP←500 'E' '''USER EVENT 500 - TRAPPED'''

      ⎕SIGNAL 500
USER EVENT 500 - TRAPPED


Thread Child Numbers

Thread Child Numbers: R←⎕TCNUMS Y

Y must be a simple array of integers representing thread numbers.

The result R is a simple integer vector of the child threads of each thread of Y.

Examples

      ⎕TCNUMS 0
2 3

      ⎕TCNUMS 2 3
4 5 6 7 8 9


Get Tokens

Get Tokens: {R}←{X} ⎕TGET Y

Y must be a simple integer scalar or vector that specifies one or more tokens, each with a specific non-zero token type, that are to be retrieved from the pool.

X is an optional time-out value in seconds.

Shy result R is a scalar or vector containing the values of the tokens of type Y that have been retrieved from the token pool.

Note that types of the tokens in the pool may be positive or negative, and the elements of Y may also be positive or negative.

A request (⎕TGET) for a positive token will be satisfied by the presence of a token in the pool with the same positive or negative type. If the pool token has a positive type, it will be removed from the pool. If the pool token has a negative type, it will remain in the pool. Negatively typed tokens will therefore satisfy an infinite number of requests for their positive equivalents. Note that a request for a positive token will remove one if it is present, before resorting to its negative equivalent

A request for a negative token type will only be satisfied by the presence of a negative token type in the pool, and that token will be removed.

If, when a thread calls ⎕TGET, the token pool satisfies all of the tokens specified by Y, the function returns immediately with a (shy) result that contains the values associated with the pool tokens. Otherwise, the function will block (wait) until all of the requested tokens are present or until a timeout (as specified by X) occurs.

For example, if the pool contains only tokens of type 2:

    ⎕TGET 2 4        ⍝ blocks waiting for a 4-token ...

The ⎕TGET operation is atomic in the sense that no tokens are taken from the pool until all of the requested types are present. While this last example is waiting for a 4-token, other threads could take any of the remaining 2-tokens.

Note also, that repeated items in the right argument are distinct. The following will block until there are at least 3 × 2-tokens in the pool:

    ⎕TGET 3/2       ⍝ wait for 3 × 2-tokens ...

The pool is administered on a first-in-first-out basis. This is significant only if tokens of the same type are given distinct values. For example:

    ⎕TGET ⎕TPOOL             ⍝ empty pool.

    'ABCDE'⎕TPUT¨2 2 3 2 3  ⍝ pool some tokens.

    ⊢⎕TGET 2 3
AC

    ⊢⎕TGET 2 3
BE

Timeout is signalled by the return of an empty numeric vector ⍬ (zilde). By default, the value of a token is the same as its type. This means that, unless you have explicitly set the value of a token to ⍬, a ⎕TGET result of ⍬ unambiguously identifies a timeout.

Beware - the following statement will wait forever and can only be terminated by an interrupt.

    ⎕TGET 0       ⍝ wait forever ...

Note too that if a thread waiting to ⎕TGET tokens is ⎕TKILLed, the thread disappears without removing any tokens from the pool. Conversely, if a thread that has removed tokens from the pools is ⎕TKILLed, the tokens are not returned to the pool.


Current Thread Identity

Current Thread Identity: R←⎕TID

R is a simple integer scalar whose value is the number of the current thread.

Examples

      ⎕TID     ⍝ Base thread number
0

      ⍎&'⎕TID' ⍝ Thread number of async ⍎.
1


Kill Thread

Kill Thread: {R}←{X}⎕TKILL Y

Y must be a simple array of integers representing thread numbers to be terminated. X is a Boolean single, defaulting to 1, which indicates that all descendant threads should also be terminated.

The shy result R is a vector of the numbers of all threads that have been terminated.

The base thread 0 is always excluded from the cull.

Examples

      ⎕TKILL 0            ⍝ Kill background threads.

      ⎕TKILL ⎕TID         ⍝ Kill self and descendants.

      0 ⎕TKILL ⎕TID       ⍝ Kill self only.

      ⎕TKILL ⎕TCNUMS ⎕TID ⍝ Kill descendants.


Current Thread Name

Current Thread Name: ⎕TNAME

The system variable ⎕TNAME reports and sets the name of the current APL thread. This name is used to identify the thread in the Tracer.

The default value of ⎕TNAME is an empty character vector.

You may set ⎕TNAME to any valid character vector, but it is recommended that control characters (such as ⎕AV[⎕IO] ) be avoided.

Example:

      ⎕TNAME←'Dylan'
      ⎕TNAME
Dylan


Token Pool

Token Pool: R←⎕TPOOL

R is a simple scalar or vector containing the token types for each of the tokens that are currently in the token pool.

The following (⎕ML=0) function returns a 2-column snapshot of the contents of the pool. It does this by removing and replacing all of the tokens, restoring the state of the pool exactly as before. Coding it as a single expression guarantees that snap is atomic and cannot disturb running threads.

      snap←{(⎕TGET ⍵){(⍉↑⍵ ⍺){⍺}⍺ ⎕TPUT¨⍵}⍵}

      snap ⎕TPOOL
1       hello world
2                 2
3                 2
2  three-type token
2                 2


Put Tokens

Put Tokens: {R}←{X} ⎕TPUT Y

Y must be a simple integer scalar or vector of non-zero token types.

X is an optional array of values to be stored in each of the tokens specified by Y.

Shy result R is a vector of thread numbers (if any) unblocked by the ⎕TPUT.

Examples

    ⎕TPUT 2 3 2     ⍝ put a 2-token, a 3-token and another
                      2-token into the pool.

    88 ⎕TPUT 2      ⍝ put another 2-token into the pool
                      this token has the value 88.

    'Hello'⎕TPUT ¯4 ⍝ put a ¯4-token into the pool with
                      the value 'Hello'.

If X is omitted, the value associated with each of the tokens added to the pool is the same as its type.

Note that you cannot put a 0-token into the pool; 0-s are removed from Y.


Token Requests

Token Requests: R←⎕TREQ Y

Y is a simple scalar or vector of thread numbers.

R is a vector containing the concatenated token requests for all the threads specified in Y. This is effectively the result of catenating all of the right arguments together for all threads in Y that are currently executing ⎕TGET.

Example

    ⎕TREQ ⎕TNUMS    ⍝ tokens required by all threads.


Wait for Threads to Terminate

Wait for Threads to Terminate: R←⎕TSYNC Y

Y must be a simple array of thread numbers.

If Y is a simple scalar, R is an array, the result (if any) of the thread.

If Y is a simple non-scalar, R has the same shape as Y, and result is an array of enclosed thread results.

Examples

      dup←{⍵ ⍵}        ⍝ Duplicate

      ⎕←dup&88         ⍝ Show thread number
11
88 88

      ⎕TSYNC dup&88    ⍝ Wait for result
88 88

      ⎕TSYNC,dup&88
 88 88

      ⎕TSYNC dup&1 2 3
 1 2 3  1 2 3

      ⎕TSYNC dup&¨1 2 3
 1 1  2 2  3 3

Deadlock

The interpreter detects a potential deadlock if a number of threads wait for each other in a cyclic dependency. In this case, the thread that attempts to cause the deadlock issues error number 1008: DEADLOCK.

     ⎕TSYNC ⎕TID      ⍝ Wait for self
DEADLOCK
      ⎕TSYNC ⎕TID
      ^

      ⎕EN
1008

Potential Value Error

If any item of Y does not correspond to the thread number of an active thread, or if any subject thread terminates without returning a result, then ⎕TSYNC does not return a result. This means that, if the calling context of the ⎕TSYNC requires a result, for example: rslt←⎕TSYNC tnums, a VALUE ERROR will be generated. This situation can occur if threads have completed before ⎕TSYNC is called.

      ⎕←÷&4          ⍝ thread (3) runs and terminates.
3
0.25
      ⎕TSYNC 3       ⍝ no result required: no prob
      ⎕←⎕tsync 3     ⍝ context requires result
VALUE ERROR

      ⎕←⎕tsync {}&0  ⍝ non-result-returning fn: no result.
VALUE ERROR

Coding would normally avoid such an inconvenient VALUE ERROR either by arranging that the thread-spawning and ⎕TSYNC were on the same line:

      rslt ← ⎕TYSYNC myfn&¨ argvec

or

      tnums←myfn&¨ argvec ⋄ rslt←⎕TSYNC tnums

or by error-trapping the VALUE ERROR.


Shared Variable Access Control

Shared Variable Access Control ⎕SVC

Dyadic ⎕SVC means

Set Access Control

      1 ⎕SVC 'X EXTNAME'
1 1 1 1

Monadic ⎕SVC means

Query Access Control

      ⎕SVC 'X'
1 1 1 1

Language Elements


Query Access Control

Query Access Control: R←⎕SVC Y

This system function queries the access control on one or more shared variables.

Y is a character scalar, vector, or matrix containing names of shared variables. Each name may optionally be paired with its surrogate. If so, the surrogate must be separated from the name by at least one space.

If Y specifies a single name, the result R is a Boolean vector containing the current effective access control vector. If Y is a matrix of names, R is a Boolean matrix whose rows contain the current effective access control vectors for the corresponding row in Y.

For further information, see the preceding section on setting the access control vector.

Example

      ⎕SVC 'X'
0 0 0 0


Set Access Control

Set Access Control: R←X ⎕SVC Y

This system function sets access control on one or more shared variables.

Y is a character scalar, vector, or matrix containing names of shared variables. Each name may optionally be paired with its surrogate. If so, the surrogate must be separated from the name by at least one space.

X may be a 4-element Boolean vector which specifies the access control to be applied to all of the shared variables named in Y. Alternatively, X may be a 4-column Boolean matrix whose rows specify the access control for the corresponding name in Y. X may also be a scalar or a 1-element vector. If so, it treated as if it were a 4-element vector with the same value in each element.

Each shared variable has a current access control vector which is a 4-element Boolean vector. A 1 in each of the four positions has the following impact :

[1] | You cannot set a new value for the shared variable until after an intervening use or set by your partner.
[2] | Your partner cannot set a new value for the shared variable until after an intervening use or set by you.
[3] | You cannot use the value of the shared variable until after an intervening set by your partner.
[4] | Your partner cannot use the value of the shared variable until after an intervening set by you.

The effect of ⎕SVC is to reset the access control vectors for each of the shared variables named in Y by OR-ing the values most recently specified by your partner with the values in X. This means that you cannot reset elements of the control vector which your partner has set to 1.

Note that the initial value of your partner's access control vector is normally 0 0 0 0. However, if it is a non-APL client application that has established a hot DDE link, its access control vector is defined to be 1 0 0 1. This inhibits either partner from setting the value of the shared variable twice, without an intervening use (or set) by the other. This prevents loss of data which is deemed to be desirable from the nature of the link. (An application that requests a hot link is assumed to require every value of the shared variable, and not to miss any). Note that APL's way of inhibiting another application from setting the value twice (without an intervening use) is to delay the acknowledgement of the DDE message containing the second value until the variable has been used by the APL workspace. An application that waits for an acknowledgement will therefore hang until this happens. An application that does not wait will carry on obliviously.

The result R is a Boolean vector or matrix, corresponding to the structure of X, which contains the new access control settings. If Y refers to a name which is not a shared variable, or if the surrogate name is mis-spelt, the corresponding value in R is 4⍴0.

Examples

      1 0 0 1 ⎕SVC 'X'
1 0 0 1

      1 ⎕SVC 'X EXTNAME'
1 1 1 1

      (2 4⍴1 0 0 1 0 1 1 0) ⎕SVC ↑'ONE' 'TWO'
1 1 1 1
0 1 1 0


Shared Variable Offer

Shared Variable Offer ⎕SVO

Dyadic ⎕SVO means

Shared Variable Offer

      DATA←⍳9
     'DDE:' ⎕SVO 'DATA'
1

Monadic ⎕SVO means

Query Degree of Coupling

      ⎕SVO 'DATA'
1

Language Elements


Shared Variable Offer

Shared Variable Offer: R←X ⎕SVO Y

This system function offers to share one or more variables with another APL workspace or with another application. Shared variables are implemented using Dynamic Data Exchange (DDE) and may be used to communicate with any other application that supports this protocol. See Interface Guide for further details.

Y is a character scalar, vector or matrix. If it is a vector it contains a name and optionally an external name or surrogate. The first name is the name used internally in the current workspace. The external name is the name used to make the connection with the partner and, if specified, must be separated from the internal name by one or more blanks. If the partner is another application, the external name corresponds to the DDE item specified by that application. If the external name is omitted, the internal name is used instead. The internal name must be a valid APL name and be either undefined or be the name of a variable. There are no such restrictions on the content of the external name.

Instead of an external name, Y may contain the special symbol '⍎' separated from the (internal) name by a blank. This is used to implement a mechanism for sending DDE_EXECUTE messages, and is described at the end of this section.

If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

The left argument X is a character vector or matrix. If it is a vector, it contains a string that defines the protocol, the application to which the shared variable is to be connected, and the topic of the conversation. These three components are separated by the characters ':' and '|' respectively. The protocol is currently always 'DDE', but future implementations of Dyalog APL may support additional communications protocols if applicable. If Y specifies more than one name, X may be a vector or a matrix with one row per row in Y.

If the shared variable offer is a general one (server), X, or the corresponding row of X, should contain 'DDE:'.

The result R is a numeric scalar or vector with one element for each name in Y and indicates the "degree of coupling". A value of 2 indicates that the variable is fully coupled (via a warm or hot DDE link) with a shared variable in another APL workspace, or with a DDE item in another application. A value of 1 indicates that there is no connection, or that the second application rejected a warm link. In this case, a transfer of data may have taken place (via a cold link) but the connection is no longer open. Effectively, APL treats an application that insists on a cold link as if it immediately retracts the sharing after setting or using the value, whichever is appropriate.

Examples

      'DDE:' ⎕SVO 'X'
1

      'DDE:' ⎕SVO 'X SALES_92'
1

      'DDE:' ⎕SVO ↑'X SALES_92' 'COSTS_92'
1 1

      'DDE:DYALOG|SERV_WS' ⎕SVO 'X'
2

      'DDE:EXCEL|SHEET1' ⎕SVO 'DATA R1C1:R10C12'
2

A special syntax is used to provide a mechanism for sending DDE_EXECUTE messages to another application. This case is identified by specifying the '⍎' symbol in place of the external name. The subsequent assignment of a character vector to a variable shared with the external name of '⍎' causes the value of the variable to be transmitted in the form of a DDE_EXECUTE message. The value of the variable is then reset to 1 or 0 corresponding to a positive or negative acknowledgement from the partner. In most (if not all) applications, commands transmitted in DDE_EXECUTE messages must be enclosed in square brackets []. For details, see the relevant documentation for the external application.

Examples:

      'DDE:EXCEL|SYSTEM' ⎕SVO 'X ⍎'
2

      X←'[OPEN("c:\mydir\mysheet.xls")]'
      X
1

      X←'[SELECT("R1C1:R5C10")]'
      X
1


Query Degree of Coupling

Query Degree of Coupling: R←⎕SVO Y

This system function returns the current degree of coupling for one or more shared variables.

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks.

If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

If Y specifies a single name, the result R is a 1-element vector whose value 0, 1 or 2 indicates its current degree of coupling. If Y specifies more than one name, R is a vector whose elements indicate the current degree of coupling of the variable specified by the corresponding row in Y. A value of 2 indicates that the variable is fully coupled (via a warm or hot DDE link) with a shared variable in another APL workspace, or with a DDE item in another application. A value of 1 indicates that you have offered the variable but there is no such connection, or that the second application rejected a warm link. In this case, a transfer of data may have taken place (via a cold link) but the connection is no longer open. A value of 0 indicates that the name is not a shared variable.

Examples

      ⎕SVO 'X'
2
      ⎕SVO ↑'X SALES' 'Y' 'JUNK'
2 1 0


Shared Variable Query

Shared Variable Query: R←⎕SVQ Y

This system function is implemented for compatibility with other versions of APL but currently performs no useful function. Its purpose is to obtain a list of outstanding shared variable offers made to you, to which you have not yet responded.

Using DDE as the communication protocol, it is not possible to implement ⎕SVQ effectively.


Shared Variable Retract Offer

Shared Variable Retract Offer: R←⎕SVR Y

This system function terminates communication via one or more shared variables, or aborts shared variable offers that have not yet been accepted.

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks. If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

The result R is vector whose length corresponds to the number of names specified by Y, indicating the level of sharing of each variable after retraction.

See Shared Variable State: for further information on the possible states of a shared variable.


Shared Variable State

Shared Variable State: R←⎕SVS Y

This system function returns the current state of one or more shared variables.

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks. If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

If Y specifies a single name, the result R is a 4-element vector indicating its current state. If Y specifies more than one name, R is a matrix whose rows indicate the current state of the variable specified by the corresponding row in Y.

There are four possible shared variable states:

0 0 1 1 | means that you and your partner are both aware of the current value, and neither has since reset it. This is also the initial value of the state when the link is first established.
1 0 1 0 | means that you have reset the shared variable and your partner has not yet used it. This state can only occur if both partners are APL workspaces.
0 1 0 1 | means that your partner has reset the shared variable but that you have not yet used it.
0 0 0 0 | the name is not that of a shared variable

Examples

      ⎕SVS 'X'
0 1 0 1

      ⎕SVS ↑'X SALES' 'Y' 'JUNK'
0 0 1 1
1 0 1 0
0 0 0 0


Line Count

Line Count: R←⎕LC

This is a simple vector of line numbers drawn from the state indicator (See The State Indicator). The most recently activated line is shown first. If a value corresponds to a defined function in the state indicator, it represents the current line number where the function is either suspended or pendent.

The value of ⎕LC changes immediately upon completion of the most recently activated line, or upon completion of execution within ⍎ or ⎕. If a ⎕STOP control is set, ⎕LC identifies the line on which the stop control is effected. In the case where a stop control is set on line 0 of a defined function, the first entry in ⎕LC is 0 when the control is effected.

The value of ⎕LC in a clear workspace is the null vector.

Examples

      )SI
#.TASK1[5]*
⍎
#.BEGIN[3]

      ⎕LC
5 3

      →⎕LC
      ⎕LC

      ⍴⎕LC
0


Monitor Controls

Monitor Controls ⎕MONITOR

Dyadic ⎕MONITOR means

Set Monitor Controls

      +(0,⍳10) ⎕MONITOR 'FOO'
0 1 2 3 4 5

Monadic ⎕MONITOR means

Query Monitor Controls

      ⎕MONITOR 'FOO'
0 1 2 3 4 5

Language Elements


Query Monitor

Query Monitor: R←⎕MONITOR Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. R is a simple non-negative integer matrix of 5 columns with one row for each line in the function or operator Y which has the monitor set, giving:

Column 1 | Line number
Column 2 | Number of times the line was executed
Column 3 | CPU time in milliseconds
Column 4 | Elapsed time in milliseconds
Column 5 | Reserved

The value of 0 in column one indicates that the monitor is set on the function or operator as a whole.

Example

      ∇ FOO
[1]   A←?25 25⍴100
[2]   B←⌹A
[3]   C←⌹B
[4]   R1←⌊0.5+A+.×B
[5]   R2←A=C
      ∇

      (0,⍳5) ⎕MONITOR 'FOO' ⍝ Set monitor

      FOO                   ⍝ Run function

      ⎕MONITOR 'FOO'        ⍝ Monitor query
0 1 1418 1000 0
1 1   83    0 0
2 1  400    0 0
3 1  397    0 0
4 1  467 1000 0
5 1  100    0 0


Set Monitor

Set Monitor: {R}←X ⎕MONITOR Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. X must be a simple non-negative integer scalar or vector. R is a simple integer vector of non-negative elements.

X identifies the numbers of lines in the function or operator named by Y on which a monitor is to be placed. Numbers outside the range of line numbers in the function or operator (other than 0) are ignored. The number 0 indicates that a monitor is to be placed on the function or operator as a whole. The value of X is independent of ⎕IO.

R is a vector of numbers on which a monitor has been placed in ascending order. The result is suppressed unless it is explicitly used or assigned.

The effect of ⎕MONITOR is to accumulate timing statistics for the lines for which the monitor has been set. See Query Monitor: for details.

Examples

      +(0,⍳10) ⎕MONITOR 'FOO'
0 1 2 3 4 5

Existing monitors are cancelled before new ones are set:

      +1 ⎕MONITOR 'FOO'
1

All monitors may be cancelled by supplying an empty vector:

      ⍬ ⎕MONITOR 'FOO'

Monitors may be set on a locked function or operator, but no information will be reported. Monitors are saved with the workspace.


Cross References

Cross References: R←⎕REFS Y

Y must be a simple character scalar or vector, identifying the name of a function or operator, or the object representation form of a function or operator (see Object Representation: ). R is a simple character matrix, with one name per row, of identified names in the function or operator in Y excluding distinguished names of system constants, variables or functions.

Example

      ⎕VR'OPTIONS'
     ∇ OPTIONS;OPTS;INP
[1]   ⍝ REQUESTS AND EXECUTES AN OPTION
[2]    OPTS ←'INPUT' 'REPORT' 'END'
[3]   IN:INP←ASK'OPTION:'
[4]    →EX⍴⍨(⊂INP)∊OPTS
[5]    'INVALID OPTION. SELECT FROM',OPTS ⋄ →IN
[6]   EX:→EX+OPTS⍳⊂INP
[7]    INPUT ⋄ →IN
[8]    REPORT ⋄ →IN
[9]   END:
     ∇

    ⎕REFS'OPTIONS'
ASK
END
EX
IN
INP
INPUT
OPTIONS
OPTS
REPORT

If Y is locked or is an External Function, R contains its name only. For example:

      ⎕LOCK 'OPTIONS' ⋄ ⎕REFS 'OPTIONS'
OPTIONS

If Y is the name of a primitive, external or derived function, R is an empty matrix with shape 0 0.


Shadow Name

Shadow Name: ⎕SHADOW Y

Y must be a simple character scalar, vector or matrix identifying one or more APL names. For a vector Y, names are separated by one or more blanks. For a matrix Y, each row is taken to be a single name.

Each valid name in Y is shadowed in the most recently invoked defined function or operator, as though it were included in the list of local names in the function or operator header. The class of the name becomes 0 (undefined). The name ceases to be shadowed when execution of the shadowing function or operator is completed. Shadow has no effect when the state indicator is empty.

If a name is ill-formed, or if it is the name of a system constant or system function, DOMAIN ERROR is reported.

If the name of a top-level GUI object is shadowed, it is made inactive.

Example

      ⎕VR'RUN'
     ∇ NAME RUN FN
[1]   ⍝ Runs function named <NAME> defined
[2]   ⍝ from representation form <FN>
[3]    ⎕SHADOW NAME
[4]    ⍎⎕FX FN
     ∇

      0 ⎕STOP 'RUN' ⍝ stop prior RUN exiting

      'FOO' RUN 'R←FOO' 'R←10'
10

RUN[0]

      )SINL
#.RUN[0]*       FOO     FN      NAME

      →⎕LC

      FOO
VALUE ERROR
      FOO
      ^


State Indicator

State Indicator: R←⎕SI

R is a nested vector of vectors giving the names of the functions or operators in the execution stack.

Example

      )SI
#.PLUS[2]*
.
#.MATDIV[4]
#.FOO[1]*
⍎

      ⎕SI
 PLUS  MATDIV  FOO

      (⍴⎕LC)=⍴⎕SI
1

If execution stops in a callback function, ⎕DQ will appear on the stack, and may occur more than once

      )SI
#.ERRFN[7]*
⎕DQ
#.CALC
⎕DQ
#.MAIN

To edit the function on the top of the stack:

      ⎕ED ⊃⎕SI

The name of the function which called this one:

      ⊃1↓⎕SI

To check if the function ∆N is pendent:

     ((⊂∆N)∊1↓⎕SI)/'Warning : ',∆N,' is pendent'

See also Extended State Indicator: .


Extended State Indicator

Extended State Indicator: R←⎕XSI

R is a nested vector of character vectors giving the full path names of the functions or operators in the execution stack. Note that if a function has changed space, its original (home) space is reported, rather than its current one.

Example

In the following, function foo in namespace x has called goo in namespace y. Function goo has then changed space (⎕CS) to namespace z where it has been suspended:

      )si
[z] y.goo[2]*
x.foo[1]

⎕XSI reports the full path name of each function:

      ⎕xsi
 #.y.goo  #.x.foo

This can be used for example, to edit all functions in the stack, irrespective of the current namespace by typing: ⎕ed ⎕xsi

See also State Indicator: .


Space Indicator

Space Indicator: R←⎕RSI

R is a vector of refs to the spaces from which functions in the state indicator were called (⍴⎕RSI←→⍴⎕NSI←→⍴⎕SI).

⎕RSI and ⎕NSI are identical except that ⎕RSI returns refs to the spaces whereas ⎕NSI returns their names. Put another way: ⎕NSI←→⍕¨⎕RSI.

Note that ⎕RSI returns refs to the spaces from which functions were called not those in which they are currently running.

Example

      )OBJECTS
xx      yy

      ⎕VR 'yy.foo'
     ∇ r←foo
[1]    r←⎕SE.goo
     ∇
      ⎕VR'⎕SE.goo'
     ∇ r←goo
[1]    r←⎕SI,[1.5]⎕RSI
     ∇

      )CS xx
#.xx
      calling←#.yy.foo
      ]display calling
┌→───────────┐
↓ ┌→──┐      │
│ │goo│ #.yy │
│ └───┘      │
│ ┌→──┐      │
│ │foo│ #.xx │
│ └───┘      │
└∊───────────┘


Namespace Indicator

Namespace Indicator: R←⎕NSI

R is a nested vector of character vectors containing the names of the spaces from which functions in the state indicator were called (⍴⎕NSI←→⍴⎕RSI←→⍴⎕SI).

⎕RSI and ⎕NSI are identical except that ⎕RSI returns refs to the spaces whereas ⎕NSI returns their names. Put another way: ⎕NSI←→⍕¨⎕RSI.

Note that ⎕NSI contains the names of spaces from which functions were called not those in which they are currently running.

Example

      )OBJECTS
xx      yy

      ⎕VR 'yy.foo'
     ∇ r←foo
[1]    r←⎕SE.goo
     ∇
      ⎕VR'⎕SE.goo'
     ∇ r←goo
[1]    r←⎕SI,[1.5]⎕NSI
     ∇

      )CS xx
#.xx
      calling←#.yy.foo
      ]display calling
┌→─────────────┐
↓ ┌→──┐ ┌→───┐ │
│ │goo│ │#.yy│ │
│ └───┘ └────┘ │
│ ┌→──┐ ┌→───┐ │
│ │foo│ │#.xx│ │
│ └───┘ └────┘ │
└∊─────────────┘


State Indicator Stack

State Indicator Stack: R←⎕STACK

R is a two-column matrix, with one row per entry in the State Indicator.

Column 1 :⎕OR form of user defined functions or operators on the State Indicator. Null for entries that are not user defined functions or operators.

Column 2 :Indication of the type of the item on the stack.

space | user defined function or operator
⍎ | execute level
⎕ | evaluated input
* | desk calculator level
⎕DQ | in callback function
other | primitive operator

Example

      )SI
#.PLUS[2]*
.
#.MATDIV[4]
#.FOO[1]*
⍎

      ⎕STACK
         *
∇PLUS
         .
∇MATDIV
         *
∇FOO
         ⍎
         *

      ⍴⎕STACK
8 2

      (⍴⎕LC)=1↑⍴⎕STACK
0

Pendent defined functions and operators may be edited in Dyalog APL with no resulting SI damage. However, only the visible definition is changed; the pendent version on the stack is retained until its execution is complete. When the function or operator is displayed, only the visible version is seen. Hence ⎕STACK is a tool which allows the user to display the form of the actual function or operator being executed.

Example

To display the version of MATDIV currently pendent on the stack:

      ⊃⎕STACK[4;1]
     ∇ R←A MATDIV B
[1]   ⍝ Divide matrix A by matrix B
[2]    C←A⌹B
[3]   ⍝ Check accuracy
[4]    D←⌊0.5+A PLUS.TIMES B
     ∇


State of Object

State of Object: R←⎕STATE Y

Y must be a simple character scalar or vector which is taken to be the name of an APL object. The result returned is a nested vector of 4 elements as described below. ⎕STATE supplies information about shadowed or localised objects that is otherwise unobtainable.

1⊃R | Boolean vector, element set to 1 if and only if this level shadows Y .Note: (⍴1⊃R)=⍴⎕LC
2⊃R | Numeric vector giving the stack state of this name as it entered this level. Note: (⍴2⊃R)=⍴⎕LC 0=not on stack 1=supended 2=pendent (may also be suspended) 3=active (may also be pendent or suspended)
3⊃R | Numeric vector giving the name classification of Y as it entered this level. Note: (⍴3⊃R)=+/1⊃R
4⊃R | Vector giving the contents of Y before it was shadowed at this level. Note: (⍴4⊃R)=+/0≠3⊃R

Example

      ⎕FMT∘⎕OR¨'FN1' 'FN2' 'FN3'
    ∇ FN1;A;B;C      ∇ FN2;A;C               ∇ FN3;A
[1]   A←1        [1]   A←'HELLO'         [1]   A←100
[2]   B←2        [2]   B←'EVERYONE'      [2]   ∘
[3]   C←3        [3]   C←'HOW ARE YOU?'      ∇
[4]   FN2        [4]   FN3
    ∇                ∇

      )SI
#.FN3[2]*
#.FN2[4]
#.FN1[4]

      ⎕STATE 'A'
 1 1 1  0 0 0  2 2 0   HELLO  1

      R←⎕STATE '⎕TRAP'


Stop Controls

Stop Controls ⎕STOP

Dyadic ⎕STOP means

Set Stop Controls

      ⊢(0,⍳10) ⎕STOP 'FOO'
0 1

Monadic ⎕STOP means

Query Stop Controls

      ⎕STOP 'FOO'
0 1

Language Elements


Set Stop

Set Stop: {R}←X ⎕STOP Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. X must be a simple non-negative integer scalar or vector. R is a simple integer vector of non-negative elements. X identifies the numbers of lines in the function or operator named by Y on which a stop control is to be placed. Numbers outside the range of line numbers in the function or operator (other than 0) are ignored. The number 0 indicates that a stop control is to be placed immediately prior to exit from the function or operator. If X is empty, all existing stop controls are cancelled. The value of X is independent of ⎕IO.

R is a vector of the line numbers on which a stop control has been placed in ascending order. The result is suppressed unless it is explicitly used or assigned.

Examples

      ⊢(0,⍳10) ⎕STOP 'FOO'
0 1

Existing stop controls in the function or operator named by Y are cancelled before new stop controls are set:

      ⊢1 ⎕STOP 'FOO'
1

All stop controls may be cancelled by giving X an empty vector:

      ⍴'' ⎕STOP 'FOO'
0

      ⍴⍬ ⎕STOP 'FOO'
0

Attempts to set stop controls in a locked function or operator are ignored.

      ⎕LOCK'FOO'

      ⊢0 1 ⎕STOP'FOO'

The effect of ⎕STOP when a function or operator is invoked is to suspend execution at the beginning of any line in the function or operator on which a stop control is placed immediately before that line is executed, and immediately before exiting from the function or operator if a stop control of 0 is set. Execution may be resumed by a branch expression. A stop control interrupt (1001) may also be trapped - see Trap Event: .

Example

      ⎕FX'R←FOO' 'R←10'

      0 1 ⎕STOP'FOO'

      FOO
FOO[1]

      R
VALUE ERROR
      R
      ^

      →1
FOO[0]

      R
10

      →⎕LC
10


Query Stop

Query Stop: R←⎕STOP Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. R is a simple non-negative integer vector of the line numbers of the function or operator named by Y on which stop controls are set, shown in ascending order. The value 0 in R indicates that a stop control is set immediately prior to exit from the function or operator.

Example

      ⎕STOP'FOO'
0 1


Trace Controls

Trace Controls ⎕TRACE

Dyadic ⎕TRACE means

Set Trace Controls

      +(0,⍳10) ⎕TRACE 'foo'
0 1 2 3 4 5

Monadic ⎕TRACE means

Query Trace Controls

      ⎕TRACE 'foo'
0 1 2 3 4 5

Language Elements


Query Trace

Query Trace: R←⎕TRACE Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. R is a simple non-negative integer vector of the line numbers of the function or operator named by Y on which trace controls are set, shown in ascending order. The value 0 in R indicates that a trace control is set to display the result of the function or operator immediately prior to exit.

Example

      ⎕TRACE'DSL'
0 1 2 3 4 5 6


Set Trace

Set Trace: {R}←X ⎕TRACE Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator. X must be a simple non-negative integer scalar or vector.

X identifies the numbers of lines in the function or operator named by Y on which a trace control is to be placed. Numbers outside the range of line numbers in the function or operator (other than 0) are ignored. The number 0 indicates that a trace control is to be placed immediately prior to exit from the function or operator. The value of X is independent of ⎕IO.

R is a simple integer vector of non-negative elements indicating the lines in the function or operator on which a trace control has been placed.

Example

      +(0,⍳10) ⎕TRACE'FOO'
0 1

Existing trace controls in the function or operator named by Y are cancelled before new trace controls are set:

      + 1 ⎕TRACE'FOO'
1

All trace controls may be cancelled by giving X an empty vector:

      ⍴⍬ ⎕TRACE 'FOO'
0

Attempts to set trace controls in a locked function or operator are ignored.

      ⎕LOCK 'FOO'
      +1 ⎕TRACE 'FOO'

The effect of trace controls when a function or operator is invoked is to display the result of each complete expression for lines with trace controls as they are executed, and the result of the function if trace control 0 is set. If a line contains expressions separated by ⋄, the result of each complete expression is displayed for that line after execution.

The result of a complete expression is displayed even where the result would normally be suppressed. In particular:

  • the result of a branch statement is displayed;
  • the result (pass-through value) of assignment is displayed;
  • the result of a function whose result would normally be suppressed is displayed;

For each traced line, the output from ⎕TRACE is displayed as a two element vector, the first element of which contains the function or operator name and line number, and the second element of which takes one of two forms.

  • The result of the line, displayed as in standard output.
  • → followed by a line number.

Example

      ⎕VR 'DSL'
     ∇ R←DSL SKIP;A;B;C;D
[1]    A←2×3+4
[2]    B←(2 3⍴'ABCDEF')A
[3]    →NEXT×⍳SKIP
[4]    'SKIPPED LINE'
[5]   NEXT:C←'one' ⋄ D←'two'
[6]   END:R←C D
     ∇

      (0,⍳6) ⎕TRACE 'DSL'

      DSL 1
 DSL[1]  14
 DSL[2]   ABC   14
          DEF
 DSL[3]  →5
 DSL[5]  one
 DSL[5]  two
 DSL[6]   one   two
 DSL[0]   one   two
 one  two


Account Information

Account Information: R←⎕AI

This is a simple integer vector, whose four elements are:

⎕AI[1] | user identification.Under Windows, this is the aplnid (network ID from configuration dialog box).Under UNIX and LINUX, this is the UID of the account. 1
⎕AI[2] | compute time for the APL session in milliseconds.
⎕AI[3] | connect time for the APL session in milliseconds.
⎕AI[4] | keying time for the APL session in milliseconds.

Elements beyond 4 are not defined but reserved.

Example

      ⎕AI
52 7396 2924216 2814831


Account Name

Account Name: R←⎕AN

This is a simple character vector containing the user (login) name.

Example

      ⎕AN
Pete

      ⍴⎕AN
4


Clear Workspace

Clear Workspace: ⎕CLEAR

A clear workspace is activated, having the name CLEAR WS. The active workspace is lost. All system variables assume their default values. The maximum size of workspace is available.

The contents of the session namespace ⎕SE are not affected.

Example

      ⎕CLEAR
      ⎕WSID
CLEAR WS


Comparison Tolerance

Comparison Tolerance: ⎕CT

The value of ⎕CT determines the precision with which two numbers are judged to be equal. Two numbers, X and Y, are judged to be equal if:

(|X-Y)≤⎕CT×(|X)⌈|Y where ≤ is applied without tolerance.

⎕CT may be assigned any value in the range from 0 to 16*¯8. A value of 0 ensures exact comparison. The value in a clear workspace is 1E¯14.

⎕CT is an implicit argument of the monadic primitive functions Ceiling (⌈), Floor (⌊) and Unique (∪), and of the dyadic functions Equal (=), Excluding (~), Find (⍷), Greater (>), Greater or Equal (≥), Index of (⍳), Intersection (∩), Less (<), Less or Equal (≤), Match (≡), Membership (∊), Not Match (≢), Not Equal (≠), Residue (|) and Union (∪), as well as ⎕FMT O-format.

Examples

      ⎕CT←1E¯10
      1.00000000001 1.0000001 = 1
1 0


Decimal Comparison Tolerance

Decimal Comparison Tolerance: ⎕DCT

The value of ⎕DCT determines the precision with which two numbers are judged to be equal when the value of ⎕FR is 1287. If ⎕FR is 645, the system uses ⎕CT.

⎕DCT may be assigned any value in the range from 0 to 2.3283064365386962890625E¯10. A value of 0 ensures exact comparison. The value in a clear workspace is 1E¯28.

For further information, see Comparison Tolerance: .

Examples

      ⎕DCT←1E¯10
      1.00000000001 1.0000001 = 1
1 0


Division Method

Division Method: ⎕DIV

The value of ⎕DIV determines how division by zero is to be treated. If ⎕DIV=0, division by 0 produces a DOMAIN ERROR except that the special case of 0÷0 returns 1.

If ⎕DIV=1, division by 0 returns 0.

⎕DIV may be assigned the value 0 or 1. The value in a clear workspace is 0.

⎕DIV is an implicit argument of the monadic function Reciprocal (÷) and the dyadic function Divide (÷).

Examples

      ⎕DIV←0

      1 0 2 ÷ 2 0 1
0.5 1 2

      ÷0 1
DOMAIN ERROR
      ÷0 1
      ^

      ⎕DIV←1

      ÷0 2
0 0.5

      1 0 2 ÷ 0 0 4
0 0 0.5


Floating Point Representation

Floating-Point Representation: ⎕FR

The value of ⎕FR determines the way that floating-point operations are performed.

If ⎕FR is 645, all floating-point calculations are performed using IEEE 754 64-bit floating-point operations and the results of these operations are represented internally using binary64http://en.wikipedia.org/wiki/Double_precision_floating-point_format 1 floating-point format.

If ⎕FR is 1287, all floating-point calculations are performed using IEEE 754-2008 128-bit decimal floating-point operations and the results of these operations are represented internally using decimal128http://en.wikipedia.org/wiki/Decimal128_floating-point_format 2 format.

Note that when you change ⎕FR, its new value only affects subsequent floating-point operations and results. Existing floating-point values stored in the workspace remain unchanged.

The default value of ⎕FR (its value in a clear ws) is configurable.

⎕FR has workspace scope, and may be localised. If so, like most other system variables, it inherits its initial value from the global environment.

However:Although ⎕FR can vary, the system is not designed to allow “seamless” modification during the running of an application and the dynamic alteration of is not recommended. Strange effects may occur. For example, the type of a constant contained in a line of code (in a function or class), will depend on the value of ⎕FR when the function is fixed.

Also note:

      ⎕FR←1287
      x←1÷3

      ⎕FR←645
      x=1÷3
1

The decimal number has 17 more 3’s. Using the tolerance which applies to binary floats (type 645), the numbers are equal. However, the “reverse” experiment yields 0, as tolerance is much narrower in the decimal universe:

      ⎕FR←645
      x←1÷3
      ⎕FR←1287
      x=1÷3
0

Since ⎕FR can vary, it will be possible for a single workspace to contain floating-point values of both types (existing variables are not converted when ⎕FR is changed). For example, an array that has just been brought into the workspace from external storage may have a different type from ⎕FR in the current namespace. Conversion (if necessary) will only take place when a new floating-point array is generated as the result of “a calculation”. The result of a computation returning a floating-point result will not depend on the type of the arrays involved in the expression: ⎕FR at the time when a computation is performed decides the result type, alone.

Structural functions generally do NOT change the type, for example:

      ⎕FR←1287
      x←1.1 2.2 3.3

      ⎕FR←645
      ⎕DR x
1287
      ⎕DR 2↑x
1287

128-bit decimal numbers not only have greater precision (roughly 34 decimal digits); they also have significantly larger range – from ¯1E6145 to 1E6145. Loss of precision is accepted on conversion from 645 to 1287, but the magnitude of a number may make the conversion impossible, in which case a DOMAIN ERROR is issued:

      ⎕FR←1287
      x←1E1000
      ⎕FR←645 ⋄ x+0
DOMAIN ERROR

When experimenting with ⎕FR it is important to note that numeric constants entered into the Session are evaluated (and assigned a data type) before the line is actually executed. This means that constants are evaluated according to the value of ⎕FR that pertained before the line was entered. For example:

      ⎕FR←645
      ⎕FR
645

      ⎕FR←1287 ⋄ ⎕DR 0.1
645
      ⎕DR 0.1
1287

WARNING: The use of COMPLEX numbers when ⎕FR is 1287 is not recommended, because:

any 128-bit decimal array into which a complex number is inserted or appended will be forced in its entirety into complex representation, potentially losing precision.

all comparisons are done using ⎕DCT when ⎕FR is 1287, and the default value of 1E¯28 is equivalent to 0 for complex numbers.


Index Origin

Index Origin: ⎕IO

⎕IO determines the index of the first element of a non-empty vector.

⎕IO may be assigned the value 0 or 1. The value in a clear workspace is 1.

⎕IO is an implicit argument of any function derived from the Axis operator ([K]), of the monadic functions Fix (⎕FX), Grade Down (⍒), Grade Up (⍋), Index Generator (⍳), Roll (?), and of the dyadic functions Deal (?), Grade Down (⍒), Grade Up (⍋), Index Of (⍳), Indexed Assignment, Indexing, Pick (⊃) and Transpose (⍉).

Examples

        ⎕IO←1
        ⍳5
1 2 3 4 5

        ⎕IO←0
        ⍳5
0 1 2 3 4

        +/[0]2 3⍴⍳6
3 5 7

        'ABC',[¯.5]'='
ABC
===


Key Label

Key Label: R←⎕KL Y

Classic Edition only.

Y is a simple character vector or a vector of character vectors containing Input Codes for Keyboard Shortcuts. In the Classic Edition, keystrokes are associated with Keyboard Shortcuts by the Input Translate Table.

R is a simple character vector or a vector of character vectors containing the labels associated with the codes. If Y specifies codes that are not defined, the corresponding elements of R are the codes in Y.

⎕KL provides the information required to build device-independent help messages into applications, particularly full-screen applications using ⎕SM and ⎕SR.

Examples:

      ⎕KL 'RC'
Right

      ⎕KL 'ER' 'EP' 'QT' 'F1' 'F13'
  Enter  Esc  Shift+Esc  F1  Shift+F1


Load Workspace

Load Workspace: ⎕LOAD Y

Y must be a simple character scalar or vector containing the identification of a saved workspace.

If Y is ill-formed or does not identify a saved workspace or the user account does not have access permission to the workspace, a DOMAIN ERROR is reported.

Otherwise, the active workspace is replaced by the workspace identified in Y. The active workspace is lost. If the loaded workspace was saved by the )SAVE system command, the latent expression (⎕LX) is immediately executed, unless APL was invoked with the -x option. If the loaded workspace was saved by the ⎕SAVE system function, execution resumes from the point of exit from the ⎕SAVE function, with the result of the ⎕SAVE function being 0.

The workspace identification and time-stamp when saved is not displayed.

If the workspace contains any GUI objects whose Visible property is 1, these objects will be displayed. If the workspace contains a non-empty ⎕SM but does not contain an SM GUI object, the form defined by ⎕SM will be displayed in a window on the screen.

Under UNIX, the interpreter attempts to open the file whose name matches the contents of Y. Under Windows, unless Y contains at least one ".", the interpreter will append the file extension ".DWS" to the name.


Latent Expression

Latent Expression: ⎕LX

This may be a character vector or scalar representing an APL expression. The expression is executed automatically when the workspace is loaded. If APL is invoked using the -x flag, this execution is suppressed.

The value of ⎕LX in a clear workspace is ''.

Example

      ⎕LX←'''GOOD MORNING PETE'''

      )SAVE GREETING
GREETING saved Tue Sep 8 10:49:29 1998

      )LOAD GREETING
./GREETING saved Tue Sep 8 10:49:29 1998
GOOD MORNING PETE


Program Function Key

Program Function Key: R←{X}⎕PFKEY Y

⎕PFKEY is a system function that sets or queries the programmable function keys. ⎕PFKEY associates a sequence of keystrokes with a function key. When the user subsequently presses the key, it is as if he had typed the associated keystrokes one by one.

Y is an integer scalar in the range 0-255 specifying a programmable function key. If X is omitted the result R is the current setting of the key. If the key has not been defined previously, the result is an empty character vector.

If X is specified it is a simple or nested character vector defining the new setting of the key. The value of X is returned in the result R.

The elements of X are either character scalars or 2-element character vectors which specify Input Translate Table codes.

Programmable function keys are recognised in any of the three types of window (SESSION, EDIT and TRACE) provided by the Dyalog APL development environment. ⎕SR operates with the 'raw' function keys and ignores programmed settings.

Note that key definitions can reference other function keys.

The size of the buffer associated with ⎕PFKEY is specified by the pfkey_size parameter.

Examples

      (')FNS',⊂'ER') ⎕PFKEY 1
 )FNS  ER

      ]display ⎕PFKEY 1
.→-------------.
|         .→-. |
| ) F N S |ER| |
| - - - - '--' |
'∊-------------'

      (')VARS',⊂'ER') ⎕PFKEY 2
 )VARS  ER
      'F1' 'F2' ⎕PFKEY 3   ⍝ Does )FNS and )VARS
 F1  F2


Print Precision

Print Precision: ⎕PP

⎕PP is the number of significant digits in the display of numeric output.

⎕PP may be assigned any integer value in the range 1 to 17. The value in a clear workspace is 10. Note that in all Versions of Dyalog APL prior to Version 11.0, the maximum value for ⎕PP was 16.

⎕PP is used to format numbers displayed directly. It is an implicit argument of monadic function Format (⍕), monadic ⎕FMT and for display of numbers via ⎕ and ⍞ output. ⎕PP is ignored for the display of integers.

Examples:

      ⎕PP←10

      ÷3 6
0.3333333333 0.1666666667

      ⎕PP←3

      ÷3 6
0.333 0.167

If ⎕PP is set to its maximum value of 17, floating-point numbers may be converted between binary and character representation without loss of precision. In particular, if ⎕PP is 17 and ⎕CT is 0 (to ensure exact comparison), for any floating-point number N the expression N=⍎⍕N is true. Note however that denormal numbers are an exception to this rule.

Numbers, very close to zero, in the range 2.2250738585072009E¯308 to 4.9406564584124654E¯324 are called denormal numbers. Such numbers can occur as the result of calculations and are displayed correctly.

Numbers below the lower end of this range (4.94E¯324) are indistinguishable from zero in IEEE double floating point format.


Print Width

Print Width: ⎕PW

⎕PW is the maximum number of output characters per line before folding the display.

⎕PW may be assigned any integer value in the range 42 to 32767. Note that in versions of Dyalog APL prior to 13.0 ⎕PW had a minimum value of 30; this was increased to support 128-bit decimal values.

If an attempt is made to display a line wider than ⎕PW, then the display will be folded at or before the ⎕PW width and the folded portions indented 6 spaces. The display of a simple numeric array may be folded at a width less than ⎕PW so that individual numbers are not split.

⎕PW ony affects output, either direct or through ⎕ output. It does not affect the result of the function Format (⍕), of the system function ⎕FMT, or output through the system functions ⎕ARBOUT and ⎕ARBIN, or output through ⍞.

Note that if the auto_pw parameter (Options/Configure/Session/Auto PW) is set to 1, ⎕PW is automatically adjusted whenever the Session window is resized. In these circumstances, a value assigned to ⎕PW will only apply until the Session window is next resized.

Examples

      ⎕PW←42

      ⎕←3⍴÷3
0.3333333333 0.3333333333 0.3333333333
      0.3333333333


Random Link

Random Link: ⎕RL

⎕RL establishes a base or seed for generating random numbers using Roll and Deal, and returns the current state of such generation.

Three different random number generatators are provided, which are referred to here as RNG0, RNG1 and RNG2. These are selected using (16807⌶). See Random Number Generator:. ⎕RL is relevant only to RNG0 and RNG1 for which repeatable pseudo-random series can be obtained by setting ⎕RL to a particular value first.

Using RNG0 or RNG1, you can set ⎕RL to any integer in the range 1 to ¯2+2*31 .

In a clear ws, ⎕RL is initialised to the value defined by the default_rl parameter which itself defaults to 16807 if it is not defined.

Using RNG0, ⎕RL returns an integer which represents the seed for the next random number in the sequence.

Using RNG1, the system internally retains a block of 312 64-bit numbers which are used one by one to generate the results of roll and deal. When the first block of 312 have been used up, the system generates a second block. In this case, ⎕RL returns an integer vector of 32-bit numbers of length 625 (the first is an index into the block of 312) which represents the internal state of the random number generator. This means that, as with RNG0, you may save the value of ⎕RL in a variable and reassign it later.

Internally, APL maintains the current state separately for RNG0 and RNG1. When you switch from one Random Number Generator to the other, the appropriate state is loaded into ⎕RL.

RNG2 does not permit access to the seed, so in this case ⎕RL is not relevant and is not used by Roll and Deal. It will accept any value but will always return zilde.

Examples

      16807⌶1 ⍝ Select RNG1
0
      ⎕RL←16807
      10?10
4 1 6 5 2 9 7 10 3 8
      5↑⎕RL
10 0 16807 1819658750 ¯355441828
      X←?1000⍴1000
      5↑⎕RL
100 ¯465541037 ¯1790786136 ¯205462449 996695303
      ⎕RL←16807
      10?10
4 1 6 5 2 9 7 10 3 8
      Y←?1000⍴1000
      X≡Y
1
      5↑⎕RL
100 ¯465541037 ¯1790786136 ¯205462449 996695303
      16807⌶0 ⍝ Select RNG0
1
      ⎕RL
16807
      ?9 9 9
2 7 5
      ?9
7
      ⎕RL
984943658

      ⎕RL←16807
      ?9 9 9
2 7 5
      ?9
7
      ⎕RL
984943658

      16807⌶1 ⍝ Select RNG1
0
      5↑⎕RL
100 ¯465541037 ¯1790786136 ¯205462449 996695303


Save Workspace

Save Workspace: {R}←{X}⎕SAVE Y

Y must be a simple character scalar or vector, identifying a workspace name. Note that the name must represent a valid file name for the current Operating System. R is a simple logical scalar. The active workspace is saved with the given name in Y. In the active workspace, the value 1 is returned. The result is suppressed if not used or assigned.

The optional left argument X is either 0 or 1. If X is omitted or 1, the saved version of the workspace has execution suspended at the point of exit from the ⎕SAVE function. If the saved workspace is subsequently loaded by ⎕LOAD, execution is resumed, and the value 0 is returned if the result is used or assigned, or otherwise the result is suppressed. In this case, the latent expression value (⎕LX) is ignored.

If X is 0, the workspace is saved without any State Indicator in effect. The effect is the same as if you first executed )RESET and then )SAVE. In this case, when the workspace is subsequently loaded, the value of the latent expression (⎕LX) is honoured if applicable.

A DOMAIN ERROR is reported if the name in Y is not a valid workspace name or file name, or the reference is to an unauthorised directory.

As is the case for )SAVE (see Save Workspace: ), monadic ⎕SAVE will fail and issue DOMAIN ERROR if any threads (other than the root thread 0) are running or if there are any Edit or Trace windows open. However, neither of these restrictions apply if the left argument X is 0.

Note that the values of all system variables (including ⎕SM) and all GUI objects are saved.

Example

      (⊃'SAVED' 'ACTIVE' [⎕IO+⎕SAVE'TEMP']),' WS'
ACTIVE WS
      ⎕LOAD 'TEMP'
SAVED WS


Workspace Available

Workspace Available: R←⎕WA

This is a simple integer scalar. It identifies the total available space in the active workspace area given as the number of bytes it could hold.

A side effect of using ⎕WA is an internal reorganisation of the workspace and process memory, as follows:

  1. Any un-referenced memory is discarded. This process, known as garbage collection, is required because whole cycles of refs can become un-referenced.
  2. Numeric arrays are demoted to their tightest form. For example, a simple numeric array that happens to contain only values 0 or 1, is demoted or squeezed to have a ⎕DR type of 11 (Boolean).
  3. All remaining used memory blocks are copied to the low-address end of the workspace, leaving a single free block at the high-address end. This process is known as compaction.
  4. Workspace above a small amount (1/16 of the configured maximum workspace size) of working memory is returned to the Operating System. On a Windows system, you can see the process size changing by using Task Manager.

Example

      ⎕WA
261412


Workspace Identification

Workspace Identification: ⎕WSID

This is a simple character vector. It contains the identification name of the active workspace. If a new name is assigned, that name becomes the identification name of the active workspace, provided that it is a correctly formed name.

See Workspaces for workspace naming conventions.

It is useful, though not essential, to associate workspaces with a specific directory in order to distinguish workspaces from other files.

The value of ⎕WSID in a clear workspace is 'CLEAR WS'.

Example

      ⎕WSID
CLEAR WS

      ⎕WSID←'WS/MYWORK'     (UNIX)

      ⎕WSID←'B:\WS\MYWORK'   (Windows)


Windows Command

Windows Command ⎕CMD

Monadic ⎕CMD means

Execute Windows Command

      ⎕cmd 'DIR *.dws'
 Volume in drive C is OS
 Volume Serial Number is 6AFE-193E

 Directory of C:\Documents and Settings\Pete

01/12/2011  16:46            25,632 netcontrol.DWS
15/06/2011  09:39            16,308 ReadTrans.DWS
25/09/2011  10:34         4,597,592 temp.DWS
               3 File(s)      4,639,532 bytes
               0 Dir(s)  166,407,012,352 bytes free

Dyadic ⎕CMD means

Start Windows Auxiliary Processor

      )CLEAR
clear ws
      'xutils' ⎕CMD ''
      )fns
avx     box     dbr     getenv  hex     ltom    ltov    mtol    ss      vtol

Language Elements


Start Windows Auxiliary Processor

Start Windows Auxiliary Processor: X ⎕CMD Y

Used dyadically, ⎕CMD starts an Auxiliary Processor. The effect, as far as the APL workspace is concerned, is identical under both Windows and UNIX, although the method of implementation differs. ⎕CMD is a synonym of ⎕SH. Either function may be used in either environment (Windows or UNIX) with exactly the same effect. ⎕CMD is probably more natural for the Windows user. This section describes the behaviour of ⎕CMD and ⎕SH under Windows. See Examples for a discussion of the behaviour of these system functions under UNIX.

X must be a simple character vector containing the name (or pathname) of a Dyalog APL Auxiliary Processor (AP). See User Guide for details of how to write an AP.

Y may be a simple character scalar or vector, or a vector of character vectors. Under Windows the contents of Y are ignored.

⎕CMD loads the Auxiliary Processor into memory. If no other APs are currently running, ⎕CMD also allocates an area of memory for communication between APL and its APs.

The effect of starting an AP is that one or more external functions are defined in the workspace. These appear as locked functions and may be used in exactly the same way as regular defined functions.

When an external function is used in an expression, the argument(s) (if any) are passed to the AP for processing via the communications area described above. APL halts whilst the AP is processing, and waits for a result. Under Windows, unlike under UNIX, it is not possible for external functions to run in parallel with APL.


Execute Windows Command

Execute Windows Command: R←⎕CMD Y

⎕CMD executes a Windows Command Processor or UNIX shell or starts another Windows application program. ⎕CMD is a synonym of ⎕SH. Either system function may be used in either environment (Windows or UNIX) with exactly the same effect. ⎕CMD is probably more natural for the Windows user. This section describes the behaviour of ⎕CMD and ⎕SH under Windows. See Execute (UNIX) Command: for a discussion of the behaviour of these system functions under UNIX.

The system commands )CMD and )SH provide similar facilities but may only be executed from the APL Session.

Executing a Windows Command

If Y is a simple character vector, ⎕CMD invokes the Windows Command Processor (normally cmd.exe) and passes Y to it for execution. R is a vector of character vectors containing the result of the command. Each element in R corresponds to a line of output produced by the command.

Example

      Z←⎕CMD'DIR'
      ⍴Z
8
      ↑Z
 Volume in drive C has no label
 Directory of C:\DYALOG

.            <DIR>     5-07-89  3.02p
..           <DIR>     5-07-89  3.02p
SALES    DWS    110092 5-07-89  3.29p
EXPENSES DWS    154207 5-07-89  3.29p

If the command specified in Y already contains the redirection symbol (>) the capture of output through a pipe is avoided and the result R is empty. If the command specified by Y issues prompts and expects user input, it is ESSENTIAL to explicitly redirect input and output to the console. If this is done, APL detects the presence of a ">" in the command line, runs the command processor in a visible window, and does not direct output to the pipe. If you fail to do this your system will appear to hang because there is no mechanism for you to receive or respond to the prompt.

Example

      ⎕CMD 'DATE <CON >CON'

(Command Prompt window appears)

Current date is Wed 19-07-1995

Enter new date (dd-mm-yy): 20-07-95

(COMMAND PROMPT window disappears)

Implementation Notes

The right argument of ⎕CMD is simply passed to the appropriate command processor for execution and its output is received using an unnamed pipe.

By default, ⎕CMD will execute the string ('cmd.exe /c',Y); where Y is the argument given to ⎕CMD. However, the implementation permits the use of alternative command processors as follows.

Before execution, the argument is prefixed and postfixed with strings defined by the APL parameters CMD_PREFIX and CMD_POSTFIX. The former specifies the name of your command processor and any parameters that it requires. The latter specifies a string which may be required. If CMD_PREFIX is not defined, it defaults to the name defined by the environment variable COMSPEC followed by "/c". If COMSPEC is not defined, it defaults to cmd.exe. If CMD_POSTFIX is not defined, it defaults to an empty vector.

⎕CMD treats certain characters as having special meaning as follows:

# | marks the start of a trailing comment,
; | divides the command into sub-commands,
> | if found within the last sub-command, causes ⎕CMD to use a visible window.

If you simply wish to open a Command Prompt window, you may execute the command as a Windows Program (see below). For example:

      ⎕CMD 'cmd.exe' ''

Executing a Windows Program

If Y is a 2-element vector of character vectors, ⎕CMD starts the executable program named by Y[1] with the initial window parameter specified by Y[2]. The shy result is an integer scalar containing the window handle allocated by the window manager.

Y[1] must specify the name or complete pathname of an executable program. If the name alone is specified, Windows will search the following directories:

  1. the current directory,
  2. the Windows directory,
  3. the Windows system directory,
  4. the directories specified by the PATH variable,
  5. the list of directories mapped in a network.

Note that Y[1] may contain the complete command line, including any suitable parameters for starting the program. If Windows fails to find the executable program, ⎕CMD will fail and report FILE ERROR 2.

Y[2] specifies the window parameter and may be one of the following. If not, a DOMAIN ERROR is reported.

'Normal' '' | Application is started in a normal window, which is given the input focus
'Unfocused' | Application is started in a normal window, which is NOT given the input focus
'Hidden' | Application is run in an invisible window
'Minimized' 'Minimised' | Application is started as an icon which is NOT given the input focus
'Maximized' 'Maximised' | Application is started maximized (full screen) and is given the input focus

An application started by ⎕CMD may ONLY be terminated by itself or by the user. There is no way to close it from APL. Furthermore, if the window parameter is HIDDEN, the user is unaware of the application (unless it makes itself visible) and has no means to close it.

Examples

      Path←'c:\Program Files\Microsoft Office\Office\'
      ⎕←⎕CMD (Path,'excel.exe') ''
33
      ⎕CMD (Path,'winword /mMyMacro') 'Minimized'


Map File

Map File: R←{X}⎕MAP Y

⎕MAP function associates a mapped file with an APL array in the workspace.

Two types of mapped files are supported; APL and raw. An APL mapped file contains the binary representation of a Dyalog APL array, including its header. A file of this type must be created using the supplied utility function ∆MPUT. When you map an APL file, the rank, shape and data type of the array is obtained from the information on the file.

A raw mapped file is an arbitrary collection of bytes. When you map a raw file, you must specify the characteristics of the APL array to be associated with this data. In particular, the data type and its shape.

The type of mapping is determined by the presence (raw) or absence (APL) of the left argument to ⎕MAP.

The right argument Y specifies the name of the file to be mapped and, optionally, the access type and a start byte in the file. Y may be a simple character vector, or a 2 or 3-element nested vector containing:

  1. file name (character scalar/vector)
  2. access code (character scalar/vector) : one of : 'R' or 'r' (read-only access) , 'W' or 'w' (read-write access).
  3. start byte offset (integer scalar/vector). Must be a multiple of 4 (default 0)

If you map a file with read-only access you may modify the corresponding array in the workspace, however your changes are not written back to the file.

If X is specified, it defines the type and shape to be associated with raw data on file. X must be an integer scalar or vector. The first item of X specifies the data type and must be one of the following values:

Classic Edition | 11, 82, 83, 163, 323 or 645
Unicode Edition | 11, 80, 83, 160, 163, 320, 323 or 645

The values are more fully explained in Data Representation (Monadic):.

Following items determine the shape of the mapped array. A value of ¯1 on any (but normally the first) axis in the shape is replaced by the system to mean: read as many complete records from the file as possible. Only one axis may be specified in this way.

NB: If X is a singleton, the data on the file is mapped as a scalar and only the first value on the file is accessible.

If no left argument is given, file is assumed to contain a simple APL array, complete with header information (type, rank, shape, etc). Such mapped files may only be updated by changing the associated array using indexed/pick assignment: var[a]←b, the new values must be of the same type as the originals.

Note that a raw mapped file may be updated only if its file offset is 0.

Examples

Map raw file as a read-only vector of doubles:

      vec←645 ¯1 ⎕MAP'c:\myfile'

Map raw file as a 20-column read-write matrix of 1-byte integers:

      mat←83 ¯1 20 ⎕MAP'c:\myfile' 'W'

Replace some items in mapped file:

      mat[2 3;4 5]←2 2⍴⍳4

Map bytes 100-180 in raw file as a 5×2 read-only matrix of doubles:

      dat←645 5 2 ⎕MAP'c:\myfile' 'R' 100

Put simple 4-byte integer array on disk ready for mapping:

      (⊃83 323 ⎕DR 2 3 4⍴⍳24)∆MPUT'c:\myvar'

Then, map a read-write variable:

      var←⎕MAP'c:\myvar' 'w'

Note that a mapped array need not be named. In the following example, a ‘raw’ file is mapped, summed and released, all in a single expression:

      +/163 ¯1 ⎕MAP'c:\shorts.dat'
42

If you fail to specify the shape of the data, the data on file will be mapped as a scalar and only the first value in the file will be accessible:

      83 ⎕MAP 'myfile'   ⍝ map FIRST BYTE of file.
¯86

Compatibility between Editions

In the Unicode Edition ⎕MAP will fail with a TRANSLATION ERROR (event number 92) if you attempt to map an APL file which contains character data type 82.

In order for the Unicode Edition to correctly interpret data in a raw file that was written using data type 82, the file may be mapped with data type 83 and the characters extracted by indexing into ⎕AVU.


Name Association

Name Association: {R}←{X}⎕NA Y

⎕NA provides access from APL to compiled functions within a Dynamic Link Library (DLL). A DLL is a collection of functions typically written in C (or C++) each of which may take arguments and return a result.

Instructional examples using ⎕NA can be found in supplied workspace: QUADNA.DWS.

The DLL may be part of the standard operating system software, purchased from a third party supplier, or one that you have written yourself.

The right argument Y is a character vector that identifies the name and syntax of the function to be associated. The left argument X is a character vector that contains the name to be associated with the external function. If the ⎕NA is successful, a function (name class 3) is established in the active workspace with name X. If X is omitted, the name of the external function itself is used for the association.

The shy result R is a character vector containing the name of the external function that was fixed.

For example, math.dll might be a library of mathematical functions containing a function divide. To associate the APL name div with this external function:

      'div' ⎕NA 'F8 math|divide I4 I4'

where F8 and I4, specify the types of the result and arguments expected by divide. The association has the effect of establishing a new function: div in the workspace, which when called, passes its arguments to divide and returns the result.

      )fns
div
      div 10 4
2.5

Type Declaration

In a compiled language such as C, the types of arguments and results of functions must be declared explicitly. Typically, these types will be published with the documentation that accompanies the DLL. For example, function divide might be declared:

double divide(int32_t, int32_t);

which means that it expects two long (4-byte) integer arguments and returns a double (8-byte) floating point result. Notice the correspondence between the C declaration and the right argument of ⎕NA:

C:             double    divide       (int32_t,  int32_t);
APL:'div' ⎕NA 'F8   math|divide        I4        I4 '

It is imperative that care be taken when coding type declarations. A DLL cannot check types of data passed from APL. A wrong type declaration will lead to erroneous results or may even cause the workspace to become corrupted and crash.

The full syntax for the right argument of ⎕NA is:

[result] library|function [arg1] [arg2] ...

Note that functions associated with DLLs are never dyadic. All arguments are passed as items of a (possibly nested) vector on the right of the function.

Locating the DLL

The DLL may be specified using a full pathname, file extension, and function type.

Pathname:

APL uses the LoadLibrary() system function under Windows and dlopen() under UNIX and LINUX to load the DLL. If a full or relative pathname is omitted, these functions search standard operating system directories in a particular order. For further details, see the operating system documentation about these functions.

Alternatively, a full or relative pathname may be supplied in the usual way:

      ⎕NA'... c:\mydir\mydll|foo ...'

Errors:

If the specified DLL (or a dependent DLL) fails to load it will generate:

FILE ERROR 2 No such file or directory

If the DLL loads successfully, but the specified library function is not accessible, it will generate:

VALUE ERROR

File Extension:

Under Windows, if the file extension is omitted, .dll is assumed. Note that some DLLs are in fact .exe files, and in this case the extension must be specified explicitly:

      ⎕NA'... mydll.exe|foo ...'

Example

      ⎕NA'... mydll.exe.P32|foo ...'⍝ 32 bit Pascal

Call by Ordinal Number

Under Windows, a DLL may associate an ordinal number with any of its functions. This number may then be used to call the function as an alternative to calling it by name. Using ⎕NA to call by ordinal number uses the same syntax but with the function name replaced with its ordinal number. For example:

      ⎕NA'... mydll|57 ...'

Multi-Threading

Appending the ‘&’ character to the function name causes the external function to be run in its own system thread. For example:

      ⎕NA'... mydll|foo& ...'

This means that other APL threads can run concurrently with the one that is calling the ⎕NA function.

Data Type Coding Scheme

The type coding scheme introduced above is of the form:

[direction] [special] type [width] [array]

The options are summarised in the following table and their functions detailed below.

Description | Symbol | Meaning
Direction | < | Pointer to array input to DLL function.
 | > | Pointer to array output from DLL function
 | = | Pointer to input/output array.
Special | 0 | Null-terminated string.
 | # | Byte-counted string
Type | I | int
 | U | unsigned int
 | C | char
 | T | charClassic Edition: - translated to/from ANSI 1
 | F | float
 | D | decimal
 | J | complex
 | P | uintptr-t equivalent to U4 on 32-bit Versions and U8 on 64-bit Versions 2
 | A | APL array
 | Z | APL array with header (as passed to a TCP/IP socket)
Width | 1 | 1-byte
 | 2 | 2-byte
 | 4 | 4-byte
 | 8 | 8-byte
 | 16 | 16-byte (128-bit)
Array | [n] | Array of length n elements
 | [] | Array, length determined at call-time
Structure | {...} | Structure.

In the Classic Edition, C specifies untranslated character, whereas T specifies that the character data will be translated to/from ⎕AV.

In the Unicode Edition, C and T are identical (no translation of character data is performed) except that for C the default width is 1 and for T the default width is "wide" (2 bytes under Windows, 4 bytes under UNIX).

The use of T with default width is recommended to ensure portability between Editions.

Direction

C functions accept data arguments either by value or by address. This distinction is indicated by the presence of a ‘*’ or ‘[]’ in the argument declaration:

int  num1;       // value of num1 passed.
int *num2;       // Address of num2 passed.
int num3[];      // Address of num3 passed.

An argument (or result) of an external function of type pointer, must be matched in the ⎕NA call by a declaration starting with one of the characters: <, >, or =.

In C, when an address is passed, the corresponding value can be used as either an input or an output variable. An output variable means that the C function overwrites values at the supplied address. Because APL is a call-by-value language, and doesn’t have pointer types, we accommodate this mechanism by distinguishing output variables, and having them returned explicitly as part of the result of the call.

This means that where the C function indicates a pointer type, we must code this as starting with one of the characters: <, > or =.

< | indicates that the address of the argument will be used by C as an input variable and values at the address will not be over-written.
> | indicates that C will use the address as an output variable. In this case, APL must allocate an output array over which C can write values. After the call, this array will be included in the nested result of the call to the external function.
= | indicates that C will use the address for both input and output. In this case, APL duplicates the argument array into an output buffer whose address is passed to the external function. As in the case of an output only array, the newly modified copy will be included in the nested result of the call to the external function.

Examples

<I2 | Pointer to 2-byte integer - input to external function
>C | Pointer to character output from external function.
=T | Pointer to character input to and output from function.
=A | Pointer to APL array modified by function.

Special

In C it is common to represent character strings as null-terminated or byte counted arrays. These special data types are indicated by inserting the symbol 0 (null-terminated) or # (byte counted) between the direction indicator (<, >, =) and the type (T or C) specification. For example, a pointer to a null-terminated input character string is coded as <0T[], and an output one coded as >0T[].

Note that while appending the array specifier ‘[]’ is formally correct, because the presence of the special qualifier (0 or #) implies an array, the ‘[]’ may be omitted: <0T, >0T, =#C, etc.

Note also that the 0 and # specifiers may be used with data of all types (excluding A and Z) and widths. For example, in the Classic Edition, <0U2 may be useful for dealing with Unicode.

Type

The data type of the argument may be one of the following characters and may be specified in lower or upper case:

 | Type | Description
I | Integer | The value is interpreted as a 2s complement signed integer
U | Unsigned integer | The value is interpreted as an unsigned integer
C | Character | The value is interpreted as a character. In the Unicode Edition, the value maps directly onto a Unicode code point. In the Classic Edition, the value is interpreted as an index into ⎕AV. This means that ⎕AV positions map onto corresponding ANSI positions. For example, with ⎕IO=0: ⎕AV[35] = 's', maps toANSI[35] = ’
 | Type | Description
T | Translated character | The value is interpreted as a character. In the Unicode Edition, the value maps directly onto a Unicode code point. In the Classic Edition, the value is translated using standard Dyalog ⎕AV to ANSI translation. This means that ⎕AVcharacters map onto corresponding ANSI characters. For example, with ⎕IO=0: ⎕AV[35] = 's', maps toANSI[115] = ’s’
F | Float | The value is interpreted as an IEEE 754-2008 binary64 floating point number
D | Decimal | The value is interpreted as an IEEE 754-2008 decimal128 floating point number (DPD format)
J | Complex |
P | uintptr-t | This is equivalent to U4 on 32-bit versions and U8 on 64-bit Versions
Z | APL array with header | This is the same format as is used to transmit APL arrays over TCP/IP Sockets

Width

The type specifier may be followed by the width of the value in bytes. For example:

I4 | 4-byte signed integer.
U2 | 2-byte unsigned integer.
F8 | 8-byte floating point number.
F4 | 4-byte floating point number.
D16 | 16-byte decimal floating-point number
Type | Possible values for Width | Default value for Width
I | 1, 2, 4, 8 | 4
U | 1, 2, 4, 8 | 4
C | 1,2,4 | 1
T | 1,2,4 | wide character(see below)
F | 4, 8 | 8
D | 16 | 16
J | 16 | 16
P | Not applicable |
A | Not applicable |
Z | Not applicable |

In the Unicode Edition, the default width is the width of a wide character according to the convention of the host operating system. This translates to T2 under Windows and T4 under UNIX or Linux.

Note that 32-bit versions can support 64-bit integer arguments, but not 64-bit integer results.

Examples

I2 | 16-bit integer
<I4 | Pointer to input 4-byte integer
U | Default width unsigned integer
=F4 | Pointer to input/output 4-byte floating point number.

Arrays

Arrays are specified by following the basic data type with [n] or [], where n indicates the number of elements in the array. In the C declaration, the number of elements in an array may be specified explicitly at compile time, or determined dynamically at runtime. In the latter case, the size of the array is often passed along with the array, in a separate argument. In this case, n, the number of elements is omitted from the specification. Note that C deals only in scalars and rank 1 (vector) arrays.

int vec[10];               // explicit vector length.
unsigned size, list[];     // undetermined length.

could be coded as:

I[10] | vector of 10 ints.
U U[] | unsigned integer followed by an array of unsigned integers.

Confusion sometimes arises over a difference in the declaration syntax between C and ⎕NA. In C, an argument declaration may be given to receive a pointer to either a single scalar item, or to the first element of an array. This is because in C, the address of an array is deemed to be the address of its first element.

   void foo (char *string);
   char ch = 'a', ptr = "abc";
   foo(&ch);// call with address of scalar.
   foo(ptr);// call with address of array.

However, from APL’s point of view, these two cases are distinct and if the function is to be called with the address of (pointer to) a scalar, it must be declared: '<T'. Otherwise, to be called with the address of an array, it must be declared: '<T[]'. Note that it is perfectly acceptable in such circumstances to define more than one name association to the same DLL function specifying different argument types:

      'FooScalar'⎕NA'mydll|foo <T'   ⋄ FooScalar'a'
      'FooVector'⎕NA'mydll|foo <T[]' ⋄ FooVector'abc'

Structures

Arbitrary data structures, which are akin to nested arrays, are specified using the symbols {}. For example, the code {F8 I2} indicates a structure comprised of an 8-byte float followed by a 2-byte int. Furthermore, the code <{F8 I2}[3] means an input pointer to an array of 3 such structures.

For example, this structure might be defined in C thus:

typedef struct
{
    double  f;
    short   i;
} mystruct;

A function defined to receive a count followed by an input pointer to an array of such structures:

void foo(unsigned count, mystruct *str);

An appropriate ⎕NA declaration would be:

      ⎕NA'mydll.foo U <{F8 I2}[]'

A call on the function with two arguments - a count followed by a vector of structures:

      foo 4,⊂(1.4 3)(5.9 1)(6.5 2)(0 0)

Notice that for the above call, APL converts the two Boolean (0 0) elements to an 8-byte float and a 2-byte int, respectively.

Specifying Pointers Explicitly

⎕NA syntax enables APL to pass arguments to DLL functions by value or address as appropriate. For example if a function requires an integer followed by a pointer to an integer:

void fun(int valu, int *addr);

You might declare and call it:

      ⎕NA'mydll|fun I <I' ⋄ fun 42 42

The interpreter passes the value of the first argument and the address of the second one.

Two common cases occur where it is necessary to pass a pointer explicitly. The first is if the DLL function requires a null pointer, and the second is where you want to pass on a pointer which itself is a result from a DLL function.

In both cases, the pointer argument should be coded as P. This causes APL to pass the pointer unchanged, by value, to the DLL function.

In the previous example, to pass a null pointer, (or one returned from another DLL function), you must code a separate ⎕NA definition.

      'fun_null'⎕NA'mydll|fun I P' ⋄ fun_null 42 0

Now APL passes the value of the second argument (in this case 0 - the null pointer), rather than its address.

Note that by using P, which is 4-byte for 32-bit processes and 8-byte for 64-bit processes, you will ensure that the code will run unchanged under both 32-bit and 64-bit Versions of Dyalog APL.

Using a Function

A DLL function may or may not return a result, and may take zero or more arguments. This syntax is reflected in the coding of the right argument of ⎕NA. Notice that the corresponding associated APL function is niladic or monadic (never dyadic), and that it always returns a vector result - a null one if there is no output from the function. See Result Vector section below. Examples of the various combinations are:

DLL function Non-result-returning:

⎕NA    'mydll|fn1'          ⍝ Niladic
⎕NA    'mydll|fn2 <0T'      ⍝ Monadic - 1-element arg
⎕NA    'mydll|fn3 =0T <0T'  ⍝ Monadic - 2-element arg

DLL function Result-returning:

⎕NA 'I4 mydll|fn4'          ⍝ Niladic
⎕NA 'I4 mydll|fn5 F8'       ⍝ Monadic - 1-element arg
⎕NA 'I4 mydll|fn6 >I4[] <0T'⍝ Monadic - 2-element arg

When the external function is called, the number of elements in the argument must match the number defined in the ⎕NA definition. Using the example functions defined above:

      fn1                   ⍝ Niladic Function.
      fn2, ⊂'Single String' ⍝ 1-element arg
      fn3 'This' 'That'     ⍝ 2-element arg

Note in the second example, that you must enclose the argument string to produce a single item (nested) array in order to match the declaration. Dyalog converts the type of a numeric argument if necessary, so for example in fn5 defined above, a Boolean value would be converted to double floating point (F8) prior to being passed to the DLL function.

Pointer Arguments

When passing pointer arguments there are three cases to consider.

< Input pointer:

In this case you must supply the data array itself as argument to the function. A pointer to its first element is then passed to the DLL function.

      fn2 ⊂'hello'

> Output pointer:

Here, you must supply the number of elements that the output will need in order for APL to allocate memory to accommodate the resulting array.

      fn6 10 'world'  ⍝ 1st arg needs space for 10 ints.

Note that if you were to reserve fewer elements than the DLL function actually used, the DLL function would write beyond the end of the reserved array and may cause the interpreter to crash with a System Error (syserr 999 on Windows or SIGSEGV on Unix).

= Input/Output:

As with the input-only case, a pointer to the first element of the argument is passed to the DLL function. The DLL function then overwrites some or all of the elements of the array, and the new value is passed back as part of the result of the call. As with the output pointer case, if the input array were too short, so that the DLL wrote beyond the end of the array, the interpreter would almost certainly crash.

      fn3 '.....' 'hello'

Result Vector

In APL, a function cannot overwrite its arguments. This means that any output from a DLL function must be returned as part of the explicit result, and this includes output via ‘output’ or ‘input/output’ pointer arguments.

The general form of the result from calling a DLL function is a nested vector. The first item of the result is the defined explicit result of the external function, and subsequent items are implicit results from output, or input/output pointer arguments.

The length of the result vector is therefore: 1 (if the function was declared to return an explicit result) + the number of output or input/output arguments.

⎕NA Declaration | Result | Output Arguments | Result Length
mydll|fn1 | 0 |  | 0
mydll|fn2 <0T | 0 | 0 | 0
mydll|fn3 =0T <0T | 0 | 1 0 | 1
I4 mydll|fn4 | 1 |  | 1
I4 mydll|fn5 F8 | 1 | 0 | 1
I4 mydll|fn6 >I4[] <0T | 1 | 1 0 | 2

As a convenience, if the result would otherwise be a 1-item vector, it is disclosed. Using the third example above:

      ⍴fn3 '.....' 'abc'
5

fn3 has no explicit result; its first argument is input/output pointer; and its second argument is input pointer. Therefore as the length of the result would be 1, it has been disclosed.

ANSI /Unicode Versions of Library Calls

Under Windows, most library functions that take character arguments, or return character results have two forms: one Unicode (Wide) and one ANSI. For example, a function such as MessageBox(), has two forms MessageBoxA() and MessageBoxW(). The A stands for ANSI (1-byte) characters, and the W for wide (2-byte Unicode) characters.

It is essential that you associate the form of the library function that is appropriate for the Dyalog Edition you are using, i.e. MessageBoxA() for the Classic Edition, but MessageBoxW() for the Unicode Edition.

To simplify writing portable code for both Editions, you may specify the character * instead of A or W at the end of a function name. This will be replaced by A in the Classic Edition and W in the Unicode Edition.

The default name of the associated function (if no left argument is given to ⎕NA), will be without the trailing letter (MessageBox).

Type Definitions (typedefs)

The C language encourages the assignment of defined names to primitive and complex data types using its #define and typedef mechanisms. Using such abstractions enables the C programmer to write code that will be portable across many operating systems and hardware platforms.

Windows software uses many such names and Microsoft documentation will normally refer to the type of function arguments using defined names such as HANDLE or LPSTR rather than their equivalent C primitive types: int or char*.

It is beyond the scope of this manual to list all the Microsoft definitions and their C primitive equivalents, and indeed, DLLs from sources other than Microsoft may well employ their own distinct naming conventions.

In general, you should consult the documentation that accompanies the DLL in order to convert typedefs to primitive C types and thence to ⎕NA declarations. The documentation may well refer you to the ‘include’ files which are part of the Software Development Kit, and in which the types are defined.

The following table of some commonly encountered Windows typedefs and their ⎕NA equivalents might prove useful.

Windows typedef | ⎕NA equivalent
HWND | P
HANDLE | P
GLOBALHANDLE | P
LOCALHANDLE | P
DWORD | U4
WORD | U2
BYTE | U1
LPSTR | =0T[] (note 1)
LPCSTR | <0T[] (note 2)
WPARAM | U (note 3)
LPARAM | U4 (note 3)
LRESULT | I4
BOOL | I
UINT | U
ULONG | U4
ATOM | U2
HDC | P
HBITMAP | P
HBRUSH | P
HFONT | P
HICON | P
HMENU | P
HPALETTE | P
HMETAFILE | P
HMODULE | P
HINSTANCE | P
COLORREF | {U1[4]}
POINT | {I I}
POINTS | {I2 I2}
RECT | {I I I I}
CHAR | T or C

Notes

  1. LPSTR is a pointer to a null-terminated string. The definition does not indicate whether this is input or output, so the safest coding would be =0T[] (providing the vector you supply for input is long enough to accommodate the result). You may be able to improve simplicity or performance if the documentation indicates that the pointer is ‘input only’ (<0T[]) or ‘output only’ (>0T[]). See Direction above.
  2. LPCSTR is a pointer to a constant null-terminated string and therefore coding <0T[] is safe.
  3. WPARAM is an unsigned value, LPARAM is signed. They are 32 bit values in a 32-bit APL, and 64-bit in a 64 bit APL. You should consult the documentation for the specific function that you intend to call to determine what type they represent
  4. The use of type T with default width ensures portability of code between Classic and Unicode Editions. In the Classic Edition, T (with no width specifier) implies 1-byte characters which are translated between ⎕AV and ASCII, while In the Unicode Edition, T (with no width specifier) implies 2-byte (Unicode) characters.

Dyalog32.dll or Dyalog64.dll

Included with Dyalog APL are utility DLLs called dyalog32.dll and dyalog64.dll. These DLLs contain three functions: MEMCPY, STRNCPY and SRTLEN.

MEMCPY

MEMCPY is an extremely versatile function used for moving arbitrary data between memory buffers.

Its C definition is:

void *MEMCPY(       // copy memory
      void *to,     // target address
      void *fm,     // source address
      size_t size   // number of bytes to copy
      );

MEMCPY copies size bytes starting from source address fm, to destination address to. The source and destination areas should not overlap; if they do the behaviour is undefined and the result is the first argument.

MEMCPY’s versatility stems from being able to associate to it using many different type declarations.

Example

Suppose a global buffer (at address: addr) contains (numb) double floating point numbers. To copy these to an APL array, we could define the association:

      'doubles' ⎕NA 'dyalog32|MEMCPY >F8[] I4 U4'
      doubles numb addr (numb×8)

Notice that:

  • As the first argument to doubles is an output argument, we must supply the number of elements to reserve for the output data.
  • MEMCPY is defined to take the number of bytes to copy, so we must multiply the number of elements by the element size in bytes.

Example

Suppose that a database application requires that we construct a record in global memory prior to writing it to file. The record structure might look like this:

typedef struct {
        int empno;// employee number.
        float salary;// salary.
        char name[20];// name.
        } person;

Then, having previously allocated memory (addr) to receive the record, we can define:

      'prec' ⎕NA 'dyalog32|MEMCPY I4 <{P F4 T[20]} U4'
      prec addr(99 12345.60 'Charlie Brown')(4+4+20)

STRNCPY

STRNCPY is used to copy null-terminated strings between memory buffers.

Its C definition is:

void *STRNCPY(// copy null-terminated string
        char *to,// target address
        char *fm,// source address
        size_t size// MAX number of chars to copy
        );

STRNCPY copies a maximum of size characters from the null-terminated source string at address fm, to the destination address to. If the source and destination strings overlap, the result is the first argument.

If the source string is shorter than size, null characters are appended to the destination string.

If the source string (including its terminating null) is longer than size, only size characters are copied and the resulting destination string is not null-terminated

Example

Suppose that a database application returns a pointer (addr) to a structure that contains two pointers to (max 20-char) null-terminated strings.

typedef struct {  // null-terminated strings:
        char *first;  // first name (max 19 chars + 1 null).
        char *last;  // last name. (max 19 chars + 1 null).
        } name;

To copy the names from the structure:

      'get'⎕NA'dyalog32|STRNCPY >0T[] P U4'
      get 20 addr 20
Charlie
      get 20 (addr+4) 20
Brown

Note that on a 64-bit Version, ⎕FR will need to be 1287 for the addition to be reliable.

To copy data from the workspace into an already allocated (new) structure:

      'put'⎕NA'dyalog32|STRNCPY I4 <0T[] U4'
      put new 'Bo' 20
      put (new+4) 'Peep' 20

Notice in this example that you must ensure that names no longer than 19 characters are passed to put. More than 19 characters would not leave STRNCPY enough space to include the trailing null, which would probably cause the application to fail.

STRLEN

STRLEN calculates the length of a C string (a 0-terminated string of bytes in memory). Its C declaration is:

size_t STRLEN(         // calculate length of string
        const char *s    // address of string
        );

Example

Suppose that a database application returns a pointer (addr) to a null-terminated string and you do not know the upper bound on the length of the string.

To copy the string into the workspace:

      'len' ⎕NA'P dyalog32|STRLEN P'
      'cpy'⎕NA'dyalog32|MEMCPY >T[] P P'
      cpy l addr (l←len addr)
Bartholemew

Examples

The following examples all use functions from the Microsoft Windows user32.dll.

This DLL should be located in a standard Windows directory, so you should not normally need to give the full path name of the library. However if trying these examples results in the error message ‘FILE ERROR 1 No such file or directory’, you must locate the DLL and supply the full path name (and possibly extension).

Example 1

The Windows function "GetCaretBlinkTime" retrieves the caret blink rate. It takes no arguments and returns an unsigned int and is declared as follows:

UINT GetCaretBlinkTime(void);

The following statements would provide access to this routine through an APL function of the same name.

      ⎕NA 'U user32|GetCaretBlinkTime'
      GetCaretBlinkTime
530

The following statement would achieve the same thing, but using an APL function called BLINK.

      'BLINK' ⎕NA 'U user32|GetCaretBlinkTime'
      BLINK
530

Example 2

The Windows function "SetCaretBlinkTime" sets the caret blink rate. It takes a single unsigned int argument, does not return a result and is declared as follows:

void SetCaretBlinkTime(UINT);

The following statements would provide access to this routine through an APL function of the same name:

      ⎕NA 'user32|SetCaretBlinkTime U'
      SetCaretBlinkTime 1000

Example 3

The Windows function "MessageBox" displays a standard dialog box on the screen and awaits a response from the user. It takes 4 arguments. The first is the window handle for the window that owns the message box. This is declared as an unsigned int. The second and third arguments are both pointers to null-terminated strings containing the message to be displayed in the Message Box and the caption to be used in the window title bar. The 4th argument is an unsigned int that specifies the Message Box type. The result is an int which indicates which of the buttons in the message box the user has pressed. The function is declared as follows:

int MessageBox(HWND, LPCSTR, LPCSTR, UINT);

The following statements provide access to this routine through an APL function of the same name. Note that the 2nd and 3rd arguments are both coded as input pointers to type T null-terminated character arrays which ensures portability between Editions.

      ⎕NA 'I user32|MessageBox* P <0T <0T U'

The following statement displays a Message Box with a stop sign icon together with 2 push buttons labelled OK and Cancel (this is specified by the value 19).

      MessageBox 0 'Message' 'Title' 19

The function works equally well in the Unicode Edition because the <0T specification is portable.

      MessageBox 0 'Το Μήνυμα' 'Ο Τίτλος' 19

Note that a simpler, portable (and safer) method for displaying a Message Box is to use Dyalog APL’s primitive MsgBox object.

Example 4

The Windows function "FindWindow" obtains the window handle of a window which has a given character string in its title bar. The function takes two arguments. The first is a pointer to a null-terminated character string that specifies the window's class name. However, if you are not interested in the class name, this argument should be a NULL pointer. The second is a pointer to a character string that specifies the title that identifies the window in question. This is an example of a case described above where two instances of the function must be defined to cater for the two different types of argument. However, in practice this function is most often used without specifying the class name. The function is declared as follows:

HWND FindWindow(LPCSTR, LPCSTR);

The following statement associates the APL function FW with the second variant of the FindWindow call, where the class name is specified as a NULL pointer. To indicate that APL is to pass the value of the NULL pointer, rather than its address, we need to code this argument as I4.

      'FW' ⎕NA 'P user32|FindWindow* I4 <0T'

To obtain the handle of the window entitled "CLEAR WS - Dyalog APL/W":

      ⎕←HNDL←FW 0 'CLEAR WS - Dyalog APL/W'
59245156

Example 5

The Windows function "GetWindowText" retrieves the caption displayed in a window's title bar. It takes 3 arguments. The first is an unsigned int containing the window handle. The second is a pointer to a buffer to receive the caption as a null-terminated character string. This is an example of an output array. The third argument is an int which specifies the maximum number of characters to be copied into the output buffer. The function returns an int containing the actual number of characters copied into the buffer and is declared as follows:

int GetWindowText(HWND, LPSTR, int);

The following associates the "GetWindowText" DLL function with an APL function of the same name. Note that the second argument is coded as ">0T" indicating that it is a pointer to a character output array.

      ⎕NA 'I user32|GetWindowText* P >0T I'

Now change the Session caption using )WSID :

      )WSID MYWS
was CLEAR WS

Then retrieve the new caption (max length 255) using window handle HNDL from the previous example:

      ]display GetWindowText HNDL 255 255
.→-------------------------.
|    .→------------------. |
| 19 |MYWS - Dyalog APL/W| |
|    '-------------------' |
'∊-------------------------'

There are three points to note. Firstly, the number 255 is supplied as the second argument. This instructs APL to allocate a buffer large enough for a 255-element character vector into which the DLL routine will write. Secondly, the result of the APL function is a nested vector of 2 elements. The first element is the result of the DLL function. The second element is the output character array.

Finally, notice that although we reserved space for 255 elements, the result reflects the length of the actual text (19).

An alternative way of coding and using this function is to treat the second argument as an input/output array.

e.g.

      ⎕NA 'I User32|GetWindowText* P =0T I'

      ]display GetWindowText HNDL (255⍴' ') 255
.→-------------------------.
|    .→------------------. |
| 19 |MYWS - Dyalog APL/W| |
|    '-------------------' |
'∊-------------------------'

In this case, the second argument is coded as =0T, so when the function is called an array of the appropriate size must be supplied. This method uses more space in the workspace, although for small arrays (as in this case) the real impact of doing so is negligible.

Example 6

The function "GetCharWidth" returns the width of each character in a given range Its first argument is a device context (handle). Its second and third arguments specify font positions (start and end). The third argument is the resulting integer vector that contains the character widths (this is an example of an output array). The function returns a Boolean value to indicate success or failure. The function is defined as follows. Note that this function is provided in the library: gdi32.dll.

BOOL GetCharWidth(HDC, UINT, UINT, int FAR*);

The following statements provide access to this routine through an APL function of the same name:

      ⎕NA 'U4 gdi32|GetCharWidth* P U U >I[]'

     'P'⎕WC'Printer'

      ]display GetCharWidth ('P' ⎕WG 'Handle') 65 67 3
.→-------------.
|   .→-------. |
| 1 |50 50 50| |
|   '~-------' |
'∊-------------'

Note: 'P'⎕WG'Handle' returns a handle This is represented as a number. The number will be in the range (0 - 2*32] on a 32-bit Version and (0 - 2*64] on a 64-bit Version. These can be passed to a P type parameter. Older Versions used a 32-bit signed integer.

Example 7

The following example from the supplied workspace: QUADNA.DWS illustrates several techniques which are important in advanced ⎕NA programming. Function DllVersion returns the major and minor version number for a given DLL. Note that this example assumes that the computer is running the 64-bit version of Dyalog.

In advanced DLL programming, it is often necessary to administer memory outside APL’s workspace. In general, the procedure for such use is:

  1. Allocate global memory.
  2. Lock the memory.
  3. Copy any DLL input information from workspace into memory.
  4. Call the DLL function.
  5. Copy any DLL output information from memory to workspace.
  6. Unlock the memory.
  7. Free the memory.

Notice that steps 1 and 7 and steps 2 and 6 complement each other. That is, if you allocate global system memory, you must free it after you have finished using it. If you continue to use global memory without freeing it, your system will gradually run out of resources. Similarly, if you lock memory (which you must do before using it), then you should unlock it before freeing it. Although on some versions of Windows, freeing the memory will include unlocking it, in the interests of good style, maintaining the symmetry is probably a good thing.

    ∇ version←DllVersion file;Alloc;Free;Lock;Unlock;Size
                  ;Info;Value;Copy;size;hndl;addr;buff;ok
[1]
[2]  'Alloc'⎕NA'P kernel32|GlobalAlloc U4 U4'
[3]   'Free'⎕NA'P kernel32|GlobalFree P'
[4]   'Lock'⎕NA'P kernel32|GlobalLock P'
[5] 'Unlock'⎕NA'U4 kernel32|GlobalUnlock P'
[6]
[7]  'Size'⎕NA'U4 version|GetFileVersionInfoSize* <0T >U4'
[8]  'Info'⎕NA'U4 version|GetFileVersionInfo*<0T U4 U4 P'
[9] 'Value'⎕NA'U4 version|VerQueryValue* P <0T >P >U4'
[10]
[11] 'Copy'⎕NA'dyalog64|MEMCPY >U4[] P P'
[12]
[13]  :If ×size←⊃Size file 0               ⍝ Size of info
[14]  :AndIf ×hndl←Alloc 0 size            ⍝ Alloc memory
[15]    :If ×addr←Lock hndl                ⍝ Lock memory
[16]      :If ×Info file 0 size addr       ⍝ Version info
[17]        ok buff size←Value addr'\' 0 0 ⍝ Version value
[18]        :If ok
[19]          buff←Copy(size÷4)buff size   ⍝ Copy info
[20]          version←(2/2*16)⊤⊃2↓buff     ⍝ Split version
[21]        :EndIf
[22]      :EndIf
[23]      ok←Unlock hndl                   ⍝ Unlock memory
[24]    :EndIf
[25]    ok←Free hndl                       ⍝ Free memory
[26]  :EndIf
    ∇

Lines [2-11] associate APL function names with the DLL functions that will be used.

Lines [2-5] associate functions to administer global memory.

Lines [7-9] associate functions to extract version information from a DLL.

Line[11] associates Copy with MEMCPY function from dyalog64.dll.

Lines [13-26] call the DLL functions.

Line [13] requests the size of buffer required to receive version information for the DLL. A size of 0 will be returned if the DLL does not contain version information.

Notice that care is taken to balance memory allocation and release:

On line [14], the :If clause is taken only if the global memory allocation is successful, in which case (and only then) a corresponding Free is called on line [25].

Unlock on line[23] is called if and only if the call to Lock on line [15] succeeds.

A result is returned from the function only if all the calls are successful Otherwise, the calling environment will sustain a VALUE ERROR.

More Examples

⎕NA'I4 advapi32 |RegCloseKey          P'
⎕NA'I4 advapi32 |RegCreateKeyEx*      P <0T U4 <0T U4 U4 P >P >U4'
⎕NA'I4 advapi32 |RegEnumValue*        P U4 >0T =U4 =U4 >U4 >0T =U4'
⎕NA'I4 advapi32 |RegOpenKey*          P <0T >P'
⎕NA'I4 advapi32 |RegOpenKeyEx*        P <0T U4 U4 >P'
⎕NA'I4 advapi32 |RegQueryValueEx*     P <0T =U4 >U4 >0T =U4'
⎕NA'I4 advapi32 |RegSetValueEx*       P <0T =U4 U4 <0T U4'
⎕NA'P  dyalog32 |STRNCPY              P P P'
⎕NA'P  dyalog32 |STRNCPYA             P P P'
⎕NA'P  dyalog32 |STRNCPYW             P P P'
⎕NA'P  dyalog32 |MEMCPY               P P P'
⎕NA'I4 gdi32    |AddFontResource*     <0T'
⎕NA'I4 gdi32    |BitBlt               P I4 I4 I4 I4 P I4 I4 U4'
⎕NA'U4 gdi32    |GetPixel             P I4 I4'
⎕NA'P  gdi32    |GetStockObject       I4'
⎕NA'I4 gdi32    |RemoveFontResource*  <0T'
⎕NA'U4 gdi32    |SetPixel             P I4 I4 U4'
⎕NA'   glu32    |gluPerspective       F8 F8 F8 F8'
⎕NA'I4 kernel32 |CopyFile*            <0T <0T I4'
⎕NA'P  kernel32 |GetEnvironmentStrings'
⎕NA'U4 kernel32 |GetLastError'
⎕NA'U4 kernel32 |GetTempPath*         U4 >0T'
⎕NA'P  kernel32 |GetProcessHeap'
⎕NA'I4 kernel32 |GlobalMemoryStatusEx ={U4 U4 U8 U8 U8 U8 U8 U8}'
⎕NA'P  kernel32 |HeapAlloc            P U4 P'
⎕NA'I4 kernel32 |HeapFree             P U4 P'
⎕NA'   opengl32 |glClearColor         F4 F4 F4 F4'
⎕NA'   opengl32 |glClearDepth         F8'
⎕NA'   opengl32 |glEnable             U4'
⎕NA'   opengl32 |glMatrixMode         U4'
⎕NA'I4 user32   |ClientToScreen       P ={I4 I4}'
⎕NA'P  user32   |FindWindow*          <0T <0T'
⎕NA'I4 user32   |ShowWindow           P I4'
⎕NA'I2 user32   |GetAsyncKeyState     I4'
⎕NA'P  user32   |GetDC                P'
⎕NA'I4 User32   |GetDialogBaseUnits'
⎕NA'P  user32   |GetFocus'
⎕NA'U4 user32   |GetSysColor          I4'
⎕NA'I4 user32   |GetSystemMetrics     I4'
⎕NA'I4 user2    |InvalidateRgn        P P I4'
⎕NA'I4 user32   |MessageBox*          P <0T <0T U4'
⎕NA'I4 user32   |ReleaseDC            P P'
⎕NA'P  user32   |SendMessage*         P U4 P P'
⎕NA'P  user32   |SetFocus             P'
⎕NA'I4 user32   |WinHelp*             P <0T U4 P'
⎕NA'I4 winnm    |sndPlaySound         <0T U4'


UNIX Command

UNIX Shell ⎕SH

Monadic ⎕SH means

Execute UNIX Command

       ⎕SH'ls'
FILES WS temp

Dyadic ⎕SH means

Start UNIX Auxiliary Processor

      )CLEAR
clear ws
      'xutils' ⎕SH ''
      )fns
avx     box     dbr     getenv  hex     ltom    ltov    mtol    ss      vtol

Language Elements


Start UNIX Auxiliary Processor

Start UNIX Auxiliary Processor: X ⎕SH Y

Used dyadically, ⎕SH starts an Auxiliary Processor. The effect, as far as the APL user is concerned, is identical under both Windows and UNIX although there are differences in the method of implementation. ⎕SH is a synonym of ⎕CMD. Either function may be used in either environment (UNIX or Windows) with exactly the same effect. ⎕SH is probably more natural for the UNIX user. This section describes the behaviour of ⎕SH and ⎕CMD under UNIX. See Start Windows Auxiliary Processor: for a discussion of the behaviour of these system functions under Windows.

X must be a simple character vector. Y may be a simple character scalar or vector, or a nested character vector.

⎕SH loads the Auxiliary Processor from the file named by X using a search-path defined by the environment variable WSPATH.

The effect of starting an AP is that one or more external functions are defined in the workspace. These appear as locked functions and may be used in exactly the same way as regular defined functions.

When an external function is used in an expression, the argument(s) (if any) are piped to the AP for processing. If the function returns a result, APL halts while the AP is processing and waits for the result. If not it continues processing in parallel.

The syntax of dyadic ⎕SH is similar to the UNIX execl(2) system call, where 'taskname' is the name of the auxiliary processor to be executed and arg0 through argn are the parameters of the calling line to be passed to the task, viz.

      'taskname' ⎕SH 'arg0' 'arg1' ... 'argn'

See User Guide for further information.

Examples

      'xutils' ⎕SH 'xutils' 'ss' 'dbr'

      '/bin/sh' ⎕SH 'sh' '-c' 'adb test'


Execute UNIX Command

Execute (UNIX) Command: {R}←⎕SH Y

⎕SH executes a UNIX shell or a Windows Command Processor. ⎕SH is a synonym of ⎕CMD. Either function may be used in either environment (UNIX or Windows) with exactly the same effect. ⎕SH is probably more natural for the UNIX user. This section describes the behaviour of ⎕SH and ⎕CMD under UNIX. See Execute Windows Command: for a discussion of the behaviour of these system functions under Windows.

Y must be a simple character scalar or vector representing a UNIX shell command. R is a nested vector of character vectors.

Y may be any acceptable UNIX command. It could cause another process to be entered, such as sed or vi. If the command does not return a result, R is ⊂'' but the result is suppressed if not explicitly used or assigned. If the command has a non-zero exit code, then APL will signal a DOMAIN ERROR. If the command returns a result and has a zero exit code, then each element of R will be a line from the standard output (stdout) of the command. Output from standard error (stderr) is not captured unless redirected to stdout.

Examples

      ⎕SH'ls'
FILES WS temp

      ⎕SH 'rm WS/TEST'

      ⎕SH 'grep bin /etc/passwd ; exit 0'
bin:!:2:2::/bin:

      ⎕SH 'apl MYWS <inputfile >out1 2>out2 &'


Time Stamp

Time Stamp: R←⎕TS

This is a seven element vector which identifies the clock time set on the particular installation as follows:

⎕TS[1] | Year
⎕TS[2] | Month
⎕TS[3] | Day
⎕TS[4] | Hour
⎕TS[5] | Minute
⎕TS[6] | Second
⎕TS[7] | Millisecond

Example

      ⎕TS
1989 7 11 10 42 59 123

Note that on some systems, where time is maintained only to the nearest second, a zero is returned for the seventh (millisecond) field.


Sign Off APL

Sign Off APL: ⎕OFF

This niladic system function terminates the APL session, returning to the shell command level. The active workspace does not replace the last continuation workspace.

Although ⎕OFF is niladic, you may specify an optional integer I to the right of the system function which will be reported to the Operating System as the exit code. If I is an expression generating an integer, you should put the expression in parentheses. I must be in the range 0..255, but note that on UNIX processes use values greater than 127 to indicate the signal number which was used to terminate a process, and that currently APL itself generates values 0..8; this list may be extended in future.


Search

Search: R←{X}(A ⎕S B) Y

See Replace: .


Replace

Replace: R←{X}(A ⎕R B) Y

⎕R (Replace) and ⎕S (Search) are system operators which take search pattern(s) as their left arguments and transformation rule(s) as their right arguments; the derived function operates on text data to perform either a search, or a search and replace operation.

The search patterns may include Regular Expressions so that complex searches may be performed. ⎕R and ⎕S utilise the open-source regular-expression search engine PCRE, which is built into Dyalog APL and distributed according to the PCRE license which is published separately.

The transformation rules are applied to the text which matches the search patterns; they may be given as a simple character vector, numeric codes, or a function.

The two system operators, ⎕R for replace and ⎕S for search, are syntactically identical. With ⎕R, the input document is examined; text which matches the search pattern is amended and the remainder is left unchanged. With ⎕S, each match in the input document results in an item in the result whose type is dependent on the transformation specified.The operators use the Variant operator to set options.

A specifies one or more search patterns, being given as a single character, a character vector, a vector of character vectors or a vector of both characters and character vectors. See ‘search pattern’ following.

B is the transformation to be performed on matches within the input document; it may be either one or more transformation patterns (specified as a character, a character vector, a vector of character vectors, or a vector of both characters and character vectors), one or more transformation codes (specified as a numeric scalar or a numeric vector) or a function; see ‘transformation pattern’, ‘transformation codes’ and ‘transformation function’ following.

Y specifies the input document; see ‘input document’ below.

X optionally specifies an output stream; see ‘output’ below.

R is the result value; see ‘output’ below.

Examples of replace operations

      ('.at' ⎕R '\u0') 'The cat sat on the mat'
The CAT SAT on the MAT

In the search pattern the dot matches any character, so the pattern as a whole matches sequences of three characters ending ‘at’. The transformation is given as a character string, and causes the entire matching text to be folded to upper case.

      ('\w+' ⎕R {⌽⍵.Match}) 'The cat sat on the mat'
ehT tac tas no eht tam

The search pattern matches each word. The transformation is given as a function, which receives a namespace containing various variables describing the match, and it returns the match in reverse, which in turn replaces the matched text.

Examples of search operations

      STR←'The cat sat on the mat'
      ('.at' ⎕S '\u0') STR
CAT  SAT  MAT

The example is identical to the first, above, except that after the transformation is applied to the matches the results are returned in a vector, not substituted into the source text.

      ('.at' ⎕S {⍵.((1↑Offsets),1↑Lengths)}) STR
4 3  8 3  19 3

When searching, the result vector need not contain only text and in this example the function returns the numeric position and length of the match given to it; the resultant vector contains these values for each of the three matches.

      ('.at' ⎕S 0 1) STR
4 3  8 3  19 3

Here the transformation is given as a vector of numeric codes which are a short-hand for the position and length of each match; the overall result is therefore identical to the previous example.

These examples all operate on a simple character vector containing text, but the text may be given in several forms - character vectors, vectors of character vectors, and external data streams. These various forms constitute a ‘document’. When the result also takes the form of a document it may be directed to a stream.

Input Document

The input document may be an array or a data stream.

When it is an array it may be given in one of two forms:

  1. A character scalar or vector
  2. A vector of character vectors

Currently, the only supported data stream is a native file, specified as tie number, which is read from the current position to the end. If the file is read from the start, and there is a valid Byte Order Mark (BOM) at the start of it, the data encoding is determined by this BOM. Otherwise, data in the file is assumed to be encoded as specified by the InEnc option.

Hint: once a native file has been read to the end by ⎕R or ⎕S it is possible to reset the file position to the start so that it may be read again using:

      {} ⎕NREAD tienum 82 0 0

The input document is comprised of lines of text. Line breaks may be included in the data:

Implicitly

  • Between each item in the outer vector (type 2, above)

Explicitly, as

  • carriage return
  • line feed
  • carriage return and line feed together, in that order
  • vertical tab (U+000B)
  • newline (U+0085)
  • form Feed (U+000C)
  • line Separator (U+2028)
  • paragraph Separator (U+2029)

The implicit line ending character may be set using the EOL option. Explicit line ending characters may also be replaced by this character - so that all line endings are normalised - using the NEOL option.

The input document may be processed in line mode, document mode or mixed mode. In document mode and mixed mode, the entire input document, line ending characters included, is passed to the search engine; in line mode the document is split on line endings and passed to the search engine in sections without the line ending characters. The choice of mode affects both memory usage and behaviour, as documented in the section ‘Line, document and mixed modes’.

Output

The format of the output is dependent on whether ⎕S or ⎕R are in use, whether an output stream is specified and, for ⎕R, the form of the input and whether the ResultText option is specified.

An output data stream may optionally be specified. Currently, the only supported data stream is a native file, specified as tie number, and all output will be appended to it. Data in the stream is encoded as specified by the OutEnc option. If this encoding specifies a Byte Order Mark and the file is initially empty then the Byte Order Mark will be written at the start. Appending to existing data using a different encoding is permitted but unlikely to produce desirable results. If an input stream is also used, care must be taken to ensure the input and output streams are not the same.

⎕R

With no output stream specified and unless overridden by the ResultText option, the derived function result will be a document which closely matches the format of the input document, as follows:

A character scalar or vector input will result in a character vector output. Any and all line endings in the output will be represented by line ending characters within the character vector.

A vector of character vectors as input will result in a vector of character vectors as document output. Any and all line endings in the output document will be implied at the end of each character vector.

A stream as input will result in a vector of character vectors document output. Any and all line endings in the output document will be implied at the end of each character vector.

Note that the shape of the output document may be significantly different to that of the input document.

If the ResultText option is specified, the output type may be forced to be a character vector or vector of character vectors as described above, regardless of the input document.

With an output stream specified there is no result - instead the text is appended to the stream. If the appended text does not end with a line ending character then the line ending character specified by the EOL option is also appended.

⎕S

With no output stream specified, the result will be a vector containing one item for each match in the input document, of types determined by the transformation performed on each match.

With an output stream specified there is no result - instead each match is appended to the stream. If any match does not end with a line ending character then the line ending character specified by the EOL option is also appended. Only text may be written to the stream, which means:

  • When a transformation function is used, the function may only generate a character vector result.
  • Transformation codes may not be used.

Search pattern

A summary of the syntax of the search pattern is reproduced from the PCRE documentation verbatim in Appendix A herein. A full description is provided in the topic PCRE Regular Expression Details in the HTML and on-line help for Dyalog APL, and in Appendix A to the Version 13.0 Release Notes..

There may be multiple search patterns. If more than one search pattern is specified and more than one pattern matches the same part of the input document then priority is given to the pattern specified first.

Transformation pattern

For each match in the input document, the transformation pattern causes the creation of text which, for ⎕R, replaces the matching text and, for ⎕S, generates one item in the result.

There may be either one transformation pattern, or the same number of transformation patterns as search patterns. If there are multiple search patterns and multiple transformation patterns then the transformation pattern used corresponds to the search pattern which matched the input text.

Transformation patterns may not be mixed with transformation codes or functions.

The following characters have special meaning:

% | acts as a placeholder for the entire line (line mode) or document (document mode or mixed mode) which contained the match
& | acts as a placeholder for the entire portion of text which matched
\n | represents a line feed character
\r | represents a carriage return
\0 | equivalent to &
\n | acts as a placeholder for the text which matched the first to ninth subpattern; n may be any single digit value from 1 to 9
\(n) | acts as a placeholder for the text which matched the numbered subpattern; n may have an integer value from 0 to 63.
\<name> | acts as a placeholder for the text which matched the named subpattern
\\ | represents the backslash character
\% | represents the percent character
\& | represents the ampersand character

The above may be qualified to fold matching text to upper- or lower-case by using the u and l modifiers respectively. Character sequences beginning with the backslash place the modifier after the backslash; character sequences with no leading backslash add both a backslash and the modifier to the start of the sequence, for example:

\u& | acts as a placeholder for the entire portion of text which matched, folded to upper case
\l0 | equivalent to \l&

Character sequences beginning with the backslash other that those shown are invalid. All characters other than those shown are literal values and are included in the text without modification.

Transformation codes

The transformation codes are a numeric scalar or vector. For each match in the input document, a numeric scalar or vector of the same shape as the transformation codes is created, with the codes replaced with values as follows:

0 | The offset from the start of the line (line mode) or document (document mode or mixed mode) of the start of the match, origin zero.
1 | The length of the match.
2 | In line mode, the block number in the source document of the start of the match. The value is origin zero. In document mode or mixed mode this value is always zero.
3 | The pattern number which matched the input document, origin zero. Transformation codes may only be used with ⎕S

.

Transformation Function

The transformation function is called for each match within the input document. The function is monadic and is passed a namespace, containing the following variables:

Block | The entire line (line mode) or document (document mode or mixed mode) in which the match was found.
BlockNum | With line mode, the block (line) number in the source document of the start of the match. The value is origin zero. With document mode or mixed mode the entire document is contained within one block and this value is always zero.
Pattern | The search pattern which matched.
PatternNum | The index-zero pattern number which matched.
Match | The text within Block which matched Pattern.
Offsets | A vector of one or more index-zero offsets relative to the start of Block. The first value is the offset of the entire match; any and all additional values are the offsets of the portions of the text which matched the subpatterns, in the order of the subpatterns within Pattern.
Lengths | A vector of one or more lengths, corresponding to each value in Offset.
Names | A vector of one or more character vectors corresponding to each of the values in Offsets, specifying the names given to the subpatterns within Pattern. The first entry (corresponding to the match) and all subpatterns with no name are included as length zero character vectors.
ReplaceMode | A Boolean indicating whether the function was called by ⎕R (value 1) or ⎕S (value 0).
TextOnly | A Boolean indicating whether the return value from the function must be a character vector (value 1) or any value (value 0).

The return value from the function is used as follows:

With ⎕R the function must return a character vector. The contents of this vector are used to replace the matching text.

With ⎕S the function may return no value. If it does return a value:

  • When output is being directed to a stream it must be a character vector.
  • Otherwise, it may be any value. The overall result of the derived function is the catenation of the enclosure of each returned value into a single vector.

The passed namespace exists over the lifetime of ⎕R or ⎕S; the function may therefore preserve state by creating variables in the namespace.

The function may itself call ⎕R or ⎕S.

The locations of the match within Block and subpatterns within Match are given as offsets rather than positions, i.e. the values are the number of characters preceding the data, and are not affected by the Index Origin.

There may be only one transformation function, regardless of the number of search patterns.

Options

Options are specified using the Variant operator. The Principal option is IC.

Default values are highlighted thus.

IC Option

When set, case is ignored in searches.

1 | Matches are not case sensitive.
0 | Matches are case sensitive.

Example:

      ('[AEIOU]' ⎕R 'X' ⍠ 'IC' 1) 'ABCDE abcde'
XBCDX XbcdX
      ('[AEIOU]' ⎕R 'X' ⍠ 1)'ABCDE abcde'
XBCDX XbcdX

Mode Option

Specifies whether the input document is interpreted in line mode, document mode or mixed mode.

L | When line mode is set, the input document is split into separate lines (discarding the line ending characters themselves), and each line is processed separately. This means that the ML option applies per line, and the '^' and '$' anchors match the start and end respectively of each line. Because the document is split, searches can never match across multiple lines, nor can searches for line ending characters ever succeed. Setting line mode can result in significantly reduced memory requirements compared with the other modes.
D | When document mode is set, the entire input document is processed as a single block. The ML option applies to this entire block, and the '^' and '$' anchors match the start and end respectively of the block - not the lines within it. Searches can match across lines, and can match line ending characters.
M | When mixed mode is set, the '^' and '$' anchors match the start and end respectively of each line, as if line mode is set, but in all other respects behaviour is as if document mode is set - the entire input document is processed in a single block.

Examples:

      ('$' ⎕R '[Endline]' ⍠ 'Mode' 'L') 'ABC' 'DEF'
        ABC[Endline]  DEF[Endline]

      ('$' ⎕R '[Endline]' ⍠ 'Mode' 'D') 'ABC' 'DEF'
 ABC  DEF[Endline

      ('$' ⎕R '[Endline]' ⍠ 'Mode' 'M') 'ABC' 'DEF'
 ABC[Endline]  DEF[Endline]

DotAll Option

Specifies whether the dot (‘.’) character in search patterns matches line ending characters.

0 | The ‘.’ character in search patterns matches most characters, but not line endings.
1 | The ‘.’ character in search patterns matches all characters.

This option is invalid in line mode, because line endings are stripped from the input document.

Example:

      ('.' ⎕R 'X' ⍠'Mode' 'D') 'ABC' 'DEF'
 XXX  XXX
      ('.' ⎕R 'X' ⍠('Mode' 'D')('DotAll' 1)) 'ABC' 'DEF'
 XXXXXXXX

EOL Option

Sets the line ending character which is implicitly present between character vectors, when the input document is a vector of character vectors.

CR | Carriage Return (U+000D)
LF | Line Feed (U+000A)
CRLF | Carriage Return followed by New Line
VT | Vertical Tab (U+000B)
NEL | New Line (U+0085)
FF | Form Feed (U+000C)
LS | Line Separator (U+2028)
PS | Paragraph Separator (U+2029)

In the Classic Edition, setting a value which is not in ⎕AVU may result in a TRANSLATION ERROR.

Example:

      ('\n' ⎕R'X' ⍠('Mode' 'D')('EOL' 'LF')) 'ABC' 'DEF'
 ABCXDEF

Here, the implied line ending between ‘ABC’ and ‘DEF’ is ‘\n’, not the default ‘\r\n’.

NEOL Option

Specifies whether explicit line ending sequences in the input document are normalised by replacing them with the character specified using the EOL option.

0 | Line endings are not normalised.
1 | Line endings are normalised.

Example:

      a←'ABC',(1↑2↓⎕AV),'DEF',(1↑3↓⎕AV),'GHI'
      ('\n'⎕S 0 ⍠ 'Mode' 'D' ⍠ 'NEOL' 1 ⍠ 'EOL' 'LF') a
3 7

‘\n’ has matched both explicit line ending characters in the input, even though they are different.

ML Option

Sets a limit to the number of processed pattern matches per line (line mode) or document (document mode and mixed mode).

Positive value n | Sets the limit to the first n matches.
0 | Sets no limit.
Negative value ¯n | Sets the limit to exactly the nth match.

Examples:

      ('.' ⎕R 'x' ⍠ 'ML' 2) 'ABC' 'DEF'
 xxC  xxF
      ('.' ⎕R 'x' ⍠ 'ML' ¯2) 'ABC' 'DEF'
 AxC  DxF
      ('.' ⎕R 'x' ⍠ 'ML' ¯4 ⍠ 'Mode' 'D') 'ABC' 'DEF'
 ABC  xEF

Greedy Option

Controls whether patterns are “greedy” (and match the maximum input possible) or are not (and match the minimum). Within the pattern itself it is possible to specify greediness for individual elements of the pattern; this option sets the default.

1 | Greedy by default.
0 | Not greedy by default.

Examples:

      ('[A-Z].*[0-9]' ⎕R 'X' ⍠ 'Greedy' 1)'ABC123 DEF456'
X
      ('[A-Z].*[0-9]' ⎕R 'X' ⍠ 'Greedy' 0)'ABC123 DEF456'
X23 X56

OM Option

Specifies whether matches may overlap.

1 | Searching continues for all patterns and then from the character following the start of the match, thus permitting overlapping matches.
0 | Searching continues from the character following the end of the match.

This option may only be used with ⎕S. With ⎕R searching always continues from the character following the end of the match (the characters following the start of the match will have been changed).

Examples:

      ('[0-9]+' ⎕S '\0' ⍠ 'OM' 0) 'A 1234 5678 B'
 1234  5678
      ('[0-9]+' ⎕S '\0' ⍠ 'OM' 1) 'A 1234 5678 B'
 1234  234  34  4  5678  678  78  8

InEnc Option

This option specifies the encoding of the input stream when it cannot be determined automatically.

When the stream is read from its start, and the start of the stream contains a recognised Byte Order Mark (BOM), the encoding is taken as that specified by the BOM and this option is ignored. Otherwise, the encoding is assumed to be as specified by this option.

UTF8 | The stream is processed as UTF-8 data. Note that ASCII is a subset of UTF-8, so this default is also suitable for ASCII data.
UTF16LE | The stream is processed as UTF16 little-endian data.
UTF16BE | The stream is processed as UTF16 big-endian data.
ASCII | The stream is processed as ASCII data. If the stream contains any characters outside of the ASCII range then an error is produced.
ANSI | The stream is processed as ANSI (Windows-1252) data.

For compatibility with the OutEnc option, the above UTF formats may be qualified with -BOM (e.g. UTF-BOM). For input streams, the qualified and unqualified options are equivalent.

OutEnc Option

When the output is written to a stream, the data may be encoded on one of the following forms:

Implied | If input came from a stream then the encoding format is the same as the input stream, otherwise UTF-8
UTF8 | The data is written in UTF-8 format.
UTF16LE | The data is written in UTF-16 little-endian format.
UTF16BE | The data is written in UTF-16 big-endian format.
ASCII | The data is written in ASCII format.
ANSI | The data is written in ANSI (Windows-1252) format.

The above UTF formats may be qualified with -BOM (e.g. UTF8-BOM) to specify that a Byte Order Mark should be written at the start of the stream. For files, this is ignored if the file already contains any data.

Enc Option

This option sets both InEnc and OutEnc simultaneously, with the same given value. Any option value accepted by those options except Implied may be given.

ResultText Option

For ⎕R, this option determines the format of the result.

Implied | The output will either be a character vector or a vector of character vectors, dependent on the input document type
Simple | The output will be a character vector. Any and all line endings in the output will be represented by line ending characters within the character vector.
Nested | The output will be a vector of character vectors. Any and all line endings in the output document will be implied at the end of each character vector.

This option may only be used with ⎕R.

Examples:

      ⎕UCS ¨ ('A' ⎕R 'x') 'AB' 'CD'
 120 66  67 68
      ⎕UCS ('A' ⎕R 'x' ⍠ 'ResultText' 'Simple') 'AB' 'CD' 120 66 13 10 67 68

Line, document and mixed modes

The Mode setting determines how the input document is packaged as a block and passed to the search engine. In line mode each line is processed separately; in document mode and mixed mode the entire document is presented to the search engine. This affects both the semantics of the search expression, and memory usage.

Semantic differences

  • The ML option applies per block of data.
  • In line mode, search patterns cannot be constructed to span multiple lines. Specifically, patterns that include line ending characters (such as ‘\r’) will never match because the line endings are never presented to the search engine.
  • By default the search pattern metacharacters ‘^’ and ‘$’ match the start and end of the block of data. In line mode this is always the start and end of each line. In document mode this is the start and end of the document. In mixed mode the behaviour of ‘^’ and ‘$’ are amended by setting the PCRE option ‘MULTILINE’ so that they match the start and end of each line within the document.

Memory usage differences

  • Blocks of data passed to the search engine are processed and stored in the workspace. Processing the input document in line mode limits the total memory requirements; in particular this means that large streams can be processed without holding all the data in the workspace at the same time.

Technical Considerations

⎕R and ⎕S utilise the open-source regular-expression search engine PCRE, which is built into the Dyalog software and distributed according to the PCRE license which is published separately.

Before data is passed to PCRE it is converted to UTF-8 format. This converted data is buffered in the workspace; processing large documents may have significant memory requirements. In line mode, the data is broken into individual lines and each is processed separately, potentially reducing memory demands.

It is possible to save a workspace with an active ⎕R or ⎕S on the stack and execution can continue when the workspace is reloaded with the same interpreter version. Later versions of the interpreter may not remain compatible and may signal a DOMAIN ERROR with explanatory message in the status window if it is unable to continue execution.

PCRE has a buffer length limit of 231 bytes (2GB). UTF-8 encodes each character using between 1 and 6 bytes (typically 1 or 3). In the very worst case, where every character is encoded in 6 bytes, the maximum block length which can be searched would be 357,913,940 characters.

Further Examples

Several of the examples use the following vector as the input document:

      text
To be or not to be– that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles

Replace all upper and lower-case vowels by 'X':

       ('[aeiou]' ⎕R 'X' ⍠ 'IC' 1) text
TX bX Xr nXt tX bX– thXt Xs thX qXXstXXn:
WhXthXr 'tXs nXblXr Xn thX mXnd tX sXffXr
ThX slXngs Xnd XrrXws Xf XXtrXgXXXs fXrtXnX,
Xr tX tXkX Xrms XgXXnst X sXX Xf trXXblXs

Replace only the second vowel on each line by '\VOWEL\':

       ('[aeiou]' ⎕R '\\VOWEL\\'⍠('IC' 1)('ML' ¯2)) text
To b\VOWEL\ or not to be– that is the question:
Wheth\VOWEL\r 'tis nobler in the mind to suffer
The sl\VOWEL\ngs and arrows of outrageous fortune,
Or t\VOWEL\ take arms against a sea of troubles

Case fold each word:

      ('(?<first>\w)(?<remainder>\w*)' ⎕R '\u<first>\l<remainder>') text
To Be Or Not To Be– That Is The Question:
Whether 'Tis Nobler In The Mind To Suffer
The Slings And Arrows Of Outrageous Fortune,
Or To Take Arms Against A Sea Of Troubles

Extract only the lines with characters ‘or’ (in upper or lower case) on them:

      ↑('or' ⎕S '%' ⍠ ('IC' 1)('ML' 1)) text
To be or not to be– that is the question:
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles

Identify which lines contain the word ‘or’ (in upper or lower case) on them:

      ('\bor\b'⎕S 2⍠('IC' 1)('ML' 1))text
0 3

Note the difference between the characters ‘or’ (which appear in ‘fortune’) and the word ‘or’.

Place every non-space sequence of characters in brackets:

      ('[^\s]+' ⎕R '(&)' ) 'To be or not to be, that is the question'
(To) (be) (or) (not) (to) (be,) (that) (is) (the) (question)

Replace all sequences of one or more spaces by newline. Note that the effect of this is dependent on the input format:

Character vector input results in a single character vector output with embedded newlines:

      ]display ('\s+' ⎕R '\r') 'To be or not to be, that is the question'
┌→───────┐
│To      │
│be      │
│or      │
│not     │
│to      │
│be,     │
│that    │
│is      │
│the     │
│question│
└────────┘

A vector of two character vectors as input results in a vector of 10 character vectors output:

      ]display ('\s+' ⎕R '\r') 'To be or not to be,' 'that is the question'
┌→─────────────────────────────────────────────────────────────┐
│ ┌→─┐ ┌→─┐ ┌→─┐ ┌→──┐ ┌→─┐ ┌→──┐ ┌→───┐ ┌→─┐ ┌→──┐ ┌→───────┐ │
│ │To│ │be│ │or│ │not│ │to│ │be,│ │that│ │is│ │the│ │question│ │
│ └──┘ └──┘ └──┘ └───┘ └──┘ └───┘ └────┘ └──┘ └───┘ └────────┘ │
└∊─────────────────────────────────────────────────────────────┘

Change numerals to their expanded names, using a function:

     ∇r←f a
[1]   r←' ',⊃(⍎a.Match)↓'zero' 'one' 'two' 'three' 'four'
                      'five' 'six' 'seven' 'eight' 'nine'
     ∇
      verbose←('[0-9]' ⎕R f)
      verbose ⍕27×56×87
 one three one five four four

Swap ‘red’ and ‘blue’:

      ('red' 'blue' ⎕R 'blue' 'red') 'red hat blue coat'
blue hat red coat

Convert a comma separated values (CSV) file so that

  • dates in the first field are converted from European format to ISO, and
  • currency values are converted from Deutsche Marks (DEM) to Euros (DEM 1.95583 to €1).

The currency conversion requires the use of a function. Note the nested use of ⎕R.

Input file:

01/03/1980,Widgets,DEM 10.20
02/04/1980,Bolts,DEM 61.75
17/06/1980,Nuts; special rate DEM 17.00,DEM 17.00
18/07/1980,Hammer,DEM 1.25

Output file:

1980-03-01,Widgets,€ 5.21
1980-04-02,Bolts,€ 31.57
1980-06-17,Nuts; special rate DEM 17.00,€ 8.69
1980-07-18,Hammer,€ 0.63
     ∇ ret←f a;d;m;y;v
[1]    ⎕IO←0
[2]    :Select a.PatternNum
[3]    :Case 0
[4]        d m y←{a.Match[a.Offsets[⍵+1]+⍳a.Lengths[⍵+1]]}¨⍳3
[5]        ret←y,'-',m,'-',d,','
[6]    :Else
[7]        v←⍎a.Block[a.Offsets[1]+⍳a.Lengths[1]]
[8]        v÷←1.95583
[9]        ret←',€ ',('(\d+\.\d\d).*'⎕R'\1')⍕v
[10]   :EndSelect
     ∇
      in ← 'x.csv' ⎕NTIE 0
      out ← 'new.csv' ⎕NCREATE 0
      dateptn←'(\d{2})/(\d{2})/(\d{4}),'
      valptn←',DEM ([0-9.]+)'
      out (dateptn valptn ⎕R f) in
      ⎕nuntie¨in out

Create a simple profanity filter. For the list of objectionable words:

       profanity←'bleeding' 'heck'

first construct a pattern which will match the words:

      ptn←(('^' '$' '\r\n') ⎕R '\\b(' ')\\b' '|'
                           ⎕OPT 'Mode' 'D') profanity
      ptn
\b(bleeding|heck)\b

then a function that uses this pattern:

      sanitise←ptn ⎕R '****' ⎕opt 1
      sanitise '"Heck", I said'
"****", I said


Base Class

Base Class: R←⎕BASE.Y

⎕BASE is used to access the base class implementation of the name specified by Y.

Y must be the name of a Public member (Method, Field or Property) that is provided by the Base Class of the current Class or Instance.

⎕BASE is typically used to call a method in the Base Class which has been superseded by a Method in the current Class.

Note that ⎕BASE.Y is special syntax and any direct reference to ⎕BASE on its own or in any other context, is meaningless and causes SYNTAX ERROR.

In the following example, Class DomesticParrot derives from Class Parrot and supersedes its Speak method. DomesticParrot.Speak calls the Speak method in its Base Class Parrot, via ⎕BASE.

:Class Parrot: Bird
    ∇ R←Speak
      :Access Public
      R←'Squark!'
    ∇
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    ∇ R←Speak
      :Access Public
      R←⎕BASE.Speak,' Who''s a pretty boy, then!'
    ∇
:EndClass ⍝ DomesticParrot

      Maccaw←⎕NEW Parrot
      Maccaw.Speak
Squark!

      Polly←⎕NEW DomesticParrot
      Polly.Speak
Squark! Who's a pretty boy, then!


Class

Class: R←{X}⎕CLASS Y

Monadic Case

Monadic ⎕CLASS returns a list of references to Classes and Interfaces that specifies the class hierarchy for the Class or Instance specified by Y.

Y must be a reference to a Class or to an Instance of a Class.

R is a vector or vectors whose items represent nodes in the Class hierarchy of Y. Each item of R is a vector whose first item is a Class reference and whose subsequent items (if any) are references to the Interfaces supported by that Class.

Example 1

This example illustrates a simple inheritance tree or Class hierarchy. There are 3 Classes, namely:

Animal

Bird (derived from Animal)

Parrot (derived from Bird)

:Class Animal
...
:EndClass ⍝ Animal

:Class Bird: Animal
...
:EndClass ⍝ Bird

:Class Parrot: Bird
...
:EndClass ⍝ Parrot
       ⎕CLASS Eeyore←⎕NEW Animal
  #.Animal
       ⎕CLASS Robin←⎕NEW Bird
  #.Bird    #.Animal
       ⎕CLASS Polly←⎕NEW Parrot
  #.Parrot    #.Bird    #.Animal

      ⎕CLASS¨ Parrot Animal
   #.Parrot    #.Bird    #.Animal      #.Animal

Example 2

The Penguin Class example (see Penguin Class Example) illustrates the use of Interfaces.

In this case, the Penguin Class derives from Animal (as above) but additionally supports the BirdBehaviour and FishBehaviour Interfaces, thereby inheriting members from both.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
  #.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal

Dyadic Case

If X is specified, Y must be a reference to an Instance of a Class and X is a reference to an Interface that is supported by Instance Y or to a Class upon which Instance Y is based.

In this case, R is a reference to the implementation of Interface X by Instance Y, or to the implementation of (Base) Class X by Instance Y, and is used as a cast in order to access members of Y that correspond to members of Interface of (Base) Class X.

Example 1:

Once again, the Penguin Class example (see Penguin Class Example) is used to illustrate the use of Interfaces.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
  #.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal

      (FishBehaviour ⎕CLASS Pingo).Swim
I can dive and swim like a fish
      (BirdBehaviour ⎕CLASS Pingo).Fly
Although I am a bird, I cannot fly
      (BirdBehaviour ⎕CLASS Pingo).Lay
I lay one egg every year
      (BirdBehaviour ⎕CLASS Pingo).Sing
Croak, Croak!

Example 2:

This example illustrates the use of dyadic ⎕CLASS to cast an Instance to a lower Class and thereby access a member in the lower Class that has been superseded by another Class higher in the tree.

      Polly←⎕NEW DomesticParrot
      Polly.Speak
Squark! Who's a pretty boy, then!

Note that the Speak method invoked above is the Speak method defined by Class DomesticParrot, which supersedes the Speak methods of sub-classes Parrot and Bird.

You may use a cast to access the (superseded) Speak method in the sub-classes Parrot and Bird.

      (Parrot ⎕CLASS Polly).Speak
Squark!
      (Bird ⎕CLASS Polly).Speak
Tweet, tweet!


Display Form

Display Form: R←⎕DF Y

⎕DF sets the Display Form of a namespace, a GUI object, a Class, or an Instance of a Class.

Y must be a simple character array that specifies the display form of a namespace. If defined, this array will be returned by the format functions and ⎕FMT instead of the default for the object in question. This also applies to the string that is displayed when the name is referenced but not assigned (the default display).

The result R is the previous value of the Display Form which initially is ⎕NULL.

      'F'⎕WC'Form'
      ⍕F
#.F
      ⍴⍕F
3
      ⎕FMT F
#.F
      ⍴⎕FMT F
1 3
      F ⍝ default display uses ⍕
#.F

       F.⎕DF 'Pete''s Form'
       ⍕F
Pete's Form
       ⍴⍕F
11
       ⎕FMT F
Pete's Form
       ⍴⎕FMT F
1 11

Notice that ⎕DF will accept any character array, but ⎕FMT always returns a matrix.

      F.⎕DF 2 2 5⍴⎕A
      F
ABCDE
FGHIJ

KLMNO
PQRST
      ⍴⍕F
2 2 5

      ⍴⎕←⎕FMT F
ABCDE
FGHIJ

KLMNO
PQRST
5 5

Note that ⎕DF defines the Display Form statically, rather than dynamically.

      'F'⎕WC'Form' 'This is the Caption'
      F
#.F

      F.(⎕DF Caption)⍝ set display form to current caption
      F
This is the Caption

      F.Caption←'New Caption' ⍝ changing caption does not
                              ⍝ change the display form
      F
This is the Caption

You may use the Constructor function to assign the Display Form to an Instance of a Class. For example:

:Class MyClass
    ∇ Make arg
      :Access Public
      :Implements Constructor
      ⎕DF arg
    ∇
:EndClass ⍝ MyClass

      PD←⎕NEW MyClass 'Pete'
      PD
Pete

It is possible to set the Display Form for the Root and for ⎕SE

      )CLEAR
clear ws
      #
#
      ⎕DF ⎕WSID
      #
CLEAR WS

      ⎕SE
⎕SE
      ⎕SE.⎕DF 'Session'
      ⎕SE
Session

Note that ⎕DF applies directly to the object in question and is not automatically applied in a hierarchical fashion.

      'X'⎕NS ''
      X
#.X

      'Y'X.⎕NS ''
      X.Y
#.X.Y
      X.⎕DF 'This is X'
      X
This is X

      X.Y
#.X.Y


Fix Script

Fix Script: {R}←{X}⎕FIX Y

⎕FIX fixes a Class from the script specified by Y.

Y must be a vector of character vectors or character scalars that contains a well-formed Class script. If so, the shy result R is a reference to the new Class fixed by ⎕FIX.

The Class specified by Y may be named or unnamed.

If specified, X must be a numeric scalar. If X is omitted or non-zero, and the Class script Y specifies a name (for the Class), ⎕FIX establishes that Class in the workspace.

If X is 0 or the Class specified by Y is unnamed, the Class is not established per se, although it will exist for as long as a reference to it exists.

In the first example, the Class specified by Y is named (MyClass) but the result of ⎕FIX is discarded. The end-result is that MyClass is established in the workspace as a Class.

      ⎕←⎕FIX ':Class MyClass' ':EndClass'
#.MyClass

In the second example, the Class specified by Y is named (MyClass) and the result of ⎕FIX is assigned to a different name (MYREF). The end-result is that a Class named MyClass is established in the workspace, and MYREF is a reference to it.

      MYREF←⎕FIX ':Class MyClass' ':EndClass'
      )CLASSES
MyClass MYREF
      ⎕NC'MyClass' 'MYREF'
9.4 9.4
      MYREF
#.MyClass

In the third example, the left-argument of 0 causes the named Class MyClass to be visible only via the reference to it (MYREF). It is there, but hidden.

      MYREF←0 ⎕FIX ':Class MyClass' ':EndClass'
      )CLASSES
MYREF
      MYREF
#.MyClass

The final example illustrates the use of un-named Classes.

      src←':Class' '∇Make n'
      src,←'Access Public' 'Implements Constructor'
      src,←'⎕DF n' '∇' ':EndClass'
      MYREF←⎕FIX src
      )CLASSES
MYREF
      MYINST←⎕NEW MYREF'Pete'
      MYINST
Pete


Instances

Instances: R←⎕INSTANCES Y

⎕INSTANCES returns a list all the current instances of the Class specified by Y.

Y must be a reference to a Class.

R is a vector of references to all existing Instances of Class Y.

Examples

This example illustrates a simple inheritance tree or Class hierarchy. There are 3 Classes, namely:

Animal

Bird (derived from Animal)

Parrot (derived from Bird)

:Class Animal
...
:EndClass ⍝ Animal

:Class Bird: Animal
...
:EndClass ⍝ Bird

:Class Parrot: Bird
...
:EndClass ⍝ Parrot
      Eeyore←⎕NEW Animal
      Robin←⎕NEW Bird
      Polly←⎕NEW Parrot

      ⎕INSTANCES Parrot
 #.[Parrot]
      ⎕INSTANCES Bird
 #.[Bird]  #.[Parrot]
      ⎕INSTANCES Animal
 #.[Animal]  #.[Bird]  #.[Parrot]

      Eeyore.⎕DF 'eeyore'
      Robin.⎕DF 'robin'
      Polly.⎕DF 'polly'

      ⎕INSTANCES Parrot
 polly
      ⎕INSTANCES Bird
 robin  polly
      ⎕INSTANCES Animal
 eeyore  robin  polly


New Instance

New Instance: R←⎕NEW Y

⎕NEW creates a new instance of the Class or .Net Type specified by Y.

Y must be a 1- or 2-item scalar or vector. The first item is a reference to a Class or to a .Net Type, or a character vector containing the name of a Dyalog GUI object. The second item, if specified, contains the argument to be supplied to the Class or Type Constructor.

The result R is a reference to a new instance of Class or Type Y.

For further information, see Interface Guide.

Class Example

:Class Animal
    ∇ Name nm
      :Access Public
      :Implements Constructor
      ⎕DF nm
    ∇
:EndClass ⍝ Animal

      Donkey←⎕NEW Animal 'Eeyore'
      Donkey
Eeyore

If ⎕NEW is called with just a Class reference (i.e. without parameters for the Constructor), the default constructor will be called. A default constructor is defined by a niladic function with the :Implements Constructor attribute. For example, the Animal Class may be redefined as:

:Class Animal
    ∇ NoName
      :Access Public
      :Implements Constructor
      ⎕DF 'Noname'
    ∇
    ∇ Name nm
      :Access Public
      :Implements Constructor
      ⎕DF nm
    ∇
:EndClass ⍝ Animal

      Horse←⎕NEW Animal
      Horse
Noname

.Net Examples

      ⎕USING←'System' 'System.Web.Mail,System.Web.dll'
      dt←⎕NEW DateTime (2006 1 1)
      msg←⎕NEW MailMessage
      ⎕NC 'dt' 'msg' 'DateTime' 'MailMessage'
9.2 9.2 9.6 9.6

Note that .Net Types are accessed as follows.

If the name specified by the first item of Y would otherwise generate a VALUE ERROR, and ⎕USING has been set, APL attempts to load the Type specified by Y from the .Net assemblies (DLLs) specified in ⎕USING. If successful, the name specified by Y is entered into the SYMBOL TABLE with a name-class of 9.6. Subsequent references to that symbol (in this case DateTime) are resolved directly and do not involve any assembly searching.

      F←⎕NEW ⊂'Form'
      F←⎕NEW'Form'(('Caption' 'Hello')('Posn' (10 10)))

      ⎕NEW'Form'(('Caption' 'Hello')('Posn' (10 10)))
#.[Form]


Variant

Variant: {R}←{X}(f ⎕OPT B)Y

⎕OPT is synonymous with the Variant Operator symbol ⍠ and is the only form available in the Classic Edition.

See Variant:.


Source

Source: R←⎕SRC Y

⎕SRC returns the script that defines the scripted object Y.

Y must be a reference to a scripted object. Scripted objects include Classes, Interfaces and scripted Namespaces.

R is a vector of character vectors containing the script that was used to define Y.

      )ed ○MyClass
:Class MyClass
∇ r←foo arg
:Access public shared
r←1+arg
∇
:EndClass

      z←⎕SRC MyClass
      ⎕z
6
      ⍴¨z
 14  15  27  13  5  9
      ⍪z
 :Class MyClass
     ∇ r←foo arg
       :Access public shared
       r←1+arg
     ∇
 :EndClass

Note: The only two ways to permanently alter the source of a scripted object are to change the object in the editor, or by refixing it using ⎕FIX. A useful technique to ensure that a scripted object is in sync with its source is to ⎕FIX ⎕SRC object_reference.


This Space

This Space: R←⎕THIS

⎕THIS returns a reference to the current namespace, i.e. to the space in which it is referenced.

If NC9 is a reference to any object whose name-class is 9, then:

      NC9≡NC9.⎕THIS
1

Examples

      ⎕THIS
#
      'X'⎕NS ''
      X.⎕THIS
#.X
     'F'⎕WC'Form'
     'F.B'⎕WC'Button'
      F.B.⎕THIS
#.F.B

      Polly←⎕NEW Parrot
      Polly.⎕THIS
#.[Parrot]

An Instance may use ⎕THIS to obtain a reference to its own Class:

    Polly.(⊃⊃⎕CLASS ⎕THIS)
#.Parrot

or a function (such as a Constructor or Destructor) may identify or enumerate all other Instances of the same Class:

      Polly.(⍴⎕INSTANCES⊃⊃⎕CLASS ⎕THIS)
1


Thread Numbers

Thread Numbers: R←⎕TNUMS

⎕TNUMS reports the numbers of all current threads.

R is a simple integer vector of the base thread and all its living descendants.

Example

      ⎕TNUMS
0 2 4 5 6 3 7 8 9


Introduction

System commands are not executable APL expressions. They provide services or information associated with the workspace and the external environment.

Command Presentation

System commands may be entered from immediate execution mode or in response to the prompt ⎕: within evaluated input. All system commands begin with the symbol ), known as a right parenthesis. All system commands may be entered in upper or lower case.

Table 20: System Commands

Command | Description
)CLASSES | List classes
)CLEAR | Clear the workspace
)CMD Y | Execute a Windows Command
)CONTINUE | Save a Continue workspace and terminate APL
)COPY {Y} | Copy objects from another workspace
)CS {Y} | Change current namespace
)DROP {Y} | Drop named workspace
)ED Y | Edit object(s)
)ERASE Y | Erase object(s)
)EVENTS | List events of GUI namespace or object
)FNS {Y} | List user defined Functions
)HOLDS | Display Held tokens
)LIB {Y} | List workspaces in a directory
)LOAD {Y} | Load a workspace
)METHODS | List methods in GUI namespace or object
)NS {Y} | Create a global Namespace
)OBJECTS {Y} | List global namespaces
)OBS {Y} | List global namespaces (alternative form)
)OFF | Terminate the APL session
)OPS {Y} | List user defined Operators
)PCOPY {Y} | Perform Protected Copy of objects
)PROPS | List properties of GUI namespace or object
)RESET | Reset the state indicator
)SAVE {Y} | Save the workspace
)SH {Y} | Execute a (UNIX) Shell command
)SI | State Indicator
)SIC | Clear State Indicator
)SINL | State Indicator with local Name Lists
)TID {Y} | Switch current Thread Identity
)VARS {Y} | List user defined global Variables
)WSID {Y} | Workspace Identification
)XLOAD Y | Load a workspace; do not execute ⎕LX
{ } indicates that the parameter(s) denoted by Y are optional.


List Classes

List Classes: )CLASSES

This command lists the names of APL Classes in the active workspace.

Example:

      )CLEAR
clear ws
      )ED ○MyClass

:Class MyClass
    ∇ Make Name
      :Implements Constructor
      ⎕DF Name
    ∇
:EndClass ⍝ MyClass

      )CLASSES
MyClass
      )COPY OO YourClass
.\OO saved Sun Jan 29 18:32:03 2006
      )CLASSES
MyClass YourClass
      ⎕NC 'MyClass' 'YourClass'
9.4 9.4


Clear Workspace

Clear Workspace: )CLEAR

This command clears the active workspace and gives the report "clear ws". The active workspace is lost. The name of a clear workspace is CLEAR WS. System variables are initialised with their default values as described in System Variables.

In GUI implementations of Dyalog APL, )CLEAR expunges all GUI objects, discards any unprocessed events in the event queue and resets the properties of the Root object '.' to their default values.

Example

      )CLEAR
clear ws


Windows Command Processor

Windows Command Processor: )CMD cmd

This command allows Windows Command Processor or UNIX shell commands to be given from APL. )CMD is a synonym of )SH. Either command may be given in either environment (Windows or UNIX) with exactly the same effect. )CMD is probably more natural for the Windows user. This section describes the behaviour of )CMD and )SH under Windows. See Example for a discussion of the behaviour of these commands under UNIX.

The system functions ⎕CMD and ⎕SH provide similar facilities but may be executed from within APL code.

Note that under Windows, you may not execute )CMD without a command. If you wish to, you can easily open a new Command Prompt window outside APL.

Example

      )CMD DIR

 Volume in drive C has no label
 Directory of C:\PETE\WS

.            <DIR>     5-07-94  3.02p
..           <DIR>     5-07-94  3.02p
SALES    DWS    110092 5-07-94  3.29p
EXPENSES DWS    154207 5-07-94  3.29p

If cmd issues prompts and expects user input, it is ESSENTIAL to explicitly redirect input and output to the console. If this is done, APL detects the presence of a ">" in the command line and runs the command processor in a visible window and does not direct output to the pipe. If you fail to do this your system will appear to hang because there is no mechanism for you to receive or respond to the prompt.

Example

      )CMD DATE <CON >CON

(Command Prompt window appears)

Current date is Wed 19-07-1995
Enter new date (dd-mm-yy): 20-07-95

(Command Prompt window disappears)

Implementation Notes

The argument of )CMD is simply passed to the appropriate command processor for execution and its output is received using an unnamed pipe.

By default, )CMD will execute the string ('cmd.exe /c',Y) where Y is the argument given to )CMD. However, the implementation permits the use of alternative command processors as follows:

Before execution, the argument is prefixed and postfixed with strings defined by the APL parameters CMD_PREFIX and CMD_POSTFIX. The former specifies the name of your command processor and any parameters that it requires. The latter specifies a string which may be required. If CMD_PREFIX is not defined, it defaults to the name defined by the environment variable COMSPEC followed by "\c". If COMSPEC is not defined, it defaults to COMMAND.COM or CMD.EXE as appropriate. If CMD_POSTFIX is not defined, it defaults to an empty vector.


Save Continuation

Save Continuation: )CONTINUE

This command saves the active workspace under the name CONTINUE and ends the Dyalog APL session.

When you subsequently start another Dyalog APL session, the CONTINUE workspace is loaded automatically. When a CONTINUE workspace is loaded, the latent expression (if any) is NOT executed.

Note that the values of all system variables (including ⎕SM) and GUI objects are also saved in CONTINUE.


Copy Workspace

Copy Workspace: )COPY {ws {nms}}

This command brings all or selected global objects nms from a stored workspace with the given name. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE. See Workspaces for the rules for specifying a workspace name.

If the list of names is excluded, all defined objects (including namespaces) are copied.

If the workspace name identifies a valid, readable workspace, the system reports the workspace name, "saved" and the date and time when the workspace was last saved.

Examples

      )COPY WS/UTILITY
WS/UTILITY saved Mon Nov  1 13:11:19 1992

      )COPY TEMP ⎕LX FOO X A.B.C
./TEMP saved Mon Nov  1 14:20:47 1992
not found X

Copied objects are defined at the global level in the active workspace. Existing global objects in the active workspace with the same name as a copied object are replaced. If the copied object replaces either a function in the state indicator, or an object that is an operand of an operator in the state indicator, or a function whose left argument is being executed, the original object remains defined until its execution is completed or it is no longer referenced by an operator in the state indicator. If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports ws not found.

You may copy an object from a namespace by specifying its full pathname. The object will be copied to the current namespace in the active workspace, losing its original parent and gaining a new one in the process. You may only copy a GUI object into a namespace that is a suitable parent for that object. For example, you could only copy a Group object from a saved workspace if the current namespace in the active workspace is itself a Form, SubForm or Group.

If the workspace name identifies a file that is not a workspace, the system reports bad ws.

If the source workspace is too large to be loaded, the system reports ws too large.

When copying data between Classic and Unicode Editions, )COPY will fail with TRANSLATION ERROR if any object in the source workspace fails conversion between Unicode and ⎕AV indices, whether or not that object is specified by nms. See Atomic Vector - Unicode: for further details.

If "ws" is omitted, the file open dialog box is displayed and all objects copied from the selected workspace.

If the list of names is included, the names of system variables may also be included and copied into the active workspace. The global referents will be copied.

If an object is not found in the stored workspace, the system reports not found followed by the name of the object.

If the list of names includes the name of:

  • an Instance of a Class but not the Class itself
  • a Class but not a Class upon which it depends
  • an array or a namespace that contains a ref to another namespace, but not the namespace to which it refers

the dependant object(s) will also be copied but will be unnamed and hidden. In such as case, the system will issue a warning message.

For example, if a saved workspace named CFWS contains a Class named #.CompFile and an Instance (of CompFile) named icf,

      )COPY CFWS icf
.\CFWS saved Fri Mar 03 10:21:36 2006
copied object created an unnamed copy of class #.CompFile

The existence of a hidden copy can be confusing, especially if it is a hidden copy of an object which had a name which is in use in the current workspace. In the above example, if there is a class called CompFile in the workspace into which icf is copied, the copied instance may appear to be an instance of the visible CompFile, but it will actually be an instance of the hidden CompFile - which may have very different (or perhaps worse: very slightly different) characteristics to the named version.

If you copy a Class without copying its Base Class, the Class can be used (it will use the invisible copy of the Base Class), but if you edit the Class, you will either be unable to save it because the editor cannot find the Base Class, or - if there is a visible Class of that name in the workspace - it will be used as the Base Class. In the latter case, the invisible copy which was brought in by )COPY will now disappear, since there are no longer any references to it - and if these two Base Classes were different, the behaviour of the derived Class will change (and any changes made to the invisible Base Class since it was copied will be lost).


Change Space

Change Space: )CS {nm}

)CS changes the current space to the global namespace nm.

If no nm is given, the system changes to the top level (Root) namespace. If nm is not the name of a global namespace, the system reports the error message Namespace does not exist.

name may be either a simple name or a compound name separated by '.', including one of the special names '#' (Root) or '##' (Parent).

Examples

      )CS
#
      )CS X
#.X
      )CS Y.Z
#.X.Y.Z
      )CS ##
#.X.Y
      )CS #.UTIL
#.UTIL


Drop Workspace

Drop Workspace: )DROP {ws}

This command removes the specified workspace from disk storage. See Workspaces for information regarding the rules for specifying a workspace name.

If ws is omitted, a file open dialog box is displayed to elicit the workspace name.

Example

      )DROP WS/TEMP
Thu Sep 17 10:32:18 1998


Edit Object

Edit Object: )ED nms

)ED invokes the Dyalog APL editor and opens an Edit window for each of the objects specified in nms.

If a name specifies a new symbol it is taken to be a function/operator. However, if a name is localised in a suspended function/operator but is otherwise undefined, it is assumed to be a vector of character vectors.

The type of a new object may be specified explicitly by preceding its name with an appropriate symbol as follows:

∇ | function/operator
→ | simple character vector
∊ | vector of character vectors
- | character matrix
⍟ | Namespace script
○ | Class script
∘ | Interface

The first object named becomes the top window on the stack. See User Guide for details. )ED ignores names which specify GUI objects.

Examples

      )ED MYFUNCTION

      )ED ∇FOO -MAT ∊VECVEC


List Events

List Events: )EVENTS

The )EVENTS system command lists the Events that may be generated by the object associated with the current space.

For example:

      ⎕CS 'BB' ⎕WC 'BrowseBox'

      )EVENTS
Close   Create  FileBoxCancel   FileBoxOK

)EVENTS produces no output when executed in a pure (non-GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )EVENTS


List Global Defined Functions

List Global Defined Functions: )FNS {nm}

This command displays the names of global defined functions in the active workspace or current namespace. Names are displayed in ⎕AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Examples

      )FNS
ASK DISPLAY GET PUT ZILCH
      )FNS G
GET PUT ZILCH


Display Held Tokens

Display Held Tokens: )HOLDS

System command )HOLDS displays a list of tokens which have been acquired or requested by the :Hold control structure.

Each line of the display is of the form:

token:  acq  req  req ...

Where acq is the number of the thread that has acquired the token, and req is the number of a thread which is requesting it. For a token to appear in the display, a thread (and only one thread) must have acquired it, whereas any number of threads can be requesting it.

Example

Thread 300’s attempt to acquire token 'blue' results in a deadlock:

300:DEADLOCK
Sema4[1] :Hold 'blue'
        ^

      )HOLDS
blue:   100
green:  200     100
red:    300     200     100

  • Blue has been acquired by thread 100.
  • Green has been acquired by 200 and requested by 100.
  • Red has been acquired by 300 and requested by 200 and 100.

The following cycle of dependencies has caused the deadlock:

Thread 300 attempts to acquire blue,      300 → blue
which is owned by 100,                     ↑      ↓
which is waiting for red,                 red ←  100
which is owned by 300.


List Workspace Library

List Workspace Library: )LIB {dir}

This command lists the names of Dyalog APL workspaces contained in the given directory.

Example

      )LIB WS
MYWORK TEMP

If a directory is not given, the workspaces on the user's APL workspace path (WSPATH) are listed. In this case, the listing is divided into sections identifying the directories concerned. The current directory is identified as ".".

Example

      )LIB
.
        PDTEMP  WORK   GRAPHICS
C:\DYALOG\WS
        DISPLAY GROUPS


Load Workspace

Load Workspace: )LOAD {ws}

This command causes the named stored workspace to be loaded. The current active workspace is lost.

If "ws" is a full or relative pathname, only the specified directory is examined. If not, the APL workspace path (WSPATH as specified in APL.INI) is traversed in search of the named workspace. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE. If ‘ws’ is omitted, the File Open dialog box is displayed.

If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports "ws not found". If the workspace name identifies a file or directory that is not a workspace, the system reports workspace name "is not a ws". If successfully loaded, the system reports workspace name "saved", followed by the date and time when the workspace was last saved. If the workspace is too large to be loaded into the APL session, the system reports "ws too large". After loading the workspace, the latent expression (⎕LX) is executed unless APL was invoked with the -x option.

If the workspace contains any GUI objects whose Visible property is 1, these objects will be displayed. If the workspace contains a non-empty ⎕SM but does not contain an SM GUI object, the form defined by ⎕SM will be displayed in a window on the screen.

Holding the Ctrl key down while entering a )LOAD command or selecting a workspace from the session file menu now causes the incoming latent expression to be traced.

Holding the Shift key down while selecting a workspace from the session file menu will prevent execution of the latent expression.

Example

      )LOAD SMDEMO
/usr/dyalog/WS/SMDEMO saved Wed Sep 6 21:46:27 1989
Type HOWDEMO for help


List Methods

List Methods: )METHODS

The )METHODS system command lists the Methods that apply to the object associated with the current space.

For example:

      ⎕CS 'F' ⎕WC 'Form'
      )METHODS
Animate ChooseFont   Detach  GetFocus    GetTextSize Wait

)METHODS produces no output when executed in a pure (non-GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )METHODS


Create Namespace

Create Namespace: )NS {nm}

)NS creates a global namespace and displays its full name, nm.

nm may be either a simple name or a compound name separated by '.', including one of the special names '#' (Root) or '##' (Parent).

If name does not start with the special Root space identifier '#', the new namespace is created relative to the current one.

If name is already in use for a workspace object other than a namespace, the command fails and displays the error message Name already exists.

If name is an existing namespace, no change occurs.

)NS with no nm specification displays the current namespace.

Examples

      )NS
#

      )NS W.X
#.W.X

      )CS W.X
#.W.X

      )NS Y.Z
#.W.X.Y.Z

      )NS
#.W.X


List Global Namespaces

List Global Namespaces: )OBJECTS {nm}

This command displays the names of global namespaces in the active workspace. Names are displayed in the ⎕AV collating order. If a name is included after the command, only those names starting at or after the given name in collating order are displayed. Namespaces are objects created using ⎕NS, )NS or ⎕WC and have name class 9.

Note: )OBS can be used as an alternative to )OBJECTS

Examples

      )OBJECTS
FORM1   UTIL    WSDOC   XREF

      )OBS W
WSDOC   XREF


List Global Namespaces Short

List Global Namespaces: )OBS {nm}

This command is the same as the )OBJECTS command. See List Global Namespaces:


Sign Off APL

Sign Off APL: )OFF

This command terminates the APL session, returning to the Operating System command processor or shell.


List Global Defined Operators

List Global Defined Operators: )OPS {nm}

This command displays the names of global defined operators in the active workspace or current namespace. Names are displayed in ⎕AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Examples

      )OPS
AND DOIF DUAL ELSE POWER

      )OPS E
ELSE POWER


Protected Copy

Protected Copy: )PCOPY {ws {nms}}

This command brings all or selected global objects from a stored workspace with the given name provided that there is no existing global usage of the name in the active workspace. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE.

)PCOPY does not copy ⎕SM. This restriction may be removed in a later release.

If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports "ws not found". If the workspace name identifies a file that is not a workspace, or is a workspace with an invalid version number (one that is greater than the version of the current APL) the system reports "bad ws". See Workspaces for the rules for specifying a workspace name.

If the workspace name is the name of a valid, readable workspace, the system reports the workspace name, "saved", and the date and time that the workspace was last saved.

If the list of names is excluded, all global defined objects (functions and variables) are copied. If an object is not found in the stored workspace, the system reports "not found" followed by the name of the object. If an object cannot be copied into the active workspace because there is an existing referent, the system reports "not copied" followed by the name of the object.

For further information, see Copy Workspace: .

Examples

      )PCOPY WS/UTILITY
WS/UTILITY saved Mon Nov  1 13:11:19 1993
not copied COPIED IF
not copied COPIED JOIN

      )PCOPY TEMP FOO X
./TEMP saved Mon Nov  1 14:20:47 1993
not found X


List Properties

List Properties: )PROPS

The )PROPS system command lists the Properties of the object associated with the current space.

For example:

      ⎕CS 'BB' ⎕WC 'BrowseBox'

      )PROPS
BrowseFor       Caption ChildList       Data    Event
EventList       HasEdit KeepOnClose     MethodList
PropList        StartIn Target  Translate       Type

)PROPS produces no output when executed in a pure (non GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )PROPS


Reset State Indicator

Reset State Indicator: )RESET

This command cancels all suspensions recorded in the state indicator and discards any unprocessed events in the event queue.

)RESET also performs an internal re-organisation of the workspace and process memory. See Workspace Available: for details.

Example

      )SI
#.FOO[1]*
⍎
#.FOO[1]*

      )RESET

      )SI


Save Workspace

Save Workspace: )SAVE {ws}

This command compacts (see Workspace Available: for details) and saves the active workspace

The workspace is saved with its state of execution intact. A stored workspace may subsequently be loaded with the system command )LOAD or the system function ⎕LOAD, and objects may be copied from a stored workspace with the system commands )COPY or )PCOPY or the system function ⎕CY.

This command may fail with one of the following error messages:

unacceptable char | The given workspace name was ill-formed
not saved this ws is WSID | An attempt was made to change the name of the workspace for the save, and that workspace already existed.
not saved this ws is CLEAR WS | The active workspace was CLEAR WS and no attempt was made to change the name.
Can't save - file could not be created. | The workspace name supplied did not represent a valid file name for the current Operating System.
cannot create | The user does not have access to create the file OR the workspace name conflicts with an existing non-workspace file.
cannot save with windows open | A workspace may not be saved if trace or edit windows are open.

An existing stored workspace with the same name will be replaced. The active workspace may be renamed by the system command )WSID or the system function ⎕WSID.

After a successful save, the system reports the workspace name, "saved", followed by the time and date.

Example

      )SAVE MYWORK
./MYWORK saved Thu Sep 17 10:32:20 1998


Execute UNIX Command

Execute (UNIX) Command: )SH {cmd}

This command allows WINDOWS or UNIX shell commands to be given from APL. )SH is a synonym of )CMD. Either command may be given in either environment (WINDOWS or UNIX) with exactly the same effect. )SH is probably more natural for the UNIX user. This section describes the behaviour of )SH and )CMD under UNIX. See Windows Command Processor: for a discussion of their behaviour under WINDOWS.

The system commands ⎕SH and ⎕CMD provide similar facilities but may be executed from within APL code.

)SH allows UNIX shell commands to be given from APL. The argument must be entered in the appropriate case (usually lower-case). The result of the command, if any, is displayed.

)SH causes Dyalog APL to invoke the system() library call. The shell which is used to run the command is therefore the shell which system() is defined to call. For example, under AIX this would be /usr/bin/sh.

When the shell is closed, control returns to APL. See User Guide for further information.

The parameters CMD_PREFIX and CMD_POSTFIX may be used to execute a different shell under the shell associated with system().

Example

      )SH ls
EXT
FILES


State Indicator

State Indicator: )SI

This command displays the contents of the state indicator in the active workspace. The state indicator identifies those operations which are suspended or pendent for each suspension.

The list consists of a line for each suspended or pendent operation beginning with the most recently suspended function or operator. Each line may be:

  • The name of a defined function or operator, followed by the line number at which the operation is halted, and followed by the * symbol if the operation is suspended. The name of the function or operator is its full pathname relative to the root namespace #. For example, #.UTIL.PRINT. In addition, the display of a function or operator which has dynamically changed space away from its origin is prefixed with its current space. For example, [⎕SE] TRAV.
  • A primitive operator symbol.
  • The Execute function symbol (⍎).
  • The Evaluated Input symbol (⎕).
  • The System Function ⎕DQ or ⎕SR (occurs when executing a callback function).

Examples

      )SI
#.PLUS[2]*
.
#.MATDIV[4]
#.FOO[1]*
⍎

This example indicates that at some point function FOO was executed and suspended on line 1. Subsequently, function MATDIV was invoked, with a function derived from the Inner Product or Outer Product operator (.) having defined function PLUS as an operand.

In the following, function foo in namespace x has called goo in namespace y. Function goo has then changed space (⎕CS) to namespace z where it has been suspended:

      )si
[z] y.goo[2]*
x.foo[1]

Threads

In a multithreading application, where parent threads spawn child threads, the state indicator assumes the structure of a branching tree. Branches of the tree are represented by indenting lines belonging to child threads. For example:

      )SI
·   #.Calc[1]
&5
·   ·   #.DivSub[1]
·   &7
·   ·   #.DivSub[1]
·   &6
·   #.Div[2]*
&4
#.Sub[3]
#.Main[4]

Here, Main has called Sub, which has spawned threads 4 and 5 with functions: Div and Calc. Function Div, after spawning DivSub in each of threads 6 and 7, has been suspended at line [2].


Clear State Indicator

Clear State Indicator: )SIC

This command is a synonym for )RESET. See Reset State Indicator:


State Indicator Name List

State Indicator & Name List: )SINL

This command displays the contents of the state indicator together with local names. The display is the same as for )SI (see above) except that a list of local names is appended to each defined function or operator line.

Example

      )SINL
#.PLUS[2]*        B       A       R       DYADIC  END
.
#.MATDIV[4]       R       END     I       J       ⎕TRAP
#.FOO[1]* R
⍎


Thread Identity

Thread Identity: )TID {tid}

)TID associates the Session window with the specified thread so that expressions that you subsequently execute in the Session are executed in the context of that thread.

If you attempt to )TID to a thread that is paused or running, that thread will, if possible, be interrupted by a strong interrupt. If the thread is in a state which it would be inappropriate to interrupt (for example, if the thread is executing an external function), the system reports:

      Can't switch, this thread is n

If no thread number is given, )TID reports the number of the current thread.

Examples

      ⍝ State indicator
      )si
·   #.print[1]
&3
·   ·   #.sub_calc[2]*
·   &2
·   #.calc[1]
&1

      ⍝ Current thread
      )tid
is 2

      ⍝ Switch suspension to thread 3
      )tid 3
was 2

      ⍝ State indicator
      )si
·   #.print[1]*
&3
·   ·   #.sub_calc[2]
·   &2
·   calc[1]
&1

      ⍝ Attempt to switch to pendent thread 1
      )tid 1
Can't switch, this thread is 3


List Global Defined Variables

List Global Defined Variables: )VARS {nm}

This command displays the names of global defined variables in the active workspace or current namespace. Names are displayed in ⎕AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Examples

      )VARS
A  B  F  TEMP VAR

      )VARS F
F TEMP VAR


Workspace Identification

Workspace Identification: )WSID {ws}

This command displays or sets the name of the active workspace.

If a workspace name is not specified, )WSID reports the name of the current active workspace. The name reported is the full path name, including directory references.

If a workspace name is given, the current active workspace is renamed accordingly. The previous name of the active workspace (excluding directory references) is reported. See Workspaces for the rules for specifying a workspace name.

Examples

      )LOAD WS/TEMP
WS/TEMP saved Thu Sep 17 10:32:19 1998

      )WSID
is WS/TEMP

      )WSID WS/KEEP
was WS/TEMP

      )WSID
WS/KEEP


Load without Latent Expression

Load without Latent Expression: )XLOAD {ws}

This command causes the named stored workspace to be loaded. The current active workspace is lost.

)XLOAD is identical in effect to )LOAD except that )XLOAD does not cause the expression defined by the latent expression ⎕LX in the saved workspace to be executed.


Error Messages

Introduction

The error messages reported by APL are described in this chapter. Standard APL messages that provide information or report error conditions are summarised in APL Error Messages and described later in alphabetical order.

APL also reports messages originating from the Operating System (WINDOWS or UNIX) which are summarised in Typical Operating System Error Messages and Windows Operating System Messages. Only those Operating System error messages that might occur through normal usage of APL operations are described in this manual. Other messages could occur as a direct or indirect consequence of using the Operating System interface functions ⎕CMD and ⎕SH or system commands )CMD and )SH, or when a non-standard device is specified for the system functions ⎕ARBIN or ⎕ARBOUT. Refer to the WINDOWS or UNIX reference manual for further information about these messages.

Most errors may be trapped using the system variable ⎕TRAP, thereby retaining control and inhibiting the standard system action and error report. The table, Trappable Event Codes identifies the error code for trappable errors. The error code is also identified in the heading block for each error message when applicable.

See User Guide for a full description of the Error Handling facilities in Dyalog APL.


Standard Error Action

The standard system action in the event of an error or interrupt whilst executing an expression is to suspend execution and display an error report. If necessary, the state indicator is cut back to a statement such that there is no halted locked function visible in the state indicator.

The error report consists of up to three lines

  1. The error message, preceded by the symbol ⍎ if the error occurred while evaluating the Execute function.
  2. The statement in which the error occurred (or expression being evaluated by the Execute function), preceded by the name of the function and line number where execution is suspended unless the state indicator has been cut back to immediate execution mode. If the state indicator has been cut back because of a locked function in execution, the displayed statement is that from which the locked function was invoked.
  3. The symbol ^ under the last referenced symbol or name when the error occurred. All code to the right of the ^ symbol in the expression will have been evaluated.

Examples

      X PLUS U
VALUE ERROR
      X PLUS U
             ^
      FOO
INDEX ERROR
FOO[2] X←X+A[I]
           ^

      CALC
⍎DOMAIN ERROR
CALC[5] ÷0
        ^


APL Error Messages Table

APL Errors

Table 21: APL Error Messages

Error Code | Report
 | bad ws
 | cannot create name
 | clear ws
 | copy incomplete
1008 | DEADLOCK
 | defn error
11 | DOMAIN ERROR
1005 | EOF INTERRUPT
90 | EXCEPTION
52 | FIELD CONTENTS RANK ERROR
53 | FIELD CONTENTS TOO MANY COLUMNS
54 | FIELD POSITION ERROR
55 | FIELD SIZE ERROR
56 | FIELD CONTENTS/TYPE MISMATCH
57 | FIELD TYPE/BEHAVIOUR UNRECOGNISED
58 | FIELD ATTRIBUTES RANK ERROR
59 | FIELD ATTRIBUTES LENGTH ERROR
60 | FULL-SCREEN ERROR
61 | KEY CODE UNRECOGNISED
62 | KEY CODE RANK ERROR
63 | KEY CODE TYPE ERROR
70 | FORMAT FILE ACCESS ERROR
71 | FORMAT FILE ERROR
19 | FILE ACCESS ERROR
35 | FILE ACCESS ERROR - CONVERTING FILE
38 | FILE COMPONENT DAMAGED
23 | FILE DAMAGED
21 | FILE FULL
20 | FILE INDEX ERROR
22 | FILE NAME ERROR
32 | FILE NAME QUOTA USED UP
26 | FILE SYSTEM ERROR
34 | FILE SYSTEM NO SPACE
28 | FILE SYSTEM NOT AVAILABLE
30 | FILE SYSTEM TIES USED UP
18 | FILE TIE ERROR
24 | FILE TIED
25 | FILE TIED REMOTELY
31 | FILE TIE QUOTA USED UP
7 | FORMAT ERROR
 | incorrect command
12 | HOLD ERROR
3 | INDEX ERROR
 | insufficient resources
99 | INTERNAL ERROR
1003 | INTERRUPT
 | is name
5 | LENGTH ERROR
10 | LIMIT ERROR
16 | NONCE ERROR
72 | NO PIPES
 | name is not a ws
 | Name already exists
 | Namespace does not exist
 | not copied name
 | not found name
 | not saved this ws is name
13 | OPTION ERROR
76 | PROCESSOR TABLE FULL
4 | RANK ERROR
1007 | RESIZE
 | name saved date/time
2 | SYNTAX ERROR
 | sys error number
1006 | TIMEOUT
 | too many names
92 | TRANSLATION ERROR
84 | TRAP ERROR
6 | VALUE ERROR
 | warning duplicate label
 | warning duplicate name
 | warning label name present in line 0
 | warning pendent operation
 | warning unmatched brackets
 | warning unmatched parentheses
 | was name
1 | WS FULL
 | ws not found
 | ws too large


Operating System Error Messages

Table 22 refers to Unix Operating Systems under which the error code reported by Dyalog APL is (100 + the Unix file error number). The text for the error message, which is obtained by calling perror(), will vary from one type of system to another.

Table 23 refers to the equivalent error messages under Windows.

Table 22: Typical Operating System Error Messages

Error Code | Report
101 | FILE ERROR 1 Not owner
102 | FILE ERROR 2 No such file or directory
103 | FILE ERROR 3 No such process
104 | FILE ERROR 4 Interrupted system call
105 | FILE ERROR 5 I/O error
106 | FILE ERROR 6 No such device or address
107 | FILE ERROR 7 Arg list too long
108 | FILE ERROR 8 Exec format error
109 | FILE ERROR 9 Bad file number
110 | FILE ERROR 10 No children
111 | FILE ERROR 11 No more processes
112 | FILE ERROR 12 Not enough code
113 | FILE ERROR 13 Permission denied
114 | FILE ERROR 14 Bad address
115 | FILE ERROR 15 Block device required
116 | FILE ERROR 16 Mount device busy
117 | FILE ERROR 17 File exists
118 | FILE ERROR 18 Cross-device link
119 | FILE ERROR 19 No such device
120 | FILE ERROR 20 Not a directory
121 | FILE ERROR 21 Is a directory
122 | FILE ERROR 22 Invalid argument
123 | FILE ERROR 23 File table overflow
124 | FILE ERROR 24 Too many open files
125 | FILE ERROR 25 Not a typewriter
126 | FILE ERROR 26 Text file busy
127 | FILE ERROR 27 File too large
128 | FILE ERROR 28 No space left on device
129 | FILE ERROR 29 Illegal seek
130 | FILE ERROR 30 Read-only file system
131 | FILE ERROR 31 Too many links
132 | FILE ERROR 32 Broken pipe
133 | FILE ERROR 33 Math argument
134 | FILE ERROR 34 Result too large


Windows Operating System Error Messages

Table 23: Windows Operating System Messages

Error Code | Report
101 | FILE ERROR 1 No such file or directory
102 | FILE ERROR 2 No such file or directory
103 | FILE ERROR 3 Exec format error
105 | FILE ERROR 5 Not enough memory
106 | FILE ERROR 6 Permission denied
107 | FILE ERROR 7 Argument list too big
108 | FILE ERROR 8 Exec format error
109 | FILE ERROR 9 Bad file number
111 | FILE ERROR 11 Too many open files
112 | FILE ERROR 12 Not enough memory
113 | FILE ERROR 13 Permission denied
114 | FILE ERROR 14 Result too large
115 | FILE ERROR 15 Resource deadlock would occur
117 | FILE ERROR 17 File exists
118 | FILE ERROR 18 Cross-device link
122 | FILE ERROR 22 Invalid argument
123 | FILE ERROR 23 File table overflow
124 | FILE ERROR 24 Too many open files
133 | FILE ERROR 33 Argument too large
134 | FILE ERROR 34 Result too large
145 | FILE ERROR 45 Resource deadlock would occur


bad ws

This report is given when an attempt is made to )COPY or )PCOPY from a file that is not a valid workspace file. Invalid files include workspaces that were created by a version of Dyalog APL later than the version currently being used.


cannot create name

This report is given when an attempt is made to )SAVE a workspace with a name that is either the name of an existing, non-workspace file, or the name of a workspace that the user does not have permission to overwrite or create.


clear ws

This message is displayed when the system command )CLEAR is issued.

Example

      )CLEAR
clear ws


copy incomplete

This report is given when an attempted )COPY or )PCOPY fails to complete. Reasons include:

  • Failure to identify the incoming file as a workspace.
  • Not enough active workspace to accommodate the copy.


DEADLOCK

DEADLOCK 1008

If two threads succeed in acquiring a hold of two different tokens, and then each asks to hold the other token, they will both stop and wait for the other to release its token. The interpreter detects such cases and issues an error (1008) DEADLOCK.


defn error

This report is given when either:

  • The system editor is invoked in order to edit a function that does not exist, or the named function is pendent or locked, or the given name is an object other than a function.
  • The system editor is invoked to define a new function whose name is already active.
  • The header line of a function is replaced or edited in definition mode with a line whose syntax is incompatible with that of a header line. The original header line is re-displayed by the system editor with the cursor placed at the end of the line. Back-spacing to the beginning of the line followed by line-feed restores the original header line.

Examples

      X←1
      ∇X
defn error

      ∇FOO[0⎕]
[0]   R←FOO
[0]   R←FOO:X
defn error
[0]   R←FOO:X

      ⎕LOCK'FOO'
      ∇FOO[⎕]
defn error


DOMAIN ERROR

DOMAIN ERROR 11

This report is given when either:

  • An argument of a function is not of the correct type or its numeric value is outside the range of permitted values or its character value does not constitute valid name(s) in the context.
  • An array operand of an operator is not an array, or it is not of the correct type, or its numeric value is outside the range of permitted values. A function operand of an operator is not one of a prescribed set of functions.
  • A value assigned to a system variable is not of the correct type, or its numeric value is outside the range of permitted values
  • The result produced by a function includes numeric elements which cannot be fully represented.

Examples

      1÷0
DOMAIN ERROR
      1÷0
      ^

      (×∘'CAT')2 4 6
DOMAIN ERROR
      (×∘'CAT')2 4 6
      ^

      ⎕IO←5
DOMAIN ERROR
      ⎕IO←5
      ^


EOF INTERRUPT

EOF INTERRUPT 1005

This report is given on encountering the end-of-file when reading input from a file. This condition could occur when an input to APL is from a file.


EXCEPTION

EXCEPTION 90

This report is given when a Microsoft .Net object throws an exception. For details see Exception: .


FIELD CONTENTS RANK ERROR

FIELD CONTENTS RANK ERROR 52

This report is given if a field content of rank greater than 2 is assigned to ⎕SM.


FIELD CONTENTS TOO MANY COLUMNS

FIELD CONTENTS TOO MANY COLUMNS 53

This report is given if the content of a numeric or date field assigned to ⎕SM has more than one column.


FIELD POSITION ERROR

FIELD POSITION ERROR 54

This report is given if the location of the field assigned to ⎕SM is outside the screen.


FIELD CONTENTS TYPE MISMATCH

FIELD CONTENTS TYPE MISMATCH 56

This report is given if the field contents assigned to ⎕SM does not conform with the given field type e.g. character content with numeric type.


FIELD TYPE BEHAVIOUR UNRECOGNISED

FIELD TYPE BEHAVIOUR UNRECOGNISED 57

This report is given if the field type or behaviour code assigned to ⎕SM is invalid.


FIELD ATTRIBUTES RANK ERROR

FIELD ATTRIBUTES RANK ERROR 58

This report is given if the current video attribute assigned to ⎕SM is non-scalar but its rank does not match that of the field contents.


FIELD ATTRIBUTES LENGTH ERROR

FIELD ATTRIBUTES LENGTH ERROR 59

This report is given if the current video attribute assigned to ⎕SM is non-scalar but its dimensions do not match those of the field contents.


FULL SCREEN ERROR

FULL SCREEN ERROR 60

This report is given if the required full screen capabilities are not available to ⎕SM. This report is only generated in UNIX environments.


KEY CODE UNRECOGNISED

KEY CODE UNRECOGNISED 61

This report is given if a key code supplied to ⎕SR or ⎕PFKEY is not recognised as a valid code.


KEY CODE RANK ERROR

KEY CODE RANK ERROR 62

This report is given if a key code supplied to ⎕SR or ⎕PFKEY is not a scalar or a vector.


KEY CODE TYPE ERROR

KEY CODE TYPE ERROR 63

This report is given if a key code supplied to ⎕SR or ⎕PFKEY is numeric or nested; i.e. is not a valid key code.


FORMAT FILE ACCESS ERROR

FORMAT FILE ACCESS ERROR 70

This report is given if the date format file to be used by ⎕SM does not exist or cannot be accessed.


FORMAT FILE ERROR

FORMAT FILE ERROR 71

This report is given if the date format file to be used by ⎕SM is ill-formed.


FILE ACCESS ERROR

FILE ACCESS ERROR 19

This report is given when the user attempts to execute a file system function for which the user is not authorised, or has supplied the wrong passnumber. It also occurs if the file specified as the argument to ⎕FERASE or ⎕FRENAME is not exclusively tied.

Examples

      'SALES' ⎕FSTIE 1

      ⎕FRDAC 1
0 4121 0
0 4137 99

      X ⎕FREPLACE 1
FILE ACCESS ERROR
      X ⎕FREPLACE 1
      ^

      'SALES' ⎕FERASE 1
FILE ACCESS ERROR
      'SALES' ⎕FERASE 1
      ^


FILE ACCESS ERROR CONVERTING

When a new version of Dyalog APL is used, it may be that improvements to the component file system demand that the internal structure of component files must alter. This alteration is performed by the interpreter on the first occasion that the file is accessed. If the operating system file permissions deny the ability to perform such a restructure, this report is given.


FILE COMPONENT DAMAGED

FILE COMPONENT DAMAGED 38

This report is given if an attempt is made to access a component that is not a valid APL object. This will rarely occur, but may happen as a result of a previous computer system failure. Components files may be checked using qfsck. (See User Guide.)


FILE DAMAGED

FILE DAMAGED 23

This report is given if a component file becomes damaged. This rarely occurs but may result from a computer system failure. Components files may be checked using qfsck. (See User Guide.)


FILE FULL

FILE FULL 21

This report is given if the file operation would cause the file to exceed its file size limit.


FILE INDEX ERROR

FILE INDEX ERROR 20

This report is given when an attempt is made to reference a non-existent component.

Example

      ⎕FSIZE 1
1 21 16578 4294967295

      ⎕FREAD 1 34
FILE INDEX ERROR
      ⎕FREAD 1 34
      ^
      ⎕FDROP 1 50
FILE INDEX ERROR
      ⎕FDROP 1 50
      ^


FILE NAME ERROR

FILE NAME ERROR 22

This report is given if:

  • the user attempts to ⎕FCREATE using the name of an existing file.
  • the user attempts to ⎕FTIE or ⎕FSTIE a non-existent file, or a file that is not a component file.
  • the user attempts to ⎕FERASE a component file with a name other than the EXACT name that was used when the file was tied.


FILE NAME QUOTA USED UP

FILE NAME QUOTA USED UP 32

This report is given when the user attempts to execute a file system command that would result in the User's File Name Quota (see User Guide) being exceeded.

This can occur with ⎕FCREATE, ⎕FTIE, ⎕FSTIE or ⎕FRENAME .


FILE SYSTEM ERROR

FILE SYSTEM ERROR 26

This report is given if the File System Control Block (FSCB) is removed or altered while files are tied.

Contact the System Administrator. If this occurs when a file is share-tied, the file may be damaged. It is therefore advisable to check the integrity of all such files using qfsck.

See User Guide for details.


FILE SYSTEM NO SPACE

FILE SYSTEM NO SPACE 34

This report is given if the user attempts a file operation that cannot be completed because there is insufficient disk space.


FILE SYSTEM NOT AVAILABLE

FILE SYSTEM NOT AVAILABLE 28

This report is given if the File System Control Block (FSCB) is missing or inaccessible. See User Guide for details.


FILE SYSTEM TIES USED UP

FILE SYSTEM TIES USED UP 30

This report is given if the File System Control Block (FSCB) is full. See User Guide for details.


FILE TIE ERROR

FILE TIE ERROR 18

This report is given when the argument to a file system function contains a file tie number used as if it were tied when it is not or as if it were available when it is already tied. It also occurs if the argument to ⎕FHOLD contains the names of non-existent external variables.

Examples

      ⎕FNAMES,⎕FNUMS
SALES  1
COSTS  2
PROFIT 3

      X ⎕FAPPEND 4
FILE TIE ERROR
      X ⎕FAPPEND 4
      ^
      'NEWSALES' ⎕FCREATE 2
FILE TIE ERROR
      'NEWSALES' ⎕FCREATE 2
      ^

      'EXTVFILE' ⎕XT'BIGMAT'
      ⎕FHOLD 'BIGMAT'
FILE TIE ERROR
      ⎕FHOLD 'BIGMAT'
      ^
      ⎕FHOLD⊂'BIGMAT'


FILE TIED

FILE TIED 24

This report is given if the user attempts to tie a file that is exclusively tied by another task, or attempts to exclusively tie a file that is already share-tied by another task.


FILE TIED REMOTELY

FILE TIED REMOTELY 25

This report is given if the user attempts to tie a file that is exclusively tied by another task, or attempts to exclusively tie a file that is already share-tied by another task; and that task is running on other than the user's processor.


FILE TIE QUOTA USED UP

FILE TIE QUOTA USED UP 31

This report is given if an attempt is made to ⎕FTIE, ⎕FSTIE or ⎕FCREATE a file when the user already has the maximum number of files tied. (See File Tie Quota , User Guide)


FORMAT ERROR

FORMAT ERROR 7

This report is given when the format specification in the left argument of system function ⎕FMT is ill-formed.

Example

      'A1,1X,I5'⎕FMT CODE NUMBER
FORMAT ERROR
      'A1,1X,I5'⎕FMT CODE NUMBER
       ^

(The correct specification should be 'A1,X1,I5' .)


HOLD ERROR

HOLD ERROR 12

This report is given when an attempt is made to save a workspace using the system function ⎕SAVE if any external arrays or component files are currently held (as a result of a prior use of the system function ⎕FHOLD).

Example

      ∇HOLD∆SAVE
[1]    ⎕FHOLD 1
[2]    ⎕SAVE 'TEST'
      ∇

      'FILE' ⎕FSTIE 1

      HOLD∆SAVE
HOLD ERROR
HOLD∆SAVE[2] ⎕SAVE'TEST'
             ^


incorrect command

This report is given when an unrecognised system command is entered.

Example

      )CLERA
incorrect command


INDEX ERROR

INDEX ERROR 3

This report is given when either:

  • The value of an index, whilst being within comparison tolerance of an integer, is outside the range of values defined by the index vector along an axis of the array being indexed. The permitted range is dependent on the value of ⎕IO.
  • The value specified for an axis, whilst being within comparison tolerance of an integer for a derived function requiring an integer axis value or a non-integer for a derived function requiring a non-integer, is outside the range of values compatible with the rank(s) of the array argument(s) of the derived function. Axis is dependent on the value of ⎕IO.

Examples

      A
1 2 3
4 5 6

      A[1;4]
INDEX ERROR
      A[1;4]
      ^

      ↑ [2]'ABC' 'DEF'
INDEX ERROR
      ↑ [2]'ABC' 'DEF'
      ^


INTERNAL ERROR

INTERNAL ERROR 99

INTERNAL ERROR indicates a severe system error from which Dyalog APL has recovered.

Should you encounter INTERNAL ERROR, Dyalog strongly recommends that you save your work(space) , and report the issue.


INTERRUPT

INTERRUPT 1003

This report is given when execution is suspended by entering a hard interrupt. A hard interrupt causes execution to suspend as soon as possible without leaving the environment in a damaged state.

Example

      1 1 2 ⍉(2 100⍴⍳200)∘.|?1000⍴200

(Hard interrupt)

INTERRUPT
      1 1 2 ⍉(2 100⍴⍳200)∘.|?1000⍴200
            ^


is name

This report is given in response to the system command )WSID when used without a parameter. name is the name of the active workspace including directory references given when loaded or named. If the workspace has not been named, the system reports is CLEAR WS.

Example

      )WSID
is WS/UTILITY


LENGTH ERROR

LENGTH ERROR 5

This report is given when the shape of the arguments of a function do not conform, but the ranks do conform.

Example

      2 3+4 5 6
LENGTH ERROR
      2 3+4 5 6
      ^


LIMIT ERROR

LIMIT ERROR 10

This report is given when a system limit is exceeded. System limits are installation dependent.

Example

      (16⍴1)⍴1
LIMIT ERROR
      (16⍴1)⍴1
      ^


NONCE ERROR

NONCE ERROR 16

This report is given when a system function or piece of syntax is not currently implemented but is reserved for future use.


NO PIPES

NO PIPES 72

This message applies to the UNIX environment ONLY.

This message is given when the limit on the number of pipes communicating between tasks is exceeded. An installation-set quota is assigned for each task. An associated task may require more than one pipe. The message occurs on attempting to exceed the account's quota when either:

  • An APL session is started
  • A non-APL task is started by the system function ⎕SH
  • An external variable is used.

It is necessary to release pipes by terminating sufficient tasks before proceeding with the required activity. In practice, the error is most likely to occur when using the system function ⎕SH.

Examples

      'via' ⎕SH 'via'
NO PIPES
      'via' ⎕SH 'via'
      ^

      'EXT/ARRAY' ⎕XT 'EXVAR'
NO PIPES
      'EXT/ARRAY' ⎕XT 'EXVAR'
                  ^


name is not a ws

This report is given when the name specified as the parameter of the system commands )LOAD, )COPY or )PCOPY is a reference to an existing file or directory that is not identified as a workspace.

This will also occur if an attempt is made to )LOAD a workspace that was )SAVE’d using a later version of Dyalog APL.

Example

      )LOAD EXT\ARRAY
EXT\ARRAY is not a ws


Name already exists

This report is given when an )NS command is issued with a name which is already in use for a workspace object other than a namespace.


Namespace does not exist

This report is given when a )CS command is issued with a name which is not the name of a global namespace.


not copied name

This report is given for each object named or implied in the parameter list of the system command )PCOPY which was not copied because of an existing global referent to that name in the active workspace.

Example

      )PCOPY WS/UTILITY A FOO Z
WS/UTILITY saved Mon Nov 1 13:11:19 1993
not copied Z


not found name

This report is given when either:

  • An object named in the parameter list of the system command )ERASE is not erased because it was not found or it is not eligible to be erased.
  • An object named in the parameter list (or implied list) of names to be copied from a saved workspace for the system commands )COPY or )PCOPY is not copied because it was not found in the saved workspace.

Examples

      )ERASE ⎕IO
not found ⎕IO

      )COPY WS/UTILITY UND
WS/UTILITY saved Mon Nov 1 13:11:19 1993
not found UND


not saved this ws is name

This report is given in the following situations:

  • When the system command )SAVE is used without a name, and the workspace is not named. In this case the system reports not saved this ws is CLEAR WS.
  • When the system command )SAVE is used with a name, and that name is not the current name of the workspace, but is the name of an existing file.

In neither case is the workspace renamed.

Examples

      )CLEAR
      )SAVE
not saved this ws is CLEAR WS

      )WSID JOHND
      )SAVE
      )WSID ANDYS
      )SAVE JOHND
not saved this ws is ANDYS


OPTION ERROR

OPTION ERROR 13

This report is given when an invalid right operand is given to the Variant operator ⍠ or ⎕OPT.


PROCESSOR TABLE FULL

PROCESSOR TABLE FULL 76

This report can only occur in a UNIX environment.

This report is given when the limit on the number of processes (tasks) that the computer system can support would be exceeded. The limit is installation dependent. The report is given when an attempt is made to initiate a further process, occurring when an APL session is started.

It is necessary to wait until active processes are completed before the required task may proceed. If the condition should occur frequently, the solution is to increase the limit on the number of processes for the computer system.

Example

      'prefect' ⎕SH 'prefect'
PROCESSOR TABLE FULL
      'prefect' ⎕SH 'prefect'
      ^


RANK ERROR

RANK ERROR 4

This report is given when the rank of an argument or operand does not conform to the requirements of the function or operator, or the ranks of the arguments of a function do not conform.

Example

      2 3 + 2 2⍴10 11 12 13
RANK ERROR
      2 3 + 2 2⍴10 11 12 13
      ^


RESIZE

RESIZE 1007

This report is given when the user resizes the ⎕SM window. It is only applicable to Dyalog APL/X and Dyalog APL/W.


name saved date time

This report is given when a workspace is saved, loaded or copied.

date/time is the date and time at which the workspace was most recently saved.

Examples

      )LOAD WS/UTILITY
WS/UTILITY saved Fri Sep 11 10:34:35 1998

      )COPY SPACES GEOFF JOHND VINCE
./SPACES saved Wed Sep 30 16:12:56 1998


SYNTAX ERROR

SYNTAX ERROR 2

This report is given when a line of characters does not constitute a meaningful statement. This condition occurs when either:

  • An illegal symbol is found in an expression.
  • Brackets, parentheses or quotes in an expression are not matched.
  • Parentheses in an expression are not matched.
  • Quotes in an expression are not matched.
  • A value is assigned to a function, label, constant or system constant.
  • A strictly dyadic function (or derived function) is used monadically.
  • A monadic function (or derived function) is used dyadically.
  • A monadic or dyadic function (or derived function) is used without any arguments.
  • The operand of an operator is not an array when an array is required.
  • The operand of an operator is not a function (or derived function) when a function is required.
  • The operand of an operator is a function (or derived function) with incorrect valency.
  • A dyadic operator is used with only a single operand.
  • An operator is used without any operands.

Examples

      A>10)/A
SYNTAX ERROR
      A>10)/A
      ^

      ⊤2 4 8
SYNTAX ERROR
      ⊤2 4 8
      ^

      A.+1 2 3
SYNTAX ERROR
      A.+1 2 3
      ^


sys error number

This report is given when an internal error occurs in Dyalog APL.

Under UNIX it may be necessary to enter a hard interrupt to obtain the UNIX command prompt, or even to kill your processes from another screen. Under WINDOWS it may be necessary to reboot your PC.

If this error occurs, please submit a fault report to your Dyalog APL distributor.


TIMEOUT

TIMEOUT 1006

This report is given when the time limit specified by the system variable ⎕RTL is exceeded while awaiting input through character input (⍞) or ⎕SR.

It is usual for this error to be trapped.

Example

      ⎕RTL←5 ⋄ ⍞←'RESPOND WITHIN 5 SECONDS: ' ⋄ R←⍞
RESPOND WITHIN 5 SECONDS:
TIMEOUT
      ⎕RTL←5 ⋄ ⍞←'RESPOND WITHIN 5 SECONDS: ' ⋄ R←⍞
                                                  ^


TRANSLATION ERROR

TRANSLATION ERROR 92

This report is given when the system cannot convert a character from Unicode to an Atomic Vector index or vice versa. Conversion is controlled by the value of ⎕AVU. Note that this error can occur when you reference a variable whose value has been obtained by reading data from a TCPSocket or by calling an external function. This is because in these cases the conversion to/from ⎕AV is deferred until the value is used.


TRAP ERROR

TRAP ERROR 84

This report is given when a workspace full condition occurs whilst searching for a definition set for the system variable ⎕TRAP after a trappable error has occurred. It does not occur when an expression in a ⎕TRAP definition is being executed.


too many names

This report is given by the function editor when the number of distinct names (other than distinguished names beginning with the symbol ⎕) referenced in a defined function exceeds the system limit of 4096.


VALUE ERROR

VALUE ERROR 6

This report is given when either:

  • There is no active definition for a name encountered in an expression.
  • A function does not return a result in a context where a result is required.

Examples

     X
VALUE ERROR
     X
     ^

     ∇ HELLO
[1]    'HI THERE'
[2]  ∇

     2+HELLO
HI THERE
VALUE ERROR
     2+HELLO
      ^


warning duplicate label

This warning message is reported on closing definition mode when one or more labels are duplicated in the body of the defined function. This does not prevent the definition of the function in the active workspace. The value of a duplicated label is the lowest of the line-numbers in which the labels occur.


warning duplicate name

This warning message is reported on closing definition mode when one or more names are duplicated in the header line of the function. This may be perfectly valid. Definition of the function in the active workspace is not prevented. The order in which values are associated with names in the header line is described in Defined Functions & Operators.


warning pendent operation

This report is given on opening and closing definition mode when attempting to edit a pendant function or operator.

Example

[0]   ∇FOO
[1]    GOO
[2]   ∇

[0]   ∇GOO
[1]    ∘
[2]   ∇

      FOO
SYNTAX ERROR
GOO[1] ∘
       ^

      ∇FOO
warning pendent operation
[0]   ∇FOO
[1]    GOO
[2]   ∇
warning pendent operation


warning label name present

This warning message is reported on closing definition mode when one or more label names also occur in the header line of the function. This does not prevent definition of the function in the active workspace. The order in which values are associated with names is described in Defined Functions & Operators.


warning unmatched brackets

This report is given after adding or editing a function line in definition mode when it is found that there is not an opening bracket to match a closing bracket, or vice versa, in an expression. This is a warning message only. The function line will be accepted even though syntactically incorrect.

Example

[3]   A[;B[;2]←0
warning unmatched brackets
[4]


warning unmatched parentheses

This report is given after adding or editing a function line in definition mode when it is found that there is not an opening parenthesis to match a closing parenthesis, or vice versa, in an expression. This is a warning message only. The function line will be accepted even though syntactically incorrect.

Example

[4]   X←(E>2)^E<10)⌿A
warning unmatched parentheses
[5]


was name

This report is given when the system command )WSID is used with a parameter specifying the name of a workspace. The message identifies the former name of the workspace. If the workspace was not named, the given report is was CLEAR WS.

Example

      )WSID TEMP
was UTILITY


WS FULL

WS FULL 1

This report is given when there is insufficient workspace in which to perform an operation. Workspace available is identified by the system constant ⎕WA.

The maximum workspace size allowed is defined by the environment variable MAXWS. See User Guide for details.

Example

      ⎕WA⍴1.2
WS FULL
      ⎕WA⍴1.2
      ^


ws not found

This report is given when a workspace named by the system commands )LOAD, )COPY or )PCOPY does not exist as a file, or when the user does not have read access authorisation for the file.

Examples

      )LOAD NOWS
ws not found

      )COPY NOWS A FOO X
ws not found


ws too large

This report is given when:

  • the user attempts to )LOAD a workspace that needs a greater work area than the maximum that the user is currently permitted.
  • the user attempts to )COPY or )PCOPY from a workspace that would require a greater work area than the user is currently permitted if the workspace were to be loaded.

The maximum work area permitted is set using the environment variable MAXWS.


FILE ERROR 1 Not owner

FILE ERROR 1 Not owner 101

This report is given when an attempt is made to modify a file in a way which is forbidden except to the owner or super-user, or in some instances only to a super-user.


FILE ERROR 2 No such file

This report is given when a file (which should exist) does not exist, or when a directory in a path name does not exist.


FILE ERROR 5 I O error

FILE ERROR 5 I O error 105

This report is given when a physical I/O error occurred whilst reading from or writing to a device, indicating a hardware fault on the device being accessed.


FILE ERROR 6 No such device

This report is given when a device does not exist or the device is addressed beyond its limits. Examples are a tape which has not been mounted or a tape which is being accessed beyond the end of the tape.


FILE ERROR 13 Permission denied

FILE ERROR 13 Permission denied 113

This report is given when an attempt is made to access a file in a way forbidden to the account.


FILE ERROR 20 Not a directory

FILE ERROR 20 Not a directory 120

This report is given when the request assumes that a directory name is required but the name specifies a file or is not a legal name.


FILE ERROR 21 Is a directory

FILE ERROR 21 Is a directory 121

This report is given when an attempt is made to write into a directory.


FILE ERROR 23 File table overflow

FILE ERROR 23 File table overflow 123

This report is given when the system limit on the number of open files is full and a request is made to open another file. It is necessary to wait until the number of open files is reduced. If this error occurs frequently, the system limit should be increased.


FILE ERROR 24 Too many open

This report is given when the task limit on the number of open files is exceeded. It may occur when an APL session is started or when a shell command is issued to start an external process through the system command ⎕SH. It is necessary to reduce the number of open files. It may be necessary to increase the limit on the number of open files to overcome the problem.


FILE ERROR 26 Text file busy

FILE ERROR 26 Text file busy 126

This report is given when an attempt is made to write a file which is a load module currently in use. This situation could occur on assigning a value to an external variable whose associated external file name conflicts with an existing load module's name.


FILE ERROR 27 File too large

FILE ERROR 27 File too large 127

This report is given when a write to a file would cause the system limit on file size to be exceeded.


FILE ERROR 28 No space left

This report is given when a write to a file would exceed the capacity of the device containing the file.


FILE ERROR 30 Read only file

This report is given when an attempt is made to write to a device which can only be read from. This would occur with a write-protected tape.


GUI Overview

The Dyalog APL GUI is based upon the concepts of objects, properties, events and methods.

Objects

Objects are instances of classes that contain information and provide functionality. Most Dyalog APL objects are GUI objects that may be displayed on the screen and with which you can interact. An example of an object is a push-button (an instance of class Button) which you may press to cause the program to take a particular action. Objects are defined in hierarchies.

Properties

Each object has an associated set of properties which describe how it looks and behaves. For example, a Button has a property called Caption which defines the character string to be displayed in it.

Events

During interaction with the user, an object is capable of generating events.

An example is the Select event. For a Button object, this event is generated when the user presses the Button. This can be done in several ways. Firstly, the user may click the left mouse button over the object. Secondly, under certain circumstances, the Select event can be generated when the user presses the Enter key. Finally, the event will occur if the user presses a "short-cut" (mnemonic) key that is associated with the Button.

Methods

Methods are effectively functions that an object provides; they are things that you may invoke to make the object do something for you. In Dyalog APL, the distinction between methods and events is tenuous, because events also make objects perform actions and you may generate events under program control. For example, a Scroll event is generated by a scrollbar when the user moves the thumb. Conversely, you can make a scrollbar scroll by generating a Scroll event. Nevertheless, the concept of a method is useful to describe functions that can only be invoked by a program and are not directly accessible to the user.

Object Management Functions

This is a set of system functions used to create objects, set properties, respond to events, and call methods.


Objects Categorised

Objects: A-Z

System Objects
Root | system-level object
Printer | for hard-copy output
Clipboard | provides access to Windows clipboard
Container Objects
CoolBand | represents a band in a CoolBar
CoolBar | a container for CoolBand objects
Form | top-level Window
MDIClient | container for MDI windows
SubForm | acts as an MDI window or a constrained Form
Group | a frame for grouping Buttons and other objects
Static | a frame for drawing and clipping graphics
StatusBar | ribbon status bar
TabBar | contains TabBtns (tabs)
TabControl | contains TabButtons (tabs)
ToolBar | ribbon tool bar
ToolControl | standard Windows tool control
PropertySheet | contains PropertyPages
PropertyPage | tabbed or paged container for other controls
Splitter | divides a container into panes
Menu
MenuBar | pull-down menu bar
Menu | pop-up menu
MenuItem | selects an option or action
Separator | separator between items
Action |
Button | selects an option
ToolButton | performs an action or selects an option
TabBtn | selects a tabbed SubForm
TabButton | selects a tabbed SubForm
Scroll | scroll bar
UpDown | spin buttons
Locator | graphical (positional) input device
Timer | generates events at regular intervals
Information
Label | displays static text
StatusField | displays status information
MsgBox | displays a message box
TipField | displays pop-up context sensitive help
ProgressBar | displays the progress of a lengthy operation
Input & Selection
Calendar | displays a month calendar control
Grid | displays a data matrix as a spreadsheet
Edit | text input field
ButtonEdit | text input field with dropdown button
RichEdit | text input with word-processing capabilities
Spinner | input field with spin buttons
List | for selecting an item
ListView | displays a collection of items for selection
Combo | edit field with selectabe list of choices
TreeView | displays a hierarchical collection of items
TrackBar | a slider control for analogue input/output
FileBox | prompts user to select a file
Resource
Font | loads a font
Bitmap | defines a bitmap
Icon | defines an icon
ImageList | defines a collection of bitmaps or icons
Metafile | loads a Windows Metafile
Cursor | defines a cursor
Graphical Output
Circle | draws a circle
Ellipse | draws an ellipse
Marker | draws a series of polymarkers
Poly | draws lines
Rect | draws rectangles
Image | displays Bitmaps, Icons and Metafiles
Text | draws graphical text
Miscellaneous
ActiveXContainer | represents the application hosting a Dyalog APL ActiveXControl
ActiveXControl | represents an ActiveX control written in Dyalog APL
NetClient | provides access to .Net Classes
NetControl | instantiates a .Net Control.
NetType | exports an APL namespace as a Net Class
OCXClass | provides access to OLE Custom Controls
OLEClient | provides access to OLE Automation objects
OLEServer | enables APL to act as an OLE Automation server
SM | specifies a window for ⎕SM(character mode interface)
TCPSocket | provides an interface to TCP/IP sockets


Objects A-Z

Objects: Categorised

Object | Description
ActiveXContainer | represents the application hosting a Dyalog APL ActiveXControl
ActiveXControl | implements an ActiveX control written in Dyalog APL
Animation | plays simple AVIs
Bitmap | can be used to fill an area, or as a background pattern
BrowseBox | allows the user to browse for a folder or other resource
Button | used to perform a task or select an option
ButtonEdit | single-line input field with custom button
Calendar | displays a month calendar control
Circle | draws circles, arcs and pies
Clipboard | provides access to the Windows clipboard
ColorButton | allows the user to select a colour
Combo | combines text entry field with list of choices
ComboEx | an extended version of the Combo object that provides additional features including item images
CoolBand | represents a band in a CoolBar
CoolBar | acts as a container for CoolBand objects
Cursor | creates user-defined cursor
DateTimePicker | an editable date/time field with an optional drop-down Calendar
Edit | single or multi-line edit box for entering data
Ellipse | draws ellipses, elliptical arcs and pies
FileBox | standard File Selection dialog box
Font | a font resource
Form | window that acts as a container for other objects
Grid | spreadsheet object for editing data
Object | Description
Icon | can be displayed, or used when a Form is minimized
Image | graphical object for displaying bitmaps and icons
ImageList | specifies a collection of bitmaps or icons for a ListView or TreeView
Label | fixed text that the user cannot change
List | list of items from which the user can choose
ListView | collection of items from which the user can choose
Locator | moving line, rectangle or ellipse for graphics input
Marker | draws marker at a series of points
MDIClient | provides Multiple Document Interface (MDI) behaviour
Menu | displays a pulldown or pop-up menu
MenuBar | displays list of pulldown menus across top of Form
MenuItem | component of a Menu that performs action or makes choice
Metafile | provides access to Windows Metafiles
MsgBox | displays message in dialog box and waits for response
NetClient | Provides access to .NET Classes
NetType | Exports a namespace as a .NET class
OCXClass | provides access to OLE Custom Controls
OLEClient | provides access to OLE Automation objects
OLEServer | enables APL to act as an OLE Automation server
Poly | draws lines, polygons and filled areas
Printer | controls output to a printer
ProgressBar | indicates the progress of a lengthy operation
PropertyPage | tabbed or paged container for other controls
PropertySheet | container for PropertyPages
Rect | draws filled and unfilled rectangles
RichEdit | an edit box with word-processing capabilities
Root | the system object that is the progenitor of all others
Object | Description
Scroll | horizontal or vertical scrollbar
Separator | horizontal or vertical line in Menu, or vertical break in MenuBar
SM | allows ⎕SM and ⎕SRto be used with GUI objects
Spinner | input field with spin buttons
Splitter | divides a Form or SubForm into resizable panes
Static | frame or box used to contain graphics
StatusBar | manages a set of StatusField objects
StatusField | displays context-sensitive help, or keyboard status
SubForm | child Form that is constrained within its parent
SysTrayItem | represents an item that you can create in the Windows system tray
TabBar | manages a set of TabBtn objects
TabBtn | brings forward an associated SubForm
TabButton | represents a tab or button in a TabControl
TabControl | represents the standard Windows tab control
TCPSocket | provides an interface to TCP/IP sockets
Text | displays or prints arbitrary text
Timer | generates events at regular intervals
TipField | displays pop-up context-sensitive help
ToolBar | manages a block of controls including Buttons
ToolButton | represents a or button in a ToolControl
ToolControl | represents the standard Windows tool control
TrackBar | slider control for analogue input/output
TreeView | displays a hierarchical list of items
UpDown | a pair of arrow buttons


Properties A-Z
Property | Description
Accelerator | specifies keystroke that will generate Select event
Active | determines whether object can generate events
Align | determines the position of text or for Scroll object
AlignChar | specifies a character for column alignment in a Grid
AlwaysShowBorder | specifies how the current cell in a Grid is displayed when the Grid loses focus.
AlwaysShowSelection | specifies how the highlighted selection in an object is displayed when the object loses focus.
APLVersion | reports the version of Dyalog APL being run
ArcMode | determines how arcs are drawn (Ellipse)
Attach | specifies how object is reconfigured when parent is resized
AutoArrange | whether or not items in a ListView are rearranged automatically
AutoBrowse | specifies whether or not functions and variables are fixed when an OLEClient is created
AutoConf | how a child reacts to its parent being resized
AutoExpand | whether rows and columns are added to a Grid
BandBorders | Specifies whether or not narrow lines are drawn to separate adjacent bands in a CoolBar
BCol | specifies background colour
Bits | defines the pattern for a Bitmap, Cursor, or Icon
Border | determines whether or not an object has a border
BtnPix | associates Bitmaps with Button, Menu and MenuItem objects
Btns | determines the buttons shown in a MsgBox
ButtonsAcceptFocus | affects the keyboard handling in a ToolControl
CalendarCols | Specifies the colours used for various elements in the Calendar object
Cancel | used to associate the Esc key with a particular Button
Caption | specifies text in an object
CBits | represents the picture in a Bitmap object
CellFonts | specifies fonts to be used by the cells in a Grid
CellHeights | specifies the heights of the cells in a Grid
CellSelect | specifies the type(s) of selection a user can perform in a Grid
CellSet | flags which cells in a Grid have values and which are empty
CellTypes | specifies the type of the cells in a Grid
Cells | specifies the widths of cells in a Grid
Changed | flags whether or not data in an object has been changed
CharFormat | specifies character formatting in a RichEdit
CharSet | specifies the character encoding of a Font object.
CheckBoxes | specifies whether or not check boxes are displayed alongside items in a ListView or TreeView object
Checked | determines whether check mark is displayed by MenuItem
ChildEdge | specifies whether or not a CoolBand leaves space above and below its child window
ChildList | reports the types of object that may be children of an object
CircleToday | specifies whether or not a circle is drawn around the Today date in a Calendar object
ClassID | reports the CLSID of an OLEClient or OLEServer
ClassName | specifies the name of the OLE object to which an OLEClient object is to be connected.
ClipCells | specifies whether or not columns of a Grid are clipped.
CMap | defines a colour map for a Bitmap or Icon
ColLineTypes | specifies the appearance of vertical grid lines in a Grid.
ColSortImages | specifies the images to be used to display sort images in the column titles of a Grid.
ColTitle3D | specifies the appearance of column titles for a ListView
ColTitleAlign | specifies the alignment of column titles
ColTitleBCol | specifies the background colour for column titles
ColTitleDepth | specifies the structure of hierarchical column titles for a Grid
ColTitleFCol | specifies the colour of the row titles in a Grid
ColTitles | specifies the column titles for a Grid or ListView
Column | specifies the width of columns for a multi-column List
Container | the Object Representation of an ActiveXContainer object
Coord | specifies the coordinate system for an object
Cue | specifies text displayed in an empty input field
CurCell | identifies the current cell in a Grid
CurrentColor | Specifies the currently selected colour in a ColorButton object
CurrentState | reports the current state of a TCPSocket object
CursorObj | associates a cursor with an object
CustomColors | Specifies the custom colors associated with a ColorButton object
Decimals | specifies the number of decimal places for a Numeric field
Default | nominates a Button to be selected with the Enter key
DefaultColors | Specifies the default colors associated with a ColorButton object
Depth | specifies the structure of items for a TreeView
DevCaps | reports the device capabilities of the screen or printer
Directory | specifies the directory for a FileBox
Divider | controls the presence or absence of a recessed line in a ToolControl object
Dragable | specifies whether user may drag an object with the mouse
Dragitems | specifies whether user may drag/drop items in a ListView
Dragitems | specifies whether user may drag/drop items in a ListView
DrawMode | provides direct control over the low-level drawing operation performed by graphical objects
EdgeStyle | specifies 3-dimensional appearance
EditLabels | specifies whether or not the user may edit the labels in a ListView or TreeView
Elevated | affects the appearance of a CommandLink Button
Encoding | specifies how character data are encoded or translated for a TCPSocket
EnterReadOnlyCells | specifies whether or not the user may visit read-only cells in a Grid
EvaluationDays | Specifies the number of days before the evaluation version of a Dyalog APL application expires. PocketAPL only.
Event | associates an event with a callback funtion or ⎕DQ termination
EventList | reports names of events generated by an object
ExportedFns | specifies the functions to be exposed as methods by an OLEServer object
ExportedVars | specifies the variables to be exposed as properties by an OLEServer object
FCol | specifies foreground colour
FieldType | specifies formatting and validation
FileMode | specifies the mode (read or write) for a FileBox object
File | specifies a filename
FillCol | specifies fill colour
Filters | specifies file filters for a FileBox
FirstDay | specifies the day that is considered to be the first day of the week for a Calendar object
Fixed | specifies whether a font is fixed-width or proportional
FixedOrder | specifies whether or not the CoolBar displays CoolBands in the same order
FlatSeparators | specifies whether or not separators are drawn between buttons in a TabControl object
FontList | provides a list of available fonts
FontObj | specifies the font to be used
Formats | data formats currently available from the Clipboard object
Formatstring | defines a ⎕FMT specification to be used to format a numeric value
FStyle | specifies fill style
FullRowSelect | specifies whether or not the entire row is highlighted when an item in a ListView or a TreeView is selected
GridBCol | specifies the background colour for a Grid
GridFCol | specifies the colour of (all) grid lines for a Grid
GridLineFCol | specifies grid line colours for a Grid
GridLine | specifies grid line widths for a Grid
GridLines | specifies whether or not lines are displayed between items in a ListView object
GripperMode | specifies whether or not a CoolBand has a gripper bar
HAlign | specifies horizontal text alignment
Handle | Returns the window handle of an object
HasApply | Specifies whether or not a PropertySheet has an Apply button
HasButtons | Specifies whether or not a TreeView object displays buttons
HasHelp | Specifies whether or not a Help button is displayed or active
HasLines | Specifies whether or not a TreeView object displays tree lines
HasTicks | Specifies whether or not tick marks are displayed in a TrackBar
HasToday | Specifies whether or not the Today date is displayed in the bottom left corner of a Calendar object
Header | specifies whether or not column titles are displayed in a ListView
HeaderImageIndex | Specifies the images for each column title in a ListView
HeaderImageList | Specifies the images for column titles in a ListView
HelpButton | specifies whether or not a question (?) button appears in the title bar of a Form
HelpFile | reports the name of a help file associated with an OLE Control
HighlightHeaders | Specifies whether or not row and column headings in a Grid are highlighted to indicate the current selection
HintObj | specifies the object in which to display the Hint
Hint | specifies the text for a context sensitive help message
HotSpot | specifies the hotspot for a Cursor
HotTrack | specifies whether or not the tabs or buttons in a TabControl object are automatically highlighted by the mouse pointer
HScroll | determines whether an object has a horizontal scrollbar
IconObj | associates an Icon with a minimized Form
ImageCount | Reports the number of images in an ImageList
ImageIndex | Maps images in an ImageList to items in a ListView or TreeView
ImageListObj | Associates an ImageList with a ListView or TreeView
Index | position of items in Combo or List, or selected filter in a FileBox
Input | names of objects associated with cells of Grid
InputMode | specifies the behaviour of cursor keys etc. in a Grid
InputModeKey | specifies the key used to switch to Incell editing in a Grid
InputProperties | Specifies the mapping between the Values property of a Grid and properties of external objects (ActiveX controls and .NET classes) which are displayed in Grid cells.
Interval | frequency with which a Timer generates events
Italic | specifies whether or not a font is italic
Items | list of items
ItemGroups | specifies item groupings for a ListView object
ItemGroupMetrics | specifies caption, colours and spacing for grouped items in a ListView object
Justify | determines how text is justified within an object
KeepBits | determines how Bitmap objects are stored in the workspace
KeepOnClose | determines whether or not namespaces are retained when their GUI components are destroyed
LastError | provides information about the most recent error reported by OLE
Limits | specifies minimum and maximum values for an object
LocalAddrName | specifies the host name of your computer
LocalAddr | specifies the IP address of your computer
Locale | specifies the language in which the OLE server, attached to an OLEClient, exposes its methods and properties
LocalPortName | specifies the port name of the local service that you wish to offer as a TCP/IP server
LocalPort | identifies the port number associated with a TCPSocket object
LStyle | specifies line style
LWidth | specifies line width
MapCols | specifies whether button colours in bitmaps and icons in an ImageList are re-mapped to reflect the users colour preferences
Masked | specifies the type of image in an ImageList
Mask | specifies the mask for a Cursor or Icon
MaxButton | determines whether or not a Form has a "maximize" button
MaxDate | specifies the largest date that may be displayed by a Calendar object
MaxLength | specifies the maximum number of characters that the user may enter into an object
MaxSelCount | specifies the maximum number of contiguous days that the user may select in a Calendar object
MDIActive | specifies the name of the active SubForm in an MDI application
MDIActiveObject | specifies a ref to the active SubForm in an MDI application
MDIMenu | nominates a particular Menu to be the MDI application menu
Metafile | accesses clipboard data in Windows Metafile format
MethodList | reports the names of methods provided by an OLE Control
MinButton | determines whether a Form has a "minimize" button
MinDate | Specifies the smallest date that may be displayed by a Calendar object
MonthDelta | specifies the number of months by which a Calendar object scrolls when the user clicks its scroll buttons
Moveable | determines whether a Form may be moved on the screen
MultiColumn | specifies whether or not a List displays items in more than one column
MultiLine | determines whether or not the tabs or buttons will be arranged in multiple flights or multiple rows/columns in a TabControl or ToolControl object
MultiSelect | specifies whether or not the user can select more than one button in a TabControl at the same time
NewLine | specifies whether or not a CoolBand starts a new row in a CoolBar
Note | specifies additional text for a CommandLink Button
OLEControls | reports the names of OLE Controls installed on the computer
OnTop | specifies that a Form is permanently raised to the front or specifies the level at which a graphic is drawn on a Grid
Orientation | specifies the orientation of the Printer
OtherButton | Specifies whether or not a ColorButton object displays an Other button, that allows access to custom colours.
OverflowChar | specifies the character to be displayed in a Grid cell to indicate that its contents will not fit
Page | specifies the width of the paper for a RichEdit
PageActive | specifies the name of the current PropertyPage in a PropertySheet
PageActiveObject | specifies a ref to the current PropertyPage in a PropertySheet
PageSize | specifies the size of the thumb in a scrollbar
ParaFormat | specifies paragraph formatting for a RichEdit
Password | specifies the symbol for a password field
Picture | specifies a BitMap, Icon or Metafile object to be drawn
PName | specifies the device for a Printer object, or the face name for a Font
Points | specifies points for graphical objects
Popup | specifies the name of a (popup) Menu object that is associated with a ToolButton
Posn | specifies the position of an object within its parent
PrintList | reports the list of installed printers
ProgressStyle | specifies the appearance of a ProgressBar control
PropList | reports the list of properties applicable to the object
QueueEvents | specifies how events are handled for an instance of an OCXClass object (an ActiveX control)
Radius | specifies the radius for a Circle
Range | specifies the range of a scrollbar
ReadOnly | specifies whether or not the user may change data in an Edit orSpinner, or the State of a Button
RealSize | specifies the size of a placeable Metafile
Redraw | specifies whether or not an object is automatically redrawn when required
RemoteAddrName | specifies the host name of the remote computer to which you wish to make a TCP/IP connection
RemoteAddr | identifies the port number associated with a service on a remote computer
RemotePortName | specifies the port name of the remote service to which you wish to make a TCP/IP connection
RemotePort | identifies the port number associated with a service on a remote computer
ReportBCol | specifies background colours for items in a ListView in Report View
ReportImageIndex | specifies images for individual column titles in a ListView in Report View
ReportInfo | specifies additional information for a ListView
ResizeCols | specifies whether or not the user may alter the width of columns in a Grid by dragging
ResizeColTitles | specifies whether or not the user may alter the height of the column titles in a Grid by dragging
ResizeRows | specifies whether or not the user may alter the height of rows in a Grid by dragging
ResizeRowTitles | specifies whether or not the user may alter the width of the row titles in a Grid by dragging
Rotate | specifies the angle of rotation for a font
RowHiddenDepth | identifies which rows in a Grid are hidden
RowLineTypes | specifies the appearance of horizontal grid lines in a Grid.
Rows | number of rows displayed in drop-down list of a Combo
RowTitleAlign | specifies the alignment of the row titles in a Grid
RowTitleBCol | specifies the background colour for row titles
RowTitleDepth | specifies the structure of hierarchical row titles in a Grid
RowTitleFCol | specifies the colour of the row titles in a Grid
RowTitles | specifies the row titles for a Grid
RowTreeDepth | specifies the structure of rows for a Grid
RowTreeImages | specifies the images (bitmaps) for the treeview items in a Grid
RowTreeStyle | specifies the appearance of treeview items in a Grid
RTFText | specifies the contents of an object in Rich Text Format
RunMode | specifies the way in which an OLEServer object serves multiple clients
ScrollOpposite | specifies that unneeded tabs scroll to the opposite side of a TabControl
SelDate | identifies the range of dates that is currently selected in a Calendar object
SelectionBorderWidth | specifies the width of the border drawn around the block of selected cells in a Grid
SelectionColor | specifies the colour of the block of selected cells in a Grid
SelectionColorAlpha | specifies the transparency of the block of selected cells in a Grid
SelImageIndex | specifies which images in an ImageList are used to identify selected items in a TreeView
SelItems | specifies the selected item(s) in an object.
SelRange | specifies the selected range in a TrackBar
SelText | specifies the selected text in an Edit or Combo
ServerVersion | specifies the version number of an OLEServer object
ShowCaptions | specifies whether or not the captions of individual ToolButton objects are drawn
ShowCueWhenFocused | specifies whether or not a Cue is displayed when the input field receives the input focus
ShowDropDown | specifies whether or not a drop-down menu symbol is drawn in a ColorButton or alongside ToolButton objects
ShowInput | determines how Combo and Button objects associated with cells of a Grid are displayed
ShowSession | specifies whether or not the APL Session window is displayed when an OLEServer object is started by an OLE client
ShowThumb | specifies whether or not the thumb is displayed in a TrackBar
SingleClickExpand | specifies whether or not an item in a TreeView control is expanded when the user selects the item
SIPMode | specifies the behaviour of the Input Panel (PocketAPL only)
SIPResize | specifies the resize behaviour of a Form when the Input Panel is raised and lowered (PocketAPL only)
Sizeable | specifies whether user may resize an object using the mouse
Size | specifies the size of an object
SocketNumber | reports the Window handle of the socket attached to the TCPSocket object
SocketType | specifies the type of the TCP/IP socket for a TCPSocket object.
SortItems | specifies whether or not the items in a List object are sorted.
SplitObj1 | specifies the name of an object managed by a Splitter
SplitObj2 | specifies the name of an object managed by a Splitter
Start | specifies start angles for arcs of Circle and Ellipse objects
State | specifies the state of a Button or Form
Step | increments for movement
Style | specifies the style of an object
SysMenu | determines whether a Form has a standard system menu
TabFocus | specifies the focus behaviour for the TabControl object
TabIndex | Specifies the tabbing order for controls
TabJustify | Specifies the positions at which the picture and caption are drawn within a TabButton
TabObj | specifies name of SubForm associated with a TabBtn
TabSize | specifies the size of fixed size tabs or buttons in a TabControl object
TargetState | reports the intended final state of a TCPSocket object
Text | specifies/reports the text in an Edit, MsgBox, or Combo
TextSize | reports the bounding rectangle for text
Thumb | specifies the position of the thumb in a scrollbar
ThumbRect | reports the extents of the thumb in a TrackBar
TickAlign | specifies the alignment of tick marks in a TrackBar
TickSpacing | specifies the spacing of tick marks in a TrackBar
TipObj | specifies the object in which to display the Tip
Tip | specifies the text for a pop-up help message
TitleHeight | specifies the height of the column titles in a Grid
Title | specifies the width of the row titles in a Grid
Today | specifies today's date in a Calendar object
ToolboxBitmap | reports the bitmap image associated with an OLE Control
TrackRect | reports the extents of the slider in a TrackBar
Translate | specifies whether or not an object performs ⎕AVtranslation
Transparent | specifies whether or not a ToolControl is transparent
TypeLibFile | reports the name of the file in which the Type Library for an OLEServer object is stored
TypeLibID | reports the value of the globally unique identifier (GUID) of the Type Library associated with an OLEServer object.
TypeList | reports the names of data types associated with an OLE Control
Type | specifies the type of an object
Underline | specifies whether or not a font is underlined
UpperCase | specifies that property names are to be reported in uppercase
ValidIfEmpty | specifies whether or not an empty Edit object is deemed to be valid
VAlign | specifies vertical text alignment
Value | value of a number, date or time in an Edit or Label object
Values | the data matrix in a Grid
VariableHeight | specifies whether or not a CoolBar displays bands at the minimum required height, or all the same height
View | specifies how items in a ListView are arranged
Visible | specifies whether or not an object is currently visible
VScroll | specifies whether or not an object has a vertical scrollbar
WantsReturn | specifies how the Enter key is treated by an edit box
WeekNumbers | specifies whether or not a Calendar object displays week numbers
Weight | specifies the weight (boldness) of a font
WordFormat | specifies word formatting for a RichEdit
Wrap | specifies whether or not an object wraps its contents
XRange | specifies origin and scale on the x-axis
Yield | specifies how frequently Dyalog APL/W yields control
YRange | specifies origin and scale on the y-axis


Events A-Z
Event | Num | Description
ActivateApp | 137 | User has switched to/from the APL application.
AddCol | 153 | appended a column to a Grid object.
AddRow | 152 | appended a row to a Grid object
AmbientChanged | 533 | reported when any of the ambient properties change in an application hosting an ActiveXControl object.
BadValue | 180 | attempted to leave Edit object with invalid text
BalloonHide | 862 | reported when a BalloonTip is displayed
BallonShow | 861 | reported when a BalloonTip disappears
BalloonTimeout | 863 | reported when a BalloonTip is dismissed
BalloonUserClick | 864 | reported when a BalloonTip is clicked
BeginEditLabel | 300 | signals the start of an edit operation in a ListView or TreeView object
CalendarDblClick | 273 | reported when the user double-clicks the left mouse button over a Calendar object
CalendarDown | 271 | reported when the user depresses the left mouse button over a Calendar object
CalendarMove | 274 | reported when the user moves the left mouse button over a Calendar object
CalendarUp | 272 | reported when the user releases the left mouse button over a Calendar object
CellChanged | 164 | modified and updated the contents of a cell in a Grid object
CellChange | 150 | modified the contents of a cell in a Grid object
CellDblClick | 163 | double-clicked the mouse on a cell in a Grid
CellDown | 161 | depressed a mouse button over a cell in a Grid
CellError | 157 | input invalid data into a cell in a Grid
CellMove | 151 | moved to a new cell in a Grid object
CellOver | 160 | mouse moved over a cell in a Grid object
CellUp | 162 | released a mouse button over a cell in a Grid
Change | 36 | altered the text in an Edit or Combo
ClipChange | 120 | data in the clipboard has changed
Close | 33 | Form is about to be closed
ColorChange | 430 | user has selected a colour in a ColorButton
ColumnClick | 320 | user has clicked on a heading in a ListView.
Configure | 31 | position and/or size of an object is about to change
Create | 34 | reported after an object has been created
DDE | 50 | DDE message has been received or sent
DisplayChange | 137 | user has changed screen resolution or number of colours
DragDrop | 11 | moved an object using drag & drop operation
DropFiles | 450 | user has drag/dropped a file icon onto an object
DropObjects | 455 | user has drag/dropped an object icon from the Workspace Explorer or Find Objects tool onto an object
DyalogCustomMessage1 | 95 | allows external applications and dynamic link libraries to insert events into the Dyalog APL/W message queue
EndEditLabel | 301 | signals completion of an edit operation in a ListView or TreeView object
EndSplit | 282 | reported when user releases the left mouse button to signify the end of a drag operation on a Splitter object
ExitApp | 132 | selected End Task from the Windows Task List
ExitWindows | 131 | requested Windows to terminate
Expanding | 302 | reported by a TreeView object as it is about to expand
Expose | 32 | exposed part or all of a Form or a Static
FileBoxCancel | 72 | selected the Cancel button in a FileBox
FileBoxOk | 71 | selected the Ok button in a FileBox
GetDayStates | 266 | reported when a Calendar object requires the APL program to provide state information
GotFocus | 40 | object has received the input focus
GridCopy | 191 | copies selected cells of a Grid to the clipboard
GridCut | 190 | copies selected cells of a Grid to the clipboard and clears them
GridDelete | 193 | clears selected cells of a Grid
GridDropSel | 195 | user has drag/dropped a block of cells in a Grid
GridPaste | 192 | pastes data from the clipboard into a Grid
GridPasteError | 194 | generated by an invalid paste operation in a Grid
GridSelect | 165 | user has changed the selection in a Grid
Help | 400 | user has clicked the Question (?) button and then clicked on an object
HScroll | 39 | requested movement in horizontal scrollbar of Form
HThumbDrag | 442 | user has dragged the thumb of the horizontal scrollbar of a Form or SubForm
Idle | 130 | generated when system is idle
IndexChanged | 210 | user has scrolled the data in a Grid so that the value of its Index property has changed.
ItemDblClick | 342 | user has double-clicked on an item in a ListView or TreeView object
ItemDown | 340 | user has depressed the left mouse button over an item in a ListView or TreeView object
ItemUp | 341 | user has released the left mouse button over an item in a ListView or TreeView object
KeyError | 23 | pressed an invalid key on the keyboard
KeyPress | 22 | pressed a key on the keyboard
Locator | 80 | terminated interaction with a Locator object
LostFocus | 41 | object has lost the input focus
MDIActivate | 42 | MDI SubForm becomes the active one
MDIDeactivate | 43 | MDI SubForm is deactivated
MouseDblClick | 5 | double-clicked a mouse button
MouseDown | 1 | pressed mouse button down
MouseEnter | 6 | moved the mouse into the object
MouseLeave | 7 | moved the mouse out of the object
MouseMove | 3 | user has moved the mouse
MouseUp | 2 | user released a mouse button
MsgBtn1 | 61 | user selected first button in a MsgBox
MsgBtn2 | 62 | user selected second button in a MsgBox
MsgBtn3 | 63 | user selected third button in a MsgBox
PageActivate | 360 | user has switched to a new PropertyPage
PageApply | 350 | user has clicked Apply in a PropertySheet
PageBack | 353 | user has clicked Back in a PropertySheet
PageCancel | 351 | user has clicked Cancel in a PropertySheet
PageChanged | 356 | user has altered Changed property of a PropertyPage
PageDeActivate | 361 | user has switched to a new PropertyPage
PageFinish | 355 | user has clicked Finish in a PropertySheet
PageHelp | 352 | user has clicked Help in a PropertySheet
PageNext | 354 | user has clicked Next in a PropertySheet
PreCreate | 534 | Reported when an instance of an ActiveXControl is created
Protected | 470 | user has attempted to alter protected text in a RichEdit object.
Retracting | 304 | reported by a TreeView object as it is about to retract
Scroll | 37 | requested a movement of the thumb in scrollbar
SelDateChange | 265 | reported when the user changes the date that is selected in a Calendar object
Select | 30 | user has selected the object
SetColSize | 176 | generated when column width changes in a Grid
SetItemPosition | 322 | generated when the user drag-drops an item in a ListView
SetRowSize | 175 | generated when row height changes in a Grid
SetSpinnerText | 421 | user has clicked a spin button in a Spinner object
SetWizard | 365 | user has clicked Next or Back in a PropertySheet
Spin | 420 | user has clicked a spin button in a Spinner object
Splitting | 281 | reported while a Splitter object is being dragged, between a StartSplit and an EndSplit
StartSplit | 280 | reported when the user depresses the left mouse button over a Splitter object
StateChange | 35 | Form is about to change state
SysColorChange | 134 | system colour scheme has changed
TCPAccept | 371 | reported when a client connects to a server TCPSocket object
TCPClose | 374 | reported when the remote end of a TCP/IP connection breaks the connection.
TCPConnect | 372 | reported when a server accepts the connection of a client TCPSocket object and is reported by the client
TCPError | 370 | generated when a fatal TCP/IP error occurs and is reported by a TCPSocket object
TCPGotAddr | 377 | reported when a host name (specified by the RemoteAddrName or LocalAddrName property) is resolved to an IP address
TCPGotPort | 378 | reported when a port name (specified by the RemotePortName or LocalPortName property) is resolved to a port number
TCPReady | 379 | reported when the TCP/IP buffers are free and there is no data waiting to be sent in the internal APL queue
TCPRecv | 373 | reported when data is received by a TCPSocket object
ThumbDrag | 440 | user is dragging the thumb in a TrackBar
Timer | 140 | event generated by a Timer object
VScroll | 38 | requested movement in vertical scrollbar of Form
VThumbDrag | 441 | user has dragged the thumb of the vertical scrollbar of a Form or SubForm
WinIniChange | 133 | WIN.INI has changed
WorkspaceLoaded | 525 | Reported when a workspace is loaded


Methods A-Z
Method | Num | Description
Abort | 103 | abort a print job
AddChildren | 310 | adds child items to an item in a TreeView
AddItems | 308 | adds items to a TreeView
CancelToClose | 367 | changes the buttons in a PropertySheet
CellFromPoint | 200 | converts from Grid coordinates to cell coordinates
ChooseFont | 240 | displays the standard Windows font selection box
ColChange | 159 | sets new values for a column of cells in a Grid
ColSorted | 174 | sets the sort image to be displayed in the column title of a Grid
DateToIDN | 264 | Converts a date from ⎕TS format into an IDN suitable for use in a Calendar object
DelCol | 155 | deletes a column from a Grid object
DeleteChildren | 311 | deletes child items from a parent item in a TreeView
DeleteItems | 309 | deletes items from a TreeView
DelRow | 154 | deletes a row from a Grid object
Detach | 270 | detaches the GUI component from an object
DuplicateColumn | 154 | Duplicates a column in a Grid object
DuplicateRow | 154 | Duplicates a row in a Grid object
FileRead | 90 | causes a graphical object to be read from a file
FileWrite | 91 | causes a graphical object to be written to a file
Flush | 135 | flushes all pending output
GetCellRect | 201 | obtains the extents of a particular Grid cell
GetCommandLine | 145 | obtains the entire command line that was used to start Dyalog APL
GetCommandLineArgs | 148 | obtains the command line and arguments (as a nested vector) that was used to start Dyalog APL
GetEventInfo | 551 | obtains information about an OLE Control event
GetFocus | 511 | obtains the name of the object that currently has the input focus
GetItemHandle | 313 | obtains the window handle of an item in a TreeView
GetItemPosition | 323 | obtains the position of an item in a ListView
GetItemState | 306 | obtains the status of an item in a TreeView
GetMethodInfo | 552 | obtains information about an OLE Control method
GetMinSize | 275 | Obtains the minimum size that you must specify for a Calendar object for it to display a complete month
GetParentItem | 312 | obtains the index of the parent of an item in a TreeView
GetPropertyInfo | 550 | obtains information about an OLE Control property
GetTypeInfo | 550 | obtains information about an OLE Control data type
GetVisibleRange | 262 | Obtains the range of dates that is currently visible in a Calendar object
IDNToDate | 263 | Used to convert a date from an IDN into ⎕TS format
LockColumns | 227 | Locks/unlocks columns in a Grid object
LockRows | 227 | Locks/unlocks rows in a Grid object
MakeGIF | 261 | Generates a GIF representation of a picture from a Bitmap object
MakePNG | 260 | Generates a PNG representation of a picture from a Bitmap object
MDIArrange | 112 | MDIClient to arrange minimised SubForm icons
MDICascade | 110 | MDIClient to overlap its SubForms
MDITile | 111 | MDIClient to rearrange SubForms in row or column
NameFromHandle | 136 | obtains the name of an object from its handle
NewPage | 102 | throws a new page on a Printer
OLEAddEventSink | 540 | Connects a named event sink to a COM object
OLEDeleteEventSink | 541 | Disconnects a named event sink from a COM object
OLEListEventSinks | 542 | Returns the names of event sinks that are currently connected to a COM object
OLEQueryInterface | 543 | Used to obtain the methods and properties associated with a particular interface that is provided by a COM object
OLEUnregister | 531 | used to unregister an OLEServer object that has previously been saved by Dyalog APL
Print | 100 | spools Printer output
ProgressStep | 250 | increments the thumb in a ProgressBar
RowChange | 158 | sets new values for a row of cells in a Grid
RTFPrint | 461 | prints the contents of a RichEdit
RTFPrintSetup | 460 | displays a print setup dialog box
SetCellType | 156 | changes CellTypes property for a cell in a Grid
SetEventInfo | 547 | Used to register an event that may be generated by an ActiveXControl object
SetFnInfo | 545 | Used to describe an APL function that is to be exported as a method, or as a property, of an ActiveXControl object
SetItemImage | 315 | allocates a picture icon to an item in a TreeView
SetItemState | 307 | sets the status of an item in a TreeView
SetMethodInfo | 546 | Used to describe a method that is exported by a COM object
SetPropertyInfo | 554 | Used to describe a property that is exported by a COM object
Setup | 101 | displays printer setup dialog box
SetVarInfo | 546 | Used to describe an APL variable that is to be exported as a property of an ActiveXControl object
ShowBalloonTip | 860 | displays a BalloonTip
ShowHelp | 580 | displays the help file associated with an OLE Control
ShowItem | 316 | displays a particular item in a TreeView
ShowProperties | 560 | displays the property sheet associated with an OLE Control
ShowSIP | 25 | Raise or lowers the Input Panel (Pocket APL only)
TCPGetHostID | 376 | obtains the IP Address of your PC
TCPSend | 375 | used to send data to a remote process connected to a TCPSocket object
TCPSendPicture | 380 | Transmits a picture represented by a Bitmap object to a TCP/IP socket
Undo | 170 | reverses last change made to a Grid object


ActiveXContainer Object
Parents Properties Methods Events
Purpose: The ActiveXContainer object represents the application that is currently hosting an instance of an ActiveXControl object.

Description

An ActiveXContainer is used to represent the host application that is hosting an ActiveXControl object, and provides access to its ambient properties such as font, and colour.

An ActiveXContainer object is created using the Container property of the ActiveXControl object.

For example, the following expression , executed within an ActiveXControl instance creates an ActiveXContainer named 'CONT'

      'CONT' ⎕NS ⎕WG'Container'

The ambient properties of the host application are reported by the FontObj, Fcol and Bcol properties which are all read-only.

The ActiveXContainer object supports the AmbientChanged event which is reported when any of the ambient properties change. This event allows the ActiveXContainer to react to such changes.


ActiveXControl Object
Parents Children Properties Methods Events
Purpose: The ActiveXControl object represents a Dyalog APL namespace as an ActiveX control.

Description

The ActiveXControl object represents a Dyalog APL namespace as an ActiveX control.

During development, an ActiveXControl is a container object that is the child of a Form and acts as a wrapper for one or more other GUI objects.

To make an ActiveXControl available to another application, you must select Make OCX from the Session File menu. This creates an .OCX file that contains your entire workspace and all of the ActiveXControls within it.

Once an ActiveXControl has been saved in an .OCX file, any application that supports ActiveX may create and use instances of it.

When an ActiveX control is loaded by a host application, it and any code that it requires, is loaded into the host application's address space; it does not run in a separate address space.

During development, an ActiveXControl is powered by the development version of Dyalog APL. However, an ActiveXControl object that is loaded by a host application, is powered by a DLL version of Dyalog APL. This automatically gets loaded when a host application creates the first instance of any Dyalog APL ActiveX control. However, within a single host application, other instances of the same or other Dyalog APL ActiveX controls share the same copy of DYALOG.DLL.

Like the development and run-time versions of Dyalog APL, DYALOG.DLL has an active workspace. When an application loads an ActiveXControl, DYALOG.DLL copies the top-level namespace that owns the ActiveXControl, together with everything it contains, into the active workspace. For example, if the ActiveXControl is named Controls.Form1.Ctrl1, the act of creating the first instance of Ctrl1 will cause the entire contents of the Controls namespace to be copied, from the corresponding .OCX file, into the active workspace. This affords the potential for controls from different OCX files to clash, but the name clash conflict is restricted to just one name.

Each instance of an ActiveXControl, is represented by a separate namespace which is automatically cloned from the original ActiveXControl namespace. Each instance namespace is entirely separate from any other instance namespace and there is no way for one instance to reference or see any other instance; nor can it reference the original class namespace from which it was cloned. In fact, each instance appears to itself to be the one and only original class namespace. Using the previous example, each instance of Ctrl1 believes that its full pathname is #.Controls.Form1.Ctrl1, although each instance is in fact a separate clone of that namespace.

When an application creates an instance of an ActiveXControl, it does so as the child of some object within its own GUI hierarchy. From the instance's viewpoint, its parent Form is replaced by a different GUI object that imposes position, size, font, background colour, and other ambient properties.

The external name of an ActiveXControl is made up of the character vector defined by the ClassName property, prefixed by the string "Dyalog ", and followed by the string " Control". If ClassName is empty (which is the default), the name of the ActiveXControl namespace is inserted instead. Note that the name should not include APL symbols such as ∆.ClassName may only be specified when you create the ActiveXControl with ⎕WC and may not be changed using ⎕WS.

The Coord property is read-only and its value is always 'Pixel'. If you wish to use a different co-ordinate system for the children of an ActiveXControl object, it is necessary to set Coord separately on each one of them.

Posn and Size are negotiable properties. When an instance of the ActiveXControl is created, the values of Posn and Size will be assigned by the host application. You may change these values using ⎕WS, but the host application has the right to refuse them and there is no guarantee that you will get what you set.

The Border and EdgeStyle properties may be used to control the outline appearance of the ActiveXControl object.

The Dragable and KeepOnClose properties apply only during development and are otherwise ignored.

The ToolBoxBitmap property specifies the name of a Bitmap object that may be used by a host application to represent the ActiveXControl when its complete visual appearance is not required.. For example, if you add an ActiveX control to the Microsoft Visual Basic development environment, its bitmap is added to the toolbox. The Bitmap should therefore be of an appropriate size, usually 24 x 24 pixels.

The Container property provides access to an ActiveXContainer object that represents the host application itself. This may be used to obtain the values of ambient properties, or to access methods exposed by the host application via OLE interfaces.

When an instance of an ActiveXControl is created, it generates first a PreCreate event, and then a Create event. The PreCreate event is generated at the point the instance is made.

The Create event is generated at the point when the host application requires the instance to appear visually. If, as is recommended, you create child controls of the instance when it is created, you must respond to the Create event, because at the time that PreCreate is generated, the object does not have a window.

Host applications which support two different modes of operation, namely design mode and run mode, differ in the way that they create instances of ActiveX controls. Microsoft Access does not require an ActiveX control to appear properly in design mode. Instead, it draws a simple box containing just the name of the object. If your ActiveXControl is hosted by Microsoft Access, it will get a PreCreate Event when an instance is created in design mode, and a Create event only when it enters run mode. Microsoft Visual Basic, however, requires the object to draw itself immediately, even in design mode, and so a Create event will be generated immediately after a PreCreate event in this case.


Animation Object
Parents Children Properties Methods Events
Purpose: The Animation object displays simple animations from basic .AVI files or resources.

Description

The Animation object displays simple animations from basic .AVI files or resources.

The Animation object can only play AVI files or resources that have no sound and can only display uncompressed AVI files or .AVI files that have been compressed using Run-Length Encoding (RLE).

For more sophisticated animations, you may use the Windows Media Player (OCX).

To display an AVI file, you must first use the AnimOpen method to open it. If the AutoPlay property is set to 1, the animation will play immediately. Otherwise, only the first frame will be displayed.

The Align property may be 'None' or 'Centre' ('Center'). If Align is 'None', the Animation window is automatically resized to fit the AVI being played. If Align is 'Centre', the AVI is centred in the Animation window. If the window is too small, the AVI is clipped.

The AnimPlay method may be used to play the animation and allows you to specify the start, number of frames, and repeat count.

The AnimStop method causes the animation to stop.

The AnimClose method closes the current AVI file and resets the contents of the object's window to its background colour.

The AnimStarted and AnimStopped events are reported when the animation starts and stops respectively.


Bitmap Object
Parents Children Properties Methods Events
Purpose: A graphical object used to represent a bitmap which may be used both to display a picture or as a pattern (brush) used to fill other objects.

Description

A Bitmap may be created either from a file (.BMP, .GIF or .PNG),) or from APL arrays. To create a Bitmap object using ⎕WC, you can either specify the File property or the Cbits property, or the Bits and CMap properties.

If you specify File, it should contain the name of a bitmap file from which the bitmap is to be read. If omitted, a .BMP file extension is added. You may also load a Bitmap from a DLL or from the DYALOG.EXE executable. See File property for details.

If instead you want to create a Bitmap dynamically from APL variables, you may do so in one of two ways.

For a palette of up to 256 colours, you may specify the image using the Bits and CMap properties. The alternative is to use the Cbits property which works for any size of colour palette.

If MaskCol is non-zero, it specifies the transparent colour for the Bitmap. Any pixels specified with the same colour will instead be displayed in whatever colour is underneath the Bitmap. This achieves similar behaviour to that of an Icon.

The KeepBits property has the value 0 or 1, and controls how a Bitmap is saved in the workspace. A value of 0 (the default) means that the values of Cbits, Bits and CMap are not kept in the workspace. If you request the values of Cbits, Bits or CMap with ⎕WG, they are obtained directly from the corresponding Windows bitmap resource. When the workspace is )LOADed, the Bitmap is recreated from the associated file defined by the value of the File property. Note that if this file doesn't exist when the workspace is )LOADed, the Bitmap is not created, but no error is generated. However, when you reference the object you will get a VALUE ERROR.

If KeepBits is 1, the values of Cbits, Bits and CMap are stored permanently in the workspace, and are used to rebuild the Bitmap when the workspace is )LOADed. In this case, the file name (if any) is ignored. Setting KeepBits to 1 uses more workspace, but may be more convenient if you want to distribute applications.

The Size property allows you to query the size of a Bitmap without having to retrieve the Cbits or Bits property and then take its "shape". This will be noticeably faster for a large Bitmap. If you set the Size property using ⎕WS the Bitmap is scaled to the new size.

A useful feature of a Bitmap is that it can be the parent of any of the graphical objects. This allows you to create or edit a bitmap by drawing lines, circles, etc. in it.

The FileRead (90) and FileWrite (91) methods allow you to dynamically manage bitmap files (.BMP). The expression :

      bmname.FileWrite

causes the Bitmap called bmname to be written to the file specified by the current value of the File property. The file is automatically written in standard bitmap format. Similarly, the expression :

      bmname.FileRead

causes the Bitmap called bmname to be redefined from the bitmap file specified by the current value of the File property.

The MakeGIF and MakePNG methods may be used to convert the image represented by a Bitmap object into a GIF or PNG data stream, suitable for display in a web browser. The TCPSendPicture method may be used to transfer a Bitmap on a TCP/IP socket.

Using a bitmap is always a 2-stage process. First you create a Bitmap object with ⎕WC. Then you use it by specifying its name as a property of another object.

The Picture property specifies the name of a Bitmap to be displayed in an ActiveXControl, Button, Form, Group, Image, MDIClient, Sm, Static, StatusBar, StatusField, SubForm, TabBar, or ToolBar.

The BtnPix property specifies three Bitmaps to be used to represent the 3 states of a Button, Menu or MenuItem.

The FStyle property specifies the name of a Bitmap to be used as a pattern to fill a Poly, Ellipse or Rect object.


BrowseBox Object
Parents Children Properties Methods Events
Purpose: The BrowseBox object allows the user to browse for and select a folder or other resource.

Description

For full functionality as described here, the BrowseBox object requires the Windows Shell Library SHELL32.DLL Version 4.71 or higher. The BrowseBox object also supports the enhanced functionality provided by SHELL32.DLL Version 5 (Windows 2000) if present.

The BrowseBox object is a dialog box that allows the user to browse for and select a folder (directory) or other resource.

The BrowseFor property specifies the type of resource and may be 'Directory'(the default), 'File', 'Computer'or 'Printer'.

The StartIn property specifies the path name where browsing should start.

The HasEdit property specifies whether or not the dialog box contains an edit field into which the user can type the name of the folder or other resource, rather than browsing for it. The default is 0.

A BrowseBox may only be used by the execution of a modal ⎕DQ. The action code for the FileBoxOK and FileBoxCancel events must be set to 1 so that the appropriate result is returned by the modal ⎕DQ.

After the user has pressed OK or Cancel, the Target property contains the name of the chosen folder or other resource.

Example:

     ∇ DIR←{START_DIR}GetDir CAPTION;BB;MSG
[1]    ⍝ Ask user for a Directory name
[2]    ⍝ CAPTION specifies Caption for dialog box
[3]    ⍝ START_IN (optional) specifies starting directory
[4]    ⍝ DIR is empty if user cancels
[5]    :With 'BB'⎕WC'BrowseBox'
[6]        :If 2=⎕NC'START_DIR'
[7]            StartIn←START_DIR
[8]        :Else
[9]            StartIn←''
[10]       :EndIf
[11]       onFileBoxOK←onFileBoxCancel←1
[12]       Caption←CAPTION
[13]       HasEdit←1
[14]       MSG←⎕DQ''
[15]       :If 'FileBoxOK'≡2⊃MSG
[16]           DIR←Target ⍝ = 3⊃MSG
[17]       :Else
[18]           DIR←''
[19]       :EndIf
[20]   :EndWith
     ∇


Button Object
Parents Children Properties Methods Events
Purpose: Allows the user to initiate an action or to select an option using a button.

Description

The type of button displayed is determined by the Style property which may take the value 'Push', 'Radio', 'Check', 'Toggle', 'Split' or 'CommandLink'. Under Windows, 'Toggle' and 'Check' are treated identically.

'Split' and 'CommandLink' apply only to Windows Vista and later and require Native Look and Feel . Otherwise the use of these Styles will produce a Button with Style 'Push'.

Push buttons are used to generate actions. When the user "presses" a pushbutton, it generates a Select event (30). To cause an action, you simply associate the name of a callback function with this event for the Button in question.

Radio buttons and Check boxes are used to select options. They each have two states between which the user can toggle by clicking the mouse. When the Button (option) is selected, its State property has the value 1; otherwise it is 0.

Only one of a group of Radio buttons which share the same parent can be set (State is 1) at any one time. Radio buttons are therefore used for a set of choices that are mutually exclusive. Check boxes however, may be set together to signify a combination of options. These are used for making choices which are not mutually exclusive.

Radio and Check buttons also generate Select events when their State changes, and you can attach callback functions to these events to keep track of their settings. However, as Radio and Check buttons are not normally used to generate actions, it is perhaps easier to wait until the user signifies completion of the dialog box in some way, and then query the State of the buttons using ⎕WG. For example, if you have a set of Radio or Check buttons in a Group called f1.options, the following statements retrieve their settings.

      OPTIONS ← (⎕WN 'f1.options') ⎕WG¨⊂'State'

or

      OPTIONS ← ⎕WG∘'State' ¨ ⎕WN 'f1.options'

The Caption property determines the text displayed in the Button. Its default value is an empty vector. If Style is 'Radio' or 'Check', the text may be aligned to the left or right of the button graphic using the Align property. Its default value is 'Right'.

The CommandLink button has an icon displayed to the left of its Caption. The appearance of the icon is controlled by the Elevated property. Elevation is a feature of User Account Control in Windows 7. In addition to the Caption , additional text may be defined by its Note property. If provided, this is displayed below the Caption.

The Split Button has a drop-down button, similar to that provided by a Combo object.

If Posn is omitted, the button is placed in the centre of its parent. If either element of Posn is set to ⍬, the button is centred along the corresponding axis.

If Size is not specified, the size of the button is determined by its Caption. If either element of Size is set to ⍬ the corresponding dimension is determined by the height or width of its Caption. If Caption is not specified, or is set to an empty vector, the value of Size is set to a default value.

Button colours can be specified using FCol and BCol. However, pushbuttons (Style 'Push') ignore BCol and instead use the standard Windows colour.

The Picture property is used to display a bitmap on a pushbutton. This property is a 2-element array containing the name of a Bitmap object and the "mode" in which it is to be displayed. The default mode (3) is the most useful, as it causes the Bitmap to be superimposed on the centre of the Button. The surrounding edges of the Button (which gives it its 3-dimensional appearance and pushbutton behaviour) are unaffected. Note that if Picture is set on a Button whose Style is 'Radio' or 'Check', the Button assumes pushbutton appearance, although its'Radio' / 'Check' behaviour is preserved.

An alternative is to use the BtnPix property. This property specifies the names of up to 3 Bitmap objects. The first Bitmap is displayed when the State of the Button is 0. The second is displayed when its State is 1. The third is shown when the Button is inactive (Active 0). BtnPix is more flexible than Bitmap, but if you want your Button to exhibit pushbutton behaviour, you must design your bitmap accordingly.

The ReadOnly property is Boolean and specifies whether or not the user may change the state of the Button. It applies only to Style 'Radio' and Style 'Check'.

The user can interact with the Button by clicking it, which generates a Select Event or (Style 'Split') the drop-down.which generates a DropDown Event


ButtonEdit Object
Parents Children Properties Methods Events
Purpose: Allows user to enter or edit data.

Description

The ButtonEdit object combines a single-line input field with a customisable button. It provides the same user and programmer interfaces as an Edit object (Style 'Single').

The appearance of the button, which is displayed to the right of the input field, is determined by the ImageListObj property. When clicked, the object generates a DropDown event. There is no default processing for this event; it is up to the programmer to take the appropriate action via a callback function.

The following picture illustrates two ButtonEdit objects

     ∇ Example;BK;White
[1]    'F'⎕WC'Form' 'ButtonEdit'
[2]    'F.IL1'⎕WC'ImageList'('Size' 16 16)('Masked' 1)
[3]    'F.IL1.Time'⎕WC'Icon' 'c:\MadCap13.2\ICO\Time.ico'
[4]    'F.BE1'⎕WC'ButtonEdit' ''(30 20)(⍬ 160)
[5]    F.BE1.(Cue ShowCueWhenFocused)←'Enter data' 1
[6]    F.BE1.(ImageListObj ImageIndex)←F.IL1 1
[7]
[8]    'F.fnt'⎕WC'Font' 'APL385 Unicode' 16
[9]    BK←16 16⍴256⊥White←255 255 255
[10]   'F.Rotate'⎕WC'Bitmap'('CBits'BK)('MaskCol'White)
[11]   'F.Rotate.'⎕WC'Text' '⌽'(0 3)('FontObj'F.fnt)
[12]   BK←F.Rotate.CBits
[13]   'F.IL1.'⎕WC'BitMap'('CBits'BK)('MaskCol'White)
[14]   'F.BE2'⎕WC'ButtonEdit' 'Hello World'(100 20)(⍬ 160)
[15]   F.BE2.(ImageListObj ImageIndex)←F.IL1 2
[16]   F.BE2.onDropDown←'Rotate'
     ∇

     ∇ Rotate msg
[1]    (⊃msg).Text←⌽(⊃msg).Text
     ∇


Calendar Object
Parents Children Properties Methods Events
Purpose: The Calendar object provides an interface to the Month Calendar Control

Description

The Calendar object displays a calendar and allows the user to select a date or range of dates. The following illustration shows a default Calendar object.

The Calendar object will display as many full months as it can fit into the area specified by its Size property as sown below.The minimum size required to encompass a single month may be obtained using the GetMinSize method.

'F'⎕WC'Form' 'Example 2'('Size' 50 50)
'F.C'⎕WC'Calendar'('Size' 100 100)

The Today property is an IDN that specifies the current day. Its default value is today's date, i.e. the local date set on your computer.

The CircleToday property is either 0 or 1 (the default) and specifies whether or not the Today date is circled when the Calendar object is showing the corresponding month.

The HasToday property is either 0 or 1 (the default) and specifies whether or not the Today date is displayed (using the Windows short date format) in the bottom left of the Calendar object.

The WeekNumbers property is either 0 (the default) or 1 and specifies whether or not the Calendar displays week numbers.

The following example shows a Calendar with both CircleToday and HasToday set to 0 and WeekNumbers set to 1.

'F'⎕WC'Form' 'Example 3'('Size' 30 30)
'F.C'⎕WC'Calendar'('CircleToday' 0)('HasToday' 0)('WeekNumbers' 1)

The FirstDay property is an integer whose value is in the range 0-6. FirstDay specifies the day that is considered to be the first day of the week and which appears first in the Calendar. The default value for FirstDay depends upon your International Settings.

The MinDate and MaxDate properties are integers that specify the minimum and maximum IDN values that the user may display and select in the Calendar object. By default these properties specify the entire range of dates that the Windows Month Calendar control can provide.

The MonthDelta property specifies the number of months by which the Calendar object scrolls when the user clicks its scroll buttons. The default is empty (zilde) which implies the number of months currently shown.

The Style property may be either 'Single' (the default) or 'Multi'. If Style is 'Single', the user may select a single date. If Style is 'Multi', the user may select a contiguous range of dates. In this case, the maximum number of contiguous days that can be selected is defined by the MaxSelCount property which is an integer whose default value is 7.

The SelDate property is a 2-element integer vector of IDN values that identifies the first and last dates that are currently selected.

When the user selects one or more dates, the Calendar object generates a SelDateChange event. This event is also generated when the Calendar object is scrolled, and the selection changes automatically to another month.

The Calendar displays day numbers using either the normal or the bold font attribute and you may specify which attribute is to be used for each day shown. However, the Calendar object does not store this information beyond the month or months currently displayed.

When the Calendar control scrolls (and potentially at other times), it generates a GetDayStates event that, in effect, asks you (the APL program) to tell it which (if any) of the dates that are about to be shown should be displayed in bold.

If you wish any dates to be displayed using the bold font attribute, you must attach a callback function to the GetDayStates event which returns this information in its result. By default, all dates are displayed using the normal font attribute, so you only need a callback function if you want any dates to be displayed in bold.

You may also set the font attribute for particular days in the range currently displayed by calling GetDayStates as a method.

The CalendarCols property specifies the colours used for various elements in the Calendar object.

You may convert dates between IDN and ⎕TS representations using the IDNToDate and DateToIDN methods. Note that these methods apply to all objects and not just to the Calendar object itself.

The GetVisibleRange method reports the range of dates that is currently visible in the Calendar object.


Circle Object
Parents Children Properties Methods Events
Purpose: A Graphical object to draw circles, arcs, and pie-slices.

Description

The Points property contains the co-ordinates of the centre of the circle. The size of the circle is determined by the Radius property. This specifies the radius along the x-axis, the height is calculated so that the object is circular.

The RadiusMode property determines whether or not the circle is adjusted by a pixel, if required in order to appear perfectly round and perfectly centred. The default value is 0 (no adjustment is made).

The Start and/or End properties are used to draw partial circles. They specify start and end angles respectively, measuring from the x-axis in a counter-clockwise direction and are expressed in radians. The type of arc is controlled by ArcMode as follows :

ArcmodeEffect

0 | An arc is drawn from Start to End.
1 | An arc is drawn from Start to End. In addition, a single straight line is drawn from one end of the arc to the other, resulting in a segment.
2 | An arc is drawn from Start to End. In addition, two lines are drawn from each end of the arc to the centre, resulting in a pie-slice

.

Points, Radius, Start and End can specify vectors so that several arcs, circles, pie slices, etc. can be drawn in one call (and with one name).

If Start is specified, but not End, end angles default to (¯1↓+\Start),○2. If End is specified, but not Start, start angles default to 0,¯1↓+\End

This means that you can draw a pie-chart using either Start or End angles; you do not have to specify both.

Examples:

A circle whose centre is (50,50) and radius 20

      'g.p1' ⎕WC 'Circle' (50 50) 20

An arc

      'g.arc' ⎕WC 'Circle' (50 50) 20 ('Start' (○0.75))('End' (○1.25))

Complete pie

      Data←12 27 21 40
      ANGLES←0,¯1↓((○2)÷+/Data)×+\Data
      COLS←(255 0 0)(0 255 0)(255 255 0)(0 0 255)
      PATS←1 2 3 4
      'g.pie' ⎕WC 'Circle' (50 50) 20 ('Start' ANGLES)
                  ('ArcMode' 2) ('FCol' (⊂0 0 0))
                  ('FStyle' PATS) ('FillCol' COLS)

Same pie as above, but 2nd slice is exploded by changing its centre and 4th slice is shrunk by reducing its radius :

      CY←50 52 50 50  ⍝ y-coord of centres
      R←20 20 20 17.5 ⍝ radii
      'g.pie' ⎕WC 'Circle' (50 CY) R ('Start' ANGLES)
                  ('ArcMode' 1) ('FCol' (⊂0 0 0))
                  ('FStyle' PATS) ('FillCol' COLS)


Clipboard Object
Parents Children Properties Methods Events
Purpose: This object provides access to the Windows clipboard.

Description

When an application places data in the Windows clipboard, it may store it in one or more formats. An application wishing to retrieve data from the clipboard can then choose which format to read it in. Dyalog APL supports standard clipboard formats, including CF_TEXT, CF_BITMAP and CF_METAFILE. If there is any data in the clipboard, the Formats property lists the formats in which it may be retrieved.

In addition, the Array property may be used to set or retrieve clipboard contents in Dyalog APL array format.

Data is read from the clipboard using ⎕WG, specifying the name of the appropriate property for the data that you want.

If the data has been stored in CF_Text format, the value of Formats will include 'Text' and you may retrieve the data by querying the value of the Text property with ⎕WG.

If the data has been stored in device-independent bitmap format, the value of Formats will include 'CBits', 'Bits' and 'CMap'. To retrieve the bitmap pattern and colour map, you may query the values of the CBits, or Bits and CMap properties using ⎕WG.

If the data has been stored in device-dependent bitmap format, only the bitmap pattern is available and Formats will contain 'Bits' but not 'CMap'. In this case you can query the Bits property but not CMap without which you cannot realise the bitmap. However, if data was posted in this format, it is highly probable that the current Windows colour map applies to it. For a standard 16-colour device this is given under the description of the CMap property.

The following example retrieves text from the clipboard :

      'CL' ⎕WC 'Clipboard'
      Data ← 'CL' ⎕WG 'Text'

The next example retrieves a bitmap from the clipboard and defines it as a Bitmap object named 'BM' ready for use :

      'BM' ⎕WC 'Bitmap' '', 'CL' ⎕WG 'Bits' 'CMap'

Data may be placed in the clipboard using ⎕WC or ⎕WS. To store text, you simply set the Text property. You may use a simple character vector or matrix, or a vector of character vectors. For example :

      'CL' ⎕WS 'Text' 'Hello World'

To store a bitmap you can set either the Picture property to the name of a Bitmap object, or you can set the Bits and CMap properties explicitly. The former is more efficient, especially for large bitmaps, for example :

      'CL' ⎕WS 'Bitmap' 'BM'

or

      Bits CMap ← 'BM' ⎕WG 'Bits' 'CMap'
      'CL' ⎕WS ('Bits' Bits)('CMap' CMap)

Note that if you use the latter method, you must set both properties in one ⎕WS statement. This is also true if you wish to store data in both Text and Bitmap formats together.

The Metafile property allows graphical information to be restored in and retrieved from the clipboard in Windows Metafile format. See the description of the Metafile property for details.

A ClipChange (120) event is generated when another application places data in the clipboard.


ColorButton Object
Parents Properties Methods Events
Purpose: The ColorButton object allows the user to select a colour.

Description

The ColorButton object displays a coloured box, with an optional drop down button. When the user clicks the ColorButton with the left mouse button, a colour selection drop-down appears below it, allowing the user to select a new colour.

The CurrentColor property (default 0 0 0) is a 3-element integer vector that specifies and reports the RGB value of the currently selected colour.

The DefaultColors property is a nested matrix which specifies the RGB values of the colours shown in the colour selection box. The shape of DefaultColors determines the number of rows and columns in the colour selection drop-down. Each element of DefaultColors is a 3-element integer vector specifying an RGB colour value.

The OtherButton property is Boolean and specifies whether or not the user can select a colour using the Windows colour selection dialog box.

If OtherButton is 1 (the default), the final row of the colour selection drop-down contains a button labelled "Other…". If the user clicks this button, the standard Windows colour selection dialog box is displayed, allowing the user to select any colour that the computer can render.

If OtherButton is 0, the button labelled "Other…" is not present and the user is restricted to the choice of colours provided by the DefaultColors property.

The CustomColors property is a 1-row, 16-column nested matrix which specifies the RGB values of the Colours displayed in the Custom colors section of the Windows colour selection dialog box. Each element of CustomColors is a 3-element integer vector specifying an RGB colour value.

The ShowDropDown property is Boolean (default 1) and specifies whether or not a drop-down button is displayed in the ColorButton object.

When the user clicks a ColorButton with the left mouse button, the object generates a DropDown event just before it displays the colour selection drop-down. This event may be used to set the DefaultColors and/or CustomColors properties dynamically.

When the user selects a new colour, the ColorButton generates a ColorChange event.

Note that Pocket PC 2002 colour selection dialog box does not provide the facility to select custom colours, so this functionality is not available in PocketAPL.


Combo Object
Parents Children Properties Methods Events
Purpose: This object combines an input area with a list box and allows the user to enter a selection by typing text or by choosing an item from the list.

Description

Three types of Combo box are provided by the Style property which may be 'Drop' (the default), 'Simple' or 'DropEdit'.

The Items property specifies the list of items which are displayed in the list box and from which the user can choose.

The SelItems property is a boolean vector which specifies which (if any) of the items is selected. When the user chooses an item from the list, it is copied to the edit field and a Select event is generated. At this point you may use SelItems to identify the chosen item. You can also use SelItems to pre-select the contents of the edit field.

If the Style is 'Simple' or 'DropEdit', the user may type text into the edit field. In these cases, the contents of the edit field may also be specified or queried using the Text property. Note that if the user first selects an item from the list box, then changes it in the edit field, the entry in the list box is automatically deselected. There is therefore no conflict between the value of Text and the value of SelItems.

Warning: Windows truncates the contents of the edit field (reflected in the value of the Text property) to 510 characters.

For a Combo with Style 'Simple', the Index property specifies or reports the position of Items in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. Note that Index can only be set using ⎕WS and not by ⎕WC and is ignored if all the Items fit in the list box. The default value for Index is ⎕IO.

The SelText property identifies the portion of the edit field that is highlighted. It is not applicable to a Combo with Style 'Drop' as the user cannot enter or change data in its edit field.

The height of a Combo object with Style 'Drop' or 'DropEdit' is defined in a manner that is different from other objects. The height of the edit field is fixed, and is dependent only upon the size of the font. The height of the associated drop-down list box is determined by the Rows property. The first element of the Size property (height) is ignored. For a Simple combo box (whose listbox is permanently displayed), the overall height is determined by the first element of Size. Rows is a "read-only" property.

The VScroll property specifies whether or not a vertical scrollbar is provided. The default value 0 means no scrollbar, setting VScroll to ¯1 or ¯2 specifies that the Combo has a vertical scrollbar.

If the Style is 'Simple' or 'DropEdit', the HScroll property determines whether or not the edit field may be scrolled. If HScroll is 0, the data is not scrollable, and the user cannot enter more characters once the field is full. If HScroll is ¯1 or ¯2 the field is scrollable, and there is no limit on the number of characters that can be entered. In neither case however is a horizontal scrollbar provided. If Style is 'Drop', the user is not allowed to enter data into the edit field anyway, and the value of HScroll is ignored.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

Note that when you change the Items property using ⎕WS, the Text, SelItems and SelText properties are all reset to their default values.

The Combo object will report a Select event (if enabled) when the user chooses an item from the list box. It will generate a Change event (if enabled) when the user manually alters the contents of the edit field and then changes the focus to another object.


ComboEx Object
Parents Children Properties Methods Events
Purpose: The ComboEx object is an extended version of the Combo object that provides additional features including item images

Description

The ComboEx object is a ComboBox that supports item images and indenting. It is a superset of the Combo object and supports all its functionality. For further details, see Combo.

For most purposes, you can use the ComboEx object in place of the Combo object whether or not you make use of the extended features of the ComboEx.

Like the basic Combo, the list of text items in the ComboEx is specified by the Items property. You may associate images with each of the text items using the ImageListObj, ImageIndex and SelImageIndex properties.

To do so, ImageListObj specifies the name of an ImageList object that contains a set of images. ImageIndex and SelImageIndex map individual images from the ImageList to each of the text items specified by Items. ImageIndex specifies the image to be displayed when the item is not selected; SelImageIndex specifies the image to be displayed when the item is selected.

The Indents property specifies the amount by which each of the items are indented in units of 10 pixels

The appearance of the items is additionally controlled by the EditImage and EditImageIndent properties. These are boolean and their effect is summarised in the table below. Notice that Images are displayed only if both these properties are set to 1 (which is the default).

There are certain restrictions that apply to a ComboEx object with Style 'Simple', namely:

  • images and indents do not apply to the edit control portion of the object.
  • the object may not redraw properly if EditImage and/or EditImageIndent are set to 0 or if CaseSensitive or PathWordBreak are set to 1.
  • PathWordBreak does not work.
 | EditImageIndent
EditImage | 0 | 1
0 | No images displayed, item text is indented as specified by Indents | No images displayed, item text is indented as specified by Indents plus the width of the images in ImageList
1 | No images displayed, item text is indented as specified by Indents | Images are displayed, items are indented as specified by Indents


CoolBand Object
Parents Children Properties Methods Events
Purpose: The CoolBand object represents an area in a CoolBar that contains a child window.

Description

The CoolBand object is a container object that represents a band in a CoolBar.

A CoolBand can have any combination of a gripper bar, a bitmap, a text label, and a single child object.

A CoolBand may not contain more than one child object, but that child object may itself be a container such as a ToolControl or a SubForm.

The Caption property specifies a text string to be displayed to the left of the CoolBand. The colour of the text is specified by the Fcol property.

The ImageIndex property specifies an optional picture which is to be displayed alongside the Caption. If specified, ImageIndex is an index into an ImageList whose name is referenced via the ImageListObj property of the parent CoolBar.

The background in a CoolBand may be specified using its Bcol or Picture properties. Although typically, the visible background area is small, it is visible through a transparent ToolControl.

The ChildEdge property specifies whether or not the CoolBand leaves space above and below its child window.

The GripperMode property specifies whether or not the CoolBand has a gripper bar which is used to reposition and resize the CoolBand within its parent CoolBar. GripperMode may be 'Always'(the default), 'Never' or 'Auto'.

The position of a Cool Band within a CoolBar is determined by its Index and NewLine properties, and by the position and size of preceding CoolBand objects in the same CoolBar. For a CoolBand, Posn is a read-only property that reports its position but Posn may not be used to set it.

The Index property specifies the position of a CoolBand within its parent CoolBar, relative to other CoolBands and is ⎕IOdependant. Initially, the value of Index is determined by the order in which the CoolBands are created. You may re-order the CoolBands within a CoolBar, under program control, by changing Index with ⎕WS.

The NewLine property specifies whether or not the CoolBand occupies the same row as an existing CoolBand, or is displayed on a new line within its CoolBar parent. The value of NewLine in the first CoolBand in a CoolBar is always 1, even if you specify it to be 0. You may move a CoolBand to the previous or next row by changing its NewLine property (using ⎕WS)from 1 to 0, or from 0 to 1 respectively.

The 2nd element of the Size property determines the width of the CoolBand; the value of the 1stelement is read-only.

Size may only be specified by ⎕WC. However, when you create a CoolBand, it will automatically occupy all the available space in the current row, to the right of any preceding CoolBands. Only when you create another CoolBand in the same row, will the Size of the first CoolBand be honoured. The rightmost CoolBand will always extend to the right edge of the CoolBar, whatever its Size.

If you create two or more CoolBands in the same row and you do not specify Size, the first CoolBand will be maximised, and the others minimised.

When the user drags a CoolBand to a different row its Index and NewLine properties may change, as may the Index and NewLine properties of any another CoolBand that is affected by the operation.

If you wish to remember the user's chosen layout when your application terminates, you must store the values of Index x, Size and NewLine for each of the CoolBands. When your application is next started, you must re-create the CoolBands with the same values of these properties.


CoolBar Object
Parents Children Properties Methods Events
Purpose: The CoolBar object acts as a container for CoolBand objects.

Description

The CoolBar and CoolBand objects provide an interface to Windows Rebar Controls

A CoolBar contains one or more bands (CoolBand objects). Each band can have any combination of a gripper bar, a bitmap, a text label, and a single child object.

Using the gripper bars, the user may drag bands from one row to another, resize bands in the same row, and maximise or minimise bands in a row.

The following example illustrates a CoolBar containing 2 CoolBands each of which is displaying a ToolControl object.

'F'⎕WC'Form' 'CoolBar Object with ToolControls'('Size' 25 50)
'F.IL'⎕WC'ImageList'('Masked' 0)('MapCols' 1)
'F.IL.'⎕WC'Bitmap'('ComCtl32' 120)⍝ STD_SMALL

'F.CB'⎕WC'CoolBar'

:With 'F.CB.C1'⎕WC'CoolBand'
    'TB'⎕WC'ToolControl'('ImageListObj' '#.F.IL')
    'TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
    'TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
    'TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)
:EndWith

:With 'F.CB.C2'⎕WC'CoolBand'
    'TB'⎕WC'ToolControl'('ImageListObj' '#.F.IL')
    'TB.B1'⎕WC'ToolButton' 'Cut'('ImageIndex' 1)
    'TB.B2'⎕WC'ToolButton' 'Copy'('ImageIndex' 2)
    'TB.B3'⎕WC'ToolButton' 'Paste'('ImageIndex' 3)
    'TB.B4'⎕WC'ToolButton' 'Undo'('ImageIndex' 4)
    'TB.B5'⎕WC'ToolButton' 'Redo'('ImageIndex' 5)
:EndWith

The CoolBar allows the user to organise the CoolBands within it as required. The next three pictures illustrate this feature.

after user has moved band 2 into row 1

after user has maximised band 1

after user has maximised band 2

The second example illustrates a CoolBar containing 3 CoolBands displaying an Edit, Combo and multi-line Edit respectively.

'F'⎕WC'Form' 'CoolBar Object with simple controls'('Size' 25 40)
'F'⎕WS'Coord' 'Pixel'

'F.CB'⎕WC'CoolBar'

:With 'F.CB.C1'⎕WC'CoolBand'
    'E1'⎕WC'Edit' 'Edit1'
:EndWith

:With 'F.CB.C2'⎕WC'CoolBand'
    'C1'⎕WC'Combo'('One' 'Two' 'Three')('SelItems' 0 1 0)
:EndWith

:With 'F.CB.C3'⎕WC'CoolBand'
    'E2'⎕WC'Edit'(3 5⍴'Edit2')('Style' 'Multi')
:EndWith

The VariableHeight property specifies whether or not the CoolBar displays bands in different rows at the minimum required height (the default), or all the same height.

The BandBorders property specifies whether or not narrow lines are drawn to separate adjacent bands. The default is 0 (no lines).

The DblClickToggle property specifies whether or not the user must single-click (the default) or double-click to toggle a child CoolBand between its maximised and minimised state.

The FixedOrder property specifies whether or not the CoolBar displays CoolBands in the same order. If FixedOrder is 1, the user may move bands to different rows, but the band order is static. The default is 0. Note that when the user moves a CoolBand within a CoolBar, its Index and (potentially) NewLine properties will change to reflect its new position.

If you wish to display pictures in one or more of the CoolBands owned by a CoolBar, you do so by setting the ImageListObj property to the name of an ImageList object which contains the pictures. Pictures are allocated to individual CoolBands via their ImageIndex properties.


Cursor Object
Parents Children Properties Methods Events
Purpose: This object defines a cursor.

Description

The File property defines the name of a cursor file associated with the Cursor object, or it specifies the name of a DLL and the resource number or name of the cursor therein. If you omit the file extension, the system assumes .CUR. To use an animated cursor you must therefore specify the .AMI extension explicitly.

If the value of the File property is set by ⎕WS, no immediate action is taken, but the corresponding file may subsequently be read or written using the FileRead or FileWrite methods.

The Bits and Mask properties define the appearance of the cursor. Both are boolean matrices with a shape of 32 32. The colour of each pixel in the cursor is defined by the following table. Note that a 0 in Bits combined with a 1 in Mask causes the corresponding pixel to be the colour of the background. This is used to give the cursor a non-rectangular shape.

Bits | 0 | 1 | 0 | 1
Mask | 0 | 0 | 1 | 1
Pixel | Black | White | Background | Inverse

The HotSpot property determines the point within the cursor that registers its position over another object.

A Cursor is used by setting the CursorObj property of another object to its name or ref.


DateTimePicker Object
Parents Children Properties Methods Events
Purpose: The DateTimePicker object is an editable date/time field with an optional drop-down Calendar.

Description

The DateTimePicker object represents the built-in Windows date and time picker control. For most purposes, the DateTimePicker supersedes the use of Label, Edit and Spinner objects for displaying and entering dates and times. Unlike the Edit and Spinner objects, it is not possible for the user to enter an invalid date or time into a DateTimePicker.

The Style property may be either 'Combo'(the default) or 'UpDown'. The former provides a drop-down calendar that behaves in the same way as the Calendar object and whose appearance and behaviour is controlled by a set of properties namely CalendarCols, CircleToday, HasToday, MaxDate, MinDate, MonthDelta, Today and WeekNumbers that are common to the Calendar. See the Calendar Object for further details.

If Style is 'Combo', the Align property specifies the horizontal alignment of the drop-down Calendar which may be 'Left'(the default) or 'Right'.

If Style is 'UpDown', the DateTimePicker includes instead a pair of spinner buttons that allow the user to increment and decrement values in the various sub-fields provided by the control.

Note that the Style property may only be set when the object is created.

The DateTime property represents the date and time value that is currently displayed in the object. This is a 4-element vector containing the IDN, hour, minutes and seconds respectively.

The FieldType property specifies one of a set of pre-defined date/time formats to be used by the control. This is a character vector that may be empty (the default), 'Date', 'DateCentury', 'LongDate', 'Time'or 'Custom'. Specifying an empty vector is the same as specifying 'Date'. Note that 'DateCentury'always displays a 4-digit year, regardless of the user's Windows settings.

If FieldType is set to 'Custom', the format is defined by the CustomFormat property. CustomFormat is a character vector that may contain a mixture of date/time format elements and body text.

The HasCheckBox property is a Boolean value (default 0) that specifies whether or not a checkbox is displayed in the object. This allows the user to specify whether or not the date/time displayed in the DateTimePicker is applicable.


Edit Object
Parents Children Properties Methods Events
Purpose: Allows user to enter or edit data.

Description

The value of the Style property, which may be 'Single' or 'Multi', determines whether the object presents a single-line data entry field or an area for viewing and editing a large block of text.

Single-Line Edit

The FieldType property (which applies only to a single-line Edit object) is either an empty vector (the default) or specifies the type of the field as reflected by its Value.property. If FieldType is empty, the Value of the field may be a number or a character vector, according to the contents defined by its Text property (this is always a character vector).

If FieldType is 'Char', the Value of the field is forced to be a character vector, even if the contents defined by its Text property is entirely numeric.

If FieldType is 'Numeric', 'LongNumeric', 'Currency', 'Date', 'LongDate', or 'Time' the Value contains a number. For fields of these types, basic validation is provided during user input. The field is revalidated when the user attempts to "leave" it and at this point the object will generate a BadValue event if its contents are inconsistent with its FieldType.

Note that when an Edit object is used as the Input property of a Grid, it is the Value of the Edit object (and not its Text property) that is used to update the Values property (i.e. the contents of) the Grid when the user moves away from the cell.

The MaxLength property defines the maximum number of characters that the user may enter into the object.

The ValidIfEmpty property may be 0 (the default) or 1 and specifies whether or not the Edit field is deemed to be valid if it is empty.

The Password property specifies the character that is displayed in response to the user typing a character. Normally, Password is empty (the default) and the object displays the character that was entered. However, if you set Password to (say) an asterisk (*) this symbol will be displayed instead of the characters the user has entered. Note however that the Text and Value properties will reflect what the user typed.

The HScroll property determines whether or not the data may be scrolled. If HScroll is 0, the data is not scrollable, and the user cannot enter more characters once the field is full. If HScroll is ¯1 or ¯2 the field is scrollable, and there is no limit on the number of characters that can be entered. In neither case however is a horizontal scrollbar provided. HScroll may only be set when the object is created and may not subsequently be changed.

Multi-Line Edit

If the Style is 'Multi', Text may be a simple character vector, a matrix, or a vector of vectors. If you specify Text as a matrix, "new-line" characters are automatically added at the end of each row. Similarly, if you specify Text as a vector of vectors, "new-line" characters are added after each vector. The user may insert a "new-line" character in the text by pressing Ctrl-Enter.

If you specify (assign) Text as a vector or vector of vectors, it will be returned as a vector of vectors when you query it. Otherwise, it will be returned as a matrix. "New-line" characters are not returned.

The Justify property determines whether the text in a multi-line Edit object is 'Left', 'Right', or 'Centre' justified. Setting Justify to 'Centre' or 'Right' also forces word-wrapping and disables horizontal scrolling, whatever the value of HScroll. Note that they keyword 'Centre' may also be spelled 'Center'. Justify may only be specified when the object is created using ⎕WC.

If Justify is 'Left', the HScroll property determines whether or not text may be scrolled horizontally. If HScroll is set to ¯2, each individual line may be any length, but the object does not have a horizontal scrollbar. Sideways scrolling is achieved using the cursor keys, or by typing. If HScroll is ¯1, each individual line may be of any length and the object will have a horizontal scrollbar. If HScroll is 0, lines are automatically "word-wrapped" at the right edge of the object. This means that the number of lines displayed may be greater than the number of lines implied by the rows of the matrix or the number of vectors supplied. In particular, if you specify a single long vector, it will be broken up into lines for you on the display, but still returned as a single vector by ⎕WG.

The VScroll property determines whether or not data may be scrolled vertically and whether or not the object has a vertical scrollbar. A value of 0 inhibits scrolling; ¯2 means scrollable, without a scrollbar; ¯1 means scrollable with a scrollbar. VScroll may only be set when the object is created and may not subsequently be changed.

The setting of Justify forces word-wrapping.

The SelText property identifies the portion of the text that is selected. It may be used to pre-select (and highlight) a part of the text, or to report the part of the text selected by the user. SelText is a 2-element integer vector which specifies the start and end of the selected area. Its structure depends upon the nature of the data specified by Text. See the description of SelText for details.

If the user changes any data in the field and attempts to change focus to another object, the Edit object will generate a Change event. You can use this to validate the new data in the field.


Ellipse Object
Parents Children Properties Methods Events
Purpose: A Graphical object to draw ellipses, arcs, and pie-slices.

Description

This object duplicates much of the functionality of the Circle object, but differs in two major respects. Firstly, ellipses, circles, and arcs are specified in terms of their bounding rectangles, rather than in terms of their centre(s) and radii. Secondly, the Ellipse object behaves like any other (rectangular) object when it is resized by its parent. The Circle object behaves differently in that when resized by its parent, it maintains a constant ratio between its physical height and width.

The Points property specifies one or more sets of co-ordinates which define the position(s) of one or more bounding rectangles. The position is defined to be the position of the corner that is nearestto the origin of its parent. The default is therefore its top-left corner.

The Size property specifies the height and width of each bounding rectangle, measuring away from the origin. To obtain a perfect circle, you must take the aspect ratio of the device into account. This is available from the DevCaps property of the Root and Printer objects. Alternatively you can use the Circle object.

The Start and/or End properties are used to draw partial ellipses and circles. They specify start and end angles respectively, measuring from the x-axis at the centre of the bounding rectangle in a counter-clockwise direction and are expressed in radians. The type of arc is controlled by ArcMode as follows.

Arcmode | Effect
0 | An arc is drawn from Start to End.
1 | An arc is drawn from Start to End. In addition, a single straight line is drawn from one end of the arc to the other, resulting in a segment.
2 | An arc is drawn from Start to End. In addition, two lines are drawn from each end of the arc to the centre, resulting in a pie-slice.

LStyle and LWidth define the style and width of the lines used to draw the boundaries of the ellipse(s), circle(s) or arc(s). FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the ellipse(s), circle(s) or arc(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the spaces between them.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Ellipse object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple ellipses, circles or arcs .

Single Ellipse, Circle or Arc

For a single ellipse, circle or arc, Points is a 2-element vector which specifies the y-coordinate and x-coordinate of the top-left corner of the bounding rectangle.

Size is also a simple 2-element vector whose elements specify the height and width of the bounding rectangle.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used to fill the ellipse, circle or arc.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

Examples:

First make a Form :

      'F' ⎕WC 'Form'

Draw a complete ellipse within the bounding rectangle located at (y=10, x=5) with (height=30, width=50) :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)

Draw an elliptical arc within the same bounding rectangle as above, occupying the upper right quadrant (0 to 90 degrees):

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('End'(○0.5))

Ditto, but between 45 and 135 degrees :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))

Ditto, but join the points of the arc to the centre of the ellipse, making a "pie-slice":

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))('ArcMode' 2)

Ditto, but use a green line and solid red fill :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))('ArcMode' 2)('FCol' 0 0 255)('FStyle' 0)('FillCol' 255 0 0)

Multiple Ellipses, Circles or Arcs

To draw a set of ellipses, circles, or arcs with a single name, Points may be a simple 2-element vector (specifying the location of all the bounding rectangles), or a 2-column matrix whose first column specifies their y-coordinates and whose second column specifies their x-coordinates, or a 2-element nested vector whose first element specifies their y-coordinate(s) and whose second element specifies their x-coordinate(s).

Likewise, Size may be a simple 2-element vector (applying to all the bounding rectangles), or a 2-column matrix whose first column specifies their heights and whose second column specifies their widths, or a 2-element nested vector whose first element specifies their height(s) and whose second element specifies their width(s).

If specified, Start and/or End define arcs in terms of the angles made by drawing a line from the centre of the bounding box to the two ends of the arc. Both properties may be simple scalars, or vectors containing one element per arc drawn.

If Start is specified, but not End, end angles default to (¯1↓+\Start),○2. If End is specified, but not Start, start angles default to 0,¯1↓+\End

This means that you can draw a pie-chart using either Start or End angles; you do not have to specify both.

ArcMode, LStyle and LWidth may each be simple scalar values (applying to all the ellipses, circles or arcs) or simple vectors whose elements refer to each of the corresponding ellipses, circles or arcs in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all rectangles, or a vector whose elements refer to each of the corresponding ellipses, circles or arcs in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the rectangles. Alternatively, these properties may contain vectors whose elements refer to each of the rectangles in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

The Coord, Dragable and Data properties are specified for the object as a whole, and may not be allocated different values for each individual ellipse, circle or arc that is drawn.

Examples

First make a Form :

      'F' ⎕WC 'Form'

Draw two ellipses in bounding rectangles located at (y=5, x=10) and (y=5, x=60), each of (height=40, width=10)

      'F.E1' ⎕WC 'Ellipse' ((5 5)(10 60)) (40 10)

Ditto, using scalar extension for (y=5) :

      'F.E1' ⎕WC 'Ellipse' (5(10 60)) (40 10)

Ditto, but draw the first with (height=40, width=30) and the second with (height=20, width=10) :

      'F.E1' ⎕WC 'Ellipse' (5(10 60)) ((40 20)(30 10))

Draw an elliptical Pie-Chart in a bounding rectangle located at (y=5, x=10) with a height and width equal to 40% of the height and width of the parent Form. Each of the 4 pie-slices is bounded by a black line :

      Data ←12 27 21 40
      ANGLES←0,¯1↓((○2)÷+/Data)×+\Data
      COLS←(255 0 0)(0 255 0)(255 255 0)(0 0 255)
      PATS←1 2 3 4

      'F.PIE' ⎕WC 'Ellipse'(5 10)(40 40)
                  ('Start' ANGLES)('ArcMode' 2)
                  ('FCol' (⊂0 0 0))('FStyle' PATS)
                  ('FillCol' COLS)


FileBox Object
Parents Children Properties Methods Events
Purpose: Prompts user to select a file.

Description

The FileBox object implements the standard Windows FileSelection Dialog Box. This is a "modal" object. When you create a FileBox with ⎕WC, it is initially invisible and the user cannot interact with it. To use it, you must execute ⎕DQ with the name of the FileBox as its right argument. This causes the FileBox to be displayed. During the "local" ⎕DQ the user may interact only with the FileBox, or with other applications. When the user terminates the operation (by pressing the "OK" or "Cancel" Buttons, or by closing the window) the "local" ⎕DQ terminates, and the FileBox disappears.

When the "local" ⎕DQ is terminated, the FileBox generates either an FileBoxOk(71) or FileBoxCancel(72) event. The former is generated when the user presses the "OK" button or closes the FileBox; the latter when the user presses the "Cancel" button.

The Caption property determines the text that appears in the title bar of the FileBox window. If undefined, Caption defaults to "Save As" if FileMode is 'Write' or to "Open" if FileMode is 'Read'. The Directory property contains a simple character vector which specifies the initial directory from which a list of suitable files is displayed.

      'F' ⎕WC 'FileBox' 'The FileBox Object' 'C:\WDYALOG'
      ⎕DQ 'F'

The Style property specifies whether the user may choose a single file name ('Single' which is the default) or several file names ('Multi').

The Filters property is a nested scalar or vector containing a list of filters. Each filter is a 2-element vector of character vectors which contain a file type mask and a file type description respectively. The file type descriptions appear in a drop-down combo box labelled "List File of Type". When the user selects one of these, the currently selected directory is searched for files which match the corresponding mask. The default value of Filters is an empty vector. This gives a file type mask of "*.*" and a file type description of "All Files (*.*)". Hence an empty vector is equivalent to (⊂'*.*' 'All Files (*.*)').

The FileMode property is a character vector which indicates the mode in which the selected file is going to be opened. FileMode may be 'Read' (the default) or 'Write'. If FileMode is 'Write', files listed in the File Selection Box are "greyed", although they may still be selected.

The Index property determines which of the filters is initially selected. Its default value is ⎕IO.

Note that when ⎕DQ terminates with FileBoxOk, the File, Directory, and Index properties are updated to reflect the contents of the fields within the FileBox.


Font Object
Parents Children Properties Methods Events
Purpose: Loads a font resource

Description

This object loads a Windows font into memory ready for use by another object. The characteristics of the font are specified by its properties as follows :

PName | A character vector containing the name of the font face. The default is 'System'. Note that case is ignored when you specify the name, although it will be returned correctly by ⎕WG.
Size | An integer that specifies the character height of the font in pixels.
Fixed | A boolean value that specifies whether the font is fixed-width (1) or proportional (0).
Italic | A boolean value that specifies whether the font is italicised (1) or not (0).
Underline | A boolean value that specifies whether the font is underlined (1) or not (0).
Weight | An integer in the range 0-1000 that specifies how bold or heavy the font is (1000 = most bold).
Rotate | A numeric scalar that specifies the angle of rotation of the font in radians. The angle is measure from the x-axis in a counter-clockwise direction.
CharSet | An integer that specifes the character encoding.

When you ask Windows to allocate a font, you may specify as many or as few of these properties as you wish. Windows actually supplies the font that most closely matches the attributes you have specified. The matching rules it uses are complex, and may be found in the appropriate Windows documentation.

The values of the above properties after ⎕WC or ⎕WS reflect the attributes of the font which has been allocated by Windows, and not necessarily the values you have specified. Furthermore, it is possible that changing the value of one property will cause the values of others to be changed.


Form Object
Parents Children Properties Methods Events
Purpose: This is a top-level window used to contain other objects (controls).

Description

The Posn property specifies the location of the internal top-left corner of the window relative to the top-left corner of the screen. If the window has a title bar and/or border, you must allow sufficient space for them. Similarly, the Size property specifies the internal size of the window excluding the title bar and border. The default for Size is 50% of the screen height and width. The default for Posn places the Form in the middle of the screen.

Normally, a Form has a title bar, a system menu box, a border and maximise and minimise buttons. To disable the System Menu box, set SysMenu to 0. To disable one or both of the maximise/minimise buttons, set MaxButton and/or MinButton to 0.

The HelpButton property specifies that a Question (?) button appears in the title bar of the Form. However, this does not apply if the Form has a maximise or minimise button which both take precedence. The user may obtain help by clicking on the Question (?) button and then on a control in the Form. It is up to you to provide the help by responding to the Help event on the control.

By default, a Form may be moved and resized using the mouse. These actions are achieved by dragging on the title bar and border respectively. It follows that a Form that is Moveable musthave a title bar, and one that is Sizeable must have a border, regardless of the value of other properties. Also, if you specify any of SysMenu, MaxButton or MinButton, the window must have a title bar in which to place these controls. A title bar itself requires a border. To obtain a window without a title bar, you must therefore set Moveable, SysMenu, MaxButton and MinButton to 0. Note that setting Caption does not force a title bar on the window.

If Sizeable is 1, the window will have a double-line border, regardless of the values of other properties. If Sizeable is 0, and any one or more of Moveable, SysMenu, MaxButton, MinButton or Border is 1, the window will have a 1-pixel border. Only if all these properties are 0 will the window be borderless. To obtain a dialog box that may only be moved or closed, set Border to 2.

Note that the default value for Caption is an empty character vector which results in a blank title.

To obtain a standard dialog box with 3-dimensional appearance, create a Form with Border set to 2 and EdgeStyle set to 'Dialog', for example:

  'F' ⎕WC 'Form' 'Dialog Box' ('EdgeStyle' 'Dialog')('Border' 2)

The State property has the value 0 if the window is currently displayed in its "normal" state, 1 if it is currently displayed as an icon, and 2 if it is currently maximised and displayed full-screen. This property does not just report the current state, but can be used to set the state under program control.

The VScroll and HScroll properties determine whether or not a Form has a vertical and horizontal scrollbar respectively. These properties are set to ¯1to obtain a scrollbar. Their default value is 0 (no scrollbar). VScroll and HScroll may only be set when the object is created and may not subsequently be changed. The Range property is a 2-element vector that specifies the maximum value for the vertical and horizontal scrollbars respectively. The PageSize property is a 2-element vector that specifies the sizes of the thumbs in each scrollbar. The Step property is a 4-element vector that specifies the sizes of the small and large change. Its first two elements refer to the vertical scrollbar, elements 3 and 4 refer to the horizontal scrollbar. The Thumb property is a 2-element vector that both reports and sets the position of the thumb in the vertical and horizontal scrollbars respectively. When the user attempts to move the thumb in one of the scrollbars, the Form generates a VScroll or HScroll event.

VScroll and HScroll cannot be changed using ⎕WS. However, you can make a scrollbar disappear by setting the corresponding element of Range to 1, thus allowing you to dynamically switch the scrollbar off and on. Note however that doing so will change the size of the Form.

Setting the FontObj property on a Form does not affect the text in its title bar. However, the value of FontObj will (unless over-ridden) be inherited by all of the objects within the Form.

The background of the Form may be coloured using BCol. The default value for BCol is the Windows Button Face colour unless EdgeStyle is set to 'None' or 'Default'in which case it is the Windows background colour. Alternatively, the background of a Form can be defined using a Bitmap or Metafile object whose name is defined by the Picture property. A Metafile is automatically scaled to fit the Form. A Bitmap can be tiled orscaled. See Picture property for details.

The OnTop property is either 0 or 1. If it is 0, the Form assumes its normal position within the stack of windows on the screen and is only brought to the front when it receives the input focus. If OnTop is set to 1, the Form is always brought to the front even when it doesn't have the focus. If more than one Form has OnTop set to 1, the stacking order of this set of Forms is defined by the order in which they were created.

A Form can be created as a child of another Form. If so, it has the following characteristics :

  • A child Form always appears on top of its parent Form (although it is not constrained by it)
  • When you minimize a parent Form, its child Forms disappear.
  • Making the parent Form invisible or inactive has no effect on a Child Form.

Note that the Posn and Size properties of a child Form are expressed in screen coordinates and are not given relative to its parent.


Grid Object
Parents Children Properties Methods Events
Purpose: Spreadsheet object for displaying and editing data.

Description

The Values property is a matrix whose elements are displayed in the cells of the Grid. An element (and therefore a cell) may contain a single number, a single character, a character vector or a character matrix.

The CellHeights property specifies the height of each of the rows of the spreadsheet. It may be a single value which applies to all rows, or a vector with one element per row. The CellWidths property determine the width of each column of the spreadsheet. It too may be a single value or a vector with one element per column.

The RowTitles property is either an empty character vector (the default) or a vector of character vectors that specify row titles displayed to the left of the cells in the Grid. If RowTitles is not specified, the Grid labels each row with its row number. The ColTitles property is similar and is used to specify column headings. If ColTitles is not specified, the Grid displays "standard" spreadsheet column headings A-Z, then AA-AZ and so forth.

The TitleHeight property specifies height of the column headers. If this is set to 0, the column titles will not be displayed. Similarly, the TitleWidth property specifies the width of the row titles and again a value of zero disables the row titles.

The FontObj property may be used to specify the font to be used for the Grid as a whole, including the titles. The CellFonts property may be used to specify fonts for individual cells.

The FCol and BCol properties may each specify a single colour for the Grid as a whole, or may specify a vector of colours whose elements are mapped to individual cells through the CellTypes property.

The CellFonts property is either a character vector or a vector of character vectors that specifies the name of a single font object to be used for all cells in the Grid, or a vector of character vectors that specifies a set of font objects that are mapped to individual cells through the CellTypes property.

The Input property is a character vector that specifies the name of an object which is to be associated with every cell in the Grid, or a vector of names whose elements are mapped to individual cells through the CellTypes property. These objects may be of type Button, ColorButton, Combo, Edit, Label, Spinner or TrackBar. In addition, the Input property may specify instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes).

If the Input property is empty (the default) the user may browse the data in the spreadsheet but may not alter it. Furthermore, no feedback is provided as to which is the current cell. If the Input property specifies the name of an object that is the child of the Grid itself, this object floats from cell to cell as the user moves around the spreadsheet, and the current cell is identified by its presence.

If the Input property specifies the name of an external object (that is, an object that is nota child of the Grid), the contents of the current cell are copied into that object as the user moves around the spreadsheet. In addition, the current cell is identified by a thick border. In either case, the associated object is used to impose formatting and validation.

If the Input property specifies the name of a Label object, that object is used to impose formatting, but the data is protected and may not be changed. If the Label is a child of the Grid, it moves from cell to cell, and its characteristics (Border, FCol, BCol and FontObj) can be used to identify the current cell. If the Label is an external one, no visual feedback is provided; even though the current cell (reflected by the CurCell property) changes as the user moves around the Grid.

If the Input property specifies one or more instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes), the InputProperties property is used to map the Values property of the Grid to specific properties of the external object.

The CellTypes property is either an empty numeric matrix (the default) or an integer matrix of the same shape as Values. If specified, each element of CellTypes determines the index into various properties, including the FCol, BCol, CellFonts and Input properties, to be used for the corresponding cell. For example, if an element in CellTypes is 3, the 3rd element of FCol is used for the foreground colour of the corresponding cell, the 3rd element of BCol specifies the background colour, and so forth.

The CurCell property may be used to set or query the current cell. The current cell is the cell which the user has picked by clicking the mouse over it or by using the cursor keys. CurCell is a 2-element vector containing the current cell's row number and column number respectively and is ⎕IOdependent. The Index property specifies the row and column number of the cell in the top-left corner of the Grid. It too is ⎕IOdependent.

The AutoExpand property is a 2-element boolean vector which specifies whether (1) or not (0) new rows and columns are added when the user presses the corresponding cursor key when at the end of the block of cells. Its default value is (0 0).

The Grid object reports a CellDown event when the user depresses a mouse button over a cell. The event message contains the row and column address of the cell in question which is ⎕IOdependent. It also reports a similar CellUp event when the mouse button is released and a CellDblClick event when it is double-clicked. The number of the mouse button and the state of the shift keys are also reported.

When the user moves to another cell, the Grid object reports a CellMove event. This simply reports the address of the new cell and may be used to take some appropriate action when a particular cell is picked. If the user alters the data in a cell and then attempts to move to another, the Grid reports a CellChange event. This can be used to perform validation.

Alternatively, the Grid may report a CellChanged event which occurs after the Values property has been updated with the new cell contents. This may be used to perform immediate recalculation.

The AddRow event is generated if the current cell is in the last row of the Grid and the user presses Cursor Down. By default, this operation adds a new row to the Grid, but you can attach a callback to the AddRow and selectively disable this default action if required. The AddCol event works in a similar manner for columns. Although the user has no direct means of inserting a row or column, your application can do this by calling AddRow or AddCol as a method on the Grid object. Typically this would be done in response to the user selecting a MenuItem or pressing a Button.

The ColChange, RowChange, DelRow, DelCol and Undo methods allow your application to perform these corresponding operations.

The Grid object maintains a buffer of the most recent 8 changes made by the user since the Values property was last set by ⎕WC or ⎕WS. Your application can restore these changes one by one by calling the Undo method. The Undo method restores the most recent change made by the user and removes that change from the undo stack. It is therefore not possible to "undo an undo".

The Grid supports the selection of a block or blocks of cells using the mouse and/or the keyboard. The ability to select a range of cells is determined by the CellSelect property. When the user performs a selection , the Grid generates a GridSelect event. The range of cells currently selected is given by the SelItems property

If a block of cells has been selected, the user may delete the contents, and cut or copy the contents of the cells to the clipboard by pressing Delete, Shift+Delete or Ctrl+Insert respectively. These operations also generate GridDelete, GridCut and GridCopy events which you can selectively disable using a callback function. You can also perform these operations under program control by calling them as methods.

If more than one block of cells has been selected, these operations are honoured only if the blocks begin and end on the same rows or begin and end on the same columns. If so, the data placed in the clipboard is the result of joining the blocks horizontally or vertically as appropriate.

The user may paste data from the clipboard into a Grid by pressing Shift+Insert. Data is pasted into the currently selected block of cells, or, if there is no selection, data is pasted starting at the current cell (CurCell). The operation also generates a GridPaste event, and, if the operation cannot proceed, a GridPasteError event.

If you move the mouse pointer over any of the four edges of a selected block of cells, the cursor changes to an arrow. You may now click and drag the border of the selected cells with the mouse.

If you press the Ctrl key at the same time, the contents of the selected cells are copied to the new location, replacing the values in the block of cells onto which they are dropped. Otherwise, the operation is treated as a move and the original block of cells is emptied. This operation also generates a GridDropSel event. You may only move or copy a single block of cells in this way.

The user may be permitted to resize the rows and/or columns of a Grid. This is controlled by the ResizeRows and ResizeCols properties whose default values are 0. To allow the user to resize, set either or both to 1. You can also specify a boolean vector to allow specific rows/columns to be resized while others are fixed. Two additional properties named ResizeRowTitles and ResizeColTitles determine whether or not the user may alter the width of the row titles and the height of the column titles.

If resizable, the cursor changes to a double-heads arrow when the user moves the mouse pointer over the lines between the row and/or column titles. The user may click and drag with the mouse to the desired size. The user may also double-click. This causes the row or column to be resized to fit the data. Both operations generate a SetColSize, or SetRowSize event.

When you edit data in a Grid, the editing behaviour and the action of the cursor movement keys is determined by the InputMode and InputModeKey properties.

The GridFCol property specifies the colour of all the grid lines. Alternatively, the GridLineFCol, GridLineWidth, RowLineTypes and ColLineTypes properties may specify the appearance for individual grid lines.

The GridBCol property specifies the colour used to fill the area between the end of the last column of data and the right edge of the Grid and between the bottom row of data and the bottom edge of the Grid.

The RowTitleFCol and ColTitleFCol properties specify the colours to be used for the row and column titles respectively.

The ClipCells property determines whether or not the Grid displays partial cells. The default is 1. If you set ClipCells to 0, the Grid displays only complete cells and automatically fills the space between the last visible cell and the edge of the Grid with the GridBCol colour.

The CellSet property is a boolean array that marks which cells are set (i.e. have values) and which are empty. This allows you to edit large numeric matrices which contain empty cells without a severe workspace penalty.

The Hscroll and Vscroll properties specify whether or not horizontal and vertical scrollbars are displayed. Either property may be given the value ¯3 which forces the corresponding scrollbar to appear always. VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

The Grid object supports comments in a manner that is consistent with the way that comments are handled by Microsoft Excel.. If a comment is associated with a cell, a small red triangle is displayed in its top right corner. When the user rests the mouse pointer over a commented cell, the comment is displayed as a pop-up with an arrow pointing back to the cell to which it refers. The comment disappears when the mouse pointer is moved away. This is referred to as tip behaviour. Comments may also be associated with row and column titles.

Grid comments are managed by a set of methods, namely AddComment, DelComment, GetComment, ShowComment, HideComment and ClickComment.

You may lock individual rows and columns using the LockRows and LockColumns methods. This facility is however not supported in combination with hierarchical rows and/or columns which are specified by RowTitleDepth and ColTitleDepth.

The Grid can display a TreeView like interface on the Row titles. In this mode, the Grid automatically shows and hides row of data as the end user expands and contracts nodes of the tree.

The RowTreeDepth property is used to specify the depth of rows in the Grid.

The appearance of the tree is determined by the RowTreeStyle property.

User defined bitmaps can be used instead of the default Images by setting the RowTreeImages property.

The Grid generates Expanding and Retracting events when the user interacts with the tree.

The RowSetVisibleDepth method can be used to set the visible depth of the tree.


Group Object
Parents Children Properties Methods Events
Purpose: This object is used to group a related set of controls together visually, and to impose "radio-button" behaviour.

Description

A Group is displayed as an empty box with a border around it whose appearance is defined by the EdgeStyle property. The Caption property defines a string of text that is displayed in the top left border. The default value is an empty vector.

A Group will be resized if its parent Form or Group is resized. It can also be resized directly by the user if its Sizeable property is set to 1. By default, when a Group is resized, it automatically adjusts the size and position of its children to maintain the same proportions within it as before. The resizing of a Group and its children can be controlled using the AutoConf property or by enabling the Configure event (31).


Icon Object
Parents Children Properties Methods Events
Purpose: This object defines an icon.

Description

The File property specifies the name of an icon file (.ICO. .GIF or .PNG), or the name of a DLL or EXE file and the identity of the icon within it.

The Style property identifies the size of the icon and must be 'Large' or 'Small'. The former specifies a 32x32 icon and is the default; the latter specifies a 16x16 icon. The size of the icon is not embedded within the icon data, so it is essential to specify Style correctly. Note that a single file may contain both sizes of an icon. Style is only relevant when loading an Icon from file.

If the value of the File property is set by ⎕WS, no immediate action is taken, but the corresponding file may subsequently be read or written using the FileRead or FileWrite methods.

Prior to Windows XP, icon images contained fewer than 256 colours and each pixel was either transparent or opaque.The images in such Icons are represented by the Bits, Mask and CMap properties.

Windows XP introduced 32-bit icons . These are 24-bit images with an 8-bit alpha channel which specifies the degree of transparency of each pixel. The pixels in these Icons are represented by the CBits property.

CBits is a rank-2 numeric array whose dimensions represent the rows and columns of pixels in the Icon. The values in CBits represent the colour and of each pixel and also its transparency.

Bits is an integer matrix whose elements define the colours of each pixel in the icon in terms of their (0-origin) indices into CMap. When the icon is displayed on the screen, the way in which these colours combine with those currently displayed on the screen (the background) is specified by Mask. This is a boolean matrix of the same size as Bits. The following table shows how the colour of each resulting pixel is determined.

Bits | Colour | 0 | Colour
Mask | 0 | 1 | 1
Pixel | Colour | Background | New Colour

If an element of Mask is 0, the corresponding element of Bits defines the colour of the resulting pixel that is displayed on the screen. If an element of Mask is 1, the resulting pixel that is displayed on the screen is either the current background colour or is a new colour chosen by MS-Windows to be visible against the background. A non rectangular icon is obtained by setting those elements of Bits and Mask that you want to exclude from the shape to be 0 and 1 respectively.

The size of Bits is restricted by the capabilities of the current display driver. Mask must have the same shape as Bits.

An Icon is used by setting the IconObj property or Picture property of another object to its name or ref.


Image Object
Parents Children Properties Methods Events
Purpose: Positions bitmaps and icons within an object.

Description

The Points property specifies the co-ordinates of one or more points at which the specified graphical objects are to be drawn.

The Picture property specifies the name(s) of Bitmap, Icon or Metafile object(s) that are to be drawn. It may be a simple character vector or a vector of vectors.

To draw a single graphic picture, the Picture property is a simple character vector specifying the name of a Bitmap, Icon or Metafile object. Points is either a 2-element vector or a 1-row, 2-column matrix whose elements specify the y-coordinate and x-coordinate respectively at which the object is to be drawn.

To draw the same picture at several different positions, the Picture property is a simple character vector specifying the name of the Bitmap, Icon or Metafile object. Points is either a 2-column matrix of y-coordinates and x-coordinates, or a nested vector whose first element contains the y-coordinates and whose second element contains the x-coordinates.

To draw several different pictures, the Picture property is a vector of character vectors specifying the names of several Bitmap, Icon and/or Metafile objects. Points is a 2-column matrix or 2-element nested vector as described above.

Setting the EdgeStyle property causes the picture to be surrounded by the appropriate border. For example, setting EdgeStyle to 'Plinth' produces a button-like appearance.

Setting the Size property causes the picture to be scaled to fit within the specified rectangle. It is only necessary to specify Size when an Image is used to draw a Metafile object. For a Bitmap or Icon, Size defaults to the size of the object being drawn.

The Dragable property specifies whether or not the Image can be dragged and dropped using the mouse.

Examples:

First make a Form

      'F' ⎕WC 'Form'

Then make two Bitmaps :

      'YES' ⎕WC 'Bitmap' 'C:\WDYALOG\WS\YES'
      'NO'  ⎕WC 'Bitmap' 'C:\WDYALOG\WS\NO'

Display the "YES" Bitmap at (20,10)

      'F.I' ⎕WC 'Image' (20 10)('Picture' 'YES')

Display the "YES" Bitmap at (20,10) and (20,50)

      'F.I' ⎕WC 'Image' (20(10 50))('Picture' 'YES')

Display the "YES" Bitmap at (20,10) and the "NO" Bitmap at (20,50)

      'F.I' ⎕WC'Image'(20(10 50))('Picture' 'YES' 'NO')


ImageList Object
Parents Children Properties Methods Events
Purpose: The ImageList object represents a set of bitmapped images.

Description

An ImageList object represents an array of bitmapped images which are used to depict items in a ListView or TreeView object, or the images in a CoolBar, Menu, TabControl or ToolControl.

Making an ImageList is a 2-step process. First, you create an (empty) ImageList specifying its Size and Masked properties. The former establishes the size of each of the bitmapped images in the array. The Masked property specifies whether the ImageList is to contain opaque or transparent images. Note that these properties must be established when the ImageList is created by ⎕WC and may not subsequently be changed using ⎕WS.

Next, you create a series of Bitmap or Icon objects as children of the ImageList. As you make each one, APL adds the corresponding image (or images) to the ImageList object. If the size of each of the Bitmap or Icon objects is equal to the Size of the ImageList itself, each child object corresponds to an image in the ImageList. However, if you add an object whose width is an exact multiple of the width of the ImageList, a corresponding number of images will be added.

For example, if the Size of the ImageList is 16x16 (the default) and you create a child Bitmap of size 16x48, three images (each of size 16x16) will be added to the ImageList. This is more efficient than building the images one-by-one. In other circumstances (where the size of the Bitmap or Icon is not equal to Size of ImageList), the Bitmap or Icon will be scaled to fit.

Note that when making Bitmaps or Icons as children of an ImageList, it is not necessary to name them because they are subsequently referenced only via the ImageIndex and SelImageIndex properties and not by name. The number of images in an ImageList is given by the read-only property, ImageCount.

The MapCols property, which must be specified at the time you create the object, specifies whether or not bitmap colours are remapped to reflect the user's colour preferences.

An ImageList is associated with a ListView or TreeView object by the ImageListObj property. Each item in the ListView or TreeView is then allocated a specific image in the ImageList by the ImageIndex and SelImageIndex properties.


Label Object
Parents Children Properties Methods Events
Purpose: Displays static text.

Description

This object displays a text label, a number, a date or a time value.

If FieldType is empty, the Label displays the text defined by its Caption property. If FieldType is 'Numeric', 'LongNumeric', 'Currency', 'Date', 'LongDate', or 'Time' the Label converts and formats the number defined by its Value property and displays this instead. See FieldType property for details.

The Border property determines whether or not the label has a border. A value of 0 means no border (the default). A value of 1 means that a 1-pixel border is drawn around the label.

By default, the value of the EdgeStyle property for a Label is 'None' and the value of BCol is 0 which is normally white, or grey if the parent object has a 3-dimensional appearance. You can change its appearance by setting EdgeStyle and/or BCol to different values.


List Object
Parents Children Properties Methods Events
Purpose: Allows the user to select one or more items from a list.

Description

The Items property is either a vector of character vectors or a character matrix, and determines the items in the List.

The size and position of the area used to display the list is defined by Size and Posn. If Size is not chosen to represent an exact number of lines of text, the bottom line of text may be clipped.

The Index property specifies or reports the position of Items in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. However, it is ignored if all the Items fit within the List object. Note that Index can only be set using ⎕WS and not by ⎕WC. The default value for Index is ⎕IO.

The Style property may be 'Single' (the default) or 'Multi'. 'Single' allows only a single item to be selected. 'Multi' allows several items to be chosen. In either case, if the Select event is enabled, it is generated whenever the selection changes. If Style is 'Multi' the List will generate a Select event every time an item is added to the selected list.

Under Windows, you may select or de-select multiple items in a List object by pressing the Ctrl key at the same time as pressing the left mouse button.

The SelItems property is a boolean vector with one element per element or row in Items and indicates which (if any) of the items is currently selected (and highlighted).

The VScroll property determines whether or not the list has a scrollbar. Its possible values are :

¯2 | scrollbar if required
¯1 | scrollbar if required
0 | no scrollbar

Note that data in a List is always scrollable if there are more items than will fit in the box. VScroll determines ONLY whether or not a scrollbar is provided.

The MultiColumn property is a boolean value that specifies whether or not the List object displays its items in columns. The default is 0 which produces a single-column display. If MultiColumn is 1, the List object displays its items in columns whose width is defined by the ColumnWidth property.


ListView Object
Parents Children Properties Methods Events
Purpose: The ListView object displays a collection of items.

Description

The ListView object is a window that displays a collection of items, each item consisting of an icon and a label. The ListView provides several ways of arranging items and displaying individual items. For example, additional information about each item can be displayed in columns to the right of the icon and label. An example of the use of a ListView object is the "My Computer" Windows utility.

The Items property is a vector of character vectors that specifies the labels for the items displayed by the ListView. The ImageListObj property specifies the names of two ImageList objects that define two sets of icons; a large icon (32x32 pixel) set and a small icon (16x16 pixel) set. Alternatively, ImageListObj may be empty (no icons displayed) or contain just the name of a single large icon ImageList.

The View property contains a character vector that determines how the items are displayed. It may have one of the following values; 'Icon' (the default), 'SmallIcon', 'List' or 'Report'. When View is 'Icon' or 'SmallIcon', the items are arranged row-wise with large or small icons as appropriate. When View is set to 'List', the items are arranged column-wise using small icons. Examples of 'Icon'and 'List' views are illustrated below.

When View is set to 'Report', the items are displayed in a single column using small icons but with the matrix specified by ReportInfo displayed alongside. In this format, the boolean Header property determines whether or not the object also provides column headings. Its default value is 1. The column headings themselves are specified by the ColTitles property. Their alignment (and the alignment of the data in the columns beneath them) is defined by the ColTitleAlign property.

The appearance of the column titles is further controlled by the ColTitle3D property. This is a boolean value (default 1) which specifies whether or not the column titles have a 3-dimensional (plinth) appearance. Header and ColTitle3D may only be set when the object is created using ⎕WC and may not subsequently be changed by ⎕WS.

In 'Report' View, columns may be resized by the user dragging the bars between the titles, or under program control using the SetColSize event. A 'Report'view example is illustrated below.

The DragItems property is boolean and specifies whether or not the user may drag an item from one position to another. Its default value is 1 (dragging is enabled).

The AutoArrange property is boolean and specifies whether or not the items are automatically re-arranged whenever an item is repositioned by the user or moved under program control. Its default value is 0.

The EditLabels is a boolean property (default 0) that determines whether or not the user may edit the labels which are specified by the Items property.

The Style property may be 'Single', which specifies that only one item may be selected at a time, or 'Multi'which permits multiple selections to be made. The default is 'Multi'.

The CheckBoxes property is Boolean and specifies whether or not check boxes are drawn to the left of items. Its default value is 0.

The GridLines property is Boolean and specifies whether or not grid lines are drawn between items. This applies only when View is 'Report'. Its default value is 0.

In 'Report' View, the ReportImageIndex property specify images to be displayed alongside each item, and overrides the images specified by ImageListObj. The HeaderImageList and HeaderImageIndex properties specify images to be displayed alongside each column title.

The following example illustrates the use of these properties.

The ReportBCol property specifies each item's background colour.

The FullRowSelect property is Boolean and specifies whether or not the entire row is highlighted to indicate selected items. This applies only when View is 'Report'. Its default value is 0.

The ItemGroups and ItemGroupMetrics properties allow you to display items in groups as illustrated below.

Note that this feature only apples if Native Look and Feel is enabled.


Locator Object
Parents Children Properties Methods Events
Purpose: Allows the user to input a point, ellipse, line or rectangle.

Description

This object is used to obtain graphical input from the user. Like a pop-up menu or a MsgBox, the Locator is a modalobject whose interaction with the user is initiated by a "local" ⎕DQ. This is terminated when the user releases a mouse button or presses any key other than a cursor movement key, Shift, Ctrl or Alt.

It is usual to initiate the ⎕DQ for the Locator from within a callback function attached to a MouseDown (1) Event.

When the "local" ⎕DQ is terminated, a Locator (80) Event is generated. The associated event message contains the new position and size of the Locator, together with how the event was generated (keystroke or mouse button). To obtain the Locator's new position or size, you must enable the event by setting its "action" code to 1, or to the name of a suitable callback function.

The value of the Style property determines the type of locator displayed. It may be 'Point', 'Line', 'Rect', or 'Ellipse'. The default value is 'Rect'. The value of the Sizeable property is 0 or 1 and determines whether or not "rubberbanding" is enabled. Its default value is 1 which turns "rubberbanding" on. The Size property determines the initial size of the Locator when displayed by ⎕DQ. Its default value is (0,0).

If Style is 'Rect'the Locator displays a rectangle. One corner of the rectangle is positioned at Posn. The diagonally opposite corner is positioned at (Posn+Size). If Sizeable is 0, the entire rectangle is dragged as the mouse is moved. If Sizeable is 1, the

corner initially defined by (Posn+Size) is dragged (rubberbanding the rectangle) as the mouse is moved. The rectangle disappears when the operation is terminated. The new position or size of the rectangle is reported in the Locator event message.

If Style is 'Ellipse'the Locator displays an ellipse. One corner of the bounding rectangle of the ellipse is positioned at Posn. The diagonally opposite corner is positioned at (Posn+Size). If Sizeable is 0, the entire ellipse is dragged as the mouse is moved. If Sizeable is 1, the corner of the bounding rectangle initially defined by (Posn+Size) is dragged (rubberbanding the ellipse) as the mouse is moved. The ellipse disappears when the operation is terminated. The new position or size of the bounding rectangle of the ellipse is reported in the Locator event message.

If Style is 'Line'the Locator displays a line drawn between the points defined by Posn and Posn+Size. If Sizeable is 0, the line is dragged with the cursor as the mouse is moved. If Sizeable is 1, the end of the line initially defined by Posn+Size is dragged (rubberbanding the line) as the mouse is moved. The line disappears when the operation is terminated. The new position or size of the line is reported in the Locator event message.

If 'Style' is 'Point', the values of Sizeable and Size are ignored. During the ⎕DQ no visible feedback (other than the cursor) is provided as the user moves the mouse. When the ⎕DQ terminates, the new position of the Locator is reported in the Locator event message.

The Step property is a 2-element integer vector (default value 1 1) that specifies the increments (in pixels) by which the size or position of the Locator changes in the Y and X directions respectively as the user moves the Locator.

The Locator is normally initiated from a MouseDown (1) event, and it is natural to place it at the current cursor position. However, if you are using rubberbanding, you will normally want to have the cursor appear at the end or corner of the Locator that moves. If you start with a non-zero sized Locator, you must set Posn (which defines the fixed end or corner) to the current cursor position minus Size to achieve this effect.


Marker Object
Parents Children Properties Methods Events
Purpose: A graphical object used to draw polymarkers.

Description

The Points property specifies one or more sets of points at which one or more sets of polymarkers are to be drawn.

The Style property determines the symbol that is drawn at each of a set of points. Marker styles are specified either by numbers which represent the following symbol shapes .

0 | .
1 | +
2 | *
3 | ⎕
4 | ×
5 | ⋄
6 | ∘

or by character vectors containing the names of Bitmap or Icon objects.

The height of each symbol is specified by the value of the Size property. However this applies only to Styles 1-6 and is ignored if Style is 0 or the name of a Bitmap. The colour of each symbol is specified by the FCol property. The default is black.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Marker object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple sets of polymarkers.

Single Set of Polymarkers

For a single set of polymarkers, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

Style and Size are both simple scalar numbers.

FCol is either a single number representing a standard colour, or a 3-element vector which specifies the marker colour explicitly in terms of RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a point at (y=20, x=10)

      'F.M1' ⎕WC 'Marker' (20 10)

Draw a row of points at (y=20, x=10, 20, ... 90) : (Note scalar extension of y-coordinate)

      'F.M1' ⎕WC 'Marker' (20(10×⍳9))

Draw "+" symbols at each corner of a box :

      Y ← 10 10 50 50
      X ← 10 50 50 10
      'F.M1' ⎕WC 'Marker' (Y X) 1

Ditto, but draw them 10% high :

      'F.M1' ⎕WC 'Marker' (Y X) 1 10

Ditto, but use "*" symbols in green :

      'F.M1' ⎕WC 'Marker' (Y X) 2 10 (0 255 0)

Multiple Sets of Polymarkers

To draw multiple sets of polymarkers with a single name, Points is a nested vector whose items are themselves 2-column matrices or 2-element nested vectors.

Style and Size may be simple scalars specifying a single type and/or size of symbol to be used for all the sets of polymarkers, or vectors specifying different symbols and/or sizes for each set.

FCol may be a single number or a single (enclosed) 3-element vector applying to all the sets of polymarkers. Alternatively, FCol may be a vector whose elements refer to each of the sets of polymarkers in turn. If so, the elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw a "⎕" at (10,20) and a "⋄" at (20,20) :

      'F.M1' ⎕WC 'Marker'((1 2⍴10 20)(1 2⍴20 20)) (3 5)

Draw "+" symbols at each corner of one box and "○" symbols at each corner of another

      Y1 X1 ← (10 10 50 50) (10 50 50 10)
      Y2 X2 ← (20 20 40 40) (20 40 40 20)
      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6)

Ditto, but draw the "+" symbols with height 2% and the "○" symbols 5% :

      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6) (2 5)

Ditto, but draw the "+" symbols in red and the "○" symbols in blue :

      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6) (2 5)
                          ('FCol' (255 0 0)(0 0 255))


MDIClient Object
Parents Children Properties Methods Events
Purpose: Implements Multiple Document Interface (MDI) behaviour.

Description

The multiple-document interface (MDI) is a document-oriented interface that is commonly used by word-processors, spreadsheets and other applications that deal with documents. An MDI application allows the user to display multiple documents at the same time, with each document displayed in its own window.

The MDIClient object is a container object that effectively specifies the client area within the parent Form in which the SubForm are displayed. The MDIClient object also imposes special MDI behaviour which is quite different from that where a SubForm is simply the child of another Form.

By default, the MDIClient occupies the entire client area within its parent Form. This is the area within the Form that is not occupied by CoolBars, MenuBars, ToolBars, ToolControls, TabBars, TabControls and StatusBars. In most applications it is therefore not necessary to specify the position and size of the MDIClient object, although you may do so if you want to reserve additional space in the parent Form for other objects.

Each of the four sides of an MDIClient object is automatically attached to the corresponding side of its parent Form and maintains its position when the parent Form is resized. This means that a default MDIClient always occupies the entire client area of its parent Form, regardless of how the parent is resized.

The appearance of the MDIClient may be changed using its Border, BCol and Picture properties. The EdgeStyle property has no direct effect and is provided only to pass on a value to its child Forms.

The MDIActive and MDIActiveObject properties contain the name of and a ref to the SubForm that currently has the focus. You may set these properties as well as query them.

You can call methods which cause the MDIClient to organise its child SubForms in some way. These methods are as follows:

MDICascade | Causes the MDIClient to organise its child Forms in an overlapping manner.
MDITile | Causes the MDIClient to arrange its child Forms as a row or column.
MDIArrange | Causes the MDIClient to arrange the icons associated with any minimised child Forms in an orderly fashion.


Menu Object
Parents Children Properties Methods Events
Purpose: This is a pop-up object which allows the user to initiate an action or to select an option using a "menu".

Description

For a Menu that is owned by a MenuBar or another Menu, the Caption property determines the text string that is displayed as the "choice". The Menu is then popped up by the user clicking on this text. It is automatically popped down when the user chooses an option (by selecting a MenuItem) or cancels the operation (by clicking elsewhere).

If a Menu belongs to a Form, SubForm or is a top-level object, it must be popped up by the application. This is commonly done in response to a MouseDown event. A Menu is popped-up by calling ⎕DQ with only the name of the Menu as its argument. The user may therefore not interact with any other object until a selection is made or until the operation is cancelled. When either occurs, the Menu is automatically popped down and de-activated, and its ⎕DQ terminates.

The Menu object does not have a Size property. Instead, its size is determined automatically by its contents.

If a Menu is owned by a MenuBar or by another Menu, its position within its parent is also calculated automatically, dependent on the order in which other related objects are established. The Posn property may however be used to insert a new Menu into an existing structure. For example, having defined three Menu objects as children of a MenuBar, you can insert a fourth one between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the Menus that were previously second and third will then be reset to 3 and 4 respectively.

If a Menu is a child of a MenuBar which is itself a child of a Form or SubForm, the Align property can be set to 'Right'. This is used to position a single Menu (or MenuItem) at the rightmost end of a MenuBar. This does not apply if the MenuBar is owned by a ToolControl.

The BtnPix property is used to display a picture in a Menu. BtnPix specifies the names of, or refs to, three Bitmap objects. The first Bitmap is displayed when the Menu does not have the focus (normal), the second when it does have the focus (highlighted). The third Bitmap is displayed when the Menu is made inactive (Active property is 0). If Caption is also defined, it is displayed on top of the bitmaps.

If the Menu is a submenu (owned by a Menu), you may set its EdgeStyle property to 'Plinth'. This causes the Menu to take on an appearance that is similar to a pushbutton and be raised when not selected and recessed when selected. Note that to enable 3-dimensional appearance, you must set EdgeStyle to something other than 'None' for all the objects above the Menu in the tree.

EdgeStyle, BtnPix, Font, FCol and BCol do not affect the appearance of a Menu if it is the direct child of a MenuBar. However, the EdgeStyle property must be set to something other than 'None' if you want its children Menu and MenuItem objects to have a 3-dimensional appearance.


MenuBar Object
Parents Children Properties Methods Events
Purpose: Specifies a horizontal menu bar displayed at the top of a Form.

Description

Unless it is made invisible the MenuBar is always available to the user to initiate actions or to select options. A MenuBar has a fixed position and size.

It is possible to have more than one MenuBar associated with the same Form or SubForm, but only one of them should be Visible at any one time.

The following example illustrates how a menu structure can be built up from a MenuBar. For clarity, the example is indented, and the definition of the Event property is omitted.

      'F'           ⎕WC 'Form' 'Menu Example'
      'F.M         '⎕WC 'MenuBar'
      'F.M.FILE'    ⎕WC 'Menu' '&File'
      'F.M.MAT'     ⎕WC 'Menu' '&Materials'
      'F.M.MAT.B'   ⎕WC 'MenuItem' '&Brick'
      'F.M.MAT.C'   ⎕WC 'MenuItem' '&Concrete'
      'F.M.MAT.S'   ⎕WC 'MenuItem' '&Stone'
      'F.M.MAT.SEP' ⎕WC 'Separator'
      'F.M.MAT.W'   ⎕WC 'Menu'     '&Wood'
      'F.M.MAT.W.O' ⎕WC 'MenuItem' '&Oak'
      'F.M.MAT.W.T' ⎕WC 'MenuItem' '&Teak'
      'F.M.MAT.W.M' ⎕WC 'MenuItem' '&Mahogany'

Note that putting a Separator (either Style) in a MenuBar has the effect of breaking the bar vertically, i.e. the next Menu or MenuItem you add will appear on the left-hand side on the line below.

The EdgeStyle property has no effect on the appearance of a MenuBar or of a direct child of a MenuBar. However, if you want the sub-menus to have a 3-dimensional appearance, you must set the EdgeStyle property of the MenuBar to something other than 'None'.

If the MenuBar is owned by a Form that is the parent of an MDIClient, you can set the MDIMenu property to the name of the Menu you wish to nominate as the window menu. This menu will automatically be updated with the Captions of the child SubForm and may be used to select the currently active one.


MenuItem Object
Parents Children Properties Methods Events
Purpose: This object allows the user to initiate an action or to select an option from a menu.

Description

The Caption property determines the text string that is displayed in its parent as the menu option. The size of a MenuItem is determined by the size of its Caption, or by the size of the largest object (Menu, MenuItem or Separator) with the same parent. The position of the MenuItem is normally determined by the order in which it is created in relation to other objects with the same parent. However, you can use the Posn property to insert a new MenuItem into an existing structure. For example, having defined three MenuItem objects as children of a Menu, you can insert a fourth one between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the MenuItems that were previously second and third will then be reset to 3 and 4 respectively.

The Style property may be 'Check' (the default) or 'Radio'. Style determines the type of graphic displayed alongside the Caption if the MenuItem is checked.

The Checked property is a single number with the value 0 or 1. 0 means not checked (the default), 1 means checked and a tick mark or radio dot is placed alongside its Caption. This property is frequently used to indicate which of a choice of options is currently set.

If a MenuItem is a child of a MenuBar which is itself a child of a Form or SubForm, the Align property can be set to 'Right'. This is used to position a single MenuItem (or Menu) at the rightmost end of a MenuBar. This does not apply if the MenuBar is owned by a ToolControl.

If you set the EdgeStyle property to 'Plinth', the MenuItem will take on an appearance that is similar to a pushbutton and be raised when not selected and recessed when selected. Note that to enable 3-dimensional appearance, you must set EdgeStyle to something other than 'None' for all the objects above the MenuItem in the tree.

The BtnPix property is used to display a picture in a MenuItem. BtnPix specifies the names of, or refs to, three Bitmap objects. The first Bitmap is displayed when the MenuItem does not have the focus (normal), the second when it does have the focus (highlighted). The third Bitmap is displayed when the MenuItem is made inactive (Active property is 0). If Caption is also defined, it is displayed on top of the bitmaps.

Alternatively, you may display an image alongside the Caption using the ImageIndex property. This selects a picture from the ImageList associated with the ImageListObj property of the parent Menu.

EdgeStyle, BtnPix, FontObj, FCol and BCol are not effective if the MenuItem is the direct child of a MenuBar.

A MenuItem generates a Select event (if enabled) when the user chooses it.


Metafile Object
Parents Children Properties Methods Events
Purpose: This object represents a picture in Windows Metafile format.

Description

The Windows Metafile is a mechanism for representing a picture in terms of a collection of graphical components. Windows Metafiles are distributed in special files (.WMF) from which they are loaded into memory for use by an application. Once loaded a Metafile is a Windows "resource" that can be used in a variety of ways. The Metafile object represents this resource.

The File property specifies the name of a .WMF file from which the Metafile is to be loaded or to which it is to be saved. If you specify File with ⎕WC the Metafile object is loaded from it. If you specify File with ⎕WS no action takes place until you instruct the Metafile object to re-initialise itself from the file or to save itself to the file. These operations are performed using the FileRead and FileWrite methods. If you omit the File property in the argument to ⎕WC or if you specify a null vector, the Metafile object is initially empty. The following example loads the picture defined by the GOLF.WMF Metafile that is distributed with Microsoft Office.

      'GOLF' ⎕WC 'Metafile' 'C:\MSOFFICE\CLIPART\GOLF'

Whether or not the Metafile object is initialised from a file, you can add graphical components to it by creating child objects. However the Metafile behaves like a Bitmap object in that its children cannot be modified using ⎕WS nor can they be removed using ⎕EX. The components of a Metafile that has been initialised from a .WMF file also cannot be referenced in any way. It is therefore recommended that you use unnamed objects when you create the graphical components of a Metafile.

The following statements create an empty Metafile called MF and then draw a line and circle in it.

      'MF' ⎕WC 'Metafile'
      'MF.' ⎕WC 'Poly' (50(10 90))
      'MF.' ⎕WC 'Circle' (50 50) 30

Like the Bitmap, Icon, Font and Cursor objects, the Metafile is a resource that is not visible until it is used. This is done by setting the Picture property of another object (Form, Image, Static or SubForm) to the name of, or ref to, the Metafile object. For example, to display the Metafile MF in a Form, you could type :

      'TEST' ⎕WC 'FORM' ('Picture' 'MF')

You can also copy a Metafile object to the Windows Clipboard from where it can be pasted into another application. This is done by creating a Clipboard object and then setting its MetafileObj property to the name of the Metafile object to be exported. For example :

      'CL' ⎕WC 'Clipboard'
      'CL' ⎕WS 'MetafileObj' 'MF'

The FileWrite method may be used to save a Metafile object on a file. The following statements save the Metafile MF in a file called TEST.WMF.

      MF.File←TEST'
      MF.FileWrite

The Size property determines the granularity of the Metafile. Its default value is the size of its parent. If you intend to replay the Metafile at higher resolution, you should set Size accordingly.

The RealSize property specifies the suggested size of a Metafile in units of 0.01mm. Setting RealSize has the effect of making the Metafile placeable. Certain programs (such as Word for Windows) only support placeable metafiles.


MsgBox Object
Parents Children Properties Methods
Purpose: Provides a "modal" dialog box for displaying messages, errors, warnings and other information. The dialog box has a title, one or more lines of text, and up to three buttons.

Description

The Caption property determines the text displayed in the object's title bar.

The Text property determines the text to be displayed as the message.

The Style property determines the type of icon which is displayed. This is a character vector with one of the following values :

'Msg' | no icon (the default)
'Info' | information message icon
'Query' | query (question) icon
'Warn' | warning icon
'Error' | critical error icon

The Btns property determines the set of buttons to be displayed. It is a simple vector (one button) or a matrix with up to 3 rows, or a vector of up to 3 character vectors specifying the captions for up to 3 buttons. MS-Windows restricts you to a fixed set of button captions which are described below. However, the property has been designed more generally to be useful under different GUIs and perhaps later revisions of Windows. The buttons are arranged along the bottom of the dialog box in the order specified.

The Btns property may specify one of six sets of buttons as follows.

  • 'OK'
  • 'OK' 'CANCEL'
  • 'RETRY' 'CANCEL'
  • 'YES' 'NO'
  • 'YES' 'NO' 'CANCEL'
  • 'ABORT' 'RETRY' 'IGNORE'

If any other combination is specified, ⎕WC and ⎕WS will report a DOMAIN ERROR. The names of the buttons are however case-insensitive, so the system will accept 'ok', 'Ok', 'oK' or 'OK'. If Btns is not specified, it assumes a default according to Style as follows :

Style | Btns
'Msg'or'Info' | 'OK'
'Warn'or'Error' | 'OK' 'CANCEL'
'Query' | 'YES' 'NO'

The Default property may be used to determine which of the buttons is the "default" button, i.e. the one which initially has the focus and is "selected" when the user presses the Enter key. It has the value 1, 2 or 3. If Default is not specified, the first button is the "default" button. Note that if the user switches focus to another button and presses Enter, this action selects the button with the focus.

Like a pop-up (floating) Menu, the MsgBox object is unusual in that it is strictly modal. It is created by ⎕WC in the normal way, but at that stage is invisible and inactive. It is activated ONLY when ⎕DQ is called with the name of the MsgBox as the argument. When this is done, the MsgBox object pops up and is activated. Because there is no other object specified in the argument to ⎕DQ, all other objects are de-activated. The only thing that the user can do (within the APL application) is to press one of the buttons in the MsgBox. When this happens, the MsgBox automatically pops down, the callback function (if any) is fired, and then ⎕DQ terminates.

Notice that the position and size of the MsgBox are determined by Windows and are fixed, although the MsgBox may be moved by the user after it has been displayed.

The MsgBox object generates one of three events; MsgBtn1 (61), MsgBtn2 (62), or MsgBtn3 (63) depending upon which button is pressed.

   Caption←'Default MsgBox' ⋄ Text←'Hello World'
   'Msg' ⎕WC 'MsgBox' Caption Text ⋄ ⎕DQ 'Msg'

   Caption←'Information MsgBox' ⋄ Text←'Update Completed'
   'Msg' ⎕WC 'MsgBox' Caption Text 'Info' ⋄ ⎕DQ 'Msg'

   Caption←'Query MsgBox' ⋄ Text←'Save Changes'
   'Msg' ⎕WC 'MsgBox' Caption Text 'Query' ⋄ ⎕DQ 'Msg'

   Caption←'Warning MsgBox'
   Text←'Calculations will take 10 minutes'
   'Msg' ⎕WC 'MsgBox' Caption Text 'Warn' ⋄ ⎕DQ 'Msg'

   Caption←'Error MsgBox'
   Text←'Data out of range'
   'Msg' ⎕WC 'MsgBox' Caption Text 'Error' ⋄ ⎕DQ 'Msg'

   Caption←'Custom MsgBox'
   Text←⊂'You can have a multi-line'
   Text,←⊂'message if you want one'
   B←'ABORT' 'RETRY' 'IGNORE'
   'Msg' ⎕WC 'MsgBox' Caption Text 'Info' B ⋄ ⎕DQ 'Msg'


NetClient Object
Parents Children
Purpose: The NetClient object represents an instance of a Microsoft .Net class.

Description

The NetClient object represents an instance of a .Net class.

Normally, you create a NetClient object using the New method. For example:

      ⎕USING ←'System'
      DT1←DateTime.New 2002 4 30
      DT1.Type
NetClient

If, for any reason, you are unable to use the New method, you may create a NetClient object using ⎕WC. In this case, the ClassName property specifies the full name of the .Net class, and the ConstructorArgs property specifies the arguments for the constructor function if required.

      ⎕USING ←'System'
      'DT2'⎕WC'NETCLIENT' 'System.DateTime'(1949 4 30)
      DT2.(Type ClassName ConstructorArgs)
 NetClient  System.DateTime  1949 4 30


NetType Object
Parents Children Properties Methods Events
Purpose: The NetType object is used to export a namespace as a Microsoft.Net class.

Description

The NetType object allows you to export an APL namespace as a .Net class that can be accessed by any conforming .Net client application.

The BaseClass property specifies the name of the .Net class from which the specified NetType object inherits. The default is System.Object.

When you create a NetType object, the name of its parent namespace specifies the name of the corresponding Microsoft .Net Namespace to which the NetType class belongs. If the NetType is created as a child of root, the corresponding Microsoft .Net Namespace is unnamed.


OCXClass Object
Parents Properties Methods Events
Purpose: This object provides access to OLE (ActiveX) Controls.

Description

This object loads an OLE Control into memory and defines a new class of object associated with it. The name of the new class is the name specified by the left argument of ⎕WC You may create an instance of the newly defined class using the name you assigned to the OCXClass object as the Type property.

Once you have defined a new OCXClass, the properties, events and methods it supports may be obtained from its PropList, EventList and MethodList properties. These are the properties, events and methods defined for the OLE control by its author.

The QueueEvents property determines how events reported by the ActiveX control are handled.

To find out how to use the OLE control, you must consult the appropriate documentation. However, a great deal of information about it can be obtained using the GetPropertyInfo, GetEventInfo, and GetMethodInfo methods.


OLEClient Object
Parents Children Properties Methods Events
Purpose: The OLEClient object provides access to an OLE Automation Server

Description

The OLEClient object allows you to control OLE Servers, which may be written in a variety of different programming languages, including Dyalog APL itself.

The ClassName property specifies the name of the OLE object to which the new object named by the left argument of ⎕WCis to be connected. A list of all the OLE Server objects installed on your system may be obtained from the OLEServers property of Root. ClassName may only be specified by ⎕WC.

Alternatively, the OLE object may be identified by the ClassID property.

The AutoBrowse property and Browse method are no longer relevant and are ignored. They are retained only for backwards compatibility with previous versions of Dyalog APL.

Note that the PropList and MethodList properties of an OLEClient instance contain the names of the properties and methods exposed by the corresponding OLE Object in addition to the generic properties and methods of the OLEClient class.

If you call an OLE method with an invalid parameter, set a read-only property, or assign it an invalid value, the LastError property of the OLEClient and Root objects will contain error information generated by OLE.


OLEServer Object
Parents Children Properties Methods Events
Purpose: The OLEServer object is used to establish a namespace as an OLE Server object that can be used by an OLE Automation client.

Description

The OLEServer object allows you to export an APL namespace so that its functions and variables become directly accessible to an OLE Automation client application such as Microsoft Visual Basic or Microsoft Excel.

An OLEServer may be saved as an out-of-process OLE server (in a workspace) or as an in-process OLE server (in a DLL). See Interface Guide for details.

When you create an OLEServer object, APL allocates various OLE attributes to it. For example, the CLSID, which uniquely identifies the object, is assigned at this stage. However, the object is not actually registered until you execute )SAVE.

Registration involves updating the Windows registry with information about the object itself, such as its name, the command required to obtain it and so forth. Registration also records information about all of the functions and variables that your object exposes. Registration is therefore a non-trivial operation and should be delayed until the point when you are ready to test your OLEServer.

You may create an empty OLEServer object and then define functions and variables within it. Alternatively, you may convert an existing namespace which is already populated with functions and variables. The latter method is recommended as it implies less registry activity during the development of the object.

The ExportedFns and ExportedVars properties specify the names of the functions and variables that will be exposed by the object to OLE clients.

The RunMode property is a character vector that specifies how the object serves multiple clients. It may be 'MultiUse'(the default), 'SingleUse', or 'RunningObject'.

The ShowSession property is either 0 (the default) or 1 and specifies whether or not the APL Session window is displayed when the first instance of the OLEServer is created.

RunMode and ShowSession apply only to out-of-process OLEServers.


Poly Object
Parents Children Properties Methods Events
Purpose: A graphical object used to draw lines, polygons, and filled areas.

Description

The Points property specifies one or more sets of co-ordinates through which one or more lines are drawn. The resulting polygon(s) may also be filled.

LStyle and LWidth define the style and width of the lines. FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the polygon(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the areas between them.

Note that if you specify filling, you do not have to define a closed polygon. The first and last points will automatically be joined for you if necessary.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Poly object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple polylines or polygons.

Single Polyline or Polygon

For a single polyline or polygon, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used as a "brush" to fill the polygon.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a single line from (y=20, x=10) to (y=30, x=50)

      'F.L1' ⎕WC 'Poly' ((20 30)(10 50))

or

      L ← 2 2⍴20 10 30 50
      'F.L1' ⎕WC 'Poly' L

Draw a horizontal line from (y=20, x=10) to (y=20, x=50). Note scalar extension of y-coordinate.

      'F.L1' ⎕WC 'Poly' (20(10 50))

Draw an empty box in green :

      Y ← 10 10 50 50 10
      X ← 10 50 50 10 10
      'F.L1' ⎕WC 'Poly' (Y X) (0 255 0)

Ditto, using a green/blue dashed line (LStyle 1) :

      'F.L1' ⎕WC 'Poly' (Y X) (0 255 0)(0 0 255) 1

Draw a red filled rectangle with a black border 5 pixels wide :

      'F.L1' ⎕WC 'Poly' (Y X) (0 0 0) ('LWidth' 5)('FStyle' 0)('FillCol' 255 0 0)

Multiple Polylines/Polygons

To draw a set of polylines or polygons with a single name, Points is a nested vector whose items are themselves 2-column matrices or 2-element nested vectors.

LStyle and LWidth may each be simple scalar values (applying to all the polylines) or simple vectors whose elements refer to each of the corresponding polylines in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all polylines, or a vector whose elements refer to each of the corresponding polylines in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the polylines. Alternatively, these properties may contain vectors whose elements refer to each of the polylines in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw two concentric triangles :

      BY ← 10 10 50 10
      BX ← 15 65 40 15
      RY ← 15 15 40 15
      RX ← 25 55 40 25
      'F.L1' ⎕WC 'Poly' ((BY BX)(RY RX))

Or, using matrices :

      BT ← BY,[1.5]BX
      RT ← RY,[1.5]RX
      'F.L1' ⎕WC 'Poly' (BT RT)

Ditto, but draw the first blue, the second red :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))

Ditto, but make the lines 3 pixels wide :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))('LWidth' 3)

Ditto, but make the line widths 3 and 6 pixels respectively :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))('LWidth' 3 6)

Draw the first hollow, but fill the second in green :

      'F.L1' ⎕WC 'Poly' (BT RT) ('FStyle' ¯1 0)('FillCol' (⊂0 255 0))


Printer Object
Parents Children Properties Methods Events
Purpose: To provide printer output.

Description

The PName property is a character vector which specifies the name of an installed printer and the device to which it is attached. The name and device are separated by a comma (,). All valid values of PName can be obtained from the PrintList property of the Root object.

If not specified, the default value of PName is (⊃'.' ⎕WG 'PrintList').

The DevCaps property reports the size of the printable area of the page in pixels (dots) and in millimetres. It also reports the number of colours available. This is 2 on a monochrome printer (black and white), although grey scales may be available.

The FontList property provides a list of fonts that are applicable and includes TrueType and printer fonts. This list is typically different from that obtained from the FontList property on the Root object which lists those fonts that apply to the screen.

The Orientation property specifies the orientation of the page and may be either 'Portrait' or 'Landscape'.

The graphics objects listed above may be printed in much the same way as they may be displayed on a Form or Static. The differences are :

Once an object has been created, it will be printed, even if its name is subsequently expunged.

An object does not replace an existing one which has the same name.

The act of changing one or more properties of a named object causes the object to be printed a second time. For example, changing the Posn of an object will print it again at a different place.

In general it is recommended that you use unnamed objects for printing.

The Printer object five methods :

Name | Event | Description
Print | 100 | Sends output to print spooler
Setup | 101 | Displays Printer Set-up dialog box
NewPage | 102 | Throws a new page
Abort | 103 | Aborts the print job
RTFPrintSetup | 460 | Displays Printer Set-up dialog box

Examples:

Start a print job on the default printer

      'PR1' ⎕WC 'Printer'

Write a centred heading at the top of the page using a proportional font

      'PR1.' ⎕WC 'Text' 'Report Title' (0 50)('HAlign' 1) ('FontObj' 'Roman' 64)

Draw a line across the page, 2 pixels wide

      'PR1.' ⎕WC 'Poly' (2(0 100)) ('LWidth' 2)

Print a character matrix. Note that a fixed width font is used.

      REPORT ← 'I6' ⎕FMT ?20 6⍴1000
      'PR1.' ⎕WC 'Text' REPORT (10 0)('FontObj' 'DyalogAPL')

Throw a new page

      PR1.NewPage

Spool output

      ⎕EX 'PR1'


ProgressBar Object
Parents Children Properties Methods Events
Purpose: The ProgressBar object is used to indicate the progress of a lengthy operation.

Description

The ProgressBar object is a window that an application can use to indicate the progress of a lengthy operation. The appearance of the bar in the ProgressBar is determined by the ProgressStyle property.

If ProgressStyle is Normal or Smooth, the size of the bar, intended to indicate the amount of progress, is determined using the Thumb property in relation to its Limits property, and/or using the ProgressStep method. This can be updated as appropriate in the application logic or by using a Timer.

The range of a ProgressBar is specified by the Limits property. This is a 2-element integer vector defining its minimum and maximum values. The position of the filled rectangle is specified by the Thumb property. You can update the ProgressBar by using ⎕WS to set the value of the Thumb directly, or by using the ProgressStep method. The latter causes the Thumb to be updated by the value of the Step property.

If you attempt to set the Thumb to a value greater than its maximum value (using either method) the behaviour depends upon the value of the Wrap property which is boolean and has a default value of 1. If Wrap is 1, the value obtained when you set the Thumb property is given by the expression:

      LIMITS[1]+(1+LIMITS[2]-LIMITS[1])|THUMB-LIMITS[1]

where THUMB is the value to which you set the Thumb property and LIMITS is the value of the Limits property. This causes the highlit rectangle to begin filling again from the left.

If ProgressStyle is Marquee, the size of the bar is fixed and its position changes with time according to the value of the Interval property. The values of Thumb, Limits, Wrap and Step are irrelevant.


PropertyPage Object
Parents Children Properties Methods Events
Purpose: The PropertyPage object represents a single page in a PropertySheet.

Description

The PropertyPage object represents a single page within a PropertySheet.

The Posn and Size properties are read-only properties determined by the parent PropertySheet and may not be changed using ⎕WC or ⎕WS.

The HasHelp property is either 1 (the default) or 0. If the parent PropertySheet has a "Help" button (determined by its own HasHelp property) this property determines whether or not the Help button is active when the PropertyPage is the current page. If the HasHelp property of a PropertyPage is 0, the Help button on the parent PropertySheet will be temporarily disabled when that PropertyPage is displayed.

The PropertyPage object generates a PageActivate event when it becomes the current page and a PageDeActivate event when another page is selected. These events may not be disabled by a callback function.

If the user presses the Cancel button, the current PropertyPage generates a PageCancel event. This is followed by a Close event which is reported by the parent PropertySheet.

Other properties and behaviour depend upon the Style of the parent PropertySheet which may be 'Standard' or 'Wizard'

Standard Behaviour

In a Standard PropertySheet, the Caption property of each PropertyPage specifies the text that is written in its tab.

PropertyPage objects owned by a Standard PropertySheet generate PageCancel, PageApply and PageHelp events. These events are all caused by the user pressing the corresponding button in the parent PropertySheet.

Conventionally, the Apply button is initially inactive. When the user changes an item on any of the PropertyPages, the Apply button immediately becomes active. When the user clicks the Apply button, the application responds (normally by changing the appropriate properties) and then the Apply button becomes inactive once again. This process is controlled as follows.

The Changed property is a boolean value that determines whether or not a PropertyPage is marked as having been in any way altered. The Apply button is active if the value of the Changed property for any of the PropertyPages is 1, and is inactive otherwise

Initially, the value of the Changed property for all of the PropertyPages is 0 and the Apply button is therefore inactive. If the user alters a control on a PropertyPage, by, for example typing into an Edit object or changing the State of a Radio Button, the PropertyPage immediately generates a PageChanged event with the parameter 1. The default processing for this event is to set the Changed property of the PropertySheet (to 1). This in turn activates the "Apply" button. If you return 0 from a callback on the PageChanged event, the Changed property remains 0 and the Apply button remains inactive.

When the user clicks the Apply button, each of the PropertyPages whose Changed flag is currently set to 1 generates a PageApply event. The default processing for this event is to generate a PageChanged event with the parameter 0. This is turn resets the Changed property of the PropertyPage to 0. Once all of the Changed flags have been reset, the Apply button becomes inactive. If you return 0 from a callback on any of the PageChanged events, the Changed property for the corresponding PropertyPage remains 1 and the Apply button remains active.

You may control the value of the Changed property using ⎕WS or by calling PageChanged as a method. In all cases, the Apply button is active if the value of Changed on any PropertyPage is 1, and inactive otherwise.

Wizard Behaviour

If the PropertyPage is owned by a Wizard PropertySheet, its Caption property specifies the text that appears in the title bar of the PropertySheet window when the PropertyPage is the current page. Note that a Wizard PropertySheet ignores its own Caption property.

There are effectively 3 page changing buttons on a Wizard PropertySheet, named Back, Next and Finish. The Next and Finish buttons actually occupy the same position and are mutually exclusive. The captions on the buttons are language-dependent.

Conventionally, the buttons change according to which of the PropertyPages is currently displayed. If the first one is displayed, the Next button is active but the Back button is inactive. When a middle page is displayed, both the Next and Back buttons are active. When the last page is displayed, the caption on the Next button changes to Finish. However, in some applications, the Back button may be disabled to prevent the user returning to a previous page.

When the user clicks the Back or Next button, the PropertyPage generates a PageBack or PageNext event followed by a PageDeactivate event. The new PropertyPage then generates a PageActivate event. These are followed by a SetWizard event which is generated by the parent PropertySheet and actually controls the state of the buttons. When the user clicks the Finish button, the PropertyPage generates a PageFinish event alone. All of these events reported by the PropertyPage are reported for information only. Returning 0 from a callback function has no effect. You may however control the buttons using the SetWizard event,


PropertySheet Object
Parents Children Properties Methods Events
Purpose: The PropertySheet object represents a standard multi-page dialog box.

Description

There are two different kinds of PropertySheet which you select using the Style property. This may only be set when the PropertySheet is created using ⎕WC and Style may not subsequently be changed using ⎕WS.

If Style is Standard (the default), the PropertySheet displays a set of pages (each represented by a PropertyPage) as a set of tabbed forms as illustrated below. The user selects the current page by clicking on the appropriate tab. This Style allows the user to select any page at any time and does not oblige the user to visit any but the first page you choose to display. This Style is useful for displaying groups of options or settings that the user may change.

If Style is Wizard, the PropertySheet displays its pages in succession starting with the first. The user steps from one to another using the Next and Back buttons and may be forced to visit all the pages in a prescribed order. This Style is useful for data entry or for asking the user to make a series of choices.

The Caption property specifies the text written in the window title bar, but only applies if the Style is Standard. The title bar text of a Wizard PropertySheet is specified by the Caption of the current PropertyPage.

The HasApply and HasHelp properties are boolean and specify whether or not the PropertySheet has "Apply" and "Help" buttons respectively. These properties may only be set when the object is created using ⎕WC. They both have default values of 1.

The FontObj and EdgeStyle properties have no effect on the appearance of the PropertySheet itself, but may be used to define the default appearance of its children.


Rect Object
Parents Children Properties Methods Events
Purpose: A graphical object used to draw boxes.

Description

The Points property specifies one or more sets of co-ordinates which define the position(s) of one or more rectangles. The position of a rectangle is defined to be the position of the corner that is nearest to the origin of its parent. The default is therefore its top-left corner. The Size property specifies the height and width of each rectangle, measuring away from the origin.

The Radius property specifies the curvature of the corners of the rectangle.

LStyle and LWidth define the style and width of the lines used to draw the boundaries of the rectangle(s). FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the rectangle(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the spaces between them.

The EdgeStyle property may specify a 3-dimensional effect. If so, the boundary line around the rectangle is replaced by a border designed to achieve the desired effect.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Rect object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple rectangles :

Single Rectangle

For a single rectangle, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

Size is a simple 2-element vector whose elements specify the height and width of the rectangle respectively.

Radius is a 2-element vector which specifies the major (y-axis) and minor (x-axis) radii of an ellipse used to draw the corners of the rectangle. Its default value is (0 0) which yields right-angled corners.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used as a "brush" to fill the rectangle.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a single rectangle at (y=10, x=5) with height=30, width=50 :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)

Ditto with rounded corners (radii 10) :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)

Ditto, but use a red line :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)(255 0 0)

Ditto, but fill in green

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)(255 0 0) ('FStyle' 0)(0 255 0)

Multiple Rectangles

To draw a set of rectangles with a single name, Points may be a simple 2-element vector (specifying the location of all the rectangles), or a 2-column matrix whose first column specifies their y-coordinates and whose second column specifies their x-coordinates, or a 2-element nested vector whose first element specifies their y-coordinate(s) and whose second element specifies their x-coordinate(s).

Likewise, Size may be a simple 2-element vector (applying to all the rectangles), or a 2-column matrix whose first column specifies their heights and whose second column specifies their widths, or a 2-element nested vector whose first element specifies their height(s) and whose second element specifies their width(s).

Radius may be a simple 2-element vector (applying to all the rectangles), or a 2-column matrix whose first column specifies major radii and whose second column specifies minor radii, or a 2-element nested vector whose first element specifies major radii and whose second element specifies minor radii.

LStyle and LWidth may each be simple scalar values (applying to all the rectangles) or simple vectors whose elements refer to each of the corresponding rectangles in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all rectangles, or a vector whose elements refer to each of the corresponding rectangles in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the rectangles. Alternatively, these properties may contain vectors whose elements refer to each of the rectangles in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw two rectangles at (y=5, x=10) and (y=5, x=60) each of (height=40, width=10)

      'F.R1' ⎕WC 'Rect' ((5 5)(10 60)) (40 10)

Ditto, using scalar extension for (y=5) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10)

Ditto, but draw the first with (height=40, width=30) and the second with (height=20, width=10) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) ((40 20)(30 10))

Draw two rectangles at (y=5, x=10) and (y=5, x=60) each of (height=40, width=10) and with rounded corners of radii (10,10) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)

Ditto, using a green line for both :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)(⊂0 255 0)

Ditto, but using red and blue lines respectively :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)((255 0 0)(0 0 255))


RichEdit Object
Parents Children Properties Methods Events
Purpose: The RichEdit object is a multi-line text editor that provides a wide range of word-processing capabilities.

Description

A RichEdit object is a window in which the user can enter and edit text. The text can be assigned character and paragraph formatting. Although the corresponding control can include embedded OLE objects, this is not yet supported by Dyalog APL.

The RichEdit object provides a programming interface for formatting text. However, your application must implement any user interface components necessary to make formatting operations available to the user. For example, your program can set the colour and font of a particular block of text, but the RichEdit itself provides no facilities for the user to do this directly. It is up to you to provide these.

The File property specifies the name of a file associated with the object. Data in the file is assumed to be in rich text format, and the default extension for the file is .RTF. You can read the file into the object by calling FileRead and you can write the contents to the file by calling FileWrite. You can also print the contents of the object by calling RTFPrint.

The Text property may be used to set or retrieve the text of the RichEdit, but ignores formatting information.

The RTFText property may be used to set or retrieve the contents of the RichEdit, including text and formatting.

The PageWidth property defines the width of the text within the object. Text entered into the object is automatically wrapped according to PageWidth. This property also defines the width when the text is printed.

You can set the default character format or the format of a particular block of text using the CharFormat property. If there is no selection, setting CharFormat defines the default character format that applies at the current insertion position and establishes the appearance of all of the text (font, colour, size etc.) that the user subsequently enters here. If there is a selection, setting CharFormat sets the character format for the selected block of text.

The WordFormat property is similar to CharFormat except that is sets the format for the selected word(s) or, if there is no selection, for the word containing the insertion point.

The Paraformat property defines the paragraph formatting which includes alignment, indentation and the location of tab stops. When you set Paraformat with ⎕WS, the formatting is applied to the current selection. If there is no selection, it defines the default paragraph formatting at the insertion point.

All of the dimensions used for text and paragraph formatting are specified in Twips. You can convert from pixels to Twips and vice versa using the DevCaps property of either Root or the Printer object as appropriate.

The behaviour of the Enter key is defined by the WantsReturn property. If WantsReturn is 1 (the default), the Enter key inputs a new line into the RichEdit object. If WantsReturn is 0 the Enter key is ignored by the RichEdit object and may instead generate a Select event on a Button. In this case the user must press Ctrl+Enter to input a new line.

The user may copy and paste information (in RTF format) between a RichEdit object and the Windows clipboard. The Clipboard object also has an RTFText property that supports RTF format

If the user attempts to alter text that is protected (see CharFormat) the RichEdit object reports a Protected event.

You may print the contents of a RichEdit object using the RTFPrint method. You may display a print set-up dialog box using the RTFPrintSetup method.


Root Object
Children Properties Methods Events
Purpose: This is an invisible "system" object that acts as the parent of all other objects.

Description

There is a single Root object called '.' which is always present. It cannot be created using ⎕WC nor can it be destroyed.

The Caption and IconObj properties of '.' are used to identify a Dyalog APL/W application as distinct from the APL Session. The Caption property specifies the application name that is displayed when you cycle through running applications using Alt+Tab and by the Windows Task List. The IconObj property specifies the name of an Icon object that is displayed alongside the application name in the box displayed by Alt+Tab. For these to take effect, your application must have at least one visible and active Form.

For the Root object, the value of Posn is (0,0). The value of Size is either (100,100) if Coord is 'Prop', or the size of the screen in pixels if Coord is 'Pixel'. XRange and YRange both have the value (0,100). The DevCaps property reports the physical size of the screen in terms of both pixels and millimetres. It also reports the number of colours available.

The FontList property provides a list of all the character fonts that are available. The PrintList property provides a list of all the installed printers. These properties are read-only and may not be changed using ⎕WS

As the default value of Coord is 'Inherit' for all other objects, the value of Coord for '.' defines the default co-ordinate system. It may be either 'Prop' (the default) or 'Pixel'. 'Inherit' and 'User' are not allowed.

The CursorObj property is used to define a cursor for the application as a whole. Its default value is an empty character vector. If it is set to any value other than '' or 0, the selected cursor overrides the CursorObj values for all other objects. If you want to indicate that the application is "busy", you can therefore set the CursorObj property on '.' to an hourglass for the duration of the operation, e.g.

      '.' ⎕WS 'CursorObj' 1  ⍝ Set cursor to an hourglass

[lengthy process...]

      '.' ⎕WS 'CursorObj' 0  ⍝ Reset cursor

The Yield property specifies how frequently APL yields to Windows during the execution of code. Its default value is 200 milliseconds.

The EdgeStyle property is used to determine whether or not objects may have 3-dimensional effects. Setting EdgeStyle to 'None' disables 3-dimensional effects on all Forms and controls. Setting EdgeStyle to any other value enables 3-dimensional effects for these objects.

The ExitApp and ExitWindows events can be used to prevent the user closing your application from the Windows Task List or by terminating Windows.

The expression ⎕EX '.' deletes all objects owned by the current thread except the Root object itself. In addition, if this expression is executed by thread 0, it resets all the properties of '.' to their default values.


Scroll Object
Parents Children Properties Methods Events
Purpose: Provides a vertical or horizontal scrollbar.

Description

The Scroll object provides a vertical or horizontal scrollbar that can be used as a "free-standing" object or can be "attached" to the side of its parent.

An "attached" scrollbar is one that extends along one edge of a Form, SubForm or Group and has a standard width or height. When the Form or Group is resized, a vertical attached scrollbar is resized vertically but remains the same width and stays fixed to the side of its parent. Similarly, a horizontal attached scrollbar is resized horizontally but remains the same height.

For most purposes, the use of the Scroll object to provide attached scrollbars in a Form has been superseded by the provision of scrollbars as a property of a Form. This facility was not available in the first release of Dyalog APL/W (Version 6.2).

A "free-standing" scrollbar is typically used as a "scale" for selecting a numeric value from a range and may appear and behave rather differently from a standard attached scrollbar. Firstly, a free-standing scrollbar will normally be positioned at an arbitrary position within its parent Form or Group and be associated with other objects such as Labels and Edit fields. Secondly, when its parent Form or Group is resized, it is probably desirable that the scrollbar reacts in the same way as the other child objects, so that the overall appearance of the layout is maintained.

The Align property determines whether or not a scrollbar is attached, and if so, to which side of the parent Group or Form it is fixed. The direction of the scrollbar is determined by the VScroll and HScroll properties, which are mutually exclusive. The position and size of the scrollbar are determined by Posn and Size.

To obtain an "attached" scrollbar, it is sufficient for most purposes to specify only the Align property. If so, the direction of the scrollbar and its position and size (which are otherwise defined by VScroll, HScroll, Posn and Size) are determined automatically for you.

To obtain a "free-standing" scrollbar, it is recommended for most purposes that you set Align to 'None' and define the orientation, position and size of the scrollbar explicitly using VScroll or HScroll, Posn and Size.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

If you do attach a "free-standing" scrollbar to a particular side of its parent using Align, it will maintain its physical position (in pixels) relative to the side to which it is attached, and its dimension in that direction will remain fixed.

The Align property is a character vector containing 'Top', 'Bottom', 'Right', 'Left' or 'None'. If you specify Align 'Right' you get a vertical scrollbar attached to the right-hand edge of the parent Form or Group. Align 'Left' also produces a vertical scrollbar, but one that is attached to the left-hand edge. Align 'Top' and 'Bottom' each produce horizontal scrollbars, attached respectively to the top and bottom edges of the Form or Group.

Note that the default value of Align is 'Right' unless HScroll is set to ¯1 in which case it is 'Bottom'. It must therefore be explicitly set to 'None' if you want a non-attached "free-standing" scrollbar.

VScroll and HScroll are used to specify the orientation of the scrollbar explicitly, usually in conjunction with Align set to 'None'. VScroll or HScroll may be specified when the object is created by ⎕WC, but cannot be changed using ⎕WS. The two properties are mutually exclusive. Each of them may be set to 0 or ¯1, where ¯1 means "true" and 0 means "false". Thus (VScroll ¯1) defines a vertical scrollbar, while (HScroll ¯1) specifies a horizontal one. Setting either property to ¯1 automatically causes the other to be set to 0. If you try to set both to ¯1, VScroll takes precedence and HScroll is reset to 0.

[Note: the reason for using two properties where one would be sufficient is to allow for the possible future implementation of scrolling groups as provided by ⎕SM/⎕SR.]

Scrolling is controlled by the Thumb, Range and Step properties.

Thumb sets and reports the current position of the "thumb" as an integer in the range 1 to the value of the Range property.

Step determines the size of changes reported when the user clicks a scroll arrow (small change) or clicks on the body of the scrollbar (large change). Step is a 2-element numeric vector whose first element specifies the value of the "small change" and whose second element specifies the value of the "large change". The PageSize property specifies the sizes of the thumb in the scrollbar.

Examples of Attached Scrollbars:

      'F' ⎕WC 'Form' 'Default Scroll Bar'
      'F.SCR' ⎕WC 'Scroll'

      'F' ⎕WC 'Form' 'Default Horizontal Scroll Bar'
      'F.SCR' ⎕WC 'Scroll' ('HScroll' ¯1)

Examples of Free-Standing Scrollbars:

      'F' ⎕WC 'Form' 'Non-Default Scroll Bar'
      'F.SCR' ⎕WC 'Scroll' (5 45)(90 10)
                  ('Align' 'None')('VScroll' ¯1)

      'F' ⎕WC 'Form' 'Horizontal Scroll Bars'
      'F.SC1' ⎕WC 'Scroll' (15 15)(15 70)
                  ('Align' 'None')('HScroll' ¯1)
      'F.SC2' ⎕WC 'Scroll' (40 40)(20 20)
                  ('Align' 'None')('HScroll' ¯1)
      'F.SC3' ⎕WC 'Scroll' (85 5)(10 90)
                  ('Align' 'None')('HScroll' ¯1)


Separator Object
Parents Children Properties Methods Events
Purpose: A horizontal or vertical line used to separate items in a menu.

Description

This object provides a vertical or horizontal line to separate items in a Menu. It may also be used to split a MenuBar over more than one line.

The orientation of the Separator is determined by its Style property, which may be 'Horz' (horizontal) or 'Vert' (vertical). The default is 'Horz'.

If you want to provide a menu with a 3-Dimensional (pushbutton) appearance, you should also set the EdgeStyle property on any Separator objects in it. Alternatively, you can achieve the same effect by setting the background colour (BCol) for the Separators to grey (192 192 192).

The Posn property is a single integer number which specifies the positional index of the Separator relative to the other objects in the Menu. A Separator does not generate any events.

Like other components of a menu, the position of a Separator is normally determined by the order in which it is created in relation to other objects with the same parent. However, you can use the Posn property to insert a Separator into an existing structure. For example, having defined three MenuItem objects as children of a Menu, you can insert a Separator between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the MenuItems that were previously second and third will then be reset to 3 and 4 respectively.

If you put a Separator (either Style) into a MenuBar, it has the effect of adding another line to it. Any items added after the Separator will appear in the new line.


SM Object
Parents Children Properties Methods Events
Purpose: Defines a window for ⎕SM/⎕SR.

Description

This object defines a window for ⎕SM/⎕SR and allows you to combine the functionality of ⎕SM/⎕SR with the "windows" GUI. For example, you can define a Form with a MenuBar at the top and a ⎕SM window beneath it, with perhaps some Buttons alongside.

To allow the user to interact with both ⎕SM and other top-level objects, you must specify the names of these objects in the right argument of ⎕SR. Thus the statement :

      CTX ← KEYS CTX ⎕SR 1 2 3 'Form1'

allows the user to interact with fields (rows) 1-3 of ⎕SMand with the object 'Form1' and its children. Callback functions associated with events in 'Form1' will be executed automatically by ⎕SR. If an enabled event without a callback occurs, the event will be placed on ⎕DQ's internal queue and ⎕SR will terminate. The nature of the termination (i.e. that it was caused by an event in an object) is reported by the value 131072 (2*17) in the fourth element of ⎕SR's result. The specific event (Configure, MouseUp, etc.) is however not reported. It is therefore generally preferable to use callbacks.

The Posn, Size and Coord properties allow you to specify the position and size of the window occupied by ⎕SM within its parent Form. Note however that the ⎕SM window will automatically be sized to be an exact number of characters in height and width which will be reported in ⎕SD.

The Border property may be used to specify a border around the outside of the ⎕SM window. It is a number with the value 0 (no border) or 1 (1 pixel border). The default is 0. The EdgeStyle property may be used to give the object a 3-dimensional appearance. Its default value is 'Recess'. The area within the SM object that is defined by ⎕SM is necessarily a multiple of the character size. The region between this area and the outer edges of the object is coloured by the background colour specified by BCol, or may be filled with a bitmap specified by Picture.

If the user resizes the Form which contains the SM object, the SM object will generate a Configure event if enabled. If the Configure event is not enabled, ⎕SR will terminate with a RESIZE error which can be trapped using ⎕TRAP. Either method can be used to reformat ⎕SM as appropriate.

The MouseDown event can be used to bring up a pop-up menu. Note however that mouse events are not reported over ⎕SM fields because ⎕SR uses these to position the cursor.

The illustration shown below was produced as follows :

      'TEST'      ⎕WC 'Form' 'SM Object' (60 10)(40 50)
      'TEST.MB'   ⎕WC 'MenuBar'
      'TEST.MB.F' ⎕WC 'Menu' '&File'
      'TEST.MB.O' ⎕WC 'Menu' '&Options'
      'TEST.B1'   ⎕WC 'Button' '&OK' (84 2)
      'TEST.B2'   ⎕WC 'Button' '&Cancel' (84 78)
      'TEST.S'    ⎕WC 'SM'(2 2)(80 96)('BCol'192 192 192)
      ⎕SM←↑('The answer is' 5 10)(42 5 30)


Spinner Object
Parents Children Properties Methods Events
Purpose: The Spinner object allows the user to enter a value, using an UpDown object to adjust it as required.

Description

The Spinner object is a special Dyalog APL composite object that consists of an edit field and a pair of spin buttons. The user may enter a value by typing in the edit field and may adjust the value with the spin buttons. The Spinner may cycle through a pre-defined set of values specified by the Items property or through a range of values specified by the Limits property. The FieldType property supports all of the standard data types, i.e. Char, Numeric, LongNumeric, Currency, Date, LongDate and Time.

The Limits property is a 2-element numeric vector that specifies the minimum and maximum value of the object. The Step property specifies the amount by which the value is incremented or decremented by the spin buttons. The current value in the object is defined by the Thumb and Value properties, which are usually identical. If ReadOnly is 0, the user may type a value into the edit field which will be validated and converted according to the FieldType. In this case, the Value and the Thumb properties may be different.

An alternative way to use the Spinner object is to specify the Items property. This defines a discrete set of values through which the user may cycle, and the object behaves rather like a Combo without a drop-down list. In this case, the Limits property is automatically set to (1,⊃⍴Items), Thumb refers to the index into the list of Items, and Step specifies the amount by which this index is updated by the spin buttons. For example, if you set Step to 3, the spin buttons would display every third item. The Items property may be a character matrix, a vector of character vectors, or a numeric vector and will be formatted according to the FieldType. For example, if you wanted the user to select one of a set of specific dates, you would set the FieldType to Date or LongDate and the Items property to the day numbers (since 1 January 1900) corresponding to the dates you require. The ReadOnly property specifies whether or not the user may enter data into the edit field. A value typed in by the user will be converted and formatted according to the FieldType but need not correspond to a value in Items.

In operation, the value in the Spinner is adjusted by the Step each time one of the spin buttons is clicked. If the user holds a spin button down, the value is adjusted at the rate defined for the keyboard repeat rate. Furthermore, the size of each adjustment is increased according to the length of time the button stays depressed. After 1 second, the amount is increased to (2 × Step). after 2 seconds, to (4 × Step), after 3 seconds to (8 × Step) and so forth until the amount of adjustment exceeds one quarter of the range (Limits[2]⍎Limits[1]).

When the value in the spinner reaches its top or bottom limit, it will wrap around to the opposite limit if the value of the Wrap property is 1 (the default). Otherwise it will stick.

The MaxLength property defines the maximum number of characters that the user may type into the edit field. The Decimals property specifies the number of decimal places to which a numeric value is displayed and applies only if the FieldType is Numeric or LongNumeric.

The Spinner generates two special events, Spin and SetSpinnerText. The Spin event is generated each time the value of the Thumb is about to be updated and reports the new value and the difference between it and the current value. You may prevent the Thumb from being updated by returning 0 from a callback function, or you may alter the new value of the Thumb by returning a modified message. The SetSpinnerText event is generated after the Thumb has been reset but before the edit field has been updated. It reports the new value of the Thumb and the text that is about to be written into the edit field. By returning a modified event message from a callback, this event allows your application to respond dynamically to the spin buttons and to control the text in the edit field directly.

Like an Edit object, the Spinner has a Changed property and generates a Change event when loses the focus after the value of its Text and/or Thumb property has been altered.

If FieldType is Numeric, LongNumeric, Currency, Date, LongDate or Time, the Spinner will generate a BadValue event when it loses the focus if the text in the edit field (i.e. the Text property) is in conflict with the FieldType property and cannot be converted to an appropriate number, or is outside the range specified by the Limits property. If the edit field is empty, a BadValue event will be generated if ValidIfEmpty is 0, but not if it is set to 1.


Splitter Object
Parents Children Properties Methods Events
Purpose: The Splitter object divides a container into resizable panes.

Description

The Splitter divides the client area of a Form or SubForm into resizable panes. Each pane created this way may be empty or be occupied by a single object. If the object in a pane is itself a container object, such as a SubForm, it may have a number of other controls within it.

A single Splitter may manage the geometry of 0, 1 or 2 other objects, which, together with the Splittter itself, share the same parent. The two objects are named by the SplitObj1 and SplitObj2 properties respectively.

A Splitter may manage objects of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If Style is 'Vert' (the default), the Splitter is drawn vertically in its parent with the first object (SplitObj1) positioned to its left, and the second object (SplitObj2) to its right. See Splitter: Example 1.

If Style is 'Horz', the Splitter is drawn horizontally in its parent with the first object (SplitObj1) positioned above, and the second object (SplitObj2) below. See Splitter: Example 2.

The Style property must be set when the object is created with ⎕WC and may not subsequently be changed using ⎕WS.

The Posn and Size properties are partially read-only, in that only one dimension of the value may be specified. If Style is 'Vert', you may specify the x-coordinate and the width of the Splitter, but you may not specify its y- coordinate nor its height. If Style is 'Horz', you may specify the y-coordinate and the width of the Splitter, but you may not specify its x-coordinate nor its length.

When the user positions the mouse pointer directly over the Splitter object, the cursor changes (by default) to a double-headed arrow (direction in accordance with Style). The user may now depress the left mouse button and drag the Splitter to a new position, resizing the objects named by SplitObj1 and SplitObj2 in the process.

You can select a different cursor using the CursorObj property. Note that setting the CursorObj property to 0 selects the default cursor, which is the appropriate double-headed arrow.

When the user depresses the mouse button, the Splitter generates a StartSplit event. When the user releases the mouse button, the Splitter generates an EndSplit event. If full-drag is in effect, the Splitter also reports Splitting events as it is dragged. All these events report the new or current position of the Splitter object and are provided for information only.

Note that the objects named by SplitObj1 and SplitObj2 and any sub-objects they contain will generate Configure events when they are resized by the Splitter.

Alignment

The Align property specifies how a Splitter behaves when its parent is resized and may be 'None', 'Left', 'Right', 'Top' or 'Bottom'.

If Align is 'None', the Splitter moves as its parent is resized, so that it divides its parent in the same proportions as before. This is the default.

Any other value of Align attaches the Splitter to the corresponding edge of its parent. For example, if Align is 'Left', the width of the object to the left of the Splitter remains fixed when its parent is resized horizontally by the user.

Like the Style property, Align may be set only when the object is created with ⎕WC and may not subsequently be changed using ⎕WS.

Using Multiple Splitters

If you want to divide a Form into more than 2 resizable panes, there are two possible approaches, each with its own different characteristics.

The first approach is a hierarchical one using SubForms. This example shows how you can create a Form containing three resizable Edit objects.

First, you create an Edit, a SubForm, and a Splitter as children of the Form, using the Splitter to divide the Form into two panes, one for the Edit and the other for the SubForm. Next, you create two Edit objects and a Splitter as children of the SubForm, using the second Splitter to divide the SubForm into two. You can continue with this approach to any reasonable depth. See Splitter: Example 3.

Notice that, by default, when the first Splitter is shifted to the left, both panes in the SubForm expand equally.

The second approach is to create multiple Splitters at the same level, i.e. owned by the same parent. See Splitter: Example 4.

In this case, the third Edit object F.E3 is unaffected by movement of the leftmost Splitter F.S1. Note also, that the first Splitter F.S1 may not be dragged further right than the second Splitter F.S2.

Using the non-hierarchical approach, horizontal and vertical Splitters may be combined in interesting ways. This can also be achieved using nested SubForms, but at the expense of a complex object hierarchy. See Splitter: Example 5.

Notice that in this example, with the exception of the last Splitter F.S4, it is necessary only to specify the SplitObj1 property for each of the Splitters. The reason is that the first four Splitters only manage one object directly. For example, the object to the right of F.S1 is in fact a horizontal Splitter F.S2. Dragging F.S1 changes the length of F.S2 which in turn changes the width of F.E2. and F.E3.

Colliding Splitters

If you have two or more vertical Splitters or two or more horizontal Splitters in the same parent object, it is possible for the user to make the Splitters collide. This can occur by dragging one of the Splitters into the other, or, unless both Splitters have Align set to 'None', by shrinking the parent.

When Splitters collide, the object being dragged by the user (a Splitter or a border of the parent) takes precedence over the setting of Align, and temporarily pushes other Splitters along in its direction of travel. If and when the operation is reversed, the other Splitters are pulled back to their original positions.


Static Object
Parents Children Properties Methods Events
Purpose: This object is primarily used to display graphics in a sub-window.

Description

The overall appearance of an empty Static object is controlled by the value of its Style property which may be one of the following character vectors :

'BlackFrame' | 'BlackBox'
'GreyFrame' or 'GrayFrame' | 'GreyBox' or 'GrayBox'
'WhiteFrame' | 'WhiteBox'

Note that the colours implied by the Style are not "hard-coded" but are actually defined by the current Windows colour scheme as follows :

Black | Window Border Colour
Grey/Gray | Desktop Colour
White | Window Background Colour

If the background colour of the Form is also set to the Window Background Colour, it follows that the Styles 'WhiteFrame' and 'WhiteBox' make the Static itself invisible (against the background), although the contents of the Static will show. This makes the Static appear like an invisible clipping window.


StatusBar Object
Parents Children Properties Methods Events
Purpose: This object is used to manage StatusField objects which display information for the user.

Description

The StatusBar is a container object that manages StatusFields. StatusField objects display textual information and are typically used for help messages and for monitoring the status of an application. They can also be used to automatically report the status of the Caps Lock, Num Lock , Scroll Lock, and Insert keys.

'TEST'⎕WC'Form' 'StatusBar' ('EdgeStyle' 'Default')
'TEST.SB'⎕WC'StatusBar'
'TEST.SB.S1'⎕WC'StatusField' 'Field1:' 'text1'
'TEST.SB.S2'⎕WC'StatusField' 'Field2:' 'text2'
'TEST.SB.S3'⎕WC'StatusField' 'Field3:' 'text3'

The Align property determines to which side of the parent Form or SubForm the StatusBar is attached. By default, a StatusBar is positioned along the lower edge of the Form (Align 'Bottom') and is 24 pixels high. Using the Align, Posn and Size properties you may create StatusBars in different positions and with differing sizes if you wish. Notice that the Align property controls how the StatusBar reacts to its parent Form being resized. If Align is 'Top' or Bottom, the StatusBar remains fixed in height but stretches and shrinks sideways with the Form. If Align is 'Left' or 'Right', the StatusBar remains fixed in width and stretches and shrinks vertically with the Form.

By default a StatusBar has a Button Face colour background and the value of its EdgeStyle property is 'Default'. This gives it the appearance shown above.

Unless you specify the position and size of its children, a StatusBar automatically manages their geometry. The first StatusField is positioned just inside its top left corner. If Align is 'Top' or 'Bottom', the next StatusField is positioned alongside the first but with a small gap between them. Subsequent StatusFields are added in a similar fashion. If Align is 'Left' or 'Right', the second and subsequent StatusFields are added below the first with a similar gap between them. In either case you can position and size the StatusFields explicitly if you wish.

If you attempt to add a StatusField that would extend beyond the right edge (Align 'Top' or 'Bottom') or bottom edge (Align 'Left' or 'Right') the behaviour depends upon the value of HScroll or VScroll. If HScroll is 0 (the default) and Align is 'Top' or 'Bottom', the StatusField is added below the first one, thereby starting a new row. If VScroll is 0 (the default) and Align is 'Left' or 'Right', it is added to the right of the first one thereby starting a new column. If HScroll or VScroll is ¯1 or ¯2, the new StatusField is simply positioned in the same row or column and may be scrolled into view using a mini scrollbar. A value for HScroll or VScroll of ¯1 causes the mini scrollbar to be permanently present in the Scroll Bar. A value of ¯2 causes it to appear only when required.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.


StatusField Object
Parents Children Properties Methods Events
Purpose: This object is used to display information for the user.

Description

The StatusField object provides an area for displaying context sensitive help messages, keyboard status, and other application dependant information.

By default a StatusField is a recessed rectangle in which information is displayed. It has a Caption and a Text property, which by default are empty, but either or both of which can be used to present information. The Caption is left justified in the field and the Text is displayed immediately to its right. Typically, you would use the Caption property as a title to describe the information that the StatusField displays, and the Text property to show its current value. However, you are not obliged to use both of them and you can achieve most effects with just one.

Note that when the StatusField is used to display hints it is its Text property that is used.

A StatusField may be used to monitor the status of the keyboard and this is controlled by its Style property. The default value for Style is an empty vector. However, you can set it to monitor various keyboard states as follows :

CapsLock | Monitors state of Caps Lock key
ScrollLock | Monitors state of Scroll Lock key
NumLock | Monitors state of Num Lock key
KeyMode | Monitors the keyboard mode (APL/ASCII)
InsRep | Monitors the state of the Insert key

In each case, the Text property of the StatusField is used to display the keyboard status. If Style is CapsLock, ScrollLock or NumLock, the field displays "Caps", "Num" or "Scroll" if the corresponding mode is selected and is blank if not.

If Style is InsRep, the StatusField displays either "Ins" or "Rep". Initially it always displays "Ins" and then toggles between "Rep" and "Ins" each time the Insert key is pressed.

If Style is KeyMode, the StatusField displays the name for the current keyboard mode which is defined in the input table being used. For the 2-mode tables APL_US.DIN, APL_UK.DIN etc., the mode name displayed is either "Apl" or "Asc". The unified tables have no modes so a StatusField with this Style does nothing.

If Style is set to one of the above, you may still use the Caption property to give the StatusField a title. You may even set the value of the Text property, but be aware that this value will be reset when the user next presses the key the StatusField is monitoring.


SubForm Object
Parents Children Properties Methods Events
Purpose: This object represents a window that is owned by and constrained within another Form or an MDIClient.

Description

If the SubForm is the child of a Form, it is by default a simple featureless window that occupies the entire client area (excluding standard ToolBars, StatusBars and TabBars) of its parent. The properties that control its appearance, including Sizeable, Moveable, SysMenu, Border, MaxButton and MinButton, all default to 0. The EdgeStyle property also defaults to 'None', so the background of the SubForm defaults to the Window Background colour.

If the SubForm is the child of an MDIClient, its default appearance is the same as for a top-level Form. By default its size is 25% of its parent client area and it is positioned in the centre of its parent object.

The Posn property specifies the location of the internal top-left corner of the SubForm relative to its parent. If the SubForm has a title bar, border, or a 3-dimensional shadow, you must allow sufficient space for these components. Similarly, the Size property specifies the internal size of the SubForm excluding the title bar and border.

A SubForm is constrained so that it cannot be moved outside its parent. In all other respects it behaves in a similar manner to a Form object. See Form object and the descriptions of its properties for further details.


SysTrayItem Object
Parents Children Properties Methods Events
Purpose: The SysTrayItem object represents an item that you can create in the Windows System Tray.

Description

The SysTrayItem object appears as an icon in the Windows System Tray and allows the user to interact with your application even if it is minimised or has no other visible presence.

Interaction is provided through a pop-up menu that is displayed when the user clicks on the SysTrayItem. The SysTrayItem does not support mouse or keyboard events directly.

The IconObj property specifies the name of an Icon object used to display the SysTrayItem. If not specified, the default is the standard Dyalog APL icon.

The Popup property specifies the name of a Menu object (which may be a child of the SysTrayItem). The Menu object is displayed automatically when the user clicks on the SysTrayItem icon. The Menu should contain one or more MenuItem objects with suitable callback functions attached.

Unlike other popup menus, the SysTrayItem menu is not activated by an explicit (modal) ⎕DQ but is posted automatically for you. The MenuItem callbacks will be executed by the current ⎕DQ, with the exception of modal ⎕DQs on MsgBox, FileBox, Locator and other popup Menu objects. For example, if your application is in a modal ⎕DQ on a Form, that ⎕DQ will react to and action events on the SysTrayItem menu, even though it is not explicitly included in the list of objects being ⎕DQ'ed.

The Tip property specifies a character string to be displayed when the user hovers the mouse over the SysTrayItem. This is displayed using the user's current setting for Tip text and it is not possible to change this appearance.


TabBar Object
Parents Children Properties Methods Events
Purpose: To manage a set of TabBtn objects.

Description

The TabBar object manages a group of TabBtn objects. These are associated with a set of SubForm objects which are positioned on top of one another. When the user clicks on a TabBtn, the corresponding SubForm is brought to the top and given the focus.

TabBar and TabBtn objects were implemented before Windows provided direct support for tabbed dialogs, and have been superceded by TabControl and TabButton objects. Please use these instead.

By default, a TabBar is a flat bar stretched across the bottom of its parent form. You can alter its appearance using its EdgeStyle property and you can control its alignment with its Align property. Align can be set to Top , Bottom (the default), Left or Right and causes the TabBar to be attached to the corresponding edge of the Form. A TabBar aligned Top or Bottom will automatically stretch or shrink horizontally when its parent Form is resized, but it will remain fixed vertically. A TabBar aligned Left or Right will stretch vertically but will remain fixed horizontally. By default a TabBar occupies the entire width or length of the side of the Form to which it is attached. Both the Posn and Size properties can be altered.

The alignment of a TabBar also determines the orientation of its TabBtns. TabBars aligned Top or Bottom cause their TabBtns to be drawn left to right with the free edge of the TabBtns facing downwards or upwards respectively. TabBar aligned Left or Right draw their TabBtns downwards with their free edges facing left or right respectively.

By default, TabBtn objects are positioned along the inner edge of the TabBar. This is the edge closest to the SubForm s they will tab. They are also positioned so that they overlap one another horizontally or vertically according to the Align property.

The HScroll and VScroll properties determine what happens when the end of the TabBar is reached. If HScroll or VScroll is 0 (the default) a TabBtn that would otherwise extend beyond the TabBar is instead positioned immediately above, below or alongside the first TabBtn in the TabBar, thereby starting a new row or column. Note however that the TabBar is not automatically resized vertically to accommodate a second row or column. If you want a multi-flight TabBar you have to set its height or width explicitly. If HScroll or VScroll is ¯1 or ¯2, TabBtns continue to be added along the TabBar even though they extend beyond its boundary and may be scrolled into view using a mini scrollbar. If HScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the TabBar. If HScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

If you specify a value for its Posn property, a TabBtn will be placed at the requested position regardless of the value of Style, HScroll or VScroll. However, the next control added will take its default position from the previous one according to the value of these properties. Thus if you wish to group your controls together with spaces between the groups, you need only specify the position of the first one in each group.

If you specify a value for its Posn property, a TabBtn will be placed at the requested position regardless of the value of Align. However, the next TabBtn added will take its default position from the previous one. Thus if you wish to group your TabBtns together with spaces between the groups, you need only specify the position of the first one in each group.


TabBtn Object
Parents Children Properties Methods Events
Purpose: To tab a SubForm.

Description

TabBtn objects are associated with SubForms which are positioned on top of one another. When the user clicks on a TabBtn, the corresponding SubForm is brought to the top and given the focus.

TabBar and TabBtn objects were implemented before Windows provided direct support for tabbed dialogs, and have been superceded by TabControl and TabButton objects. Please use these instead.

The appearance of a TabBtn is determined by its EdgeStyle, Border and Caption properties. These take their defaults from the SubForm with which the TabBtn is associated. Thus there is generally no need to specify them. BCol also defaults to that of its associated SubForm.

The position of a TabBtn is normally determined by its parent TabBar and its default size is fixed (22 x 80 pixels), and not related to the size of its Caption. These defaults can be overridden using the Posn and Size properties.

A SubForm is associated with a TabBtn by setting the TabObj property of the SubForm to the name of, or ref to, the TabBtn. The TabObj property of the TabBtn is a read-only property that contains the name of, or ref to, the associated SubForm.


TabButton Object
Parents Children Properties Methods Events
Purpose: The TabButton object represents an individual tab or button in a TabControl

Description

The TabButton object represents an individual tab or button in a TabControl

The position and size of a TabButton object are entirely determined by its parent TabControl and may not be altered. For this reason, the Posn and Size properties are read-only.

The Caption property specifies the text that appears on the button or tab.

A picture is specified by setting the ImageIndex property of the TabButton. This is a number that points to a particular icon or bitmap defined in an ImageList object whose name is specified by the ImageListObj property of the parent TabControl.

Note that all TabButton objects share the same font which is defined by the FontObj property of the TabControl.

The foreground and background colours of the TabButton object are fixed.

When used as a tab, a TabButton is normally attached to a SubForm by the TabObj property of the SubForm. The TabObj property of the TabButton itself, is a read-only property that specifies the name of, or ref to, the SubForm to which the TabButton is attached.

The State property reports the (selected) state of a TabButton and applies only when its parent TabControl has Style set to 'Buttons' or 'FlatButtons' and MultiSelect set to 1.


TabControl Object
Parents Children Properties Methods Events
Purpose: The TabControl object provides access to the native Windows tab control.

Description

The standard tab control is analogous to a set of dividers in a notebook and allows you to define a set of pages that occupy the same area of a window or dialog box. Each page consists of a set of information or a group of controls that the application displays when the user selects the corresponding tab.

A special type of tab control displays tabs that look like buttons. For example, the Windows taskbar is such a tab control.

The overall appearance of the TabControl is determined by the Style property which may be 'Tabs' (the default), 'Buttons' or 'FlatButtons'.

Individual tabs or buttons are represented by TabButton objects which should be created as children of the TabControl object. Optional captions and pictures are specified by the Caption and ImageIndex properties of the individual TabButton objects themselves. Otherwise, the appearance of the tabs or buttons is determined by properties of the TabControl itself.

To implement a multiple page tabbed dialog (see Example 1), you should create a Form, then a TabControl with Style 'Tabs' as a child of the Form. Next, create one or more pairs of TabButton and SubForm objects as children of the TabControl. You associate each SubForm with a particular tab by setting its TabObj property to the name of, or ref to, the associated TabButton object. Making the SubForms children of the TabControl ensures that, by default, they will automatically be resized correctly. You may alternatively create your SubForms as children of the main Form and establish appropriate resize behaviour using their Attach property.

A TabControl object with Style 'Buttons'(Example 2) or 'FlatButtons'(Example 3) may be used in a similar way (i.e. to display a set of alternative pages), although buttons in this type of TabControl are more normally used to execute commands. For this reason, these styles of TabControl are without borders.

If Style is 'FlatButtons', the FlatSeparators property specifies whether or not separators are drawn between the buttons. The default value of FlatSeparators is 0 (no separators).

Example 3a shows the effect of setting FlatSeparators to 1.

The Align property specifies along which of the 4 edges of the TabControl the tabs or buttons are arranged. Align also controls the relative positioning of the picture and Caption within each TabButton. Align may be Top (the default) , Bottom, Left or Right.

If Align is 'Top'or 'Bottom'( Example 4), the tabs or buttons are arranged along the top or bottom edge of the TabControl and picture is drawn to the left of the Caption.

If Align is 'Left'(Example 5), the tabs or buttons are arranged top-to-bottom along the left edge of the TabControl, and the pictures are drawn below the Captions.

If Align is 'Right' (Example 6), the tabs are arranged top-to-bottom along the right edge of the TabControl, and the pictures are drawn above the Captions.

The Attach property specifies how the TabControl responds when its parent is resized. Its default value, which is independent of the Align property, is 'None' 'None' 'None' 'None'. This causes the TabControl to maintain its original proportions when its parent is resized.

The MultiLine property determines whether or not your tabs or buttons will be arranged in multiple flights or multiple rows/columns.

The default value of MultiLine is 0, in which case, if you have more tabs or buttons than will fit in the space provided, the TabControl displays an UpDown control to permit the user to scroll them. See Example 7.

If MultiLine is set to 1, the tabs are displayed in multiple flights (Example 8)or the buttons are displayed in multiple rows (Example 9).

The ScrollOpposite property specifies that unneeded tabs scroll to the opposite side of a TabControl, when a tab is selected. Setting ScrollOpposite to 1 forces MultiLine to 1 also.

Example 10 illustrates a TabControl with ScrollOpposite set to 1, after the user has clicked Third Tab. Notice that, in this example, the SubForms have been created as children of the TabControl. This is necessary to ensure that they are managed correctly in this case.

If MultiLine is 1, the way that multiple flights of tabs or rows/columns of buttons are displayed is further defined by the Justify property which may be 'Right'(the default) or None.

If Justify is 'Right'(which is the default), the TabControl increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control. Otherwise, if Justify is empty or 'None', the rows are ragged.

See Example 11 (for tabs) and Example 12 (for buttons)

By default, the size of the tabs may vary from one to another. Fixed size tabs may be obtained by setting the TabSize property.

To obtain fixed sized tabs with MultiLine set to 1, you must however also set Justify to 'None'.

If fixed size tabs are in effect, the positions at which the picture and Caption are drawn within each TabButton is controlled by the TabJustify property which may be 'Centre', 'Edge', or 'IconEdge'.

Example 13 illustrates these different settings.

The font used to draw the captions in the TabButton objects is determined by the FontObj property of the TabControl.

You cannot specify the foreground or background colours of the tabs/buttons, nor can you use different fonts in different tabs/buttons. The orientation of the Caption text is always determined by the value of the Align property of the TabControl.

The TabObj property is read-only and reports the name of, or ref to, the TabButton that is currently selected.

The MultiSelect property specifies whether or not the user can select more than one button in a TabControl at the same time, by holding down the Ctrl key when clicking. The default is 0 (only one button may be selected). MultiSelect is ignored if Style is 'Tabs'.

The TabFocus property specifies the focus behaviour for the TabControl object and may be 'Normal'(the default), 'Never' or 'ButtonDown'.

The HotTrack property specifies whether or not the tabs or buttons are automatically highlighted by the mouse pointer. The default is 0 (no highlighting).


TCPSocket Object
Parents Children Properties Methods Events
Purpose: The TCPSocket object provides an interface to TCP/IP.

Description

The TCPSocket object provides an event-driven mechanism to communicate with other programs (including Dyalog APL) running on other computers and with the world-wide Web.

The SocketType property is a character vector that specifies the type of the TCP/IP socket. This is either 'Stream'(the default), or 'UDP'. SocketType must be defined when the object is created and may not be set or changed using ⎕WS.

The Style property is a character vector that specifies the type of data transmitted or received by the socket; it may be 'Char', 'Raw', or 'APL'. The value 'APL' is valid only if the SocketType is 'Stream'.

The Encoding property is a character vector that specifies how character data are encoded or translated. The possible values are 'None', 'UTF-8', 'Classic', or 'Unicode', depending upon the value of the Style property.

LocalAddr and LocalPort properties identify your end of the connection; RemoteAddr and RemotePort identify the other end of the connection. The values of the two sets of properties are clearly symmetrical; your LocalAddr is your partner's RemoteAddr, and there are strict rules concerning which of them you and your partner may set. See the individual descriptions of these properties for details.

The SocketNumber property is the Window handle of the socket attached to the TCPSocket object and is generally a read-only property. The only time that SocketNumber may be specified is when a server replicates (clones) a listening socket to which a client has just connected.


Text Object
Parents Children Properties Methods Events
Purpose: Writes text.

Description

The Text object is used to write arbitrary text. It can be used in a Form, SubForm or Group instead of a Label. The main difference is that a Label is implemented as a true window object (thus consuming Windows resources). A Text object is not a window and consumes no MS-Windows resources. However, a Label supports DragDrop events and has various useful properties that are not shared by the Text object.

The contents of the Text object are defined by its Text property. This is a character array containing one of the following :

  • a simple scalar
  • an enclosed vector or matrix (also a scalar)
  • a simple vector
  • a simple matrix
  • a vector of enclosed vectors or matrices

Points is either a simple 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y-coordinates and x-coordinates respectively.

There are two distinct cases :

  1. Points specifies a single point. In this case, Text may be a single scalar character, a simple vector, or a matrix containing a block of text. The result is that the character, string, or matrix is written at the specified point.
  2. Points specifies more than one point. There are three possibilities :
    1. If Text is a scalar, its contents are written at each of the points in Points. This means that by enclosing a vector or matrix, you can draw a string or block of text at several locations.
    2. If Text is a vector, each element of Text is written at the corresponding position in Points.
    3. If Text is a matrix, each row of Text is written at the corresponding position in Points.

FontObj specifies a single font to be used to write the Text. See a description of the FontObj property for details.

FCol specifies the colour of the Text. For a single text item, FCol may be a single number which specifies one of the standard MS-Windows colours, or a simple 3-element numeric vector of RGB colour intensities. If more than one text item is involved, FCol may be a vector which specifies the colour for each item separately. If so, its length must be the same as the number of points specified by Points.

BCol specifies the background colour of the text, i.e. the colour for the part of the character cell that is blank. It is defined in the same way as FCol.

HAlign and VAlign specify the horizontal and vertical alignment of the text respectively. They may each be numeric scalars or vectors with the same length as the number of points specified in Points. See HAlign and VAlign for details.

When one or more of FCol, BCol, HAlign and VAlign are vectors, the different components of Text are drawn using the corresponding colours and alignments.

The value of the Dragable property specifies whether or not the Text object can be dragged by the user. The value of the AutoConf property determines whether or not the Text object is repositioned when its parent is resized.

Examples:

Write 'A' at (10,20)

      'g.t1' ⎕WC 'Text' 'A' (10 20)

Write 'h' at (10,20) in red

      'g.t1' ⎕WC 'Text' 'h' (10 20) ('FCol' 255 0 0)

Write 'Hello' at (10,20)

      'g.t1' ⎕WC 'Text' 'Hello' (10 20)
Write 'THIS IS A
       BLOCK OF
       TEXT     '   at (20,30)
      BLK←3 9⍴'THIS IS A BLOCK OF TEXT     '
      'g.t1' ⎕WC 'Text' BLK (10 20)

Write 'A' at (10,20) and at (30,40)

      'g.t1' ⎕WC 'Text' 'A' ((10 30)(20 40))

Write a red '+' at (10,20) and a green '+' at (20 40)

      'g.t1' ⎕WC 'Text' '+' ((10 30)(20 40))('FCol' (255 0 0)(0 255 0))

Write 'Hello' at (10,20) and at (30,40)

      'g.t1' ⎕WC 'Text' (⊂'Hello') ((10 30)(20 40))

Write 'A' at (10,20) and 'B'at (30,40)

      'g.t1' ⎕WC 'Text' 'AB' ((10 30)(20 40))

Write 'Hello' at (10,20) and 'World'at (30,40)

      'g.t1' ⎕WC 'Text' ('Hello' 'World')((10 30)(20 40))


Timer Object
Parents Properties Methods Events
Purpose: To generate an action at regular intervals.

Description

The Timer object is used to generate an event at regular intervals. It can be used to produce animation and to implement "repeaters" such as spin buttons.

The Interval property specifies how often the Timer generates events and is defined in milliseconds. Its default value is 1000.

The Active property determines whether or not the Timer generates events and can be used to switch the Timer off and on as required.

Note that if you create a Timer object whose Timer event generates an error (for example by attaching it to a non-existent callback) it may be very difficult or even impossible to type into the Session, because the error will be displayed over and over again. Care is therefore recommended.


TipField Object
Parents Children Properties Methods Events
Purpose: To display pop-up help.

Description

The TipField is used to display pop-up help when the user moves the mouse pointer over an object.

Most of the GUI objects supported by Dyalog APL/W have Tip and a TipObj properties. TipObj specifies the name of, or ref to, a TipField object, and Tip specifies a "help" message. The TipField automatically pops-up to display the Tip when the user moves the mouse pointer over the object. It disappears when the user moves the mouse pointer away.

The TipField is a simple box with a 1-pixel black border in which the text specified by Tip is displayed. FCol, BCol and FontObj can be used to customise the appearance of the text within the box. FCol specifies the colour of the text; BCol specifies the background colour with which the box is filled. The default is black on yellow.

If you wish to display Tips for particular objects in different fonts and colours, you must create a separate TipField for each combination of colour and font you need.


ToolBar Object
Parents Children Properties Methods Events
Purpose: To manage a group of controls such as Buttons.

Description

The ToolBar object is used to display and manage a set of controls. It is typically used to present a set of Buttons which the user can press to perform various actions. However, the ToolBar has the ability to manage other controls too.

By default, the ToolBar is a raised bar stretched across the top of its parent form. You can alter its appearance using its EdgeStyle property and you can control its alignment with its Align property. Align can be set to Top (the default), Bottom, Left or Right and causes the ToolBar to be attached to the corresponding edge of the Form. A ToolBar aligned Top or Bottom will automatically stretch or shrink horizontally when its parent Form is resized, but it will remain fixed vertically. A ToolBar aligned Left or Right will stretch vertically but will remain fixed horizontally. By default a ToolBar occupies the entire width or length of the side of the Form to which it is attached and is 30 pixels high or wide. You can change these defaults using the Posn and Size properties.

A ToolBar organises its child controls in the order they are created. The way this is done is governed by the value of the Align property. If Align is Top or Bottom, the ToolBar arranges its controls in rows across the screen. If Align is Left or Right, the ToolBar arranges controls in columns.

The first control added to a ToolBar is automatically positioned 2 pixels down and 2 pixels across from its top left corner. The rule for positioning subsequent controls depends upon the value of the Align property.

If Align is 'Top'or 'Bottom', controls are positioned so as to be horizontally adjacent to one another. Whenever a control is added it is positioned relative to the one that immediately preceded it so that its top left corner meets the top right corner of the previous one. The HScroll property determines what happens when the end of the ToolBar is reached. If HScroll is 0 (the default) a control that would otherwise extend beyond the width of the ToolBar is instead positioned immediately below the first control in the ToolBar, thereby starting a new row. Note however that the ToolBar is not automatically resized vertically to accommodate a second row. If you want a multi-row ToolBar you have to set its height explicitly. If HScroll is ¯1 or ¯2, controls continue to be added along the ToolBar even though they extend beyond its right edge and may be scrolled into view using a mini scrollbar. If HScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the width of the ToolBar. If HScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

If Align is 'Left'or 'Right', controls are positioned so as to be vertically adjacent to one another. Whenever a control is added, its top left corner is positioned against the bottom left corner of the previous control. The VScroll property determines what happens when the bottom of the ToolBar is reached. If VScroll is 0 (the default) a control that would otherwise extend beyond the bottom of the ToolBar is instead positioned immediately to the right of the first one; thereby starting a new column. Note however that the ToolBar is not automatically resized horizontally to accommodate a second column. You must set the width of the ToolBar explicitly.

If VScroll is ¯1 or ¯2, controls continue to be added down the ToolBar even though they extend beyond its bottom edge and may be scrolled into view using a mini scrollbar. If VScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the bottom of the ToolBar. If VScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

If you specify a value for its Posn property, a control will be placed at the requested position regardless of the value of Style, VScroll or HScroll. However, the next control added will take its default position from the previous one according to the value of these properties. Thus if you wish to group your controls together with spaces between the groups, you need only specify the position of the first one in each group.

The ToolBar object was introduced in Dyalog APL before an appropriate standard Windows control existed. The ToolBar object should be considered as a legacy object and used only in old GUI applications. The ToolControl object should be used instead.


ToolButton Object
Parents Children Properties Methods Events
Purpose: The ToolButton object represents a button in a ToolControl.

Description

The ToolButton object represents a selectable button in a ToolControl object.

A ToolButton displays a text string, defined by its Caption property, and an image defined by its ImageIndex property. Apart from these characteristics, the appearance of a ToolButton is controlled by its parent ToolControl object.

ImageIndex is an index into an ImageList which contains a set of icons or bitmaps. The ImageList itself is named by the ImageListObj property of the parent ToolControl.

Typically, you will create up to three ImageLists as children of the ToolControl. These will be used to specify the pictures of the ToolButton objects in their normal, highlighted (sometimes termed hot) and inactive states respectively. The set of images in each ImageList is then defined by creating unnamed Bitmap or Icon objects as children. Finally, when you create each ToolButton you specify ImageIndex, selecting the three pictures which represent the three possible states of the button.

If you specify only a single ImageList, the picture on the ToolButton will be the same in all three states.

The behaviour and appearance of a ToolButton is further defined by its Style property, which may be 'Push', 'Check', 'Radio', 'Separator' or 'DropDown'.

Push buttons are used to generate actions and pop in and out when clicked. Radio and Check buttons are used to select options and have two states, normal (out) and selected (in). Their State property is 0 when the button is in its normal (unselected state) or 1 when it is selected.

Separator buttons are a special case as they have no Caption or picture, but appear as vertical lines used to separate groups of buttons.

A group of adjacent ToolButtons with Style 'Radio' defines a set in which only one of the ToolButtons may be selected at any one time. The act of selecting one will automatically deselect any other. Note that a group of Radio buttons must be separated from Check buttons or other groups of Radio buttons by ToolButtons of another Style.

A ToolButton with Style 'DropDown' has an associated popup Menu object which is named by its Popup property. There are two cases to consider.

If the ShowDropDown property of the parent ToolControl is 0, clicking the ToolButton causes the popup menu to appear. In this case, the ToolButton itself does not itself generate a Select event; you must rely on the user selecting a MenuItem to specify a particular action.

If the ShowDropDown property of the parent ToolControl is 1, clicking the dropdown button causes the popup menu to appear; clicking the ToolButton itself generates a Select event, but does not display the popup menu.

The following example illustrates the use of DropDown buttons.

'F'⎕WC'Form' 'ToolControl: Dropdown Buttons'('Size' 20 40)
'F.TB'⎕WC'ToolControl'('ShowDropDown' 1)

:With 'F.FMENU'⎕WC'Menu' ⍝ Popup File menu
    'NEW'⎕WC'MenuItem' '&New'
    'OPEN'⎕WC'MenuItem' '&Open'
    'CLOSE'⎕WC'MenuItem' '&Close'
:EndWith

:With 'F.EMENU'⎕WC'Menu' ⍝ Popup File menu
    'CUT'⎕WC'MenuItem' 'Cu&t'
    'COPY'⎕WC'MenuItem' '&Copy'
    'PASTE'⎕WC'MenuItem' '&Paste'
:EndWith

'F.TB.B1'⎕WC'ToolButton' 'File'('Style' 'DropDown')('Popup' 'F.FMENU')
'F.TB.B2'⎕WC'ToolButton' 'Edit'('Style' 'DropDown')('Popup' 'F.EMENU')


ToolControl Object
Parents Children Properties Methods Events
Purpose: The ToolControl object provides a standard Windows ToolBar.

Description

The ToolControl object provides an interface to the native Windows ToolBar control and supersedes the Dyalog APL ToolBar object.

The tools on a ToolControl are normally represented by ToolButton objects, but the ToolControl may also act as a parent for other objects, including a MenuBar (see below).

Unlike the ToolBar, the ToolControl fully determines the positioning of its children automatically and this is governed by their order of creation. The Posn property of any child of a ToolControl is therefore read-only. Furthermore, the height of objects in a ToolControl may be no greater than that of a ToolButton in the same ToolControl. This in turn is governed by the sizes of the FontObj and ImageList in use in that ToolControl. ToolControl objects should be used in preference to ToolBar objects.

If a ToolControl is the child of a Form, its position and orientation is defined by its Align property. This property is ignored if the ToolControl is the child of a CoolBand.

The overall appearance of the ToolButton objects displayed by the ToolControl is defined by the Style property of the ToolControl itself, rather than by individual ToolButtons. This may be 'Buttons', 'FlatButtons', 'List' or 'FlatList'.

'F'⎕WC'Form' 'ToolControl: FlatButtons Style (default)'('Size' 10 40)
'F.TB'⎕WC'ToolControl'

'F.TB.IL'⎕WC'ImageList'('Masked' 0)
'F.TB.IL.'⎕WC'Bitmap'('Comctl32' 120)
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
'F.TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
'F.TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)

'F.TB'⎕WC'ToolControl'('Style' 'Buttons')

'F.TB'⎕WC'ToolControl'('Style' 'FlatList')

'F.TB'⎕WC'ToolControl'('Style' 'List')

The presence or absence of a recessed line drawn above, below, to the left of, or to the right of the ToolControl is controlled by the Divider property whose default is 1 (show divider).

The MultiLine property specifies whether or not ToolButtons (and other controls) are arranged in several rows (or columns) when there are more than will otherwise fit. If MultiLine is 0 (the default), the ToolControl object clips its childen and the user must resize it to bring more objects into view.

'F'⎕WC'Form' 'ToolControl: MultiLine 0'('Size' 20 36)
'F.TB'⎕WC'ToolControl'('Style' 'List')

'F.TB.IL'⎕WC'ImageList'('Masked' 0)('Size' 24 24)
'F.TB.IL.'⎕WC'Bitmap'('ComCtl32' 121)⍝ STD_LARGE
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'Cut'('ImageIndex' 1)
'F.TB.B2'⎕WC'ToolButton' 'Copy'('ImageIndex' 2)
'F.TB.B3'⎕WC'ToolButton' 'Paste'('ImageIndex' 3)
'F.TB.B4'⎕WC'ToolButton' 'Undo'('ImageIndex' 4)
'F.TB.B5'⎕WC'ToolButton' 'Redo'('ImageIndex' 5)
'F.TB.B6'⎕WC'ToolButton' 'Delete'('ImageIndex' 6)

'F.TB'⎕WC'ToolControl'('MultiLine' 1)('Style' 'List')

The Transparent property specifies whether or not the ToolControl is transparent. If so, the visual effect is as if the ToolButtons (and other controls) were drawn directly on the parent Form as illustratedbelow .

'F'⎕WC'Form' 'ToolControl: Transparent 1)'('Size' 10 40)
'F.BM'⎕WC'Bitmap' 'C:\WINDOWS\WINLOGO'
'F'⎕WS'Picture' 'F.BM' 1

'F.TB'⎕WC'ToolControl'('Transparent' 1)('Style' 'FlatList')
'F.TB.IL'⎕WC'ImageList'('Masked' 0)('Size' 24 24)
'F.TB.IL.'⎕WC'Bitmap'('ComCtl32' 121)⍝ STD_LARGE
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
'F.TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
'F.TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)

The ShowCaptions property specifies whether or not the captions of ToolButton objects are drawn. Its default value is 1 (draw captions). ToolButtons drawn without captions occupy much less space and ShowCaptions provides a quick way to turn captions on/off for user customisation.

The ShowDropDown property specifies whether or not a drop-down menu symbol is drawn alongside ToolButtons which have Style 'DropDown'. ShowDropDown also affects the behaviour of such ToolButton objects when clicked.

The ButtonsAcceptFocus property determines how the ToolControl responds to rthe Tab and cursor movement keys.

As a special case, the ToolControl may contain a MenuBar as its only child. In this case, Dyalog APL causes the menu items to be drawn as buttons as shown below.

Although nothing is done to prevent it, the use of other objects in a ToolControl containing a MenuBar, is not supported.

'F'⎕WC'Form' 'ToolControl with MenuBar'('Size' 20 40)
'F.TB'⎕WC'ToolControl'

:With 'F.TB.MB'⎕WC'MenuBar'
    :With 'File'⎕WC'Menu' 'File'
        'New'⎕WC'MenuItem' 'New'
        'Open'⎕WC'MenuItem' 'Open'
        'Close'⎕WC'MenuItem' 'Close'
    :EndWith

    :With 'Edit'⎕WC'Menu' 'Edit'
        'Cut'⎕WC'MenuItem' 'Cut'
        'Copy'⎕WC'MenuItem' 'Copy'
        'Paste'⎕WC'MenuItem' 'Paste'
    :EndWith

:EndWith


TrackBar Object
Parents Children Properties Methods Events
Purpose: The TrackBar object is a slider control that allows the user to enter a value by positioning a pointer (thumb) on a scale.

Description

The TrackBar object consists of a window which contains a slider bar, a thumb, and a set of tick marks. The slider in a TrackBar moves in increments that you specify when you create it. For example, if you specify that the TrackBar should have a range of five, the slider can only occupy six positions: a position at the left side of the TrackBar and one position for each increment in the range. Typically, each of these positions is identified by a tick mark. TrackBars can have either a vertical or horizontal orientation. They can have tick marks on either side, both sides, or neither. A selection of different TrackBars is illustrated below.

The position and size of the container window are defined by the Posn and Size properties. Its appearance is defined by the EdgeStyle, Border and BCol properties. The defaults are ('EdgeStyle' 'None'), ('Border' 0) and ('BCol' 0). The default background colour ('BCol' 0) obtains either the standard Window Background colour, or grey to match the colour of the parent object if it has a 3-dimensional appearance.

The orientation of a TrackBar is determined by the HScroll and VScroll properties. A horizontal TrackBar is obtained by setting HScroll to ¯1 and VScroll to 0. This is the default. A vertical TrackBar is obtained by setting VScroll to ¯1 and HScroll to 0.

VScroll and HScroll may only be set when the object is created and may not subsequently be changed.

The ShowThumb property determines whether or not the thumb is visible. Its default value is 1. You may toggle this property dynamically using ⎕WS.

The TrackBar optionally displays tick marks at the two ends of the slider bar and spaced out along it. This behaviour is determined by the HasTicks property which may be 1 (the default) or 0 and may be set only when the object is created by ⎕WC.

If HasTicks is 1, the position and frequency of the tick marks is determined by the TickAlign and TickSpacing properties. Note that TickAlign may only be set when the TrackBar is created with ⎕WC and may not be altered using ⎕WS.

The slider and tick marks in a horizontal TrackBar are drawn along the top of the enclosing window. The slider and tick marks in a vertical TrackBar are drawn along the left edge of the window. The position and size of the slider and the thumb may be obtained from the TrackRect and ThumbRect properties which report these values in pixels. These are read-only properties and cannot not be set with ⎕WC or ⎕WS.

The value of the TrackBar is determined by its Thumb property which is an integer that may be set with ⎕WS or retrieved with ⎕WG. The Limits property specifies the minimum and maximum values of Thumb corresponding to its position at the two ends of the slider bar. The Step property is a 2-element integer vector defining the small and large increments by which the Thumb moves. A small step is obtained by pressing a cursor movement key; a large step is achieved by clicking the left mouse button either side of the thumb or by pressing Page Up and Page Down. The user may also drag the thumb to a new position or move it directly to either end of the slider by pressing Home or End.

An alternative form of the TrackBar is obtained by setting the Style property to 'Selection'. This may only be done when the object is created using ⎕WC. This style of TrackBar has a slider that is represented by a recessed thick white rectangle instead of a solid black line. Furthermore, you can select a range of values within the TrackBar by setting the SelRange property. This causes the TrackBar to display a solid blue bar within the white slider and to show the corresponding tick marks as small triangles. Note that there is no way for the user to change SelRange directly; you can only do this using ⎕WS.

In addition to the normal mouse events, the TrackBar generates a Scroll and ThumbDrag event. The Scroll event is the same event that is generated by a Scroll object and is reported when the user repositions the thumb. If enabled, the ThumbDrag event is reported continuously as the user drags the thumb with the mouse and may be used to synchronise the display of a corresponding value in another object.


TreeView Object
Parents Children Properties Methods Events
Purpose: The TreeView object displays a hierarchical list of items.

Description

A TreeView object displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of sub-items associated with it. By clicking an item, the user can expand and collapse the associated list of sub-items.

The contents of a TreeView object are defined by the Items property; a vector of character vectors that specifies the item labels.

The ImageListObj, ImageIndex and SelImageIndex properties define bitmapped images corresponding to each item. The bitmapped images are drawn to the left of the item labels.

ImageListObj specifies the name of a single ImageList object that contains one or more bitmaps

ImageIndex and SelImageIndex are ⎕IO sensitive scalars, or vectors with the same length as the number of items in the object. The value in the ith element specifies the image for the ith item and is an index into the corresponding ImageList object. ImageIndex specifies the image displayed when an item is not selected, SelImageIndex specifies the image displayed when an item is selected.

If ImageListObj is specified, but ImageIndex is empty or not specified, the first bitmap in the ImageList is drawn alongside every item. If an element of ImageIndex or SelImageIndex specifies a value that does not correspond to a bitmap in the ImageList, no picture is drawn.

The structure of the items (i.e. the parent/child relationships of the items) is defined by the Depth property. This is either a scalar 0 (the default) which means that all items are root items, or it is a numeric vector of the same length as Items. Non-zero values in Depth indicate child items.

The HasLines property is 0, 1 or 2 and determines whether or not lines are drawn that link child items to their corresponding parent item. If HasLines is 0, no lines are drawn. If HasLines is 1, lines are drawn at all except the top level, i.e. the object does not link items at the root of the hierarchy. The default value for HasLines is 2 which provides lines at all levels including the root.

The HasButtons property determines whether or not the TreeView object has a button to the left side of each parent item. It is boolean with a default value of 1. The user can click the button to expand or collapse the child items as an alternative to double-clicking the parent item. Note that by itself, setting HasButtons to 1 does not add buttons to items at the root of the hierarchy. To achieve this you must also set HasLines to 2.

The CheckBoxes property specifies whether or not check boxes are displayed alongside items in a TreeView.

The FullRowSelect property specifies whether just the item itself, or the entire row of the TreeView, is highlighted when an item is selected. FullRowSelect should not be used if HasLines is 1 or 2

When the user presses the left mouse button over an item, the object generates an ItemDown event. This is followed by an ItemUp event when the mouse button is released. The object also generates an ItemDblClick event when the left mouse is double-clicked over an item. If all three events are enabled, they are reported in the order ItemDown, ItemDblClick, ItemUp.

When a parent item is in its retracted state (its children are not visible) it can be expanded to show its children by the user double-clicking its label or by clicking over its button or tree lines. An Expanding event is reported immediately before the children are shown. Similarly, when a parent item is in its expanded state, it can be retracted to hide its children when a Retracting event is reported. You can use the Expanding event to define new children for the object just before they are shown. You can also control the actions of these events using callback functions.

The EditLabels is a boolean property (default 0) that determines whether or not the user may edit the labels which are specified by the Items property.

The SelItems property is a boolean vector that indicates which of the items is currently selected and has the focus. If more items are visible than can fit within the object, a scrollbar is automatically provided. The Index property is a ⎕IO sensitive integer that reports the index number of the first item displayed in the object and changes as the items are scrolled.

Warning: Due to the limitations of the Win32 TreeView object, it is necessary to query the state of each item in a TreeViewin order to obtain the value of the SelItems property, making it a comparatively slow operation if there are a lot of Items.


UpDown Object
Parents Children Properties Methods Events
Purpose: The UpDown object is a pair of arrow buttons used to increment or decrement a value.

Description

An UpDown object is a pair of arrow buttons that the user can click to increment or decrement a value, such as a scroll position or a number displayed in a companion control. The Spinner object is actually a composite object consisting of an UpDown and a companion Edit.


APLVersion Property
Applies To: Root

Description

This is a read-only property that provides information about the Version of Dyalog APL that you are using. It is a 4-element vector of character vectors as described in the table below.

Note: In future releases these values may change, be removed, or new ones added.

Index | Description | Possible Values
[1] Target Environment Windows
Windows-64
Windows Mobile
Linux
Linux-64
AIX
AIX-64
Solaris
Solaris-64
[2] | Version Number
[3] Version Type
W | Windows
S | Server (terminal) version
M | Motif
P | PocketAPL
[4] Program Type Development
Runtime
DLL
DLLRT

Example

      ]display '.'⎕WG 'APLVersion'
┌→───────────────────────────────────────────┐
│ ┌→──────┐ ┌→───────────┐ ┌→┐ ┌→──────────┐ │
│ │Windows│ │13.2.15457.0│ │W│ │Development│ │
│ └───────┘ └────────────┘ └─┘ └───────────┘ │
└∊───────────────────────────────────────────┘


Accelerator Property

Applies To

Description

This property specifies a keystroke that, when pressed by the user, will generate a Select event on an object. It applies to all objects whether or not they posses a "natural" Select event. You can therefore associate a keystroke with an arbitrary action on any object you desire.

The Accelerator property is a 2-element integer vector. The first element is a key number which is the number by which Windows knows the key. The second element is the shift state which is the sum of 1 (Shift key), 2 (Control key) and 4 (Alt key).

For example, to attach the keystroke Ctrl+A to an object, you would set its Accelerator to (65 2). To attach the keystroke Shift+Ctrl+F1 (key number 112), you would set its Accelerator to (112 3). Key numbers may be obtained by displaying the messages generated by the KeyPress event.

Note that a keystroke used as an Accelerator will not generate a KeyPress event.


AcceptFiles Property

Applies To

Description

The AcceptFiles property is Boolean and specifies whether or not an object will accept a file drag/drop operation. Its default value is 0. If set to 1, the object will report a DropFiles event when file icons are dropped on it.


Active Property

Applies To

Description

This property specifies whether or not an object is currently responsive to user actions. It is a single number with the value 0 (object is inactive and does not generate events) or 1 (object is active and capable of generating events). The default is 1.

Setting Active to 0 disables the object (and all its children), even though the object may be referenced in the argument to ⎕DQ. It is therefore possible to deactivate an object from a callback function.

In general, the text associated with an object whose Active property is 0 is displayed in grey.


Align Property

Applies To

Description

For an Animation, the Align property may be 'None' or 'Centre' ('Center'). If Align is 'None', the Animation window is automatically resized to fit the AVI being played. If Align is 'Centre', the AVI is centred in the Animation window. If the window is too small, the AVI is clipped.

For a Button, Menu, or MenuItem the Align property may be 'None', 'Left' or 'Right'. If the Button Style is 'Radio' or 'Check' this property specifies the position of the text relative to the button symbol. The default is 'Right'. For a Button with Style 'Push', the value of Align is 'None'.

For a Button with Style 'Radio' or 'Check' that is created as a child of a Grid the value of the Align property may also be 'Centre' or 'Center'. Either of these values causes the symbol part of the Button (the circle or checkbox) to be centred within the corresponding Grid cell(s).

For a DateTimePicker, the Align property specifies the horizontal alignment of the drop-down Calendar which may be 'Left' (the default) or 'Right'. This applies only if the Style of the DateTimePicker is 'Combo'.

For a Menu , MenuItem, or StatusField, Align 'Right' is used to position the object at the right end of its parent MenuBar or StatusBar. 'None' is equivalent to 'Left' which is the default.

For objects of type CoolBar, Splitter, Scroll, StatusBar, TabBar, ToolBar and ToolControl, Align may be 'None', 'Top', 'Bottom', 'Left' or 'Right'. It specifies to which (if any) of the four sides of the parent the object is anchored and also the default position and size of the object. Specifying Align typically causes the Attach property to be set to appropriate values as follows :

Align | Attach
'Top' | 'Top' 'Left' 'Top' 'Right'
'Bottom' | 'Bottom' 'Left' 'Bottom' 'Right'
'Left' | 'Top' 'Left' 'Bottom' 'Left'
'Right' | 'Top' 'Right' 'Bottom' 'Right'

These settings cause the object to remain at a fixed distance (in pixels) from the corresponding edge of the parent. Furthermore, the object will have a fixed height or width, but its length will stretch and shrink as the Form is resized.

Note that this does not apply to a TabControl for which the default value of Attach is 'None' 'None' 'None' 'None', regardless of the value of Align.

The default value of Align is 'Right' for a vertical Scroll, 'Bottom' for a horizontal Scroll, and 'Top' for a CoolBar, TabBar, TabControl, ToolBar and ToolControl. Furthermore, unless Posn and Size are specified explicitly, the object is placed along the corresponding edge of its parent.

For a Scroll object, Align also determines the direction of a Scroll object unless it is overridden by setting Hscroll or Vscroll directly. If neither Hscroll or VScroll is defined and Align is 'Top' or 'Bottom', a horizontal scrollbar is provided. If neither Hscroll or Vscroll is defined and Align is 'None', 'Left' or 'Right', a vertical scrollbar is provided.

Note

The value of the Align property may only be assigned by ⎕WC and may not be changed using ⎕WS.


AlignChar Property
Applies To: Grid

Description

The AlignChar property specifies a character on which the data displayed in a column of a Grid is to be aligned vertically. It is useful to align columns of numbers that are formatted by the FormatString property. AlignChar may be a scalar or singleton that applies to all columns of the Grid, or a vector with one element per column.

If the data in the column is left-justified, it is aligned using the first occurrence of the alignment character in each cell counting from the left. If the data is right-justified, it is aligned using the first occurrence of the alignment character from the right-hand end of the text.

If the text in a cell does not contain an alignment character, it is aligned as if the alignment character were placed following the last digit.


AlphaBlend Property
Applies To: Form

Description

The AlphaBlend property specifies a level of translucency which allows the area behind a Form to show through.

AlphaBlend is a scalar integer value in the range 0 to 255.

A value of 255 (the default) specifies no translucency, and the Form is entirely opaque obliterating anything behind it.

A value of 0 specifies total translucency and the Form itself is not visible. Furthermore, mouse events over the Form will not be reported by the Form itself but will be passed to any other windows underneath the Form.

Values in between specify varying levels of translucency.


AlwaysShowBorder Property
Applies To: Grid

Description

The AlwaysShowBorder property specifies whether or not the border around the current cell in a Grid is displayed when the Grid loses the focus.

It is a Boolean value with a default value of 1.


AlwaysShowSelection Property
Applies To: Grid ListView TreeView

Description

The AlwaysShowSelection property specifies whether or not the selection remains highlighted when the object loses the focus.

It is a Boolean value with a default value of 1.

If AlwaysShowSelection is 1, the highlight is dimmed. If AlwaysShowSelection is 0, the highlight disappears.


ArcMode Property
Applies To: Circle Ellipse

Description

This property determines how arcs are drawn. Its value is 0, 1 or 2.

0 | only the arc is drawn
1 | arcs define "arc segments", with a single straight line joining the two ends of the arc together
2 | arcs define "pie segments", with lines drawn from the start and end points of the arc to the centre

Note that the segments defined by ArcMode 1 and 2 may be filled (by setting FStyle).


Array Property
Applies To: Clipboard

Description

This property may be used to set or retrieve the contents of the Windows clipboard as a Dyalog APL array.


Attach Property

Applies To

Description

This property specifies how an object responds to its parent being resized. It is a 4-element vector of character vectors which defines how each of the four edges of the object moves in response to a resize request made by the parent. Note that this property is only effective if the value of AutoConf on the parent is 2 or 3 and AutoConf for the object itself is 1 or 3.

The 4 elements of Attach refer to the Top, Left, Bottom and Right edges of the object respectively. Their values may be defined as follows :

Element | Value | Meaning
[1] | 'Top' | top edge of object attached to top edge of parent.
 | 'Bottom' | top edge of object attached to bottom edge of parent.
 | 'None' | top edge of object is not attached to its parent
[2] | 'Left' | left edge of object is attached to left edge of parent
 | 'Right' | left edge of object is attached to right edge of parent
 | 'None' | left edge of object is not attached to its parent
[3] | 'Top' | bottom edge of object is attached to top edge of parent.
 | 'Bottom' | bottom edge of object is attached to bottom edge of parent.
 | 'None' | bottom edge of object is not attached to its parent
[4] | 'Left' | right edge of object is attached to left edge of parent
 | 'Right' | right edge of object is attached to right edge of its parent
 | 'None' | right edge of object is not attached to its parent

If an edge of the object is attached to an edge of its parent, its position in absolute (pixel) terms remains fixed relative to that edge when its parent is resized. Thus if Coord is 'Pixel', the corresponding Posn or Size property of the object remains unaffected by the resize. If Coord has any other value, the value of Posn or Size will change.

If an edge of the object is not attached to its parent, its absolute position (in pixels) will change in proportion to the size change (in the corresponding direction) of its parent. Thus if Coord is 'Pixel',the corresponding Posn or Size property of the object will change as a result of the resize. If Coord has any other value, the value of Posn or Size will be unaffected.

The default value of Attach is ('None' 'None' 'None' 'None'). This causes the object to reposition and resize itself in proportion to its parent.

Some objects have an Align property which, among other things, provides a quick way to set their Attach property. Examining this mechanism may help to further explain how the Attach property works. Setting Align to 'Top' has the effect of setting Attach to ('Top' 'Left' 'Top' 'Right'). Attaching the top edge of the object to the top edge of its parent causes the object to remain at a fixed distance from the top edge of its parent. The additonal measure of attaching its bottom edge to the top edge of its parent causes the height of the object to remain fixed. Attaching the left and right edges of the object to the corresponding edges of its parent causes the object to shrink and expand as the parent is resized horizontally. If you position the object at (0 0) and set its width to be the same as the width of its parent, you have an object that always occupies the entire length of its parent, yet remains of fixed height. This is precisely the behaviour required for a ToolBar or a top Scroll Bar. For further details, see Align property.


AutoArrange Property
Applies To: ListView

Description

The AutoArrange property is Boolean and specifies whether or not the items in a ListView object are automatically re-arranged when a single item is repositioned. Its default value is 0.


AutoBrowse Property
Applies To: OLEClient

Description

This property is retained for backwards compatibility with previous versions of Dyalog APL, but is no longer relevant. Setting it has no effect.


AutoConf Property

Applies To

Description

This property determines what happens to an object when its parent is resized, and how resizing an object affects its children. It may take one of the following values; the default is 3.

0 | Ignore resize by parent.Do not propagate resize to children.
1 | Accept resize by parent.Do not propagate resize to children.
2 | Ignore resize by parent.Do propagate resize to children.
3 | Accept resize by parent.Do propagate resize to children.

If AutoConf is 0 or 2, the object's physical size (in pixels) and position (in pixels) relative to the top left corner of its parent remains unchanged when its parent is resized. If the object has 'Prop' or 'User' co-ordinates, the values of its Posn and Size properties will change as a result.

If AutoConf is 1 or 3, by default, the object is physically reconfigured when its parent is resized such that its relative size and position within its parent remain unchanged. If the object has 'Pixel' co-ordinates, the values of its Posn and Size properties will change as a result. Note that this default processing can be prevented by inhibiting the Configure (31) Event.

If AutoConf is 0 or 1 and the object is resized, either by its parent or directly by the user, it does not attempt to physically reconfigure its children. This means that if the children have 'Prop' or 'User' co-ordinates, the values of their Posn and Size co-ordinates will change as a result.

If AutoConf is 2 or 3 and the object is resized, either by its parent or directly by the user, it propagates a Configure (31) Event to each of its children. By default this means that the object's children will be physically reconfigured so that they maintain their relative positions and sizes within it. If their co-ordinate system is 'Pixel', the values of their Posn and Size properties will change as a result.

Note

Additional or alternative control may be imposed by inhibiting the Configure (31) Event. This can be done either by setting the event's "action" code to ¯1 or by returning a 0 from a callback function attached to it.


AutoExpand Property
Applies To: Grid

Description

This property is a 2-element boolean value that specifies whether or not rows and columns may be added to a Grid object by the user.

If the first element of AutoExpand is 1, a row is added when the current cell is within the last row of the Grid and the user presses Cursor Down

Similarly, if the second element is 1, a column is added when the current cell is within the last column of the Grid and the user presses Cursor Right.

Note that when a row or column is added, the appropriate properties (including Values and CellTypes)are expanded accordingly.

The default value for AutoExpand is (0 0).

If AutoExpand is enabled, the Grid generates AddRow and AddCol events. You can return a zero from a callback function to selectively prevent the addition of rows and columns if appropriate.


AutoPlay Property
Applies To: Animation

Description

Specifies whether or not an AVI clip is played immediately when loaded in an Animation object.

AutoPlay is a single number with the value 0 (the default) or 1. If AutoPlay is 1, the AVI clip is automatically played through once from beginning to end when loaded from a file by the AnimOpen method.


BCol Property

Applies To

Description

This property defines the background colour(s) of an object. For objects with more than one constituent part, it may specify a set of background colours, one for each part. A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities.

If BCol is 0 (which is the default) the background colour is defined by your current colour scheme for the object in question. For example, if you select yellow as your MS-Windows "Menu Bar" colour, you will by default get a yellow background in Menu and MenuItem objects, simply by not specifying BCol or by setting it to 0.

A negative value of BCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

BCol | Colour Element | BCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If BCol is set to ⍬ (zilde), the object is drawn with a transparent background.

If BCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow.

Note that the colour realised depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

For a Button, BCol is only effective if the Style is 'Radio'or 'Check' and is ignored if the Style is 'Push'.

It is recommended that you only use pure background colours in Combo and Edit objects. This is because the text written in these objects cannot itself have a dithered background.

For the Ellipse, Poly and Rect objects, BCol specifies the background colour of the line drawn around the perimeter of the object and is effective only when a non-solid line (LStyle 1-4) is used. It also specifies the colour used to fill the spaces between hatch lines if a hatch fill (FStyle 1-6) is used.


BandBorders Property
Applies To: CoolBar

Description

The BandBorders property specifies whether or not narrow lines are drawn to separate adjacent bands in a CoolBar.

BandBorders is a single number with the value 0 (no lines) or 1 (lines are displayed); the default is 0.

The effect of BandBorders is illustrated below.


BaseClass Property
Applies To: NetType

Description

This property specifies the name of the .Net class upon which the NetType is based. The newly created NetType inherits the properties, methods and events of this class.


Bits Property
Applies To: Bitmap Clipboard Cursor Icon

Description

This property defines the pattern in a Bitmap, Cursor, or Icon object, or the pattern of a bitmap stored in the Windows clipboard.

For a Bitmap, Clipboard or Icon, Bits is an integer matrix each of whose elements represents the colour of the corresponding pixel in the bitmap. The colours are specified as 0-origin indices into the CMap property, which itself defines the complete set of different colours (the colour map) used by the object.

Please note that Bits and CMap may only be used to represent an image with a colour palette of 256 colours or less. If the colour palette is larger, the values of Bits and CMap reported by ⎕WG will be (0 0). For a high-colour image, use Cbits instead.

For a Cursor, Bits is a boolean matrix which specifies the shape of the cursor. For a Cursor and Icon, Bits is used in conjunction with the Mask property.

See CMap for further details.


Border Property

Applies To

Description

This property specifies whether or not an object is displayed with a border around it. It is a single number with the value 0 (no border)1 (Border), or 2. The value 2 applies only to a Form and is used in combination with ('EdgeStyle' 'Dialog') to obtain standard dialog box appearance

For a Form or SubForm, the value of the Border property is only relevant if Sizeable, Moveable, SysMenu, MaxButton and MinButton are all 0.

Note

The value of the Border property may only be assigned by ⎕WC and may not be changed using ⎕WS.


BrowseFor Property
Applies To: BrowseBox

Description

The BrowseFor property is a character vector that specifies the type of resource to be the target of a object.

BrowseFor may be 'Directory' (the default), 'File', 'Computer' or 'Printer'.


BtnPix Property
Applies To: Button Menu MenuItem

Description

This property is used to customise the appearance of a Button, Menu or MenuItem. It specifies the names of or refs to up to 3 Bitmap objects to be used to display the object under different circumstances. In general, BtnPix is a 3-element vector of character vectors or refs. However, if it defines a single Bitmap, it may be a single ref, a simple character scalar or vector, or an enclosed character vector.

The first Bitmap is displayed when the object is shown in its normal state. For a Button, this is when its State is 0. The second Bitmap is used for a Menu or MenuItem, when the object is selected (highlighted), or for a Button when its State is 1. The third Bitmap is used when the object is disabled by having its Active property set to 0.

For a Button with Style 'Push', this means that when the user clicks the Button, its appearance switches from the first to the second Bitmap, and then back again. To maintain the standard 3-D appearance, the Bitmaps should contain the correct shadow lines around their edges. For Buttons with Style 'Radio' or 'Check', the Button will display one or other of the two Bitmaps according to its current State.

For example, to have a Button that displays a "Tick" or a "Cross" according to its State :

      'YES' ⎕WC 'Bitmap' 'C:\WDYALOG\YES.BMP'
      'NO'  ⎕WC 'Bitmap' 'C:\WDYALOG\NO.BMP'
      'f1.r1' ⎕WC 'Button'('Style' 'Check')
                          ('BtnPix' 'YES' 'NO')


Btns Property
Applies To: MsgBox

Description

The Btns property determines the set of buttons to be displayed in a MsgBox. It is a simple vector (one button) or a matrix with up to 3 rows, or a vector of up to 3 character vectors specifying the captions for up to 3 buttons. The buttons are arranged along the bottom of the dialog box in the order specified.

Under Windows, there are restrictions on these buttons. However the property has been designed more generally to be useful under different GUIs and perhaps later revisions of Windows.

Under Windows, the Btns property may specify one of six sets of buttons as follows.

  • 'OK'
  • 'OK' 'CANCEL'
  • 'RETRY' 'CANCEL'
  • 'YES' 'NO'
  • 'YES' 'NO' 'CANCEL'
  • 'ABORT 'RETRY' 'IGNORE'

If any other combination is specified, ⎕WC and ⎕WS will report a DOMAIN ERROR. The names of the buttons are however case-insensitive, so the system will accept 'ok', 'Ok', 'oK' or 'OK'.

If the Btns property is not specified, it assumes a default according to Style as follows :

Style | Btns
'Msg' or 'Info' | 'OK'
'Warn' or 'Error' | 'OK' 'CANCEL'
'Query' | 'YES' 'NO'

If Style is not specified, Btns defaults to 'OK'.


ButtonsAcceptFocus Property
Applies To: ToolControl

Description

This is a Boolean property that determines how the Tab key and other cursor movement keys are handled by a ToolControl object.

If ButtonsAcceptFocus is 0 (the default), when the user presses Tab or Shift+Tab to switch the input focus from another object to the ToolControl, the first ToolButton in the ToolControl receives the input focus and is highlighted. Pressing Tab or Shift+Tab again causes the input focus to move to another control. The cursor movement keys have no effect.

If ButtonsAcceptFocus is 1, when the user presses Tab or Shift+Tab to switch the input focus from another object to the ToolControl, the first or last ToolButton in the ToolControl receives the input focus and is highlighted. Note that the behaviour of Shift+Tab in this case is different. Pressing Tab or Shift+Tab again causes the input focus to move to another control, although if there is no other control to accept the input focus, it moves to the first or last ToolButton as appropriate. Pressing the cursor movement keys causes the input focus to move from one ToolButton to the next.


CBits Property
Applies To: Bitmap Clipboard Icon

Description

The CBits property represents the pixels that make up a picture..

CBits provides an alternative representation to that provided by the Bits and Cmap properties which apply only to images with 256 colours or under. CBits may be used to represent both low-colour and high-colour images.

CBits is a rank-2 numeric array whose dimensions represent the rows and columns of pixels in the image. The values in CBits represent the colour of each pixel and (for an Icon) its transparency.

For a Bitmap, the colour value of each pixel is obtained by encoding the red, green and blue components, i.e.

      PIXEL←256⊥RED GREEN BLUE

where RED, GREEN and BLUE are numbers in the range 0-255.


CMap Property
Applies To: Bitmap Clipboard Cursor Icon

Description

This property defines the table of colours (the colour map) used by a Bitmap or Icon object or by a bitmap stored in the Windows clipboard. Its value is a 3-column integer matrix of numbers in the range 0-255. Each row represents a separate colour which is indexed (0-origin) by values in the Bits property. The 3 columns refer to the intensities of the red, green and blue components of colour respectively.

Please note that Bits and CMap may only be used to represent an image with a colour palette of 256 colours or less. If the colour palette is larger, the values of Bits and CMap reported by ⎕WG will be (0 0). For a high-colour image, use Cbits instead.

When you create a Bitmap or Icon by specifying Bits and CMap, the actual colours you obtain are not necessarily those that you specified. This is partly due to hardware restrictions and partly due to the way in which Windows manages colours. Firstly, your display adapter and driver limit the number of pure colours that can be displayed at any one time and therefore define a maximum size for the colour map. For example, on a standard VGA you are limited to 16 different pure colours (additional ones are provided by dithering).

Secondly, Windows reserves a certain number of colours in the colour map for its own use. When an application requests a new colour (i.e. one that is not already installed in the colour map), MS-Windows either assigns it to a spare entry, or allocates the closest match if the colour map is full. The value of Bits and CMap after ⎕WC reflect the actual colours allocated and may bear little resemblance to the values you assigned to these properties initially.

Note that if you are running 16 colours, MS-Windows reserves all 16 entries in the colour map for its own use. This means that on a 16-colour system, you cannot use any colours other than the default ones reserved by MS-Windows. In practice, the "standard" 16-colour CMap is shown in the following table.

Bits[] | CMap |  |  | Colour
1 | 0 | 0 | 0 | Black
2 | 128 | 0 | 0 | Dark red
3 | 0 | 128 | 0 | Dark Green
4 | 128 | 128 | 0 | Olive Green
5 | 0 | 0 | 128 | Dark Blue
6 | 128 | 0 | 128 | Dark Magenta
7 | 0 | 128 | 128 | Dark Cyan
8 | 128 | 128 | 128 | Dark Grey
9 | 192 | 192 | 192 | Light Grey
10 | 255 | 0 | 0 | Red
11 | 0 | 255 | 0 | Green
12 | 255 | 255 | 0 | Yellow
13 | 0 | 0 | 255 | Blue
14 | 255 | 0 | 255 | Magenta
15 | 0 | 255 | 255 | Cyan
16 | 255 | 255 | 255 | White

Table 24: The default 16-colour CMap

If you are using a 256-colour set-up, the first 9 and the last 7 entries of the 256-colour CMap are the same as the first 9 and last 7 entries of the 16-colour CMap shown above. The intervening entries represent additional colours or are initially unused (0 0 0). New colours that you specify will be allocated to unused entries until the table is full.


CalendarCols Property
Applies To: Calendar DateTimePicker

Description

The CalendarCols property specifies the colours used for various elements in the Calendar object.

CalendarCols is a 6-element integer vector whose elements specify the colours as follows:

[1] | Background colour displayed between months
[2] | Background colour displayed within the month.
[3] | Text colour within a month
[4] | Background colour displayed in the calendar's title
[5] | Colour used to display text within the calendar's title
[6] | Colour used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Each element of CalendarCols may be 0 (which means default colour), a negative singleton that specifies a particular Windows colour, or a 3-element integer vector of RGB values.

Note: At the time of writing, setting the first element of CalendarCols has no effect. Dyalog believes this to be a Windows problem that may be corrected in due course.


Cancel Property
Applies To: Button

Description

This property determines which (if any) Push button in a Form or SubForm is to be associated with the Escape key. It has the value 1 or 0.

Pressing the Escape key will generate a Select event on the Button whose Cancel property is 1, regardless of which object has the keyboard focus.

As only one button in a Form or SubForm can be the Cancel button, setting Cancel to 1 for a particular button automatically sets Cancel to 0 for all others in the same Form.


Caption Property

Applies To

Description

The Caption property is a character vector specifying fixed text associated with the object. For example, Caption defines the label on a Button, the title of a Form, SubForm or MsgBox, the heading in a Group, and the text of a Menu or a MenuItem.

For the Root object, Caption specifies the text displayed when Alt+Tab is used to switch to the Dyalog APL/W application. It may be used in conjunction with the IconObj property which specifies the name of an Icon object to be displayed alongside this text.

Its default value is an empty vector.


CaseSensitive Property
Applies To: ComboEx

Description

Specifies whether or not string searches in the items displayed by a ComboEx object will be case sensitive. Searching occurs when text is being typed into the edit box portion of the ComboEx


CellFonts Property
Applies To: Grid

Description

This property specifies the font objects to be used to display the Values in a Grid object.

CellFonts is either a single ref or a simple character vector, or a vector of refs or character vectors. If it specifies a single font object this will be used to draw the text in all of the cells in the Grid. If it specifies more than one font object, these are mapped to individual cells through the CellTypes property.


CellHeights Property
Applies To: Grid

Description

This property specifies the height of each row in a Grid object in the units specified by its Coord property. It may be a scalar or a vector whose length is the same as the number of rows implied by the Values property. If it is a scalar, it specifies a constant row height. If it is a vector it specifies the height of each row individually.


CellSelect Property
Applies To: Grid

Description

The Grid supports the selection of a contiguous block of cells by the user, using the mouse and/or the keyboard. The ability to select a range of cells is determined by the CellSelect property. This may be a character vector or a vector of character vectors comprising the following :

'Rows' | User may select an entire row by clicking on a row title and may select multiple rows by dragging the mouse over contiguous row titles.
'MultiRows' | Same as 'Rows', but user may additionally select several non-contiguous rows and blocks of rows using the Ctrl key.
'Columns' | User may select an entire column by clicking on a column title and may select multiple columns by dragging the mouse over contiguous column titles.
'MultiColumns' | Same as 'Columns', but user may additionally select several non-contiguous columns and blocks of columns using the Ctrl key.
'Partial' | User may select any rectangular block of cells by either dragging the mouse or using Shift+cursor keys.
'MultiPartial' | Same as 'Partial', but user may additonally select multiple rectangular blocks of cells using the Ctrl key.
'Whole' | User may select the entire Grid by clicking in the space to the left of the column titles and above the row titles.
'Any' | Same as ('Rows''Columns''Partial''Whole'). This is the default.
'Multi' | Same as ('MultiRows''MultiColumns''MultiPartial''Whole').
'None' | User may not select any cells in the Grid.

For example, the following expression would allow the user to select only whole rows and columns:

      gridname ⎕WS 'CellSelect' ('Rows' 'Columns')

Setting CellSelect to ('Rows' 'Columns' 'Whole' 'Partial') is equivalent to setting it to 'Any'.

When the user performs a selection , the Grid generates a GridSelect event.

The range of cells currently selected is given by the SelItems property. You can obtain the current selection by querying this property with ⎕WG and you can set it with ⎕WS.

Note that the user may delete the contents of the selected range, or cut and copy them to the clipboard by pressing Delete, Shift+Delete or Ctrl+Insert respectively. The user may also replace the current selection with the contents of the clipboard by pressing Shift+Insert. These operations generate GridDelete, GridCut, GridCopy and GridPaste events which you may disable (by setting the event action code to ¯1 or to which you may attach a callback function.

If more than one block of cells has been selected, these operations are honoured only if the blocks begin and end on the same rows or begin and end on the same columns. If so, the data placed in the clipboard is the result of joining the blocks horizontally or vertically as appropriate.

You can also invoke these events as methods. This allows you to attach these actions to MenuItems and Buttons. For example, the following expression could be used to implement Cut as a MenuItem:

      name ⎕WC 'MenuItem' 'Cu&t'('Event' 'Select' '⍎gridname.GridCut')

In addition to the ability to copy blocks of cells through the clipboard, the user may also drag a block of cells from one part of the Grid to another.

When the user places the mouse pointer over any of the four edges of a selected block of cells, the cursor changes from a cross to a n arrow pointer. The user may now drag the border of the selected block to a new location. If the Ctrl key is pressed at the same time, the contents of the selected cells are copied to the new location. If not, the operation is a move and the original block of cells is cleared (emptied). In either case, the contents of the original block replace the contents of the target block (marked by the dragging rectangle) and the target block become selected. You may only move or copy a single block of cells in this way.

These operations generate a GridDropSel event. You may prevent the user from moving and copying blocks of cells by disabling this event (by setting its event action code to ¯1) or you may control these operations selectively with a callback function. Note that although the operation of inserting cells (using Ctrl+Shift) has not been implemented, you may provide this facility yourself with the information provided by the event message.

You may also move or copy a block of cells (which need not necessarily be selected) under program control by calling GridDropSel event as a method.


CellSet Property
Applies To: Grid

Description

This property identifies which cells in a Grid are set (i.e. have values) and which are empty. Its purpose is to allow large numeric matrices containing blank cells to be displayed and edited efficiently.

The CellSet property is a boolean matrix with the same shape as the Values property. If an element of CellSet is 0, the cell is defined to be empty. Empty cells are displayed as blank and the cell contents by the Values property are ignored.

A more direct way to handle empty cells is to set the corresponding elements of Values to empty vectors. However, if Values is otherwise entirely numeric, this makes the array nested when it would otherwise be simple. For large numeric matrices, this penalty can be severe. For example, a 100x100 array of 2-byte integer values occupies about 20Kb of workspace. Setting one or more elements of the array to an empty vector increases its size to 200Kb. However, because it is boolean, the size of the CellSet property for a 100x100 array is only 1.27Kb and represents a significant saving of space.

Note that if the Values property contains text and is therefore nested anyway, the CellSet property is not helpful in conserving workspace, although it may still be useful to separate empty cells from real data.

You can dynamically change a single element of CellSet using the SetCellSet method.


CellTypes Property
Applies To: Grid

Description

This property specifies the type of each cell in a Grid object. It is a matrix whose elements are indices into other property arrays (FCol, BCol, CellFonts and Input).

For example, if CellTypes[1;1] is 3, the first cell in the Grid is displayed using the foreground colour specified by the 3rd element of FCol, the background colour specified by the 3rd element of BCol, and so forth. Note however that scalar property arrays are extended if necessary. Therefore if you require 5 different foreground colours but only one background colour, BCol need specify only a single colour.

You can dynamically change a single element of CellTypes using the SetCellType method.


CellWidths Property
Applies To: Grid

Description

This property specifies the width of each column in a Grid object in the units specified by its Coord property. It may be a scalar or a vector whose length is the same as the number of columns implied by the Values property. If it is a scalar, it specifies a constant column width. If it is a vector it specifies the width of each column individually.


Changed Property
Applies To: ButtonEdit Edit PropertyPage RichEdit Spinner

Description

The Changed property, in conjunction with the Change event, provides the means to control the validation of an object after the user has finished interacting with it.

Initially, the value of the Changed property of an object is set to 0. When the user gives the focus to the object and causes either the Text or (in the case of a Spinner) the Thumb property to be altered, the Changed property is immediately set to 1. When the object loses the input focus and the value of the Changed property is 1, the object generates a Change event. The value of the Changed property is then determined as follows:

If there is no callback function attached to the Change event, or if the Change event is disabled, the Changed property is reset to 0.

If an attached callback returns no result or returns 1, the Change property is reset to 0.

If an attached callback function returns 0, the Changed property is not altered and remains set to 1. The object will therefore generate another Change event when the user next tries to leave it, even if the text and/or Thumb are not altered this time.

Note that the object generates a Change event when it loses the focus only if the value of the Changed property is 1 at the time.


CharFormat Property
Applies To: RichEdit

Description

The CharFormat property describes or applies formatting to the currently selected text in a RichEdit object. If the selection is empty, it reports or specifies the default character formatting for the object. It is a 5-element nested array structured as follows:

[1] A vector of character vectors which describes the text attributes and is comprised of the following keywords:
'Autocolour' | default colour (Windows text colour)
'Bold' | bold text
'Italic' | bold text
'Underline' | underlined
'StrikeOut' | line through text
'Protected' | protected (read-only) text
[2] | A character vector that specifies the face name of the font used to draw the text
[3] | Character height in Twips.
[4] | Text colour. A single integer or an enclosed vector of 3 RGB values. The default is 0 which implies the standard Windows text colour.
[5] | Integer specifying the vertical offset of the character from the base line in Twips. This is used to specify superscript (positive offset) and subscript (negative offset) symbols. The default value is 0.

When you set the character format using ⎕WC or ⎕WS the following rules apply.

If you just want to set a single text attribute (element 1) you may specify a simple vector, for example (⎕WS 'CharFormat' 'Protected') is valid and will add the protected text attribute to the current set of text attributes.

To unset a text attribute (element 1) you must insert the tilde (~) character before the name of the attribute. For example, the expression (⎕WS 'CharFormat' '~Bold') will turn the bold text attribute off.

You need only specify the number of elements required, but you must insert proper values for the elements you wish to remain unaltered. However, you may use '' in the first element to leave the text attributes unchanged.

If there is no text selected, CharFormat specifies the default character format, i.e. the format that will be used to draw the next (and subsequent) characters that the user enters. If there is text selected it specifies the format of the selected block of text. If the format is not strictly homogeneous, ⎕WG may report the format of the first character in the selected block, or, if the block contains characters which use completely different fonts, the result of (⎕WG 'CharFormat') will be empty.

(⎕WS 'CharFormat' ...) will set the format of the currently selected block of text. To set the format of an arbitrary block of text you must select it first using (⎕WS 'SelText' ...).


CharSet Property
Applies To: Font

Description

This property applies to the Classic Edition only. In the Unicode Edition, its value is ignored.

CharSet is an integer that specifies the character encoding of the Font object.

The following table illustrates some of the character set encodings supported by Windows. Note that this set may vary according to the edition of Windows that is installed.

Language | CharSet
Western (Ansi) | 0
Hebrew | 177
Arabic | 178
Greek | 161
Turkish | 162
Baltic | 186
Central European | 238
Cyrillic | 204
Vietnamese | 163

Windows fonts typically contain glyphs for the ASCII character set in their first 128 positions, and glyphs for the Western European character set in positions 129-256. Additional sets of character glyphs are stored in positions 257 onwards in what are sometimes referred to as codepages.

When you change the character set encoding, to (say) Greek (161), the set of Greek characters are mapped into the top 128 positions of the font.

For example, if the CharSet is 0 (ANSI), the character code Hex EC is displayed as ì (i-grave). However, if you change CharSet to 161 (Greek), the same character code is displayed as the Greek µ.

The following example illustrates how the character string 'ôï üíïìá ìïõ Ýéíáé Ðåôå' appears differently according to the value of CharSet.

      'F'⎕WC'FORM' 'CharSet Property'('Size' 300 400)('Coord' 'Pixel')
      F.Coord←'Prop'

      'F.F1'⎕WC'Font' ('Size' 32) ('CharSet' 0)
      'F.F2'⎕WC'Font' ('Size' 32) ('CharSet' 161)
      'F.F3'⎕WC'Font' ('Size' 32) ('CharSet' 178)

      STRING←'ôï üíïìá ìïõ Ýéíáé Ðåôå'

      'F.E1'⎕WC'Edit'STRING(10 10)(⍬ 80)('Font' 'F.F1')
      'F.E2'⎕WC'Edit'STRING(40 10)(⍬ 80)('Font' 'F.F2')('Translate' 'ANSI')
      'F.E3'⎕WC'Edit'STRING(70 10)(⍬ 80)('Font' 'F.F3')('Translate' 'ANSI')

Note that setting Translate to 'ANSI' means that characters entered into the Edit fields using a corresponding National Language keyboard (Greek and Arabic) will appear in that language as intended


CheckBoxes Property
Applies To: ListView TreeView

Description

The CheckBoxes property specifies whether or not check boxes are displayed alongside items in a ListView or TreeView object.

CheckBoxes is a single number with the value 0 (check boxes are not displayed) or 1 (check boxes are displayed); the default is 0.

For a TreeView, CheckBoxes will only be honoured if the items have pictures associated with them (via the ImageListObj and ImageIndex properties).

For a ListView, CheckBoxes applies to all settings of the View property.

The GetItemState method can be used to determine if a specific item in a ListView or TreeView is checked. The result of the method will have the 13th bit set if the item is checked.

      STATE←Form.ListView.GetItemState 11
      13⊃⌽(32⍴2)⊤STATE
1

The picture below illustrates the effect on the appearance of a ListView object, of setting CheckBoxes to 1.


Checked Property
Applies To: MenuItem

Description

This property determines whether or not a check mark is displayed alongside the text in a MenuItem. It is a single number with the value 0 (not checked) or 1 (checked). The default is 0.


ChildEdge Property
Applies To: CoolBand

Description

The ChildEdge property specifies whether or not the CoolBand leaves space above and below its child window.

ChildEdge is a single number with the value 0 (no space) or 1 (space is provided); the default is 0.

The following pictures illustrate the effect of the ChildEdge property.


ChildList Property

Applies To

Description

This is a read-only property that reports the names of those objects that may be created as children of the object in question. It is a vector of character vectors in which the order of the items is not significant.


CircleToday Property
Applies To: Calendar DateTimePicker

Description

The CircleToday property specifies whether or not a circle is drawn around the Today date in a Calendar object or in the drop down calendar in a DateTimePicker, when the month containing that date is visible.

CircleToday is a single number with the value 0 (a circle is not drawn) or 1 (a circle is drawn); the default is 1.

See also HasToday property.


ClassID Property
Applies To: ActiveXControl OCXClass OLEClient OLEServer

Description

The ClassID property specifies the class identifier (usually abbreviated to CLSID) of an APL object that is used to represent a COM object. The CLSID is a globally unique identifier (GUID) that uniquely identifies the object.

When you create or recreate an ActiveXControl or OLEServer using ⎕WC, you may specify ClassID. This allows you to re-use a value that was previously allocated to that control by the system. However, you should not specify any other value because that value could be allocated now or in the future to another object on any other computer in the world. Otherwise, a new ClassID is automatically allocated by the system.

Note that the CLSID is not actually recorded on your computer (in the registry) until you register it using )SAVE or Make OCX, or by executing the OLERegister method.


ClassName Property
Applies To: ActiveXControl OCXClass OLEClient OLEServer

Description

For an OLEClient, the ClassName property specifies the name of the OLE object to which an OLEClient object named by the left argument of ⎕WC is to be connected. Similarly, for a NetControl the ClassName property specifies the name of the .Net class to be instantiated. Note that ClassName is mandatory for ⎕WC and may not subsequently be changed using ⎕WS.

For an ActiveXControl or OLEServer, ClassName specifies the external name with which the object is registered, and by which it is referenced by other applications.

For an ActiveXControl, the external name is "Dyalog xxx Control, where xxx is the value of the ClassName property, or, if ClassName is not specified, the name of the ActiveXControl namespace.

For an OLEServer, the external name is "Dyalog.xxx" where xxx is derived in the same way.

For a NetControl, the external name is the name of the .Net class which must be expressed relative to a corresponding element of ⎕USING. For example, to load one of the standard .Net controls:

      ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'


ClipCells Property
Applies To: Grid

Description

This property determines whether or not the Grid displays partial cells. The default is 1. If you set ClipCells to 0, the Grid displays only complete cells and automatically fills the space between the last visible cell and the edge of the Grid with the GridBCol colour.

The first picture below shows a default Grid (ClipCells is 1) in which the third column of data is in fact incomplete (clipped), although this is by no means apparent to the user. The second picture shows the effect on the Grid of setting ClipCells to 0 which prevents such potential confusion.


ColLineTypes Property
Applies To: Grid

Description

This property specifies the appearance of the vertical grid lines in a Grid object.

ColLineTypes is an integer vector, whose length is normally equal to the number of columns in the Grid. Each element in ColLineTypes specifies an index into the GridLineFCol and GridLineWidth properties, thus selecting the colour and width of the vertical grid lines.

For example, if ColLineTypes[1] is 3, the first vertical grid line in the Grid is displayed using the colour specified by the 3rd element of GridLineFCol, and the width specified by the 3rd element of GridLineWidth.

Note that ColLineTypes is not ⎕IO dependant, and the value 0 is treated the same as the value 1; both selecting the first colour and line width specified by GridLineFCol and GridLineWidth respectively

The default value of ColLineTypes is an empty numeric vector (⍬). If so, all vertical grid lines are drawn using the first element of GridLineFCol and GridLineWidth.

A vertical grid line is drawn down the right edge of its associated column. One pixel is drawn inside the column of cells; additional pixels (if any) are drawn between that column of cells and the next one to its right.


ColSortImages Property
Applies To: Grid

Description

The ColSortImages property identifies the names of, or refs to, up to three Bitmap objects that are used to specify the sort images for a Grid object.

If ColSortImages is not specified, default images are used.

The Bitmap specified by the 1st element of ColSortImages is used to display columns that are sorted down.

The Bitmap specified by the 2nd element of ColSortImages is used to display columns that are unsorted.

The Bitmap specified by the 3rd element of ColSortImages is used to display columns that are sorted up.

'F'⎕WC'Form' 'Grid: ColSortImages Property'
 F.(Coord Size)←'Pixel'(313 341)
 'F.fnt'⎕WC'Font' 'APL385 Unicode' 16
 F.FontObj←F.fnt
 BK←16 16⍴256⊥White←255 255 255

 'F.gu'⎕WC'Bitmap'('CBits'BK)('MaskCol'White)
 'F.gu.'⎕WC'Text' '⍋'(0 3)
 'F.gd'⎕WC'Bitmap'('CBits'BK)('MaskCol'White)
 'F.gd.'⎕WC'Text' '⍒'(0 3)

 'F.G'⎕WC'Grid'('Posn' 0 0)F.Size
 F.G.Values←#.(COUNTRIES,POPULATION,[1.5]AREA)
 F.G.ColTitles←'Country' 'Population' 'Area'
 F.G.CellWidths←140 100 100
 F.G.TitleWidth←0

 F.G.ColSortImages←'F.gd' '' 'F.gu'
 F.G.(Values←Values[⍋Values[;3];])

 F.G.ColSorted 3 1


ColTitle3D Property
Applies To: ListView

Description

The ColTitle3D property is a boolean value that specifies whether or not the column titles in a ListView object are displayed with a 3-dimensional effect. Its default value is 1. A column heading with a 3-dimensional button appearance may be used to imply that the user may click on it to sort by the values in that column.

ColTitle3D is only relevant if View is 'Report' and Header is 1. Note that this property may only be set by ⎕WC and may not subsequently be changed using ⎕WS.


ColTitleAlign Property
Applies To: Grid ListView

Description

The ColTitleAlign property specifies the alignment of column titles. For a ListView object this is only relevant only when the View property is set to 'Report'. ColTitleAlign is either a simple character vector, or a vector of character vectors with one element per column.

For a Grid, ColTitleAlign may be:'Top', 'Bottom', 'Left', 'Right', 'Centre', 'TopLeft', 'TopRight', 'BottomLeft', or 'BottomRight'.

For a ListView object, ColTitleAlign may be 'Left', 'Right' or 'Centre'. Also, for a ListView the column data itself is aligned likewise. Note that the first column in a ListView is always left-aligned regardless of the setting of ColTitleAlign. This is a Windows restriction.

Note that both spellings 'Centre' and 'Center' are accepted.


ColTitleBCol Property
Applies To: Grid

Description

The ColTitleBCol property specifies the background colour of the column titles in a Grid object

ColTitleBCol may be a scalar that specifies a single background colour to be used for all of the column titles, or a vector that specifies the background colour of each of the column titles individually. An element of ColTitleBCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see Bcol for details). Its default value is 0 which obtains the colour defined for Button Face.


ColTitleDepth Property
Applies To: Grid

Description

ColTitleDepth specifies the structure of a set of hierarchical column titles. It is an integer vector with the same length as the ColTitles property. A value of 0 indicates that the corresponding element of ColTitles is a top-level title. A value of 1 indicates that the corresponding title is a sub-title of the most recent title whose ColTitleDepth is 0; a value of 2 indicates that the corresponding title is a sub-title of the most recent title whose ColTitleDepth is 1, and so forth. For example:

      'F'⎕WC'Form'('Coord' 'Pixel')('Size' 200 498)
      'F'⎕WS'Caption' 'Hierarchical Column Titles'
      'F.G'⎕WC'Grid'(?10 12⍴100)(0 0)(200 498)
      'F.G'⎕WS('TitleWidth' 0)('TitleHeight' 60)
      'F.G'⎕WS'CellWidths' 40

      Q1←'First Quarter' 'Jan' 'Feb' 'Mar'
      Q2←'Second Quarter' 'Apr' 'May' 'Jun'
      Q3←'Third Quarter' 'Jul' 'Aug' 'Sep'
      Q4←'Fourth Quarter' 'Oct' 'Nov' 'Dec'

      CT←(⊂'1995'),Q1,Q2,Q3,Q4
      CD←0,16⍴1 2 2 2

      'F.G'⎕WS('ColTitles'CT)('ColTitleDepth'CD)

Note that the LockColumns method is not supported in combination with hierarchical column titles.


ColTitleFCol Property
Applies To: Grid

Description

The ColTitleFCol property specifies the colour of the column titles in a Grid object

ColTitleFCol may be a scalar that specifies a single colour to be used for all of the column titles, or a vector that specifies the colour of each of the column titles individually. An element of ColTitleFCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Button text.


ColTitles Property
Applies To: Grid ListView

Description

This property specifies the headings that are displayed above the columns in a Grid object. If specified, it must be a vector of character vectors or matrices whose length is the same as the number of columns implied by the Values property. The default value of ColTitles is an empty character vector. In this case, the system displays "standard" spreadsheet column titles A-Z, AA-AZ, BA-BZ and so forth.

To disable the display of column titles in a Grid, you should set the TitleHeight property to 0.


Collate Property
Applies To: Printer

Description

Specifies whether or not multiple copies of printer output are collated.

Collate is a single number with the value 0 or 1. If Collate is 1, multiple copies of output are collated separately. If Collate is 0, copies are uncollated on output.

Collate is ignored unless Copies is >1.

The default value for Collate is derived from the current printer setting and Collate is only effective if the printer supports this capability.


ColorMode Property
Applies To: Printer

Description

Specifies whether or not printing is done in colour.

ColorMode is a single number with the value 0 or 1. If ColorMode is 1, printing is done in colour. If ColorMode is 0, printing is done using black ink only.

This property only applies to colour printers.


ColumnWidth Property
Applies To: List

Description

This property specifies the column width in pixels of a multi-column List object. See MultiColumn property for details.


Container Property
Applies To: ActiveXControl

Description

The Container property is a read-only property whose value is the ⎕OR of an ActiveXContainer object that represents the ActiveX Site object of the application that is hosting the ActiveXControl.

The value of Container may be converted to a namespace using ⎕NS or ⎕WC.

The resulting object may then be used to obtain the values of ambient properties, or to access methods exposed by the host application via OLE interfaces. See OLEQueryInterface.


Coord Property

Applies To

Description

This property defines an object's co-ordinate system. It is a character string with one of the following values; 'Inherit', 'Prop', 'Pixel', 'User' or 'Cell'(graphics children of a Grid only).

If Coord is 'Inherit', the co-ordinate system for the object is inherited from its parent. Note that the default value of Coord for the system object '.'is 'Prop', so by default all objects created by ⎕WC inherit 'Prop'.

If Coord is 'Prop', the origin of the object's parent is deemed to be at its top left interior corner, and the scale along its x- and y-axes is 100. The object's position and size (Posn and Size properties) are therefore specified and reported as a percentage of the dimensions of the parent object, or, for a Form, of the screen.

If Coord is 'Pixel', the origin of the object's parent is deemed to be at its top left interior corner, and the scale along its x- and y-axes is measured in physical pixel units. The object's size and position (Posn and Size properties) are therefore reported and set in physical pixel units. If you set Coord on the system object to 'Pixel', the value of its Size property gives you the resolution of your screen, e.g. (480,640). Note that pixels are numbered from 0 to (Size -1).

If Coord is 'User', the origin and scale of the co-ordinate system are defined by the values of the YRange and XRange properties of the parent object. Each of these is a 2-element numeric vector whose elements define the co-ordinates of top left and bottom right interior corners of the (parent) object respectively.

Note that if Coord is 'User' and you change the values of YRange and/or XRange of the parent, the object (and all its siblings with Coord 'User') are redrawn (and clipped) according to the new origin and scale defined for the parent. The values of their Posn, Size and Points properties are unaffected. Changing YRange and/or XRange therefore provides a convenient and efficient means to "pan and zoom".

The Coord property for graphic objects created as a children of a Grid may also be set to Cell. Apart from being easier to compute, a graphic drawn using cell coordinates will expand and contract when the grid rows and columns are resized.

Example:

This statement creates a button 10 pixels high, 20 pixels wide, and 5 pixels down and along from the top-left corner of the parent Form.

      'TEST.B1'⎕WC'Button' 'OK'(5 5)(10 20)('Coord' 'Pixel')

If you set Coord to 'Pixel' in the Root object '.', then query its Size, you get the dimensions of the screen in pixels, i.e.

      '.' ⎕WS 'Coord' 'Pixel'
      '.' ⎕WG 'Size'
480 640


Copies Property
Applies To: Printer

Description

Specifies the number of copies to be printed.

Copies is a non-zero scalar integer value whose default is defined by the current printer settings.


Cue Property
Applies To: ButtonEdit Edit

Description

This property specifies optional text to be displayed when a ButtonEdit or an Edit object is empty. For an Edit object it applies only if the Style of the Edit object is 'Single'.

Note that this feature only apples if Native Look and Feel is enabled.

The Boolean property ShowCueWhenFocused determines whether or not the cue should also be displayed once the user has tabbed into or clicked on the input field (and thus given it the focus).

Example

      'F' ⎕WC 'Form' 'Cue Property'
      'F.E' ⎕WC 'Edit'
       F.E.Cue←'Enter Password'


CurCell Property
Applies To: Grid

Description

This property specifies or reports the current cell in a Grid object. The current cell is the one that is currently addressed by the user. The current cell is identified visibly if it has an associated object, other than an external. Label object.


CurrentColor Property
Applies To: ColorButton

Description

The CurrentColor property is a 3-element integer vector that specifies and reports the RGB value of the currently selected colour in a ColorButton object. Its default value is (0 0 0) which is black.


CurrentState Property
Applies To: TCPSocket

Description

The CurrentState property is a read-only property that reports the current state of a TCPSocket object. Its possible values and their means are as follows:

CurrentState | Description
'Open' | a client socket that is not yet connected or a UDP socket
'Bound' | a server socket that has been bound
'Listening' | a server socket to which a client has not yet connected
'Connected' | a client or server socket that is connected
'IhaveClosed' | a temporary state on the way to Closed
'PartnerHasClosed' | a temporary state on the way to Closed
'Closed' | a socket that has been closed by both client and server


CursorObj Property

Applies To

Description

This property is used to associate a particular cursor with an object. Its value is either a simple scalar number which specifies a standard Windows cursor, or the name of, or ref to, a Cursor object. The standard Windows cursors are :

0 | arrow (Windows default)
1 | hourglass
2 | crosshair
3 | I-Beam
4 | crossing vertical/horizontal double-headed arrows
5 | diagonal double-headed arrows (left-to-right)
6 | vertical double-headed arrows
7 | diagonal double-headed arrows (right-to-left)
8 | horizontal double-headed arrows
9 | upward pointing arrow
10 | box
11 | crossing vertical/horizontal double-headed arrows
12 | no-entry sign
13 | arrow with hourglass

If CursorObj is set to anything other than an empty vector (which is the default) it defines the appearance of the cursor when the mouse pointer is moved into the object. If CursorObj is an empty vector, the shape of the cursor remains unchanged when the mouse pointer enters the object. In effect, the cursor is "inherited" from its parent. Exceptions to this rule are certain objects which have special cursors by default.

If the value of CursorObj for the Root object is set to anything other than an empty vector, it applies to all Forms and their children, irrespective of their own CursorObj values. Therefore, if you want to indicate that your application is "working" and is not responsive to input, you can simply do :

      '.' ⎕WS 'CursorObj' 1 ⍝ Hourglass cursor

Then to reset the application you do :

      '.' ⎕WS 'CursorObj' ''


CustomColors Property
Applies To: ColorButton

Description

The CustomColors property is a 1-row, 16-column nested matrix which specifies the RGB values of the colours displayed in the Custom colors section of the Windows colour selection dialog box when displayed by a ColorButton object.

Each element of CustomColors is a 3-element integer vector specifying an RGB colour value.

By default, each element of CustomColors is (0 0 0). If the user selects a new custom colour from the Windows colour selection dialog box, its value will be reported by CustomColors. CustomColors must always have shape (1 16).

Note that CustomColors is maintained separately for each separate ColorButton, and CustomColors defaults to (1 16⍴⊂0 0 0) for each new ColorButton that you create. If you want to maintain a global custom colour table for your application, you must do this yourself.

Note that the Pocket PC 2002 colour selection dialog box does not provide the facility to select custom colours, so this functionality is not available in PocketAPL.


CustomFormat Property
Applies To: DateTimePicker

Description

Specifies a custom format for the date/time display in a DateTimePicker.

CustomFormat is a character vector that may contain a mixture of date/time format elements and body text. The date/time elements are replaced by the actual date/time values when the object is displayed. The body text is displayed as-is. Note that CustomFormat may only be specified when the DateTimePicker object is created.

The date/time elements are defined by the following groups of characters, notice that they are case-sensitive:

Element | Description
d | The one- or two-digit day.
dd | The two-digit day. Single-digit day values are preceded by a zero.
ddd | The three-character weekday abbreviation.
dddd | The full weekday name.
h | The one- or two-digit hour in 12-hour format.
hh | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H | The one- or two-digit hour in 24-hour format.
HH | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m | The one- or two-digit minute.
mm | The two-digit minute. Single-digit values are preceded by a zero.
M | The one- or two-digit month number.
MM | The two-digit month number. Single-digit values are preceded by a zero.
MMM | The three-character month abbreviation.
MMMM | The full month name.
t | The one-letter AM/PM abbreviation (that is, AM is displayed as "A").
tt | The two-letter AM/PM abbreviation (that is, AM is displayed as "AM").
yy | The last two digits of the year (that is, 1996 would be displayed as "96").
yyyy | The full year (that is, 1996 would be displayed as "1996").

The body text is defined by sub-strings contained within single quotes. For example, to display the current date with the format "Today is: 04:22:31 Tuesday Mar 23, 1996", the format string is defined as follows:

      CustomFormat
'Today is: 'hh':'m':'s dddd MMM dd', 'yyyy

To include a single quote in your body text, use two consecutive single quotes. For example, to produce output that looks like: "Don't forget Mar 23, 1996", CustomFormat should be specified as follows:

        CustomFormat
'Don''t forget' MMM dd',' yyyy

Note: Non format characters that are not delimited by single quotes will result in unpredictable display by the DateTimePicker object.


Data Property

Applies To

Description

This property allows you to associate arbitrary data with an object. The value of the Data property may be any APL array.


DateTime Property
Applies To: DateTimePicker

Description

Specifies the value of date/time in a DateTimePicker.

The DateTime property represents the date and time value that is currently displayed in a DateTimePicker object.

It is normally a 4-element integer vector containing the date (as an IDN), hour, minutes and seconds respectively.

However, if the checkbox shown in the object is unset (see HasCheckBox), the value of DateTime will be ⍬ (zilde).


DblClickToggle Property
Applies To: CoolBar

Description

The DblClickToggle property specifies whether or not the user must single-click or double-click to toggle a child CoolBand between its maximised or minimised state.

DblClickToggle is a single number with the value 0 (single-click toggles state) or 1 (double-click toggles state); the default is 0.


Decimals Property
Applies To: ButtonEdit Edit Label Spinner

Description

This property specifies the number of decimal places to which a number is to be displayed in an Edit or Label object with FieldType 'Numeric'. For an Edit object, Decimals also specifies the maximum number of digits that the user may enter after a decimal point.

The default value of decimals is ¯1 which allows any number of decimal places to be entered.


Default Property
Applies To: Button MsgBox

Description

This property determines which of a set of push buttons in a Form, SubForm or MsgBox is the default button.

In a Form or SubForm, the Default Button will generate a Select event (30) when the user presses the Enter key, even though the Default Button may not have the focus at the time.

If however, the user explicitly shifts the focus to another Push Button, the automatic selection of the Default Button is disabled and the Enter key applies to the Button with the focus.

For a Button, the Default property has the value 1 or 0. As only one Button can be the Default Button, setting Default to 1 for a particular Button automatically sets Default to 0 for all others with the same parent.

In a MsgBox, Default specifies which button initially has the focus. It has the value 1, 2 or 3 corresponding to the three buttons that can be defined. See Btns property for further details.


DefaultColors Property
Applies To: ColorButton

Description

The DefaultColors property is a nested matrix which specifies the RGB values of the colours shown in the colour selection drop-down displayed by a ColorButton object.

The shape of DefaultColors determines the number of rows and columns in the colour selection drop-down.

Each element of DefaultColors is a 3-element integer vector specifying an RGB colour value.


Depth Property
Applies To: TreeView

Description

The Depth property specifies the structure of the items in a TreeView object. It is either a scalar 0 or an integer vector of the same length as the Items property.

A value of 0 indicates that the corresponding item is a top-level item. A value of 1 indicates that the corresponding item is a child of the most recent item whose Depth is 0; a value of 2 indicates that the corresponding item is a child of the most recent item whose Depth is 1, and so forth. For example:

AIRPORTS | DEPTH | Description
Europe | 0 | Top-level (root) item
UK | 1 | 1st sub-item of Europe
London Heathrow | 2 | 1st sub-item of UK
London Gatwick | 2 | 2nd sub-item of UK
Manchester | 2 | 3rd sub-item of UK
France | 1 | 2nd sub-item of Europe
Paris CDG | 2 | 1st sub-item of France
Americas | 0 | Top-level (root) item
USA | 1 | 1st sub-item of N.America
California | 2 | 1st sub-item of USA
Los Angeles | 3 | 1st sub-item of California
San Francisco | 3 | 2nd sub-item of California
East Coast | 2 | 2nd sub-item of USA
New York | 3 | 1st sub-item of East Coast
Kennedy | 4 | 1st sub-item of NY
La Guardia | 4 | 2nd sub-item of NY

      'F'⎕WC'FORM' 'International Airports'
      'F.TV'⎕WC'TreeView'AIRPORTS(0 0)(100 100)('Depth'DEPTH)


DevCaps Property
Applies To: Printer Root

Description

This property reports the device capabilities of the screen or printer. It is a 3-element nested vector as follows :

[1] | Height and Width:2-element numeric vector of device in pixels
[2] | Height and Width:2-element numeric vector of device in mm
[3] | Number of colours:integer scalar

This property is useful if you want to make objects of a specific physical size. For example, to draw a 10mm square in a Form 'F' at (5,5):

      Size ← 10 × ⊃÷/2↑'.' ⎕WG 'DevCaps'
      'F.R' ⎕WC 'Rect' (5 5) Size ('Coord' 'Pixel')

Note that new elements may be added to DevCaps in a future release.

Please note that the physical size reported for the screen is typically only a nominal size, because, if you use a generic video driver, Windows has no way to tell that you have a 14", 15" or 17" screen attached to your computer.


Directory Property
Applies To: FileBox

Description

The Directory property contains a simple character vector which specifies the initial directory from which a list of suitable files is displayed.

If, whilst interacting with the FileBox, the user changes directory and exits by pressing "OK" or by closing the FileBox, the value of the Directory property is updated accordingly.


Divider Property
Applies To: ToolControl

Description

The Divider property controls the presence or absence of a recessed line drawn above, below, to the left of, or to the right of a ToolControl object.

Divider is a single number with the value 0 (dividing line is not drawn) or 1 (a dividing line is drawn); the default is 1.

The pictures below illustrates a ToolControl drawn with and without a divider.


DockChildren Property
Applies To: CoolBar Form SubForm

Description

The DockChildren property specifies the names of client objects that may be docked in a host object.

DockChildren may be a single ref or simple character scalar or vector, or a vector of refs or character vectors. Each item represents an object that may be docked. Notice that if you use a name, you must specify the simple name of the object, excluding any part of its full pathname that refers to a parent; i.e. the specified names must not contain any leading pathname information.

If the name of, or ref to, a dockable object occurs in the DockChildren property, the host object will generate DockMove events when the client is dragged over it, and will generate a DockAccept event when a docking operation takes place.

If the name of , or ref to, the client object is not present in its DockChildren property, the object will not respond in any way as the client is dragged over it.

The following example shows the creation of 3 dockable forms, all of which are dockable in a host form called h1.

The first, c1, is a totally independent Form. When docked in h1, it will become a SubForm h1.c1. When undocked, it will revert to an independent Form c1.

The second, c2, is created initially as a child of h1 and will therefore be displayed above it in the window stacking order. When docked it will become a SubForm h1.c2. When undocked, it will revert back to a dependant Form h1.c2. In all cases, it appears on top of h1.

The third, c3, is created initially as a child of another Form, h2. When docked (in h1) it will become a SubForm h1.c3. When undocked, it will become a dependant Form h1.c3, and will therefore appear above h1 in the stacking order.

      'h1'⎕WC'Form' 'Host1'
      'h2'⎕WC'Form' 'Host2'

      'c1' ⎕WC 'Form' 'Client 1' ('Dockable' 'Always')
      'h1.c2' ⎕WC 'Form' 'Client 2' ('Dockable' 'Always')
      'h2.c3' ⎕WC 'Form' 'Client 3' ('Dockable' 'Always')
      h1.DockChildren←'c1' 'c2' 'c3'


DockShowCaption Property
Applies To: Form SubForm

Description

The DockShowCaption property specifies whether or not a Form displays a title bar when it is docked as a SubForm.

DockShowCaption is a single number with the value 0 or 1 (the default).

The DockShowCaption property may be toggled on and off by the user from the object's context menu.

The first picture below illustrates a Form, docked as a SubForm, whose DockShowCaption property is 1, but is about to be set to 0.

The next picture shows the same docked Form with DockShowCaption set to 0.


Dockable Property
Applies To: CoolBand Form SubForm ToolControl

Description

The Dockable property specifies whether or not an object may be docked or undocked.

Dockable is a character vector containing 'Never' (the default), 'Always' or 'Disabled'.

If Dockable is 'Never', the object may not be docked or undocked by the user, and the docking menu items are not present in the object's context menu. This is the default.

If Dockable is 'Always', the object may be docked or undocked by the user, and the docking menu items are present in the object's context menu.

If Dockable is 'Disabled', the object may not currently be docked or undocked by the user, but the docking menu items are present in the object's context menu.

Note that by default, the user may switch between Dockable 'Always'and 'Disabled' by toggling the Dockable menu item. If you want to exercise full control over this property, you may implement your own context menu (see ContextMenu Event)


Docked Property
Applies To: Form SubForm

Description

The Docked property is a read-only property that indicates whether or not an object is currently docked.

Docked is a single number with the value 0 (is not docked) or 1 (is docked).


DragItems Property
Applies To: ListView

Description

The DragItems property is boolean and specifies whether or not the items in a ListView object may be drag/dropped by the user. Its default value is 1.


Dragable Property

Applies To

Description

This property determines whether or not an object may be the subject of a "drag and drop" operation. It is a single number with the value 0, 1 or 2. A value of 0 (which is the default) means that the object may not be drag/dropped. A value of 1 means that the object may be drag/dropped and that during the "drag" operation, a box representing the bounding rectangle around the object is displayed on the screen. A value of 2 means that the outline of the object is displayed as the object is dragged, or, if the object is an Image with a Picture property containing the name of an Icon object, the icon itself is displayed as it is dragged. For rectangular non-graphical objects, values of 1 and 2 are equivalent.

If an object is Dragable, the user may drag it by positioning the mouse pointer within the object, depressing the left mouse button, then moving the mouse with the button held down. During the drag operation, the mouse pointer is automatically changed to a "drag" symbol. The object is "dropped" by releasing the left mouse button. The effect depends upon where it is dropped, and on the action associated with the DragDrop event for the object under the mouse pointer (if any).

If there is no object under the mouse pointer, the "drag and drop" operation is ignored. Otherwise, the object under the mouse pointer generates a DragDrop event.

If the object under the mouse pointer is the parent of the object that has been "dragged and dropped", the default action is for the system to move that object to the new location within its parent. If you wish to allow your user to freely move an object within its parent Form or Group, simply set its Dragable property to 1; the system will take care of the rest. If you want to allow the user to move an object, but you want to know about it when it happens, you can associate a callback function to the DragDrop event that queries the new position. To permit the operation to complete, the callback function should either not return a result or it should return something other than a scalar 0. To selectively disable movement, your callback function should return a scalar 0 in circumstances when the "drop" is not to be permitted.

If the object under the mouse pointer is not the parent of the object being dragged, the default action is for the system to ignore the operation. However, by enabling the DragDrop event, your application can of course take whatever action is appropriate, including perhaps moving the dragged object to a new parent.

Note that a Dragable object does not generate a Configure (31) event when it is dragged and dropped.


DrawMode Property
Applies To: Circle Ellipse Marker Poly Rect Text

Description

The DrawMode property provides direct control over the low-level drawing operation performed by graphical objects.

The DrawMode property specifies the current foreground mix mode. The Windows GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colours already on the screen. The foreground mix mode defines how colours from the brush or pen and the colours in the existing image are to be combined.

DrawMode affects every drawing operation performed by Dyalog APL and not just the initial drawing operation when the object is created. Many of the drawing modes are additive (the result depends not just on what is being drawn, but on what is already there) and the effects may therefore vary. For this reason, DrawMode should normally be used only with un-named graphical objects.

You could use DrawMode to move or animate graphical objects in circumstances where the standard Dyalog APL behaviour was not ideal.

DrawMode is an integer with one of the following values:

Value | Name | Resulting Pixel Colour
1 | R2_BLACK | Pixel is always 0.
2 | R2_NOTMERGEPEN | Pixel is the inverse of the R2_MERGEPEN colour.
3 | R2_MASKNOTPEN | Pixel is a combination of the colours common to both the screen and the inverse of the pen.
4 | R2_NOTCOPYPEN | Pixel is the inverse of the pen colour.
5 | R2_MASKPENNOT | Pixel is a combination of the colours common to both the pen and the inverse of the screen.
6 | R2_NOT | Pixel is the inverse of the screen colour.
7 | R2_XORPEN | Pixel is a combination of the colours in the pen and in the screen, but not in both.
8 | R2_NOTMASKPEN | Pixel is the inverse of the R2_MASKPEN colour.
9 | R2_MASKPEN | Pixel is a combination of the colours common to both the pen and the screen.
10 | R2_NOTXORPEN | Pixel is the inverse of the R2_XORPEN colour.
11 | R2_NOP | Pixel remains unchanged.
12 | R2_MERGENOTPEN | Pixel is a combination of the screen colour and the inverse of the pen colour.
13 | R2_COPYPEN | Pixel is the pen colour.
14 | R2_MERGEPENNOT | Pixel is a combination of the pen colour and the inverse of the screen colour.
15 | R2_MERGEPEN | Pixel is a combination of the pen colour and the screen colour.
16 | R2_WHITE | Pixel is always 1.


Duplex Property
Applies To: Printer

Description

Specifies whether pages are printed on separate sheets or back-to-back.

Duplex is a character vector which is either empty or contains 'Simplex', 'Vertical', or 'Horizontal'.

The default value for Duplex is derived from the current printer setting and 'Vertical' and 'Horizontal' are only effective if the printer supports a duplex capability.


EdgeStyle Property

Applies To

Description

Note that EdgeStyle is not honoured for objects which have a natural built-in 3-dimensional appearance.

This property is used to give a 3-dimensional appearance to screen objects. This is achieved by drawing the object with a grey or white background colour and by drawing a border around it using various combinations of black, white and dark grey lines. Note that this border is drawn outside a control but inside a Form or SubForm.

The value of the EdgeStyle property is a character vector chosen from the following :

'None' | Object is drawn with no 3-dimensional effects and the EdgeStyle properties of its children are ignored (treated as None).
'Plinth' | Object is drawn with a light shadow along its top and left edges and a dark shadow along its bottom and right edges. This gives the illusion of a raised effect.
'Recess' | Object is drawn with a dark shadow along its top and left edges and a light shadow along its bottom and right edges. This gives the illusion of a sunken effect.
'Groove' | Object is drawn with a border that has the appearance of a groove.
'Ridge' | Object is drawn with a border that has the appearance of a ridge.
'Shadow' | Object is drawn with a dark border line along its top and left edges.
'Default' | Object itself is drawn with no 3-dimensional border, but the values of the EdgeStyle properties of its children are observed.
'Dialog' | Used in conjunction with ('Border' 2), this gives a Form the appearance of a standard 3-dimensional dialog box. This setting applies only to a Form or a SubForm

For the Root object, the EdgeStyle property may be 'None' or 'Default'. If EdgeStyle is 'None', screen objects are drawn without 3-dimensional effects of any kind and the value of their EdgeStyle property is ignored. If EdgeStyle is 'Default', all controls are drawn using their default EdgeStyle properties.

Note that MsgBox, FileBox and the set-up dialog box associated with the Printer object are all drawn with 3-dimensional effects regardless of the value of EdgeStyle on Root. These objects do not have their own EdgeStyle properties.

If you set EdgeStyle to 'None' on the Root object, all your objects will (by default) be drawn without 3-dimensional effects.


EditImage Property
Applies To: ComboEx

Description

Specifies whether or not the edit control portion of the ComboEx displays an image for selected items.

EditImage is a single number with the value 0 or 1 (the default). If EditImage is 1, the image associated with the selected item is displayed in the edit control, portion of the ComboEx object, to the left of the text. If EditImage is 0, only the item text is displayed in the edit control.


EditImageIndent Property
Applies To: ComboEx

Description

Specifies whether or not the indents associated with items in a ComboEx object are honoured in the edit control portion of the ComboEx.

EditImageIndent is a single number with the value 0 or 1 (the default).

If EditImageIndent is 1, the selected item which is displayed in the edit control portion of the ComboEx object is indented in the same way as when it is displayed in the dropdown portion of the object. The amount of indentation is specified by the Indents property.

If EditImageIndent is 0, the item displayed in the edit control portion of the ComboEx is not indented.


EditLabels Property
Applies To: ListView TreeView

Description

The EditLabels property is boolean and specifies whether or not the labels (specified by the Items property) in a ListView or TreeView object may be edited by the user. Its default value is 0 (editing is not allowed).

If EditLabels is 1, the user begins editing by clicking the label of the item that has the focus. This causes a pop-up edit box to appear around the item and allows the use to change it. A BeginEditLabel event is reported at the start of the edit operation and an EndLabelEdit event is reported on its completion. You may control the edit of a particular label using callback functions attached to these events.


Elevated Property
Applies To: Button

Description

The Elevated property applies only to a Button whose Style is 'CommandLink'.

Elevated is a Boolean scalar with a default value of 0. When set to 1, the icon on the CommandLink button changes from a "green arrow" to a "shield". This is intended to convey to the user that the action associated with the Button requires Elevation. This is a feature of User Account Control in Windows 7. See your Windows documentation for further information. Note that APL does not take any action (other than to cause the icon to change) when Elevated is set to 1. This is the responsibility of the programmer.


Encoding Property
Applies To: TCPSocket

Description

The Encoding property is a character vector that specifies how character data are encoded or translated. The possible values are 'None', 'UTF-8', 'Classic', or 'Unicode', depending upon the the value of the Style property.

Table 25: Unicode Edition

Style | Encoding | Description
'Raw' | 'None' | Not applicable. Only integer data may be transmitted/received.
'Char' | 'None' | Transmission is limited to characters with Unicode code points in the range 0-255. Attempting to transmit (or receive) a character outside this range will cause DOMAIN ERROR.
 | 'UTF-8' | Characters are transmitted/received using the UTF-8 encoding scheme.
'APL' | 'Classic' | Characters are transmitted/received as indices of ⎕AV, and translated according to the current value of ⎕AVU. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR
 | 'Unicode' | Characters are transmitted/received as is (as Unicode code points).

Table 26: Classic Edition

Style | Encoding | Description
'Raw' | 'None' | Not applicable. Only integer data may be transmitted/received.
'Char' | 'None' | Characters (which are represented internally as indices of ⎕AV)are translated to and from ASCII using the Output Translate Table win.dot.
 | 'UTF-8' | Characters are converted to/from Unicode using ⎕AVU and transmitted/received using the UTF-8 encoding scheme. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR.
'Raw' | 'Classic' | Characters are transmitted/received as indices of ⎕AV.
 | 'Unicode' | Characters are converted to/from Unicode using ⎕AVU and transmitted/received as Unicode code points. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR.

The default value of Encoding depends upon the value of Style as indicated Default values are highlighted thus. in the above tables.

An attempt to set the value of Encoding to a value not valid for the current Style, as implied by the above tables, will cause DOMAIN ERROR.

If you change the value of the Style property, the value of Encoding will remain unchanged if it is valid for the new Style. Otherwise it will revert to the default value for the new value of Style.

      's0'⎕WC'TCPSocket' ('LocalPort' 2001)
      s0.(Style Encoding)
Char  None

      s0.Style←'APL'
      s0.(Style Encoding)
Apl  Classic

Note that the 'Classic' encoding is intended for use in communicating with the Classic Edition, and with programs designed to communicate with Version 11.0 or earlier. This is why it is the default for now. However, it is however intended that the default will change to 'Unicode'in due course.


End Property
Applies To: Circle Ellipse

Description

This property specifies one or more end-angles for an arc, pie-slice, or chord of a circle or ellipse. It may be used in conjunction with Start which specifies start angles. Angles are measured counter-clockwise from the x-axis at the centre of the object.

If a single arc is being drawn, End is a single number that specifies the end angle of the arc in radians (0 ⍎> ○2). If multiple arcs are being drawn, End is either a single number as before (the end angle for several concentric arcs) or a numeric vector with one element per arc.

If Start is not specified, the default value of End is ○2. Otherwise, the default value of End is ((¯1↓+\Start),○2).


EnterReadOnlyCells Property
Applies To: Grid

Description

This is a Boolean property that specifies whether or not the user may visit read-only cells in a Grid object. Its default value is 1.

In this context, a read-only cell is one that satisfies one or more of the following conditions:

  • it has no associated Input object
  • its associated Input object is a Label
  • its associated Input object is an Edit object with ReadOnly set to 1.
  • its associated Input object is inactive (Active0)

If EnterReadOnlyCells is set to 0 and the user clicks the mouse on a read-only cell, the current cell does not change although CellDown, CellUp and CellDblClick events are reported if enabled. If the user presses a cursor movement key that would otherwise cause the cursor to move into a read-only cell, the cursor moves instead to the nearest editable cell in the appropriate direction.


EvaluationDays Property
Applies To: Root

Description

This is a read-only property that reports the number of days remaining before an evaluation version of a Dyalog APL run-time application expires.

It is provided so that you can display an appropriate message box to notify your end-user when your application is started.

PocketAPL only


Event Property

Applies To

Description

This property defines how an object responds to user actions. Unlike other properties which only have a single value, this property has a value corresponding to each of the events that may be generated by a particular object. Each event setting is specified by a 2 or 3-element vector containing :

[1] | event name(s) (optionally prefixed by the string 'on') or event number(s) (numeric scalar or vector).
[2] action code (numeric scalar or character vector)
¯1 | inhibit (ignore) event
0 | handle event, do not report to APL
1 | handle event, then report to APL
fn | name of callback function
fn& | name of callback function to be executedasynchronously
⍎expr | expression to be executed
[3] | any array (optional)

The event number 0 and the event name 'All', apply to all events supported by that object.

Like any other property, the Event property can be set using assignment. However, certain special considerations apply which are discussed later.

If action is set to ¯1, the event is ignored by APL. If, for example, you set the action on a KeyPress event to ¯1, all keystrokes for the object in question will be ignored. Similarly, if you set the action on a Close event for a Form to ¯1, the user will be unable to close the Form. This is possible because APL intercepts most events before Windows itself takes any action. However, certain events (e.g. focus change events) are not notified to APL until after the event has occurred and after Windows has itself responded in some way. In these circumstances it is not always practical for APL to undo what Windows has already done, and an action code of ¯1 is treated as if it were 0. For further details, see the individual entries for each event type in this Chapter.

If action code is set to 0 (the default), the event is processed by APL and Windows in the normal way (this is referred to herein as "default processing") but your program is not notified in any way that the event has occurred. For example, the default processing for a keystroke is to action it (via the translate table) and either echo a character in the object or perform some other appropriate function.

If action code is set to 1, the event is first processed by APL (and Windows) in the normal way, then ⎕DQ terminates, returning an event message as its result. The format of the event message is given under the description of each event type.

If action code is set to a character vector that specifies the name of a function, this function (termed a "callback") will be executed automatically by ⎕DQ whenever the event occurs. Default processing of the event is deferred until after the callback has been run, and may be inhibited or modified by its result. If the callback function returns no result, or returns a scalar 1, normal processing of the event is allowed to continue as soon as the callback completes. If the callback returns a scalar 0, normal processing of the event is inhibited and the effect is identical to setting the action code to ¯1. A callback function may also return an event message as its result. If so, ⎕DQwill action this event rather than the original one that fired the callback.

Note that that if a callback function does not exist at the instant it is invoked, ⎕DQ terminates with a VALUE ERROR. However, the name of the missing function is reported in the Status Window.

If, in setting the Event property, the event name is prefixed by the string 'on', for example, 'onSelect', the right argument to the callback function will contain one or more object references. If not, it will contain the corresponding object names or, if the object has no name, its display form.

If the character & is appended to the name of a callback function, the callback is executed asynchronously in a new thread. In this case, default processing of the event is performed immediately. Such a callback should not return a result; if it does so, it will be treated as normal output and will therefore be displayed in the Session window.

When a callback function is invoked by ⎕DQ, the corresponding event message is supplied as its right argument. The format of the event message is given under the description of each event type in this chapter. Note that the first element of the event message is always a reference to or the name of the object that generated the event. It is a referenceif the event name was prefixed by the string 'on'; otherwise it is a character vector containing the object's name.

If an array was specified as the 4th element of the value of the Event property, the value of this array is supplied as its left argument.

Notice that ⎕DQ takes account of the syntax defined for the callback, and supplies these arguments only if it is appropriate to do so. It is possible therefore to use a niladic callback function. This is appropriate if the callback can perform its task without needing to interrogate the event message.

If action code is set to a character vector whose first element is the execute symbol (⍎) the remaining string will be executed automatically whenever the event occurs. The default processing for the event is performed first and may not be changed or inhibited in any way.

Notice that when you specify the action to be taken on the occurrence an event there is a great difference between 'FOO'and '⍎FOO'. The former causes APL to invoke the function FOO as a callback function. If the function takes an argument, APL will supply it with the event message. Secondly, the result (if any) of the function FOOwill be used by APL and may cause the event to be disabled or changed in some way. In the second case, APL will perform the default processing for the event and then execute FOO without supplying an argument. If the function returns a result, it will be displayed in the Session.

When using ⎕WC and ⎕WSto assign different events to different callbacks, it is not necessary to repeat the 'Event' keyword. Instead, several event settings can be specified at once. In any given occurrence of the Event property you may use event number(s) or event name(s); however you may not mix numbers and names together.

If you use event names, your callback functions will receive event names in their right argument when invoked. That is to say that the second element of the event message will be a character vector. If you use event numbers, the second element of the event message will be numeric. If you want to specify several event names at once, you must enclose them. If you use numbers, ⎕WCand ⎕WS are more tolerant about the structureof their arguments, and will accept many different expressions.

If no events are set, the result obtained by ⎕WGand the result obtained by referencing Event directly are different:

      'F'⎕WC'Form'
      DISPLAY 'F'⎕WG'Event'
.→--.
|0 0|
'~--'
      DISPLAY F.Event
.⊖------------.
| .→--------. |
| | .⊖. .⊖. | |
| | | | | | | |
| | '-' '-' | |
| '∊--------' |
'∊------------'

Asynchronous Callback Functions

If you append the character & to the name of the callback function in the Event specification, the callback function will be executed asynchronously in a new thread when the event occurs. If not, it is execute synchronously.

For example, the event specification:

      onSelect←'DoIt&'

tells ⎕DQ to execute the callback function DoIt asynchronously as a thread when a Select event occurs on the object. Note that a callback function executed in this way should not return a result (because ⎕DQdoes not wait for it) and any result will be displayed in the Session window.

Specifying the Event property using Assignment

There are two ways to specify the Event property using assignment; you can specify the entire set of events, or you can set individual events one by one.

To specify the entire set of events, the array assigned to Event must contain one or more nested vectors, each containing 2 or 3 elements as described above. For example, if F1 is a Form:

Invoke callback function FOO on MouseDown, the first element of the right argument to FOOwill contain a namespace reference to F1. All other events perform their default actions.

      F1.Event ← 'onMouseDown' 'FOO'

Invoke callback function FOO on MouseDown, the first element of the right argument to FOO will contain the character vector'F1'. All other events perform their default actions.

      F1.Event ← 'MouseDown' 'FOO'

Invoke callback function FOO on MouseDown and MouseUp. All other events perform their default actions.

      F1.Event ← ('onMouseDown' 'FOO')( 'onMouseUp' 'FOO')

Add callback function FOO with ('THIS' 1) as its left-argument on the MouseMove event. All other events perform their default actions.

      F1.Event, ← ⊂ 'onMouseMove' 'FOO' ('THIS' 1)

To set individual events one by one, you make the assignment to the event name prefixed by the string 'on'. In all cases, the first element of the right argument to FOOwill contain a namespace reference to F1. You must use the 'on' prefix; you cannot assign to the Event name itself.

Invoke callback function FOO on MouseDown.

      F1.onMouseDown ← 'FOO'

Add the same callback for MouseUp.

      F1.onMouseUp ← 'FOO'

Add callback function FOO with ('THIS' 1) as its left-argument on the MouseMove event.

      F1.onMouseMove ← 'FOO' ('THIS' 1)

Specifying the Event property using ⎕WC and ⎕WS

Examples using Event Names (⎕WS)

Ignore MouseDown (1) event (APL will perform the default processing for you)

      'F1' ⎕WS 'Event' 'MouseDown' 0

Terminate ⎕DQ on MouseDown

      'F1' ⎕WS 'Event' 'MouseDown' 1

Invoke callback function FOO on MouseDown, the first element of the right argument to FOOwill contain a namespace reference to F1.

      'F1' ⎕WS 'Event' 'onMouseDown' 'FOO'

Invoke callback function FOO on MouseDown, the first element of the right argument to FOOwill contain the character vector'F1'.

      'F1' ⎕WS 'Event' 'MouseDown' 'FOO'

Invoke callback function FOO on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ('onMouseDown' 'onMouseUp') 'FOO'

Invoke callback function FOO with ('THIS' 1) as its left-argument on MouseDown

      'F1' ⎕WS 'Event' 'onMouseDown' 'FOO' ('THIS' 1)

Invoke callback function FOO with ('THIS' 1) as its left-argument on MouseDown, MouseUp and MouseMove

      EV ← 'onMouseDown' 'onMouseUp' 'onMouseMove'
      'F1' ⎕WS 'Event' EV 'FOO' ('THIS' 1)

Execute the expression COUNT +←1 on MouseDown

      'F1' ⎕WS 'Event' 'MouseDown' '⍎COUNT+←1'

Execute the expression COUNT +←1 on MouseDown, MouseUp and MouseMove

      EV ← 'MouseDown' 'MouseUp' 'MouseMove'
      'F1' ⎕WS 'Event' EV '⍎COUNT+←1'

Examples using Event Numbers (⎕WS)

Ignore MouseDown (1) event (APL will perform the default processing for you)

      'F1' ⎕WS 'Event' (1 0)
      'F1' ⎕WS 'Event' 1 0     ⍝  Ditto

Terminate ⎕DQ on MouseDown

      'F1' ⎕WS 'Event' (1 1)
      'F1' ⎕WS 'Event' 1 1     ⍝ Ditto

Call function FOO on MouseDown

      'F1' ⎕WS 'Event' (1 'FOO')
      'F1' ⎕WS 'Event' 1 'FOO'    ⍝ Ditto

Call function FOO on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ((1 2) 'FOO')
      'F1' ⎕WS 'Event' (1 2) 'FOO'              ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO'                ⍝ Ditto
      'F1' ⎕WS 'Event' (1 'FOO')(2 'FOO')       ⍝ Ditto

Call function FOO with ('THIS' 1) as its left-argument on MouseDown

      'F1' ⎕WS 'Event' (1 'FOO' ('THIS' 1))
      'F1' ⎕WS 'Event' 1 'FOO' ('THIS' 1)       ⍝ Ditto

Call function FOO with ('THIS' 1) as its left-argument on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ((1 2) 'FOO' ('THIS' 1))
      'F1' ⎕WS 'Event' (1 2) 'FOO' ('THIS' 1)   ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO' ('THIS' 1)     ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO' ('THIS' 1)     ⍝ Ditto

Execute the expression COUNT +←1 on MouseDown

      'F1' ⎕WS 'Event' 1 '⍎COUNT+←1'

Execute the expression COUNT +←1 on MouseDown, MouseUp and MouseMove

      'F1' ⎕WS 'Event' (1 2 3) '⍎COUNT+←1'
      'F1' ⎕WS 'Event' 1 2 3 '⍎COUNT+←1'     ⍝ Ditto

User defined Events

In addition to the standard events supported directly by Dyalog APL, you may specify your own events. For these, you must use event numbers; user-defined event names are not allowed.

You may use any numbers not already defined, but it is strongly recommended that you choose numbers greater than 1000 to avoid potential conflict with a future release of Dyalog APL.

You can only generate user-defined events under program control with ⎕NQ.


EventList Property

Applies To

Description

This is a read-only property that reports the names of all the events supported by an object.


ExportedFns Property
Applies To: OLEServer

Description

This property specifies the functions to be exposed as methods by an OLEServer object.

ExportedFns may be set to 0 (none), 1 (all), or a vector of character vectors containing the names of the functions to be exported.

There are certain important restrictions concerning the type of function that you can export as a method.

Firstly, only top-level defined functions within the OLEServer may be exported; you cannot export functions in other namespaces including sub-namespaces.

Furthermore, you may not export defined operators, dynamic functions, external functions, or functions created by function assignment.

Finally, OLE does not support the concept of a dyadic function, so your exported functions must be niladic, monadic, or take an optional left argument; they may not be explicitly dyadic.

If you wish to export a new function from your OLEServer, and ExportedFns is not 1, you must explicitly reset the value of the ExportedFns property before you re-save the workspace.


ExportedVars Property
Applies To: OLEServer

Description

This property specifies the variables to be exposed as properties by an OLEServer object.

ExportedVars may be set to 0 (none), 1 (all), or a vector of character vectors containing the names of the variables to be exported.

Note that you may not export external variables or shared variables, or variables in other namespaces.

If you wish to export a new variable from your OLEServer, and ExportedVars is not 1, you must explicitly reset the value of the ExportedVars property before you re-save the workspace.


FCol Property

Applies To

Description

This property defines the foreground colour(s) of an object. For non-graphical objects, FCol specifies a single colour. For graphical objects with more than one constituent part, it may specify a set of background colours, one for each part. A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities.

If FCol is 0 (which is the default) the foreground colour is defined by your current colour scheme for the object in question. For example, if you select red as your MS-Windows "Button Text" colour, you will by default get red writing on all your Button objects, simply by not specifying FCol or by setting it to 0.

A negative value of FCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

FCol | Colour Element | FCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If instead, FCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow.

Note that if the colour specified by FCol would normally be rendered as a dithered colour, it is instead converted to the nearest pure colour available on the device. The actual colour realised also depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

For a Button, Combo, Edit, Label, List, Menu and MenuItem, FCol refers to the colour of the text in the object. Borders around these objects (where applicable) are drawn using the standard Windows colour. For a Static object however, FCol specifies the colour of its border.

For the Ellipse, Poly and Rect objects, FCol specifies the colour of the line drawn around the perimeter of the object. If a dashed or dotted line is used (LStyle 1-4) the "gaps" in the line are drawn using the colour specified by BCol, or are left undrawn if BCol is not specified. For the Marker object, FCol specifies the colour in which the markers are drawn. For the graphics objects Ellipse, Poly, Rect and Text, FCol may be a vector of 3-element vectors specifying a set of colours for the constituent parts of the object. For example, a Poly object consisting of four polygons, may have a FCol property of four 3-element vectors. In addition, for graphics objects, FCol is used in place of FillCol if the latter is not specified.


FStyle Property
Applies To: Circle Ellipse Poly Rect

Description

This property determines how a graphics object is filled. It takes one of the following values, or, if the object has more than one component, a vector of such values.

FStyle | Effect
¯1 | hollow (no fill). This is the default.
0 | solid fill
1 | hatch fill with horizontal lines
2 | hatch fill with vertical lines
3 | hatch fill with diagonal lines at 135 degrees
4 | hatch fill with diagonal lines at 45 degrees
5 | hatch fill with horizontal and vertical lines
6 | hatch fill with criss-crossing diagonal lines
str | the name of. or a ref to, a Bitmap object which is used to fill the object.

For example, to fill an object with criss-crossing diagonal lines you would specify ('FStyle' 6). If the object contained two components, you could fill the first one with criss-crossing diagonal lines, and the second one with a Bitmap called 'YES', with the specification ('FStyle' 6 'YES')

If the size of the Bitmap is 8x8 APL uses a Windows "brush" to fill the object. If not, it uses "tiling". Filling with a brush is faster.


FieldType Property
Applies To: ButtonEdit DateTimePicker Edit Label Spinner

Description

The FieldType property controls data conversion, formatting and validation. For Edit, Label and Spinner objects, FieldType controls how the Value property of these objects is interpreted.

FieldType is a character vector. If it is empty (the default), the Text or Label object is a standard text object with no special formatting or, in the case of an Edit, no input validation. For a DateTimePicker, an empty FieldType implies the default which is 'Date'.

For a DateTimePicker, FieldType may be one of the following:

'Date' | Uses Windows "short date" format
'DateCentury' | Uses Windows "short date" format but with a 4-digit year regardless of user preference
'LongDate' | Uses Windows "long date" format
'Time' | Uses Windows time format
'Custom' | Uses a special format defined by the CustomFormat property

The value of the date or time is represented by the DateTime property. Note that all validation is performed by the object itself, and it is impossible to enter an invalid value.

For an Edit, Label and Spinner, if FieldType is defined, the contents of the object are defined by its Value property, which is a number, rather than by its Text property, and special formatting and validation rules are applied. FieldType may be one of the following :

'Numeric' | Simple numeric formatting and validation
'LongNumeric' | Uses Windows number format
'Date' | Uses Windows "short date" format
'LongDate' | Uses Windows "long date" format
'Currency' | Uses Windows currency format
'Time' | Uses Windows time format
'Char' | No validation, forces Value to be a character vector

FieldType 'Char' only affects an Edit object. When the user enters data into a standard single-line Edit object , the Value property is set to a number if the contents are numeric, or to a character vector if the contents do not represent a valid number. If FieldType is 'Char', the Value property is always set to a character vector, regardless of the type of the field contents.

If FieldType is 'Numeric', the object displays the number defined by its Value property rounded to the number of decimal places specified by its Decimals property. The decimal separator character used will be as specified by the Number format in the user's International Control Panel settings. If the object is an Edit object, the user is prevented from entering anything but a valid number. The number of decimal digits is also restricted to Decimals. When the user "leaves" the object, the number is re-formatted.

If FieldType is 'LongNumeric', the object displays the number specified by its Value property according to the Number format in the user's International Control Panel settings. This format specifies the 1000 separator, decimal separator, decimal digits and whether or not a leading zero is inserted. If the object is an Edit object, the user is prevented from entering anything but a valid number. However, the character specified for the 1000 separator is ignored and may be entered anywhere in the number. When the user "leaves" the object, the number is re-formatted correctly.

If the FieldType is 'Currency', the object displays the number specified by its Value property according to the Currency format in the user's International Control Panel settings. This specifies the currency symbol and placement, the way in which a negative value is displayed, and the number of decimal places. If the object is an Edit object, the user is restricted to entering a "reasonable" value. When the user leaves the object, the number is reformatted correctly.

If the FieldType is 'Date', the Value property represents the number of days since January 1st 1900 and is displayed using the "short date" format specified by the user's International Control Panel settings. If the object is an Edit object, the user is restricted to entering a "reasonable" date. The object will accept any numeric triplet separated by slash(/), colon (:) or space characters but checks that the day number and month number lie in the range 1-31 and 1-12 respectively and will not allow the user to enter a digit that would invalidate this. (Note that the position within the triplet of the day, month and year are as specified by the Windows short date format). However, the user is not prevented from entering an invalid date such as 31st September.

If the FieldType is 'LongDate', the Value property represents the number of days since January 1st 1900 and is displayed using the "long date" format specified by the user's International Control Panel settings. If the object is an Edit object, its appearance and behaviour automatically switches to FieldType 'Date' when it has the input focus and back again when it loses the focus. This allows the user to edit or input a date in a more convenient form.

If the FieldType is 'Time', the Value property represents the number of seconds since midnight and is displayed using the time format specified by the user's International Control Panel settings.

When the user attempts to move the input focus away from the object, the contents are validated. If they cannot be converted to a valid number, date, or time, the object generates a BadValue event, or, if the object is associated with a Grid, the Grid (and not the Edit object) generates a CellError event. See the descriptions of these events for further details.

Note that for Edit, Label and Spinner objects, FieldType may only be specified when you create an object using ⎕WC.


File Property

Applies To

Description

For an Animation, Bitmap, Cursor or Icon object, this property is either a simple character vector or a 2-element nested vector.

If it is simple, File specifies the name of the associated bitmap (.BMP), icon (.ICO) or cursor (.CUR) file.

If it is nested, the first element specifies the name of a DLL or (Icon only) EXE and the second element identifies the particular bitmap, icon or cursor in that file. The identifier may be its name (a character string), its resource id (a non-zero positive integer) or (Icon only), its index (0 or negative integer) within the file. As a special case, if the name of the file is an empty vector, the object is loaded from DYALOG.EXE or the Dyalog resource DLL. The name of the latter varies according to the version installed but begins DYARES. In this case, the identifier must be a name or resource id; indexes are not supported.

For a Metafile object, File must be simple and specifies the name of a metafile (.WMF) file. For a RichEdit object, File must be simple and specifies the name of a Rich text Format (.RTF) file.

When applied to a FileBox object, File contains the name (or names) of the selected file (or files) depending upon the value of its Style ('Single' or 'Multi').


FileMode Property
Applies To: FileBox

Description

The FileMode property applies only to a FileBox object. It indicates the mode in which the selected file is going to be opened. It is a character vector containing 'Read' (the default) or 'Write'. If FileMode is 'Write', files listed in the File Selection Box are greyed, although they may still be selected.


FillCol Property
Applies To: Circle Ellipse Poly Rect

Description

This property defines the fill colour in a graphics object.

If FStyle is 0 (solid fill) FillCol defines the colour with which the object is filled. If FStyle is in the range 1-6 (pattern fill) it defines the colour of the lines that make up the pattern. The areas between the lines are filled using the colour specified by BCol, or are left undrawn (transparent) if BCol is not specified. If FStyle contains the name of a Bitmap object, the value of FillCol is ignored.

A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities. A negative value of FillCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

FillCol | Colour Element | FillCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If instead, FillCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow. Note that the colour realised depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

FillCol may also be a vector of 3-element vectors specifying a set of colours for the constituent parts of the object. For example, a Poly object consisting of four polygons, may have a FillCol property of four 3-element vectors.


Filters Property
Applies To: FileBox

Description

The Filters property is a nested scalar or vector containing a list of filters. Each filter is a 2-element vector of character vectors which contain a file type mask and a file type description respectively. The file type descriptions appear in a drop-down combo box labelled "List Files of Type". When the user selects one of these, the currently selected directory is searched for files which match the corresponding mask. The default value of Filters is an empty vector. This gives a file type mask of "*.*" and a file type description of "All Files (*.*)". Hence an empty vector is equivalent to (⊂'*.*' 'All Files (*.*)').


FirstDay Property
Applies To: Calendar

Description

The FirstDay property specifies the day that is considered to be the first day of the week and which appears first in the Calendar.

FirstDay is an integer whose value is in the range 0-6. The default value for FirstDay depends upon your International Settings, but in most countries is 0 meaning Monday.


Fixed Property
Applies To: Font

Description

This property specifies whether or not a font represented by a Font object is fixed-width or proportional. It is either 0 (fixed-width) or 1 (proportional). There is no default; the value of this property reflects the characteristic of the selected font.


FixedOrder Property
Applies To: CoolBar

Description

The FixedOrder property specifies whether or not the CoolBar displays CoolBands in the same order.

FixedOrder is a single number with the value 0 (user may re-order bands) or 1 (user may not re-order bands); the default is 0.

If FixedOrder is 1, the user may move bands to different rows, but the band order is static.


FlatSeparators Property
Applies To: TabControl

Description

The FlatSeparators property specifies whether or not separators are drawn between buttons in a TabControl object. FlatSeparators only affects a TabControl if Style is 'FlatButtons' and is otherwise ignored.

FlatSeparators is a single number with the value 0 (no separators) or 1 (separators); the default is 0.

The pictures below illustrate the effect of FlatSeparators on the appearance of a TabControl object.


FontList Property
Applies To: Printer Root

Description

The FontList property is a read-only property (you cannot set its value) that provides a list of available fonts.

Its value is a vector (1 per font) of 8-element character vectors, each of which is as follows :

[1] | Face name (character vector)
[2] | Character height in "points" (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

Example:

       ↑'.'⎕WG'FontList'
 System                         16 0 0 0 700 0   0
 Terminal                       12 1 0 0 400 0 255
 Fixedsys                       15 1 0 0 400 0   0
 Roman                          37 0 0 0 400 0 255
 Script                         36 0 0 0 400 0 255
 Modern                         37 0 0 0 400 0 255
 Small Fonts                     3 0 0 0 400 0   0
 MS Serif                       10 0 0 0 400 0   0
 WST_Czec                       12 1 0 0 700 0   2
 WST_Engl                       12 1 0 0 700 0   2
 WST_Fren                       12 1 0 0 700 0   2
 WST_Germ                       12 1 0 0 700 0   2
 WST_Ital                       12 1 0 0 700 0   2
 WST_Span                       12 1 0 0 700 0   2
 WST_Swed                       12 1 0 0 700 0   2
 Courier                        13 1 0 0 400 0   0
 Serif                          13 0 0 0 400 0   0
 Causeway                       16 1 0 0 700 0   0
 Dyalog Alt                     16 1 0 0 400 0   0
 Dyalog Std                     16 1 0 0 400 0   0

Note that the list of fonts obtained from FontList for a Printer object will include TrueType fonts and printer fonts but will exclude screen fonts. FontList for Root will include TrueType fonts and screen fonts, but exclude printer-only fonts. The two lists will therefore (typically) be different.


FontObj Property

Applies To

Description

The FontObj property associates a font with an object. It specifies either the name of, or a ref to, a Font object, or it specifies the attributes of the font directly. The use of the FontObj property to specify a font directly is supported only for compatibility with previous releases of Dyalog APL/W and may be removed in the future. The Font object provides a more efficient mechanism for managing fonts and allows greater flexibility for drawing and printing graphical text. It is recommended that all fonts be specified using Font objects and not loaded directly using the FontObj property.

If unspecified, the default value for FontObj is an empty character vector. For most objects, this setting implies that the font used in the object is inherited from its parent object. However, CoolBar, Menu, MenuBar, StatusBar, TipField, ToolBar, and ToolControl objects do not inherit their font.

Note that the default value of FontObj for Root is also an empty character vector and that this implies the Windows default GUI font, which is a Windows user preference setting.

Note however that it is not currently possible to specify the font for Menu and MenuItem objects which are the direct descendants of a MenuBar. Nor is it possible to specify the font used for the Caption in a Form.

If FontObj specifies a Font object, it is a ref or a simple character vector.

If FontObj specifies a font directly, it may be either an empty character vector (this is its default value) or as an array containing up to 8 elements as follows :

[1] | Face name of requested font (character vector)
[2] | Character height in pixels (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

When you assign a value to the FontObj property of an object, Windows actually supplies the font that most closely matches the attributes you have specified. The matching rules it uses are complex, and may be found in the appropriate Windows documentation. The value of the FontObj property reflects the attributes of the font which has been allocated by Windows, not the value you originally specified.

A list of available fonts and their attributes may be obtained from the FontList property of the Root object ".".

The "Face name" is the name assigned to the font by Windows. The default is 'System'. The face name of the Dyalog APL font is 'APL'. Note that case is ignored when you specify the name, although it will be returned correctly by ⎕WG.

The size of the font is specified in terms of its height in pixels. If Windows cannot supply exactly the size you request, it will supply the nearest below that.

A value of 1 in the third element requests a fixed-width font, as opposed to a proportional one. This attribute is given the maximum weighting by Windows in choosing a matching font.

A value of 1 in the fourth and fifth elements requests the font attributes italic and underlined respectively. Windows will add these attributes to an existing font if they don't physically exist. For example, you can obtain italic and underlined APL characters from the standard APL font.

The weight is a number in the range 0 to 1000 which specifies how faint or bold the characters appear. The larger the number, the bolder the font.

The angle of rotation is measured in 1/10ths of a degree from the x-axis in a counter-clockwise direction. Its default value is 0.


FormatString Property
Applies To: ButtonEdit Edit Grid Label Spinner

Description

The FormatString property specifies one or more ⎕FMT format specifications to be used to format data in an Grid or single-line Edit. When applied to a Grid, it is either a simple character vector that specifies the format specification for the entire Grid, or a vector of character vectors. If it is a vector, its elements are mapped to individual cells via the CellTypes property. When applied to an Edit object, FormatString must be a simple character vector.

APL derives the text to be displayed in a cell by calling ⎕FMT with a left argument of the corresponding element of FormatString and a right argument of the cell value. If the format specification is invalid, the text displayed is blank.

When a formatted Edit object receives the focus, it redisplays the contents in its raw (unformatted) form. When the Edit loses the focus, its contents are reformatted. When the user moves to a formatted Grid cell, the text remains formatted until the user presses a non-movement key or enters in-cell mode. The data is then redisplayed in its raw form for editing. Data in the cell is reformatted when the user moves away.

In a Grid, formatted data may be aligned vertically using the AlignChar property as illustrated in the following example.

      'F'⎕WC'Form'
      'F.G'⎕WC'Grid'(¯50+?10 10⍴100)(0 0)(100 100)
      'F.G'⎕WS'FormatString' 'M<(>N<)>F12.3'
      'F.G'⎕WS'AlignChar' '.'


Formats Property
Applies To: Clipboard

Description

This is a "read-only" property that identifies the formats in which data is currently available in the clipboard. It is a vector of character vectors containing the names of the corresponding Clipboard properties for which data may be obtained using ⎕WG. In the following example data was copied to the Windows clipboard from Microsoft Excel. This product stores data in CF_Text and the older device-dependent CF_Bitmap formats. The latter excludes colour map information, so CMap is not available.

      'CL' ⎕WC 'Clipboard'
      'CL' ⎕WG 'Formats'
 Bits  CMap  Text


FullRowSelect Property
Applies To: ListView TreeView

Description

The FullRowSelect property specifies whether or not the entire row is highlighted when an item in a ListView or a TreeView is selected.

FullRowSelect is a single number with the value 0 (only the item name is highlighted) or 1 (the whole row is highlighted); the default is 0.

For a ListView, FullRowSelect only applies if its View property is set to 'Report'.

The picture below illustrates the effect on the appearance of a ListView object, of setting FullRowSelect to 1.


GridBCol Property
Applies To: Grid

Description

This property specifies the colour used to fill the area between the end of the last column of data and the right edge of the Grid and between the bottom row of data and the bottom edge of the Grid.

GridBCol may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). Its default value is 0 which obtains the colour defined for Window Background.


GridFCol Property
Applies To: Grid

Description

The GridFCol property specifies the colour of the grid lines in a Grid object

GridFCol may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Window text.

The grid lines may be removed by setting GridFCol to the same colour as the background colour of the cells, which is defined by Bcol.


GridLineFCol Property
Applies To: Grid

Description

The GridLineFCol property specifies the colours of the grid lines in a Grid object. GridLineFCol should be used if different coloured grid lines are required. If all the grid lines are the same colour, use GridFCol.

GridLineFCol may be a scalar or a vector. Each item may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or a scalar that defines a standard Windows colour element (see Bcol for details). Note that a single RGB triplet must be enclosed.

The default value of GridLineFCol is an empty numeric vector (⍬). If so, all the grid lines are drawn using the single colour specified by GridFCol.

Elements of GridLineFCol are allocated to individual grid lines via the RowLineTypes and ColLineTypes properties.

See also: GridLineWidth.


GridLineWidth Property
Applies To: Grid

Description

The GridLineWidth property specifies the widths in pixels of the grid lines in a Grid object.

GridLineWidth may be an integer scalar or a vector. Its default value is an empty numeric vector (⍬). If so, grid lines are drawn 1-pixel wide.

Grid lines are always displayed so that 1 pixel is drawn within the cell. If the width is greater than 1 pixel, the additional pixels are drawn between the cells.

If an element of GridLineWidth is 0, the corresponding grid lines are not drawn.

Elements of GridLineWidth are allocated to individual grid lines via the RowLineTypes and ColLineTypes properties.

See also: GridLineFCol.


GridLines Property
Applies To: ListView

Description

The GridLines property specifies whether or not lines are displayed between items in a ListView object. GridLines applies only if the value of the View property is 'Report'.

GridLines is a single number with the value 0 (no lines are displayed) or 1 (lines are displayed); the default is 0.

The picture below illustrate the effect on the appearance of a ListView object, of setting GridLines to 1.


GripperMode Property
Applies To: CoolBand

Description

The GripperMode property specifies whether or not the CoolBand has a gripper bar which is used to reposition and resize the CoolBand within its parent CoolBar.

GripperMode is a character vector with the value 'Always' (the default), 'Never' or 'Auto'.

If GripperMode is 'Always' , the CoolBand displays a gripper bar even if it is the only CoolBand in the CoolBar.

If GripperMode is 'Never' , the CoolBand does not have a gripper bar and may not be directly repositioned or resized by the user.

If GripperMode is 'Auto' , the CoolBand displays a gripper bar only if there are other CoolBands in the same CoolBar.


HAlign Property
Applies To: Text

Description

This property determines the horizontal alignment of text in a Text object. It is either a single integer value, or, if the Text object contains several components, a corresponding vector of such values.

These may be:

0 | left aligned | the left edge of the bounding box of the text is aligned on the x-co-ordinate specified by the Points property.
1 | centre aligned | the centre of the bounding box of the text is aligned on the x-co-ordinate specified by the Points property.
2 | right aligned | the right edge of the bounding box of the text is aligned on the x-coordinate specified by the Points property.


HScroll Property

Applies To

Description

For most objects to which it applies, this property determines whether or not a horizontal scrollbar is provided.

HScroll may only be set when the object is created with ⎕WC and may not subsequently be changed with ⎕WS or assignment.

When applied to a Combo, or to an Edit object with Style 'Single' (i.e. a single-line edit field), the value 0 inhibits scrolling, and prevents the user from entering more data when the field is full. If instead it has the value ¯2, the field is scrollable, and the length of data that may be entered is not limited by the length of the field.

When applied to an Edit object with Style 'Multi' (i.e. a multi-line text box), the value 0 inhibits scrolling, and causes individual lines to be "word-wrapped". The values ¯2 and ¯1 enable sideways scrolling, and permit individual lines to exceed the width of the object. The value ¯1 means that a horizontal scrollbar is provided.

For a Scroll object, the scrollbar is horizontal if HScroll is ¯1 and vertical if HScroll is 0. For a Form, a horizontal scrollbar is provided if HScroll is set to ¯1. The default value is 0 (no scrollbar).

For a StatusBar, TabBar or ToolBar with Align set to Top or Bottom, HScroll determines whether or not a horizontal scrollbar is provided and how the object positions its children. If HScroll is 0 (the default) the object organises its children in multiple rows and does not provide a scrollbar. If HScroll is ¯1 or ¯2, the object organises its children in a single row and provides a mini scrollbar to allow those positioned beyond the right edge of the object to be scrolled into view. If HScroll is ¯1, the scrollbar is always shown. If HScroll is ¯2, it is only shown when needed.

For a Grid, HScroll may be 0 (no horizontal scrollbar), ¯1 (scrollbar is displayed when required), ¯2 (same as ¯1) or ¯3 (scrollbar is always displayed).


Handle Property

Applies To

Description

This is a read-only property that reports the handle associated with an object. For a visual object, such as a Form or a Button, this is the window handle. For a Printer, it is the printer device context.

This handle allows you to access the corresponding object directly with Windows API functions via ⎕NA. This facility must be used with care and the responsibility for its behaviour is entirely yours. Do NOT use it to delete an object. This will cause APL to crash.

An example of the use of the Handle property is to set tab stops in a List object. This is illustrated by the following function:

     ∇ obj TABSTOPS stops;I;LB_SETTABSTOPS;SetTabStops;sink;args
[1]   ⍝ Sets the tabstops in the List Box OBJ to be at
[2]   ⍝ stops Horizontal Dialog units.
[3]   ⍝ Sends LB_SETTABSTOPS (402) to the List Box
[4]   ⍝ See Windows SDK for Details.
[5]
[6]    I←obj ⎕WG'Items'
[7]
[8]    LB_SETTABSTOPS←402
[9]    'SetTabStops'⎕NA'U4 USER32.C32|SendMessageA U4 U4 U4 <U4[]'
[10]
[11]   args←(obj ⎕WG'Handle') LB_SETTABSTOPS (⍴,stops)(,stops)
[12]   sink←SetTabStops args
[13]
[14]   obj ⎕WS'Items'I
     ∇


HasApply Property
Applies To: PropertySheet

Description

The HasApply property is a boolean value that specifies whether or not a PropertySheet has an Apply button. Its default value is 1. Note that an Apply button is only actually used if Style is 'Standard'.


HasButtons Property
Applies To: TreeView

Description

The HasButtons property is a boolean value and specifies whether or not buttons are shown in a TreeView object. If HasButtons is 1 (the default) a square button is displayed to the left of each parent item label. If the item is expanded (i.e. is children are visible) the button contains a minus sign. If the item is not expanded, (i.e. its children are hidden) the button contains a plus sign. The user can cause a parent item to expand or collapse by clicking this button.


HasCheckBox Property
Applies To: DateTimePicker

Description

Specifies whether or not a checkbox is displayed alongside the value in a DateTimePicker.

HasCheckBox is a single number with the value 0 (the default) or 1. If HasCheckBox is 1, the user may set or clear the checkbox to indicate whether or not the date/time displayed in the object is to apply.

If the checkbox is not set, the DateTimePicker is considered to be empty (the contents will be grayed out) and the value returned by the DateTime property is zilde. Note that HasCheckBox may only be set when the object is created.


HasEdit Property
Applies To: BrowseBox

Description

Specifies whether or not a BrowseBox has an edit field.

HasEdit is a single number with the value 0 (the default) or 1. If HasEdit is 1, the user may type in the name of a folder or other resource that is the target of the BrowseBox. If HasEdit is 0, the user must browse to it.


HasHelp Property
Applies To: PropertyPage PropertySheet

Description

The HasHelp property is a boolean value For a PropertySheet, it determines whether or not the PropertySheet has a Help button. for a PropertyPage, HasHelp determines whether or not the Help button is active when the PropertyPage is the current page. If the HasHelp property of a PropertyPage is 0, the Help button on the parent PropertySheet will be temporarily disabled when that PropertyPage is displayed.


HasLines Property
Applies To: TreeView

Description

The HasLines property specifies whether or not tree lines are drawnin a TreeView object. It is a single integer with the value 0, 1 or 2:

0 | No tree lines
1 | Tree lines are drawn at all levels except the top level
2 | Tree lines are drawn at all levels

The user can cause a parent item to expand or collapse by clicking on its corresponding tree line.


HasTicks Property
Applies To: TrackBar

Description

The HasTicks property specifies whether or not tick marks are drawn in a TrackBar object. It is boolean value with a default value of 0.

The position of the tick marks in the TrackBar is determined by the TickAlign property.


HasToday Property
Applies To: Calendar DateTimePicker

Description

The HasToday property specifies whether or not the Today date is displayed in the bottom left corner of a Calendar object or in the dop-down calendar of a DateTimePicker.

HasToday is a single number with the value 0 (the date is not shown) or 1 (the date is shown); the default is 1.

See also CircleToday property.


Header Property
Applies To: ListView

Description

The Header property is boolean and specifies whether or not a ListView object displays column titles. Its default value is 1. Header applies only if the View property is 'Report'. The column titles are defined by the ColTitles property and their alignment by the ColTitleAlign property.

Note that Header may only be set by ⎕WC and may not subsequently be changed.


HeaderImageIndex Property
Applies To: ListView

Description

The HeaderImageIndex property is an integer vector that specifies the images to be displayed alongside each column heading in a ListView object in Report View. Each positive element of HeaderImageIndex specifies an index into the ImageList object specified by the HeaderImageList property. The special values ¯1 and ¯2 specify the standard Sort Up and Sort Down images respectively.


HeaderImageList Property
Applies To: ListView

Description

The HeaderImageList property specifies the name of or ref to an ImageList object that contains images to be displayed alongside each column heading in a ListView object in Report View.


HelpButton Property
Applies To: Form PropertySheet SubForm

Description

This is a Boolean property that specifies whether or not a Question (?) button appears in the title bar of a Form or SubForm. However, this does not apply if the Form has a maximise or minimise button which both take precedence. The user may obtain help by clicking on the Question (?) button and then on a control in the Form. It is up to you to provide the help by responding to the Help event on the control. The default value of HelpButton is 0.


HelpFile Property
Applies To: ActiveXControl OCXClass OLEClient

Description

The Helpfile property is a read-only property that reports the pathname of a Windows help file associated with a particular COM object.

For an OCXClass or OLEClient object, the HelpFile property is read-only.


HighlightHeaders Property
Applies To: Grid

Description

The HighlightHeaders property is a Boolean value (default 1) that specifies whether or not the appropriate row and column titles in a Grid are highlighted corresponding to the currently selected block of cells.


Hint Property

Applies To

Description

The Hint property is a character vector that specifies a help message that is to be displayed when the user positions the mouse pointer over the object. The Hint is displayed in the object specified by its HintObj property. A StatusField is often used for this purpose.


HintObj Property

Applies To

Description

The HintObj property is a character vector or ref that specifies the name of , or a ref to, an object in which the "help" message defined by the Hint property is to be displayed. This message is displayed when the user positions the mouse pointer over the object. The Hint is displayed by automatically setting the Caption or Text property of the object named by HintObj.

The following types of object can therefore be used to display Hints: Button, Edit, Combo, Group, Form, Label, Menu, MenuItem, StatusField, SubForm and Text. For a StatusField that has both Caption and Text properties, the text property is used for displaying hints.

When the user moves the mouse pointer away from the object, the Caption or Text property of the object specified by HintObj is reset to an empty vector.

Note that if HintObj is empty, its value is inherited from its parent. Thus setting HintObj on a Form defines the default location for displaying Hints for all the controls in that Form. Setting HintObj on Root defines the default location for hints for the entire application.


HotSpot Property
Applies To: Cursor

Description

This property specifies the point within a Cursor object that registers the cursor's position over another object. The mouse position, which is reported by various events, is actually the position of the cursor's HotSpot over the object in question.

HotSpot is a 2-element numeric vector that specifies the y-position and x-position of the hotspot within the cursor. A value of (0 0) specifies the top-left corner of the cursor; (31 31) specifies the bottom right corner of the cursor. The default value of HotSpot is (15 15).


HotTrack Property
Applies To: TabControl

Description

The HotTrack property specifies whether or not the tabs or buttons in a TabControl object ( which are represented by TabButton objects), are automatically highlighted by the mouse pointer.

HotTrack is a single number with the value 0 (no highlighting) or 1. The default is 0.

If HotTrack is 1 and the Style property of the TabControl is 'Tabs' or 'Buttons', the text defined by the Caption property of the TabButton is highlighted when the mouse pointer is placed over the tab or button. If Style is 'FlatButtons', the button is highlighted by being raised.

The value of HotTrack is effective only when the object is created with ⎕WC.


IconObj Property

Applies To

Description

This property is used to specify a large and small icon for a Form or SubForm, or for the Root object which represents your application as a whole. Its value is either a single ref or character scalar or vector containing the name of, or ref to, an Icon object, or a 2-element vector of character vectors or refs that specifies 2 Icon objects.

If empty (the default value), the standard "Dyalog APL GUI" icon is used.

The large and small icons are supplied to the Operating System which uses them as and when is appropriate. Normally, the large icon is of size 32x32 and the small icon is 16x16. If you specify an icon of a different size, the Operating System will scale it as appropriate.

The icon associated with a Form is displayed when the Form is minimised. The icon associated with '.' is displayed when the user presses Alt+Tab to toggle between applications. In both cases, the text shown underneath or alongside the icon is defined by the Caption property.

For an MDIClient, the IconObj property has no direct use, but is inherited by all its child SubForms. Thus if you want all your child SubForms to use the same icon, you need only define it once for the MDIClient.


ImageCount Property
Applies To: ImageList

Description

The ImageCount property is a read-only property that reports the number of images in an ImageList object. It is an integer scalar.


ImageIndex Property

Applies To

Description

For a ComboEx, ListView or TreeView, the ImageIndex property maps bitmapped images in an ImageList to items. ImageIndex is an integer vector whose length is the same as the number of items in the object. See also SelImageIndex

For a CoolBand, MenuItem, TabButton or ToolButton, ImageIndex specifies the picture to be displayed in the object. In these cases, ImageIndex is a single integer value.

ImageIndex is ⎕IO dependent.


ImageListObj Property

Applies To

Description

The ImageListObj property is a simple character vector or a ref, or a vector of character vectors or refs that specifies ImageList objects that are associated with an object.

For aComboEx or TreeView object, the ImageListObj property specifies the name of, or ref to, a single ImageList object that contains a set of images to be displayed alongside its Items. The image(s) displayed by a particular item in its normal (unselected) and selected states are specified by the corresponding element of the ImageIndex and SelImageIndex properties respectively.

For CoolBar, Menu, and TabControl objects, the ImageListObj property specifies the name of, or ref to, a single ImageList object that contains a set of images for its CoolBand, MenuItem, and TabButton children respectively.

For a ToolControl, ImageListObj may specifiy up to three ImageList objects that correspond to the three different states, normal, highlighted (hot) and inactive, of its ToolButton children.

In all these cases, individual images are mapped to the child objects by their ImageIndex property.

For a ListView either one or two ImageList objects may be specified. The first ImageList contains the large icon set of images. the second contains the small icon set. The set that is used is determined by the value of the View property. The mapping between the set of images in the ImageList and items in the object is determined by the ImageIndex property.


Indents Property
Applies To: ComboEx

Description

Specifies the amount by which items in a ComboEx object are indented.

Indents may be an integer scalar or a vector with the same number of elements as there are items in the ComboEx. Its default value is 0.

The unit of indenting is 10 pixels. For example, if there are 3 items and Indents is (0 1 2), the items will be indented by 0, 10 and 20 pixels respectively.


Index Property

Applies To

Description

For a List and a Combo with Style 'Simple', this property specifies the position of the data in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. The value of Index is dependent upon the value of ⎕IO. Note that Index for a Combo or List cannot be set using ⎕WC. The value of Index in a Combo with a drop-down list box (Style 'Drop' or 'DropEdit') is always equal to ⎕IO.

For a Grid, Index is a 2-element vector that specifies the row and column number of the cell that is currently in the top left corner of the Grid.

For a TreeView, Index is a positive integer value that specifies which item appears at the top of the TreeView window.

For a FileBox, the Index property determines which of the Filters is initially selected.

For a CoolBand, the Index property specifies the position of the CoolBand within its parent CoolBar, relative to the other CoolBands in the CoolBar.

The value of Index is dependent on ⎕IO, and its default value is equal to ⎕IO.


Input Property
Applies To: Grid

Description

This property specifies objects to be associated with cells in a Grid. These objects may be of type Button, ColorButton, Combo, Edit, Label, Spinner or TrackBar. In addition, the Input property may specify instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes).

The Input property is either a single ref or a simple character scalar or vector, or a vector of character vectors or refs. If it specifies a single object, this will be associated with all of the cells in the Grid. If it specifies a set of objects, these are mapped to individual cells through the CellTypes property.

When a cell becomes the current cell, its value (defined by the appropriate element of the Values property) defines the value of a corresponding property of the associated object The property that corresponds to the value in the cell, depends upon the Type of the associated object as shown in the following table:

Associate Object Type | Corresponding Property
Label | Text
Edit | Value
Combo | Text
Button (Style Push) | Caption
Button (Style Radio or Check) | State
ColorButton | CurrentColor
Spinner | Value
TrackBar | Thumb
OCXClass | Specified by InputProperties
NetType | Specified by InputProperties

In effect, the user inputs a new value into the current cell by changing the corresponding property of its associated object. An associated object may be a fixedobject that is external to the Grid or a floatingobject that moves automatically from cell to cell. The latter is achieved by creating the associated object as a child of the Grid.

If the associated object is an Edit or Combo, the user may change the Text property of the object by typing, or, in the case of a Combo, by selecting an item from a list. The new value of the Text property is then used to update the value in the cell (defined by the Values property of the Grid) when the user moves on. If the associated object is a radio button, the value in the cell (0 or 1) is reflected by the State property of the Button. The user may click the Button on and off, changing its State and thereby the corresponding value in the cell.

If the associated object is a ColorButton, the corresponding elements of the Values property contain 3-element integer vectors which specify the RGB colour values.

If the associated object is an instance of an OCXClass object (ActiveX control) or a NetType object (.NET class), the Grid uses the default property of the external object if it has one. Alternatively, the InputProperties property is used to specify which property (or properties) of the external object are to be mapped to elements of Values. If more than one property is specified, elements of Values are vectors.

If there is no object associated with a cell, or if its associated object is a Label or a Button with Style Push, the cell is protected and may not be changed by the user. When the current cell is thus protected, the corresponding row and column titles are not indented as they are when the cell may be edited.

If the associated object is a numeric Edit or Label (FieldType Numeric, LongNumeric, Currency, Date, LongDate or Time) the contents of the cell are formatted accordingly, even when it is not the current cell. Thus a cell associated with a Label with FieldType Date, always displays as a date.

If the associated object is a Combo or Button, the appearance of a non-current cell is defined by the corresponding element of the ShowInput property.

The following example illustrates the use of different types of object specified by the Input and ShowInput properties.


InputMode Property
Applies To: Grid

Description

This property determines editing behaviour and the action of the cursor movement keys when the user changes the contents of a Grid using a floating Edit or DropEdit Combo control.

InputMode is a character vector with one of the following values:

'Scroll' | The cursor keys move around the Grid; the user may switch to InCell mode.
'InCell' | The cursor keys move within the Input object; the mode reverts to Scroll when the user selects a new cell.
'AlwaysScroll' | The cursor keys move around the Grid; the user may not switch to InCell mode.
'AlwaysInCell' | The cursor keys move within the Input object, even when the user moves to a new cell
'AutoEdit' | See below

By default, the input mode is Scroll. In this mode, cursor movement keys are actioned by the Grid itself and used to move from cell to cell. The user may switch to InCell mode by double-clicking or by pressing the key defined by InputModeKey (the default is "F2").

In InCell mode, all cursor movement keys are actioned by the Input object and typically move the cursor around within the Input object and do not switch between cells. When the user switches to a different cell, InputMode reverts to Scroll mode

If InputMode is AlwaysScroll or AlwaysInCell, the user remains permanently in either Scroll or InCell mode respectively.

If InputMode is 'AutoEdit', the behaviour of a cell that contains a floating Input field is as follows:

When the user enters the cell, the contents are selected (and highlighted).At this stage, the cursor movement keys move to an adjacent cell. If the user presses a (valid) data key, that character replaces the current contents of the cell.

If the user presses F2 (or the key defined by the InputModeKey property), the data is de-selected and unhighlighted and the cursor is placed at the rightmost end of the data.

In either case, the left and right cursor keys now move the cursor within the current data string, but skip to the adjacent cell from the beginning or end of the data. This behaviour differs from InCell mode in which the cursor movement keys stick at the end of the data.


InputModeKey Property
Applies To: Grid

Description

This property defines the keystroke used to switch from Scroll mode to Incell mode in a Grid. It applies only where the Grid has a floating Edit control. See the description of the InputMode property for further details.

The InputModeKey property is specified (in the same way as the Accelerator property) as a 2-element vector of integer values containing the key number and shift state respectively. Its default is (113 0) which is "F2".

As an example, if you wanted to use Ctrl+Shift+a to switch modes, you would set InputModeKey to (65 3). 65 is the keynumber for "a" and 3 means Shift (1) + Ctrl (2).


InputProperties Property
Applies To: Grid

Description

The InputProperties property is a vector of character vectors that specifies the names of properties of an OCXClass (ActiveX Control) or .NET Class that are to be mapped to the Values property in a Grid.

When an ActiveX Control or .NET Class is used as a child of the Grid, InputProperties is used to specify how the value in each Grid cell corresponds to the value of one or more properties of the child object.

For example, suppose there is a third-party ActiveX Control that displays a playing card. The control has two properties named Suit and Value that specify the suit (1=clubs, 2=diamonds, 3=hearts, 4=spades) and card value (1="Ace", 2="2", …11="Jack",…) respectively. To display these cards in a Grid, the InputProperties property may be set to ('Suit' 'Value') and each element of the Values property must be a 2-element integer vector specifying the suit and value of the corresponding card.

     'CARDS'⎕WC'OCXClass' '...'
     'F'⎕WC'Form'
     'F.G'⎕WC'Grid'
     'F.G.card'⎕WC'CARDS'
     F.G.Input←'F.G.card'
     F.G.InputProperties←'Suit' 'Value'
     F.G.Values←⍳4 13

If InputProperties is not specified, the default property of the ActiveX Control or .NET Class is used.


InstanceMode Property
Applies To: OLEClient

Description

The InstanceMode property specifies how APL attempts to connect the OLEClient to an OLE Server.

InstanceMode is a character vector that may be 'ExistingFirst' (the default), 'ExistingOnly' or 'New'. Its value is effective only when the object is created with ⎕WC. Changing InstanceMode with ⎕WS has no effect.

If InstanceMode is 'ExistingFirst', APL attempts first to connect to a running instance of the OLE Server. If there is no running instance, it starts the OLE server to obtain a new object.

If InstanceMode is 'ExistingOnly', APL attempts to connect to a running instance of the object. If there is no running instance, it fails with a DOMAIN ERROR.

Note that in either case, if there is more than one instance running, there is no way to predict to which instance APL will be connected.

If InstanceMode is 'New', APL attempts to start the OLE Server to obtain a new object, whether or not the OLE Server is already running. However, if the OLE Server has registered itself as a single instance object and is already running, APL will be connected to it, and a second instance of the Server will not in fact be started.


Interval Property
Applies To: ProgressBar Timer

Description

Interval is an integer value specified in milliseconds and has a default of 1000.

For a Timer object, the Interval property specifies the frequency with which it generates Timer events. Setting Interval to 0 disables Timer events.

For a ProgressBar with ProgressStyle 'Marquee', Interval specifies the frequency with which the animated bar is updated. Setting Interval to ¯1 stops the animation.


Italic Property
Applies To: Font

Description

This property specifies whether or not a font represented by a Font object is italicised or not. It is either 0 (normal) or 1 (italic). There is no default; the value of this property reflects the characteristic of the selected font.


ItemGroupMetrics Property
Applies To: ListView

Description

This property is used to specify colours and spacing elements for a ListView that is displaying its Items in groupings (see ItemGroups).

Note that this feature only apples if Native Look and Feel is enabled.

ItemGroupMetrics is a 3-item nested vector as follows:

[1] | Text Colours | 2-element vector of 3 element RGB values that specifies the colour of the group caption and group footer respectively.
[2] | Spacing | 4-element integer vector that specifies the top, left, bottom and right spacing around each grouping in pixels
[3] | Border | Colours4-element vector of 3 element RGB values that specifies the colours for the top, left, bottom and right borders (not yet implemented).

The following expression, coupled with the code shown in the SetGroups example, causes the items to be displayed as shown below.

      F.L.ItemGroupMetrics[1 2]←(2⍴⊂255 0 0)(10 100 0 10)


ItemGroups Property
Applies To: ListView

Description

This property specifies item groupings for a ListView object.

Note that this feature only apples if Native Look and Feel is enabled.

ItemGroups is a nested scalar or nested vector each of whose elements specifies a grouping. Each grouping is a 5-element vector as follows:

[1] | Group caption | character vector
[2] | Item index | Vector of indices to the Items property that specifies which Items are in this grouping.
[3] | Caption alignment | an integer: 1 = left aligned caption (the default) 2 = centre aligned caption 4 = right-aligned caption
[4] | State | Integer (not yet implemented)
[5] | Footer text | character vector (not yet implemented)

Note that State and Footer text are not yet implemented by Windows.

For example, the following expressions executed in the WTUTOR95 workspace will result in the display shown below.

      'F'⎕WC'Form' 'ListView Object'
      II←⍳⍴COUNTRIES
      'F.L'⎕WC'ListView'COUNTRIES(0 0)(100 100)
                       ('ImageList' 'F.I1')
                       ('ImageIndex' (⍳⍴COUNTRIES))
      'F.I1'⎕WC'ImageList'('Size' 32 32)
      (⊂'F.I1.')⎕WC¨(⊂'Icon' ''),¨↓⍉↑FLAGBITS FLAGCMAP FLAGMASK
      GROUPS←⊂'Europe'(11 4 5 6 7 8 9)
      GROUPS,←⊂'Americas'(12 3 2)
      GROUPS,←⊂'Rest of the World'(1 10)
      F.L.ItemGroups←GROUPS

You can control the appearance of the groupings using the ItemGroupMetrics property.


Items Property
Applies To: Combo ComboEx List ListView Spinner TreeView

Description

This property specifies the list of items from which the user may choose.

The value of Items is a text array. It is normally specified as a vector of character vectors each of which represents an item. For a Combo, ComboEx, or List or Spinner, Items may also be a matrix whose rows specify items. If a character scalar or simple vector is specified, it is treated as a single item.

An empty character vector is treated the same as a vector of blanks, and represents one item.

A zero-length vector of vectors or an empty matrix represents 0 items. The default value for Items is an empty matrix.

⎕WG 'Items' returns an array of the same structure as was assigned by ⎕WC or ⎕WS.


Justify Property
Applies To: Button ButtonEdit Edit Label Spinner TabControl

Description

This property determines the manner in which text is justified within the object. It is a character vector that may take the value 'Left' (the default), 'Centre' or 'Right'. The keyword 'Centre' may also be spelled 'Center'.

When applied to an Edit object with Style 'Multi', a value of 'Centre' or 'Right' forces word-wrapping and disables horizontal scrolling. Note that Justify only applies to a multi-line edit field. If you specify a value for Justify in a 1-line edit field (Style 'Single'), it will be ignored.

For a TabControl, Justify may be 'Right' (which is the default) or 'None' or empty.

If Justify is 'Right', the TabControl increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control. Otherwise, if Justify is empty or 'None', the rows are ragged.

With the exception of Label and TabControl objects, Justify may only be specified when the object is created using ⎕WC.


KeepBits Property
Applies To: Bitmap Cursor Icon

Description

This property is be used to control the way that Bitmap, Cursor and Icon objects are stored in the workspace.

When you create a Bitmap, Icon or Cursor using ⎕WC, APL asks Windows to allocate a corresponding bitmap, icon or cursor resource. This resource is allocated in Windows memory. If APL were to hold the values of the image properties (CBits, Bits and CMap for a Bitmap; Bits, CMap and Mask for Cursor and Icon objects) internally in the workspace, this data would be duplicated. For large bitmaps this would have a serious impact on memory utilisation and may affect performance. The KeepBits property is provided to allow you to control whether or not APL retains the values of the image properties in the workspace, so that you can choose a strategy to suit your configuration and requirements. KeepBits may take the value 0 or 1.

If KeepBits is 0 the values of the image properties are not stored internally in your workspace. If you save a workspace containing a Bitmap, Cursor or Icon object, the corresponding Windows resource is automatically re-allocated when the workspace is loaded by referring to the associated file. This is the file whose full pathname is defined by the value of the object's File property. It follows that if you adopt this strategy, you must ensure that the File property is set correctly. If APL cannot find the file when the workspace is )LOADed, it cannot re-create the object, and you will get a VALUE ERROR when you subsequently refer to it. A further consideration is the effect on ⎕WG. If KeepBits is 0, and you execute ⎕WG 'CBits' or 'Bits' or 'CMap' or 'Mask', APL obtains these values by requesting the data from Windows.

If KeepBits is set to 1, the contents of the image properties are stored in the workspace, thus duplicating the information which is held by Windows itself. If you save a workspace containing a Bitmap, Cursor or Icon the corresponding Windows resource is automatically re-allocated from the image properties when the workspace is loaded. The value of the File property is ignored. When you execute ⎕WG 'CBits' or 'Bits' or 'CMap' or 'Mask', APL generates the result directly from the stored values held (internally) in the workspace.


KeepOnClose Property

Applies To

Description

This property is either 0 or 1 and determines how the object is treated when its parent Form (or, in the case of a Form, the Form itself) is closed by the user, receives a Close event from ⎕NQ, or when Close is called as a method.

If KeepOnClose is 1 (for the object itself and for all its parents) when its parent Form is closed, the object changes from being a GUI object to a pure namespace. For example, the Type of a Button will change from 'Button' to 'Namespace'. Effectively, the GUI component of the object is discarded but its Namespace component (and any variables, functions, operators and other namespaces that it contains) remains intact. Monadic ⎕WC may subsequently be used to re-attach the GUI component to the object.

Note that the default value of KeepOnClose depends upon the way in which a GUI object was created with ⎕WC. If a GUI object is created by dyadic ⎕WC, KeepOnClose defaults to 0. If a GUI object is attached by monadic ⎕WC, its KeepOnClose property defaults to 1.


LStyle Property
Applies To: Circle Ellipse Locator Poly Rect

Description

This property determines the type of line used to draw a graphics object. It takes one of the following integer values, or, if the object contains more than one component, a vector of such values.

0 | solid line
1 | dashed line
2 | dotted line
3 | dash dotted line
4 | dash dot dotted line
5 | null line (invisible)

If LStyle is in the range 1-4, the gaps between the dashes and dots are drawn using the colour specified by BCol, or are left undrawn (i.e. transparent) if BCol is not defined.

If LWidth specifies a line width greater than 1 pixel, the value of LStyle is ignored and a solid (thick) line is drawn regardless.


LWidth Property
Applies To: Circle Ellipse Poly Rect

Description

This property determines the width of line used to draw a graphics object. A positive value specifies the line width in pixels. A negative value specifies line width in units of the co-ordinate system defined for the object in the x direction. If the object contains more than one component, LWidth may be a vector.

In versions of Dyalog APL prior to 13.2 revision 19489, if LWidth specified a line width greater than 1 pixel, a solid line was drawn in the colour specified by the FCol Property, regardless of the value of LStyle. From that revision onwards, if the value of LWidth is greater than 1 then the value of LStyle is honoured, but only the FCol of the line is honoured - the BCol is still ignored.


LastError Property
Applies To: ActiveXControl OLEClient OLEServer Root

Description

The LastError property provides information about the most recent error reported by OLE. You may use this property to report an error from an OLEServer or ActiveXControl to a host application.


LicenseKey Property
Applies To: OCXClass

Description

The LicenseKey property is a character string that contains the license key for an ActiveX control.

If an ActiveX control requires a license key, it must be specified by an application when it creates an instance of the control. Typically, the license key is required only by the run-time version of an ActiveX control, and is made available to an application by the development version of the control.


Limits Property
Applies To: ProgressBar Scroll Spinner TrackBar UpDown

Description

This property is a 2-element vector that specifies the minimum and maximum values of an object. The values must be in the range (-2*31) to (¯1+2*31) inclusive.


LocalAddr Property
Applies To: TCPSocket

Description

The LocalAddr property is a character vector that specifies the IP address of your computer. Its default value is '0:0:0:0' which refers to your default IP address.

Unless your computer has more than one network adapter each identified by a different IP address, you do not need to specify LocalAddr. However, in this case you may use either LocalAddr or LocalAddrName to identify the adapter. If you specify both properties, the value of LocalAddrName will be ignored.

Note that you may also set the value of LocalAddr to an empty character vector. In this case, the value returned by ⎕WG will be '0:0:0:0'.

LocalAddr may only be specified in the ⎕WC statement that creates the TCPSocket and may not subsequently be changed using ⎕WS.


LocalAddrName Property
Applies To: TCPSocket

Description

The LocalAddrName property is a character vector that specifies the host name of your computer. It may be useful when you have more than one network adapter (perhaps an Ethernet adapter and a token ring adapter) and you wish to avoid hard-coding the IP address.

Note that you may use either LocalAddr or LocalAddrName to identify the local computer. If you specify both properties, the value of LocalAddrName will be ignored.

LocalAddrName may only be specified by a server TCPSocket. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified host name has been resolved to an IP address, the TCPSocket will generate a TCPGotAddr event and update the value of LocalAddr accordingly.

For a client TCPSocket, you may not specify LocalAddrName and ⎕WG returns an empty character vector.


LocalPort Property
Applies To: TCPSocket

Description

The LocalPort property is a scalar integer in the range 1-65536 that identifies the port number associated with a TCPSocket object.

Note that you may use either LocalPort or LocalPortName to identify the service. The use of LocalPortName is slightly slower but it avoids hard-coding the port number in your program and is generally more flexible. If you specify both properties, the value of LocalPortName will be ignored.

LocalPort may be specified only by the process that is initiating the connection (the server) and must be set by the ⎕WC statement that creates the TCPSocket. LocalPort may not subsequently be changed using ⎕WS

If you specify a value of 0, the system will assign an available port number. For example:

      'S1' ⎕wc'TCPSocket' ('LocalPort' 0)
      S1.LocalPort
4047

For a process that is completing a connection, LocalPort is allocated by the system and is effectively read-only.


LocalPortName Property
Applies To: TCPSocket

Description

The LocalPortName property is a character vector that specifies the port name of the local service that you wish to offer as a server.

Note that you may use either LocalPort or LocalPortName to identify the service. The use of LocalPortName is slightly slower but it avoids hard-coding the port number in your program and is generally more flexible. If you specify both properties, the value of LocalPortName will be ignored.

LocalPortName may be specified only by the process that is initiating the connection (the server) and must be set by the ⎕WC statement that creates the TCPSocket. LocalPortName may not subsequently be changed using ⎕WS.

When the specified port name has been resolved to a port number, the TCPSocket will generate a TCPGotPort event and update the value of LocalPort accordingly.

For a client TCPSocket, you may not specify LocalPortName and ⎕WG returns an empty character vector.


Locale Property
Applies To: OLEClient

Description

The Locale property specifies the language in which the OLE server, attached to an OLEClient, exposes its methods (functions) and properties (variables).

When you create an OLEClient object, Dyalog APL/W requests the default Type Library associated with the OLE server that you specify. Many OLE servers, such as Excel.Application, provide different names for the methods and properties they expose for different languages. Without Locale, it would be difficult to write an OLE client application that could run in different countries, as the names of the functions and variables may be unpredictable.

Locale is an integer; for example, the value 9 specifies English and the value 12 specifies French.

Locale may only be specified by the ⎕WC statement that is used to create the OLEClient; it may not subsequently be changed using ⎕WS. A table of commonly used Locale values is given below.

Note that Dyalog cannot guarantee that you will actually be given the Locale you specify. This is a function of your specific installation and the OLE server in question. However, Dyalog believes that for Microsoft products, it is a fairly safe bet that the US/English interface will be available in most countries.

Language | Locale
Neutral | 0
Danish | 6
Dutch | 19
English | 9
Finnish | 11
French | 12
German | 7
Italian | 16
Norwegian | 20
Portuguese | 22
Russian | 25
Spanish | 10
Swedish | 29


MDIActive Property
Applies To: MDIClient

Description

This property contains the name of the SubForm owned by the MDIClient that is currently active. Only one SubForm may be active at a time. You can switch between SubForms in an MDI application under program control by setting this property with ⎕WS. You can also do this by generating an MDIActivate event.

See also MDIActiveObject property.


MDIActiveObject Property
Applies To: MDIClient

Description

This property contains a ref to the SubForm owned by the MDIClient that is currently active.

See also MDIActive property.


MDIMenu Property
Applies To: MenuBar

Description

This property specifies the name of, or ref to, the Menu object that is nominated as the "Window" menu in an MDI application. If such a menu is defined, the Captions of all the child Forms are automatically added to it below any other Menu or MenuItem objects that the application has created directly. This list is separated from the preceding items by a separator. The entry for the currently active SubForm is checked and the user may switch between SubForms by selecting from this list.

Note that the additional separator and the items representing the list of child forms are not Dyalog APL/W objects and may not be accessed by the application. If you prefer to maintain your own "window list" you should not use this property.


MapCols Property
Applies To: ImageList

Description

The MapCols property specifies whether or not the button colours in bitmaps and icons in an ImageList are re-mapped to reflect the users colour preferences. If your bitmaps and icons represent buttons using the standard windows button colours, this property causes those colours to be changed to suit the user's own colour scheme.

MapCols is a single number with the value 0 (no colour mapping) or 1 (colours are automatically re-mapped. The default is 0.

If MapCols is 1, the following colour mappings are performed:

Colour | Description | Mapped to
0 0 0 | Black | Button Text
128 128 128 | Dark grey | Button Shadow
191 191 191 | Light grey | Button Face
192 192 192 | Light grey | Button Face
255 255 255 | White | Button Highlight


Mask Property
Applies To: Cursor Icon

Description

This property is used to specify how the bitmap for a Cursor or Icon interacts with the pixels of the screen when it is displayed.

When a Cursor or Icon is displayed, the colour of each pixel occupied by the object on the screen is determined by :

  • The colour specified by Bits via CMap
  • The value of Mask
  • The existing colour of the screen pixel

Mask is a boolean matrix with the same shape as the Bits property. See Cursor and Icon objects for further details.


MaskCol Property
Applies To: Bitmap Form

Description

Specifies the transparent colour for a Bitmap or Form.

MaskCol may be an integer scalar or a 3-element integer vector.

If MaskCol is 0 (the default), no transparent colour is defined.

If MaskCol is a negative scalar, it specifies a standard Windows colour. See Bcol for details.

Otherwise, MaskCol is a 3-element vector of intergers in the range 0-255 that specifies the transparent colour in terms of RGB values (the intensity of the red, green and blue components of colour).

For a Bitmap, if MaskCol is non-zero, any pixels specified with the same colour will instead be displayed in whatever colour is underneath the Bitmap. This achieves similar behaviour to that of an Icon.

For a Form, if MaskCol is non-zero, any of the contents of the Form that are specified to be the same colour as MaskCol will be transparent. For example, if MaskCol is 255 0 0 (red), any red items contained in the Form will instead be transparent areas, displaying whatever is behind them on the screen. Mouse events generated over such transparent areas will be passed to any other windows behind them, and will not be reported on the Form itself.


Masked Property
Applies To: ImageList

Description

The Masked property specifies whether or not the ImageList will contain opaque or transparent images. It may be 0, 1(the default) or 2.

Masked must be established when the ImageList is created by ⎕WC and may not subsequently be altered. An inappropriate value of Masked will cause the images to be drawn incorrectly.

If Masked is 0, the ImageList expects opaque BitMap objects.

If Masked is 1, the ImageList expects low-colour (4-bit or 8-bit) Icon objects whose transparency is defined by their Mask property.

If Masked is 2, the ImageList expects BitMap or Icon objects whose alpha channel (the degree of transparency of each pixel) is encoded in their CBits property, along with the colours.


MaxButton Property
Applies To: Form SubForm

Description

This property determines whether or not a Form or a SubForm has a "maximise" button. Pressing this button will cause a Form to be resized to occupy the entire screen, or a SubForm to occupy the entire area of its parent. Pressing it again will restore the Form or SubForm to its original size. MaxButton is a single number with the value 0 (no maximise button) or 1 (maximise button is provided). The default is 1.

Note that MaxButton is independent of Sizeable, i.e. you can define a Form that can be maximised but not resized. If any of the properties MaxButton, MinButton, SysMenu and Sizeable are set to 1, the Form or SubForm will have a title bar.


MaxDate Property
Applies To: Calendar DateTimePicker

Description

The MaxDate property specifies the largest date that the user may select in a Calendar object or in the calendar drop-down of a DateTimePicker.

MaxDate is an IDN value. Its default value is 11249470 which is the maximum date that the Calendar can display.


MaxLength Property
Applies To: ButtonEdit Edit Spinner

Description

This property specifies the maximum number of characters that the user may enter in a single-line Edit object ( Style 'Single') or in the edit field associated with a Spinner. It does not apply to a multi-line Edit object (Style 'Multi'). MaxLength does not limit the length of the vector that you may assign to the Text property using ⎕WC or ⎕WS. However, if you overfill the field in this way, the user must delete excess characters before the object will accept further input.


MaxSelCount Property
Applies To: Calendar

Description

The MaxSelCount property specifies the maximum number of contiguous days that the user may select in a Calendar object.

MaxSelCount is an integer whose default value is 7.

MaxSelCount is ignored unless the Style property of the Calendar object is set to 'Multi'.


MetafileObj Property
Applies To: Clipboard

Description

This property is used to copy graphical data to and from the Windows clipboard using the Windows Metafile format.

When you set the MetafileObj property of a Clipboard object to the name of the Metafile object using ⎕WS its contents are copied to the Windows clipboard in Windows Metafile format.

To import a picture that has been stored in the Windows clipboard in Metafile format you use ⎕WG. This returns a nested array whose elements correspond to the graphical components of the picture. Each of the elements of the array may be used as the arguments of ⎕WC to draw the corresponding component of the picture. For example, if the picture stored in C:\MSOFFICE\CLIPART\BIRD.WMF is copied to the Windows clipboard, it may be imported into Dyalog APL/W as follows :

      BIRD ← 'CL' ⎕WG 'MetafileObj'
      ⍴BIRD
4

Each of the items in BIRD is a 2-element vector. The first element is a "dummy" object name which you may use or ignore as you wish. The second element is an array that defines a graphical object and is suitable as the right argument of ⎕WC. For example :

      2⊃4⊃BIRD
POLY  191 397   FSTYLE  0   FILLCOL  0 0 0    ...

190 402
187 406
182 409
176 410
172 409
168 406
165 402
164 397
165 391
168 387
172 384
176 383
182 384
187 387
190 391
191 397
189 395
191 397

From this array, you can rebuild the imported picture component by component, either as a Metafile object or directly onto a Form, Static or another object. The following example draws the picture in a Form using the dummy names supplied.

      'TEST' ⎕WC 'FORM' ('Coord' 'User')
      'TEST' ⎕WS ('YRange' 0 1024)('XRange' 0 2048)
      TEST.⎕WC/¨BIRD

Notice that the co-ordinates of each of the graphical components are typically integers in a co-ordinate system that extends from 0 to 1024 in the y-direction and 0 to 2048 in the x-direction. The simplest way to draw the picture is therefore to set up the same co-ordinate system on a Form as in the example above.


MethodList Property

Applies To

Description

This property reports the names of all the methods supported by a particular COM object or instance of an OLE control. It is a vector of character vectors returned by ⎕WG. It may not be set using ⎕WC or ⎕WS.


MinButton Property
Applies To: Form SubForm

Description

This property determines whether or not a Form or SubForm has a "minimise" button. Pressing this button will cause the Form or SubForm to be iconified. Pressing it again will restore the Form to its original size. MinButton is a single number with the value 0 (no minimise button) or 1 (minimise button is provided). The default is 1.

Note that MinButton is independent of Sizeable, i.e. you can define a Form that can be minimised but not resized.

If any of the properties MinButton, MaxButton, SysMenu, and Moveable are set to 1, the Form or SubForm will have a title bar.


MinDate Property
Applies To: Calendar DateTimePicker

Description

The MinDate property specifies the smallest date that the user may select in a Calendar or DateTimePicker object.

MinDate is an IDN value. Its default value is -109206 which is the minimum date that the Calendar can display.


MonthDelta Property
Applies To: Calendar DateTimePicker

Description

The MonthDelta property specifies the number of months by which a Calendar object scrolls when the user clicks its scroll buttons.

MonthDelta is an integer or an empty vector (zilde). The latter means that the Calendar object scrolls by the number of months that are currently displayed in its window. This is the default.


Moveable Property
Applies To: Form SubForm

Description

This property determines whether or not a Form or SubForm can be moved by the user. It is a single number with the value 0 (Form cannot be moved) or 1 (Form is moveable). If any of the properties MinButton, MaxButton, SysMenu, and Moveable are set to 1, the Form or SubForm will have a title bar. However, a Form or SubForm with a title bar is not necessarily moveable.


MultiColumn Property
Applies To: List

Description

MultiColumn is boolean and specifies whether or not a List object displays its items in a single column (0, the default) or in multiple columns (1). MultiColumn may only be set by ⎕WC and cannot be changed using ⎕WS after the object has been created. Note that a MultiColumn List will use the minimum number of columns that are required to make the items fit within it and will reconfigure itself automatically when resized.

The following example illustrates its use.

      'F'⎕WC'Form' 'MultiColumn List'('Size' 23 32)
      'F.L'⎕WC'LIST' AIRPORTS (0 0)(100 100)('MultiColumn' 1)


MultiLine Property
Applies To: TabControl ToolControl

Description

The MultiLine property determines whether or not the tabs or buttons will be arranged in multiple flights or multiple rows/columns in a TabControl or ToolControl object.

MultiLine is a single number with the value 0 (single flight of tabs, or single row/column of buttons) or 1 (multiple flights of tabs or multiple rows/columns of buttons); the default is 0.

If MultiLine is 0 and there are more tabs or buttons than will fit in the space provided, the TabControl displays an UpDown which allows the user to scroll.

However, If MultiLine is 0 in a ToolControl, the buttons are clipped, and the user may have to resize the object to see them all.

See also: Justify, TabSize.


MultiSelect Property
Applies To: TabControl

Description

The TabControl property specifies whether or not the user can select more than one button in a TabControl at the same time, by holding down the Ctrl key when clicking.

MultiSelect is a single number with the value 0 (only 1 button may be selected) or 1 (more than one button may be selected); the default is 0.

MultiSelect apples only if the Style of the TabControl is 'Buttons' or 'FlatButtons', and is ignored if Style is 'Tabs'.

Note that the State property of the associated TabButton object reports whether or not the button is selected.


NewLine Property
Applies To: CoolBand

Description

The NewLine property specifies whether or not a CoolBand occupies the same row as an existing CoolBand, or is displayed on a new line within its CoolBar parent.

NewLine is a single number with the value 0 (same row) or 1 (new row); the default is 1.

The value of NewLine in the first CoolBand in a CoolBar is always 1, even if you specify it to be 0.

When the user drags a CoolBand to another row, the value of its NewLine property, and that of any other CoolBand affected by the move, will change.

You may move a CoolBand to the previous or next row by changing its NewLine property (using ⎕WS )from 1 to 0, or from 0 to 1 respectively.


Note Property
Applies To: Button

Description

The Note property applies only to a Button whose Style is 'CommandLink'.

It is a character vector (by default empty) that specifies text to be displayed below the Caption.

Example:

'F'⎕WC'Form' 'CommandLink Button'
'F.clb'⎕WC'Button' 'Visit Us'('Style' 'CommandLink')
F.clb.Size←80 200
F.clb.Note←'www.dyalog.com'


OKButton Property
Applies To: Form

Description

OKButton applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies whether or not an [OK] button appears in the title bar of a Form. Its default value is 0.

OKButton may only be specified when the Form is created using ⎕WC; you cannot subsequently change its value.

If OKButton is 1, the Form displays an [OK] button in its title bar in place of the standard [X] button.

When the user clicks the [OK] button, the system will press the default button, which is specified by the Default property of a Button on the Form.

If there is no default button, the Form will generate a Close event.


OLEControls Property
Applies To: Root

Description

The OLEControls property reports a list of the OLE Controls installed on your computer. This information is obtained from the Windows registry. Its value is a nested vector with one element per OLE Control. Each element is a vector of 2-element character vectors. The first is the name of the OLE Control; the second is its class identifier.


OLEServers Property
Applies To: Root

Description

The OLEServers property is a read-only property that reports the names and CLSIDs of all the OLE Automation servers installed on your computer. This information comes from the Windows registry.

Its value is a nested vector with one element per OLE Server.

Each element is a vector of 2-element character vectors. The first is the name of the OLE Server; the second is its class identifier or CLSID which is a type of GUID.


OnTop Property

Applies To

Description

This property may be used to cause a Form or SubForm to be displayed on top of all other windows, even those owned by other applications.

Normally, Forms are brought to the front when they receive the input focus. Forms that do not have the input focus may be partially obscured by the one that does. If OnTop is set to 1, the Form or SubForm remains at the front even if it doesn't have the input focus. Indeed, it may partially obscure the Form that does have the focus. The default value is 0 (normal).

More than one Form may have OnTop set to 1. If so, these Forms appear on top of all others, but may overlap one another. Other applications may also have windows with this property.

For a graphical object, the OnTop property controls how it is drawn in a Grid relative to the grid lines and cell text. OnTop is applicable only if the graphic is the child of a Grid and is otherwise ignored.

0 | Graphical object is drawn behind grid lines and cell text
1 | Graphical object is drawn on top of grid lines but behind cell text
2 | Graphical object is drawn on top of grid lines and cell text


Orientation Property
Applies To: Printer

Description

The Orientation property specifies the orientation of the paper on a Printer object. It is a simple character vector which is either 'Portrait' or 'Landscape'. When you create a Printer object, the default value of the Orientation property is determined by the current setting for the corresponding printer device.

The effect of changing Orientation using ⎕WS is to spool the current page (effectively the same as sending a NewPage event) and then to change the orientation of the paper. Note that the values of the first 2 elements of the DevCaps property change accordingly. You may also set Orientation when you create the Printer object with ⎕WC. In neither case does the global setting for the printer device change.


OtherButton Property
Applies To: ColorButton

Description

The OtherButton property is Boolean and specifies whether or not the user can select a colour from a ColorButton object using the Windows colour selection dialog box.

If OtherButton is 1 (the default), the final row of the colour selection drop-down contains a button labelled "Other…". If the user clicks this button, the standard Windows colour selection dialog box is displayed, allowing the user to select any colour that the computer can render.

If OtherButton is 0, the button labelled "Other…" is not present and the user is restricted to the choice of colours provided by the DefaultColors property.


OverflowChar Property
Applies To: Grid

Description

The OverflowChar property specifies the character to be displayed in place of the digits when a numeric value cannot be displayed in its entirety in a Grid cell. If the value of OverflowChar is an empty vector (the default) the data in a numeric cell is simply clipped if it is too wide to fit in the cell. For example:

   'F'⎕WC'Form'('Coord' 'Pixel')('Size' 101 296)
   'F'⎕WS'Caption' 'OverflowChar Property'
   DATA←3 3⍴12 123456789 13 9876543 99 456 10 99 1236.893
   'F.G'⎕WC'Grid'DATA(0 0)(101 296)
   'F.G'⎕WS'CellWidths' 65
   'F.G'⎕WS'OverflowChar' '#'

The same Grid without OverflowChar being defined appears as follows. Notice how the numbers have been truncated


PName Property
Applies To: Font Printer

Description

This property is a character vector that specifies the face name for a Font object, or the printing device associated with a Printer. It is case-independent.

For a Printer, PName contains the description of the printer followed by a comma (,) and then the device to which it is attached.

Example:

      'PR1' ⎕WC 'Printer'
      'PR1' ⎕WG 'PName'
HP Universal Printing PS,hp4200


PageActive Property
Applies To: PropertySheet

Description

The PageActive property specifies the name of the current PropertyPage in a PropertySheet. You may select a particular page by setting this property or by generating a PageActivate event.

See also or PageActiveObject.


PageActiveObject Property
Applies To: PropertySheet

Description

The PageActiveObject property specifies a ref to the current PropertyPage in a PropertySheet. You may select a particular page by setting this property or by generating a PageActivate event.

See also or PageActive.


PageSize Property
Applies To: Form Scroll SubForm

Description

For a Form and SubForm, the PageSize property is a 2-element integer vector which specifies the size of the thumb in the vertical and horizontal scrollbars respectively.

For a Scroll object it is a single integer.

If PageSize is 0 (the default) it specifies the default thumb. Otherwise, PageSize is expressed in proportion to the corresponding value of Range. For example, if Range is 1000, setting PageSize to 100 will obtain a thumb which is approximately 10% of the height or length of the scrollbar.


PageWidth Property
Applies To: RichEdit

Description

The PageWidth property specifies the width of the page in a RichEdit object and is the dimension that is used to apply text wrapping and paragraph formatting to the text in the object. PageWidth is a single integer value specified in Twips.

The default value of PageWidth is 0 which disables text wrapping. You may find it convenient to set PageWidth to the width of the RichEdit window or to a value that is appropriate for your printer.


PaperSize Property
Applies To: Printer

Description

The PaperSize property specifies the size of paper to be used for printing

PaperSize may be a character vector containing the name of the paper size (eg. 'Legal 8 1/2 x 14 in' or 'A4 210 x 297 mm') or a 2-element integer vector that specifies the desired height and width of the paper in tenths of a millimetre (e.g. 3556 2159 or 2970 2099).

The default value of PaperSize is the name of the paper size associated with the current printer settings.

You can obtain a list of supported paper sizes from the PaperSizes property.


PaperSizes Property
Applies To: Printer

Description

The PaperSizes property is a read-only property that provides the names and dimensions of the various different paper sizes supported by the printer associated with the Printer object.

PaperSizes is a nested vector of 2-element vectors which contain the name, and height and width of each paper size respectively. Dimensions are reported in tenths of a millimetre.

You may set or query the current paper size using the PaperSize property.


PaperSource Property
Applies To: Printer

Description

The PaperSource property is a character vector that specifies the name of the paper bin to be used as the paper source for printing.

An empty character vector (the default) means the default bin, Otherwise, PaperSource must be a member of the PaperSources property.


PaperSources Property
Applies To: Printer

Description

The PaperSources property is a read-only property that provides the names of the paper bins installed on the printer associated with the Printer object. It is a vector of character vectors.

You may select which of the bins is to be used by specifying the PaperSource property.


ParaFormat Property
Applies To: RichEdit

Description

The ParaFormat property describes the current paragraph format or the paragraph format of the currently selected text in a RichEdit object. It is a 6-element nested array structured as follows:

[1] | A character vector that specifies the text alignment. This may be 'Left' (the default), 'Right' or 'Centre'
[2] | The size of the indentation of the first line in the paragraph measured from the left margin in Twips.
[3] | The size of the horizontal offset of the start of the second and subsequent lines. This is measured in Twips relative to the first line indentation specified in element [2].
[4] | The size of the right indentation measured in Twips from the right margin.
[5] | An integer value specifying the bullet/numbering option. 0 mean no numbering, 1 means bullets.
[6] | An integer vector specifying the size of any tab stops measured in Twips from the left margin and specified in ascending order.

If there is no text selected, ParaFormat specifies the current paragraph formatting format, i.e. that which will be used to format the current (and subsequent) lines of characters that the user enters. If there is text selected ParaFormat specifies the paragraph formatting of the selected block of text. If the format is not strictly homogeneous, ⎕WG will report the format of the first paragraph in the selected block

(⎕WS 'ParaFormat' ...) will set the format of the currently selected block of text. To set the format of an arbitrary block of text you must select it first using (⎕WS 'SelText' ...).


Password Property
Applies To: ButtonEdit Edit Spinner

Description

This property specifies the character that is echoed when a user enters data into a single-line Edit object ( Style 'Single'). It does not apply to a multi-line object (Style 'Multi'). If Password is empty (the default) the character echoed is the same as the character the user entered. If Password is set to (say) the asterisk character (*), the object will display asterisks as the user types into it.


PathWordBreak Property
Applies To: ComboEx

Description

If set, the edit control portion of the ComboEx will use the forward slash (/), back slash (\), and period (.) characters as word delimiters. This makes keyboard shortcuts for word-by-word cursor movement (Ctrl + arrow keys) effective inn path names and URLs.


Picture Property

Applies To

Description

The Picture property specifies a bitmap, icon, or other image for an object.

For Button, Form, Group, MDIClient, Static, StatusBar, StatusField, SubForm, SM, TabBar or ToolBar, this property specifies the name of, or ref to, a Bitmap, Icon, or Metafile which is drawn as a background on the object. Other controls and graphical objects are drawn on top of this background.

When it refers to a Metafile, the Picture property specifies the name of, or ref to, the Metafile to be drawn in the object. When it refers to a Bitmap or Icon, the value of the Picture property is a 2-element vector whose elements specify the name of, or ref to, the Bitmap, or Icon, and the manner in which it is displayed. This is specified as an integer as follows:

0 | The Bitmap or Icon is drawn in the top left corner of the object.
1 | The Bitmap or Icon is tiled (replicated) to fill the object.
2 | The Bitmap is scaled (up or down) to fit exactly in the object. This setting does not apply to an Icon whose size is fixed.
3 | The Bitmap or Icon is drawn in the centre of the object. This is the default. Note that the centre of the Bitmap is positioned over the centre of the object, so that you see the middle portion of a Bitmap that is larger than the object in which it is displayed.

For example, the following statements produce a Form filled with the CARS bitmap.

      'CARS' ⎕WC 'Bitmap' 'C:\WINDOWS\CARS'
      'f1' ⎕WC 'Form' ('Picture' 'CARS' 1)

An easy way to provide a customised pushbutton is to create a Button whose Picture property specifies the name of, or ref to, a Bitmap or Icon, using drawmode 3 (the default). This causes the corresponding bitmap or icon to be drawn in the centre of the Button. So long as the Button is larger than the bitmap or icon, its borders (which give it its 3-dimensional appearance and "pushbutton" behaviour) will be unaffected. Note that if Picture is set on a Button whose Style is 'Radio' or 'Check', the Button assumes pushbutton appearance, although its radio/check behaviour is preserved.

For an Image object, the Picture property specifies the name of, or ref to, a Bitmap, Icon or Metafile object to be drawn, or a vector of names or refs. The Image is a graphical object and is drawn on top of the background. It does not support the drawmode options provided by the objects in which Picture specifies the background.

For the Clipboard object, Picture is a "set-only" property that allows you to place a specified Bitmap object into the Windows clipboard. To place a Metafile object into the clipboard, use its Metafile property.


Points Property

Applies To

Description

This property specifies the co-ordinates for a graphics object. It may define a single set of co-ordinates, or be a nested vector containing several sets of co-ordinates.

Each set of co-ordinates may be:

  • a 2-column numeric matrix containing y-values in column 1 and x-values in column 2. or
  • a 2-element numeric vector whose first element specifies y-values and whose second element specifies x-values. The two elements must be of equal length unless one or both is a scalar in which case scalar extension applies.

For further details, see the specifications for the relevant objects.


Popup Property
Applies To: SysTrayItem ToolButton

Description

The Popup property specifies the name of, or ref to, a (popup) Menu object that is associated with a SysTrayItem or ToolButton.

Note that Popup is ignored unless Style is set to 'DropDown'.


Posn Property

Applies To

Description

With the exception of Menu, MenuItem and Separator objects, Posn is a 2-element numeric vector specifying the y-position and x-position respectively of the top-left corner of the object relative to its parent. For a Form, Posn specifies its position on the screen. The units are defined by the Coord property.

When specifying Posn for ⎕WC, you can allow the y-position or x-position to assume a default value by giving the corresponding element a value of ⍬.

Using ⎕WS, if you want to set the y-position, but not the x-position, or vice-versa, you should specify ⍬ for the item you don't want to change.

For Menu, MenuItem and Separator objects, Posn is a single integer that specifies the position at which the object is to be inserted in its parent. For example, to add a new MenuItem between the third and fourth items in an existing Menu, you would specify its Posn as 4. For these objects, the value of Posn returned by ⎕WG is the current index of the object within its parent.


PrintList Property
Applies To: Root

Description

This property provides a list of the printers that are installed on your computer system, i.e. those listed when you select "printers" from the MS-Windows Control Panel. It is a "read-only" property of the Root object '.'.

PrintList is a vector of character vectors. Each item in PrintList contains the name of an installed printer followed by a comma (,) and then the name of the device to which it is attached. The first item in PrintList is the default system printer.

Example:

      ⍴'.'⎕WG'PrintList'
6
      ]display ⊃'.'⎕WG'PrintList'
┌→─────────────────────┐
│KODAK ESP-3 AiO,USB001│
└──────────────────────┘
      ↑'.'⎕WG'PrintList'
KODAK ESP-3 AiO,USB001
Send To OneNote 2007,Send To Microsoft OneNote Port:
Microsoft XPS Document Writer,XPSPort:
Microsoft Office Document Image Writer,Microsoft Document Imaging Writer Port:
Fax,SHRFAX:
Auto Canon MP600 Printer on DIMENSION5150,\\DIMENSION5150\Canon


PrintRange Property
Applies To: Printer

Description

The PrintRange property specifies the range of pages to be printed.

PrintRange may be an empty character vector (the default), or 'All', either of which will cause all pages to be printed.

Alternatively, PrintRange may be a 3 or 4-element nested array whose items are:

[1] | 'Pages'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum number of pages (integer)

In this case, printing starts at the page specified to be the Start page, and ends at the page specified by End page or after the Maximum number of pages has been reached, whichever is sooner.


ProgressStyle Property
Applies To: ProgressBar

Description

The ProgressStyle property specifies the appearance of a ProgressBar control.

ProgressStyle is a character vector that may be 'Normal', 'Smooth' or 'Marquee'. Its value is effective only when the object is created with ⎕WC. Changing ProgressStyle with ⎕WS has no effect on the appearance or behaviour of the ProgressBar.

If ProgressStyle is 'Normal', the highlight in the centre of the ProgressBar is displayed as a broken bar. This is the default.

If ProgressStyle is 'Smooth', the highlight in the centre of the ProgressBar is displayed as a solid block of colour. This style only applies if Windows Classic Theme is in use. If not, it will be as if 'Normal' were specified.

If ProgressStyle is 'Marquee', the highlight in the centre of the ProgressBar is displayed as a broken bar that moves continuously from left to right. The speed is controlled by the Interval Property which determines the frequency in milliseconds with which the highlight is redrawn, each time further along the ProgressBar. The special value of ¯1 causes the animation to stop.

Note that this feature only apples if Native Look and Feel is enabled. If not, 'Marquee' will produce the same behaviour as 'Normal'.

The pictures below illustrate the appearance of the different values of ProgressStyle.

ProgressStyle Normal (the default)

ProgressStyle Smooth (Windows Classic Theme only)

ProgressStyle Marquee (requires Native Look and Feel)


PropList Property

Applies To

Description

This is a "read-only" property that supplies a list of all other properties which are applicable to the object in question. The list is returned as a vector of character vectors in the order in which the corresponding properties are expected by ⎕WC and ⎕WS.

Example:

      'F'    ⎕WC 'Form'
      'F.MB' ⎕WC 'MenuBar'
      'F.MB' ⎕WG 'PropList'
 Type  Visible  FontObj  Data  EdgeStyle  MDIMenu  PropList


QueueEvents Property
Applies To: OCXClass OLEClient

Description

The QueueEvents property specifies whether or not incoming events generated by an COM object are queued. It is a Boolean value where the (default) value 1 specifies that events are queued, and 0 that they are not.

If QueueEvents is 1, the result (if any) of your callback function is not passed back to the COM object but is discarded. Thus you cannot, for example, inhibit or modify the default processing of the event by the COM object.

If QueueEvents is 0, the following applies.

  • The callback function attached to the event is executed immediately, even if there are other APL events before it in the internal event queue. This immediate execution means that your callback can fire during the execution of any other function, including a callback function on an APL event. You must therefore take care that the callback makes no references to objects that may be shadowed.
  • The result of your callback function is then passed back to the COM object. In this situation, it is essential that the callback is not interrupted by other events from the same, or another instance, of an COM object.
  • To prevent APL itself from yielding to Windows, the Yield property is temporarily set to 0 while the callback is run. For the same reason, the tracing of a callback function, that is run immediately in this way, is disabled.

However, you must yourself also ensure that your own code does not yield. This means that you may not perform any operation in your callback that would yield to Windows; these include:

  • ⎕DL
  • certain uses of ⎕NA
  • external function calls to Auxiliary Processors

If your callback does yield to Windows, thereby allowing another COM object event to arrive, this second event and any subsequent events that arrive during the execution of the callback are queued and will be processed later. These events may therefore not be modified by their callback functions.


RTFText Property
Applies To: Clipboard RichEdit

Description

The RTFText property is used to set or retrieve the contents of a Clipboard or a RichEdit object in rich text format (RTF). It is always a character vector.


Radius Property
Applies To: Circle Rect

Description

For a Circle object, this property is a single number that specifies the radius of the circle/arc or a numeric vector that specifies the radii of a set of circles/arcs.

For a Rect object, Radius is a 2-element vector that specifies the curvature of the corners of the rectangle or set of rectangles to be drawn. The curvature is defined in terms of the vertical and horizontal radii of an ellipse. The first element of Radius defines the radius vertically, the second horizontally. If more than one rectangle is involved, either or both of the elements of Radius may be vectors. The default value is (0,0) which gives square corners.


RadiusMode Property
Applies To: Circle Root

Description

A perfectly round circle can only be drawn if the diameter is an odd number of pixels. The RadiusMode property specifies whether or not a circle is adjusted by a single pixel, if necessary, so as to appear perfectly round.

If RadiusMode is 1 or ¯1, and the diameter is an even number of pixels, the circle is actually drawn with a diameter of 1 pixel more or less than specified. If RadiusMode is 0 (the default), no such adjustment is made.

RadiusMode may be set on the Root object to be inherited by all Circle objects.


Range Property
Applies To: Form Scroll SubForm

Description

This property determines the maximum value of the thumb in a scrollbar (the minimum value is always 1). This may be any positive integer value that is greater than 1.

For a Scroll object Range is a single number. For a Form or SubForm object, Range is a 2-element vector which specifies the maxima for the Form's vertical and horizontal scrollbars respectively.


ReadOnly Property
Applies To: Button ButtonEdit Edit Spinner

Description

This property specifies whether or not the user may alter the text in an object. The default value of ReadOnly is 0 which allows the user to alter text.

If you set ReadOnly to 1, a cursor is displayed in the object, the user may navigate around the text in the usual manner with the mouse and/or the keyboard and select text and copy it to the clipboard. However, all input that would otherwise change the data is ignored.

For a Button object with Style 'Radio' or 'Check', setting ReadOnly to 1 prevents the user from changing the state of the Button, although mouse and other events will still be reported.


RealSize Property
Applies To: Metafile

Description

There are several distinct types of Windows metafiles. A placeable metafile is one that carries with it its suggested size. Certain programs (such as Word for Windows) only support placeable metafiles.

The RealSize property specifies the suggested size of a Metafile in units of 0.01mm. Thus to make a placeable Metafile with a suggested size of 20 x 10 cm, you would set RealSize to (20000 10000).

The RealSize property is not used or required by Dyalog APL/W and is provided only to enable you to make and save a new metafile that is placeable. If you create a Metafile object from a file, the value of RealSize will be obtained from the value recorded in the file (if it is placeable). Otherwise, RealSize will be (0 0). If so, you must set RealSize to make it placeable. Each element of RealSize must be an integer in the range 0-144745.


Redraw Property

Applies To

Description

The Redraw property specifies whether or not APL automatically redraws an object when it is exposed or when any of its properties change in a way that would affect its appearance.

The value reported by the Redraw property is a Boolean value; 1 means that APL automatically redraws the object when necessary (the default); 0 means that APL does not redraw the object.

Setting Redraw to 0 or 1 affects only whether or not APL will redraw the object from then on.

In addition to the values 0 and 1, you may set Redraw to 2. This has the same effect as setting it to 1, but object is also redrawn immediately.


RemoteAddr Property
Applies To: TCPSocket

Description

The RemoteAddr property is a character vector that specifies the IP address of the remote computer.

RemoteAddr may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

You may use either RemoteAddr or RemoteAddrName to identify the remote computer. If you know its IP address, it is normally quicker to specify RemoteAddr. If you specify both properties, the value of RemoteAddrName will be ignored.

For a server TCPSocket, RemoteAddr is determined by the IP address of the connecting process and is a read-only property.


RemoteAddrName Property
Applies To: TCPSocket

Description

The RemoteAddrName property is a character vector that specifies the host name of the remote computer to which you wish to make a connection.

RemoteAddrName may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified host name has been resolved to an IP address, the TCPSocket will generate a TCPGotAddr event and update the value of RemoteAddr accordingly.

Note that you may use either RemoteAddr or RemoteAddrName to identify the remote computer. If you know its IP address, it is normally quicker to specify RemoteAddr. If you specify both properties, the value of RemoteAddrName will be ignored.

For a server TCPSocket, you may not specify RemoteAddrName and ⎕WG returns an empty character vector.


RemotePort Property
Applies To: TCPSocket

Description

The RemotePort property is a scalar integer in the range 1-65536 that identifies the port number associated with a service on a remote computer.

RemotePort may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

Note that you may use either RemotePort or RemotePortName to identify the remote service. If you know the port number, it is normally quicker to specify RemotePort. However unless it is a well known port number, the use of a port name is generally more flexible. If you specify both properties, the value of RemotePortName will be ignored.

For a server TCPSocket, RemotePort is determined by the port number of the connecting process and is a read-only property.


RemotePortName Property
Applies To: TCPSocket

Description

The RemotePortName property is a character vector that specifies the port name of the remote service to which you wish to make a connection.

RemotePortName may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified port name has been resolved to a port number, the TCPSocket will generate a TCPGotPort event and update the value of RemotePort accordingly.

Note that you may use either RemotePort or RemotePortName to identify the remote service. If you know the port number, it is normally quicker to specify RemotePort. However unless it is a well known port number, the use of a port name is generally more flexible. If you specify both properties, the value of RemotePortName will be ignored.

For a server TCPSocket, you may not specify RemotePortName and ⎕WG returns an empty character vector.


ReportBCol Property
Applies To: ListView

Description

In Report View, the ReportBCol property is either a scalar or a matrix that specifies the background colours for each item displayed in a ListView object .

Its first column refers to the Items themselves, and subsequent columns to the elements of ReportInfo.

i.e. if non-scalar, (⍴ReportBCol)←→(0 1+⍴ReportInfo)

Each element of ReportBCol is either an integer colour value or a 3-element of RGB colour indices.

For further information, see BCol.


ReportImageIndex Property
Applies To: ListView

Description

The ReportImageIndex property is an integer scalar or matrix that specifies the images to be displayed alongside each item in a ListView object in Report View.

If it is a matrix, its first column specifies the indices of the icons to be displayed against the Items of the ListView, overriding the icons specified by ImageIndex, and its subsequent columns specify the indices of the icons to be displayed against the elements of ReportInfo.

i.e. if non-scalar, (⍴ReportImageIndex)←→(0 1+⍴ReportInfo)

Each element of ReportImageIndex specifies an index into the ImageList object specified by the ImageListObj property.


ReportInfo Property
Applies To: ListView

Description

The ReportInfo property is a matrix that is displayed alongside each item in a ListView object when its View property is 'Report'. Each element of the matrix may be a character vector or a number.

The information is displayed in a grid format, the first column of which contains the item labels and their icons. Subsequent columns of the grid are defined by the corresponding columns of ReportInfo. The alignment of the columns is specified by the ColTitleAlign property.


ResizeColTitles Property
Applies To: Grid

Description

This property determines whether or not the user may alter the height of the column titles in the Grid. It is either 1, which indicates that the height of the column titles is adjustable by the user, or 0 which means that it is not.

If the height of the column titles is adjustable, the cursor changes to a double headed arrow when the mouse pointer is placed over the top border of the first row title The user may resize the column titles by dragging this border. The user may also resize the column titles by double-clicking over this border. This causes the column titles to be resized to fit the data and the height of the column titles is automatically adjusted to display the tallest heading in any of its columns. Either operation generates a SetRowSize event. The value of the row number reported by the event is ¯1.

Note that the user may cause the column titles to disappear altogether by dragging them to a zero height. Once this has been done, the row titles cannot be restored.


ResizeCols Property
Applies To: Grid

Description

This property determines whether or not the user may resize columns in the Grid. It is a boolean scalar or vector with one element per column. A value of 1 indicates that the corresponding column is resizable by the user. A value of 0 means that the corresponding column may not be resized by the user.

If a column is resizable, the cursor changes to a double headed arrow when the mouse pointer is placed over the right-hand border of the column title. The user may resize the column by dragging this border. The user may also resize a column by double-clicking over its right-hand border. This causes the column to be resized to fit the data and the width of the column is automatically adjusted to display the widest value in any of its cells. Either operation generates a SetColSize event.

Note that the user may cause the column to disappear altogether by dragging it to a zero width. Once this has been done, this column may only be restored if the column to its left is itself not resizable.


ResizeRowTitles Property
Applies To: Grid

Description

This property determines whether or not the user may alter the width of the row titles in the Grid. It is either 1, which indicates that the width of the row titles is adjustable by the user, or 0 which means that it is not.

If the width of the row titles is adjustable, the cursor changes to a double headed arrow when the mouse pointer is placed over the left-hand border of the first column title. The user may resize the row titles by dragging this border. The user may also resize the row titles by double-clicking over this border. This causes the row titles to be resized to fit the data and the width of the row titles is automatically adjusted to display the longest string in any of its rows. Either operation generates a SetColSize event. The value of the column number reported by the event is ¯1.

Note that the user may cause the row titles to disappear altogether by dragging them to a zero width. Once this has been done, the row titles cannot be restored.


ResizeRows Property
Applies To: Grid

Description

This property determines whether or not the user may resize rows in the Grid. It is a boolean scalar or vector with one element per column. A value of 1 indicates that the corresponding row is resizable by the user. A value of 0 means that the corresponding row may not be resized by the user.

If a row is resizable, the cursor changes to a double headed arrow when the mouse pointer is placed over the lower border of the row title. The user may change the height of the row by dragging this border up and down. The user may also resize a row by double-clicking over its bottom border. This causes the row to be resized to fit the data and the height of the row is automatically adjusted to display the tallest value in any of its cells. Either operation generates a SetRowSize event.

Note that the user may cause the row to disappear altogether by dragging it to a zero height. Once this has been done, this row may only be restored if the row above it is itself not resizable.


Resolution Property
Applies To: Printer

Description

The Resolution property determines the print resolution.

You may set Resolution to 'Draft', 'Low', 'Medium' or 'High'.

Alternatively, you can set Resolution to a 2-element integer vector that specifies the desired number of dots per inch in the x (horizontal) and y (vertical) direction respectively.

The initial value reported by Resolution may be reported in either form (character vector or 2-element numeric vector) according to the current printer settings.


Resolutions Property
Applies To: Printer

Description

The Resolutions property is a read-only property that reports the available printer resolutions.

Resolutions is a vector of 2-element integer vectors each of which specifies the number of dots per inch in the x (horizontal) and y (vertical) directions respectively.


Rotate Property
Applies To: Font

Description

This property specifies the angle of rotation of the font measured in radians (0 → ○2) from the x-axis in a counter-clockwise direction. Note that only TrueType fonts can be rotated. Rotated fonts are supported only for use with the Text object.


RowHiddenDepth Property
Applies To: Grid

Description

The RowHiddenDepth property identifies which rows of a Grid are currently hidden.


RowLineTypes Property
Applies To: Grid

Description

This property specifies the appearance of the horizontal grid lines in a Grid object.

RowLineTypes is an integer vector, whose length is normally equal to the number of rows in the Grid. Each element in RowLineTypes specifies an index into the GridLineFCol and GridLineWidth properties, thus selecting the colour and width of the horizontal grid lines.

For example, if RowLineTypes[1] is 3, the first horizontal grid line in the Grid is displayed using the colour specified by the 3rd element of GridLineFCol, and the width specified by the 3rd element of GridLineWidth.

Note that RowLineTypes is not ⎕IO dependant, and the value 0 is treated the same as the value 1; both selecting the first colour and line width specified by GridLineFCol and GridLineWidth respectively

The default value of RowLineTypes is an empty numeric vector (⍬). If so, all horizontal grid lines are drawn using the first element of GridLineFCol and GridLineWidth.

A horizontal grid line is drawn along the bottom edge of its associated row. One pixel is drawn inside the row of cells; additional pixels (if any) are drawn between that row of cells and the next one below.


RowTitleAlign Property
Applies To: Grid

Description

The RowTitleAlign property specifies the alignment of row titles in a Grid. It is either a simple character vector, or a vector of character vectors with one element per row.

An element of RowTitleAlign may be:'Top', 'Bottom', 'Left', 'Right', 'Centre', 'TopLeft', 'TopRight', 'BottomLeft', or 'BottomRight'.

Note that both spellings 'Centre' and 'Center' are accepted.


RowTitleBCol Property
Applies To: Grid

Description

The RowTitleBCol property specifies the background colour of the row titles in a Grid object

RowTitleBCol may be a scalar that specifies a single background colour to be used for all of the row titles, or a vector that specifies the background colour of each of the row titles individually. An element of RowTitleBCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see Bcol for details). Its default value is 0 which obtains the colour defined for Button Face.


RowTitleDepth Property
Applies To: Grid

Description

RolTitleDepth specifies the structure of a set of hierarchical row titles. It is an integer vector with the same length as the RowTitles property. A value of 0 indicates that the corresponding element of RowTitles is a top-level title. A value of 1 indicates that the corresponding title is a sub-title of the most recent title whose RowTitleDepth is 0; a value of 2 indicates that the corresponding title is a sub-title of the most recent title whose RowTitleDepth is 1, and so forth. For example:

      'F'⎕WC'Form'('Coord' 'Pixel')('Size' 318 310)
      'F'⎕WS'Caption' 'Hierarchical Column Titles'
      'F.G'⎕WC'Grid'(?12 4⍴100)(0 0)(318 310)
      'F.G'⎕WS('TitleWidth' 150)('TitleHeight' 0)
      'F.G'⎕WS'CellWidths' 40

      Q1←'Q1' 'Jan' 'Feb' 'Mar'
      Q2←'Q2' 'Apr' 'May' 'Jun'
      Q3←'Q3' 'Jul' 'Aug' 'Sep'
      Q4←'Q4' 'Oct' 'Nov' 'Dec'
      RT←(⊂'1995'),Q1,Q2,Q3,Q4
      RD←0,16⍴1 2 2 2

      'F.G'⎕WS('RowTitles'RT)('RowTitleDepth'RD)

      'F.G'⎕WS'RowTitleAlign' 'Centre'

Note that the LockRows method is not supported in combination with hierarchical row titles.


RowTitleFCol Property
Applies To: Grid

Description

The RowTitleFCol property specifies the colour of the row titles in a Grid object

RowTitleFCol may be a scalar that specifies a single colour to be used for all of the row titles, or a vector that specifies the colour of each of the row titles individually. An element of RowTitleFCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Button text.


RowTitles Property
Applies To: Grid

Description

This property specifies the headings that are displayed to the left of the rows in a Grid object. If specified, it must be a vector of character vectors or matrices whose length is the same as the number of rows implied by the Values property. The default value of RowTitles is an empty character vector. In this case, the system displays the row numbers.

To disable the display of row titles in a Grid, you should set the TitleWidth property to 0.


RowTreeDepth Property
Applies To: Grid

Description

The RowTreeDepth property specifies the structure of the rows in a Grid object. It is either a scalar 0 or an integer vector of the same length as the number of rows in the Grid. RowTreeDepth is similar to the Depth property of the TreeView object.

A value of 0 indicates that the corresponding row is a top-level row. A value of 1 indicates that the corresponding row is a child of the most recent row whose RowTreeDepth is 0; a value of 2 indicates that the corresponding row is a child of the most recent row whose RowTreeDepth is 1, and so forth.

When you set RowTreeDepth, the Grid is redrawn so that only rows with a RowTreeDepth of 0 are visible.

The RowSetVisibleDepth method can be used to make data visible to a specific depth.

Example:

      'F'⎕WC'Form' 'Grid: TreeView Feature'
      'F.G'⎕WC'Grid'(30 2⍴2/⍳30)
      F.G.RowTreeDepth←30⍴0 1 2 2

The user can interact with the tree images to expand and contract rows of the Grid.


RowTreeImages Property
Applies To: Grid

Description

The RowTreeImages property is a simple character vector or ref, or a vector of character vectors or refs, that specifies the names(s) of, or ref(s) to, Bitmap objects that are used to display the tree nodes for a Grid object.

Note that images in tree nodes are only displayed if RowTreeStyle is set to 'ImagesOnly', 'ImagesAndLines', or 'AllImagesAndLines'∇.

If RowTreeImages is not specified default images are used.

The Bitmap specified by the 1st element of RowTreeImages is used to display unopened nodes.

The Bitmap specified by the 2nd element of RowTreeImages is used to display opened nodes.

The Bitmap specified by the 3rd element of RowTreeImages is used to display nodes without children.

Example:

      'Closed'⎕WC'Bitmap' 'Folder.bmp'
      'Open'⎕WC'Bitmap' 'FolderOpen.bmp'
      'Item'⎕WC'Bitmap' 'Ideas'
      F.G.RowTreeStyle←'AllImagesAndLines'
      F.G.RowTreeImages←'Closed' 'Open' 'Item'


RowTreeStyle Property
Applies To: Grid

Description

RowTreeStyle specifies the visible attributes of the tree displayed in the Row titles of a Grid.

The value of the RowTreeStyle property is a character vector chosen from the following :

'LinesOnly' | Only the lines of the tree structure are drawn.
'ImagesOnly' | Only the images of nodes with children are drawn.
'ImagesAndLines' | Both lines and images for nodes with children are drawn.
'AllImagesOnly' | Images for all nodes are drawn.
'AllImagesAndLines' | Both lines and images for all nodes are drawn.

The default value, 'ImagesAndLines', is illustrated in the first picture below. Other values are displayed in subsequent pictures.

F.G.RowTreeStyle←'LinesOnly'

f.g.RowTreeStyle←'ImagesOnly'

f.g.RowTreeStyle←'AllImagesOnly'

f.g.RowTreeStyle←'AllImagesAndLines'


Rows Property
Applies To: Combo ComboEx

Description

For Combo objects with Style 'Drop' or 'DropEdit' this property determines the number of rows displayed in the drop-down listbox when it is displayed. Note that the height of the edit field of a Combo of this type is dependent only upon the size of the font in use, and cannot otherwise be changed.

Rows is a "read-only" property for a Combo with Style 'Simple' and an attempt to set it in a Combo of this type with ⎕WC or ⎕WS will generate a NONCE ERROR. Instead, the overall height of a Simple Combo is determined by the first element of the Size property.


RunMode Property
Applies To: OLEServer

Description

This property specifies the way in which an OLEServer object serves multiple clients.

RunMode is a character vector and may be 'MultiUse' (the default), 'SingleUse' or 'RunningObject'.

If RunMode is 'MultiUse', OLE will load a single copy of Dyalog APL and the appropriate workspace into memory. All OLE client processes will communicate with the same Dyalog APL session.

Note that in this case, each OLE client is actually connected to a separate instance of the corresponding APL namespace. That is to say, each client will appear to have its own private copy of the namespace. However, the individual functions and variables in the namespace are not physically copied until they are changed. This means that, in general, OLE clients will share APL functions but have private copies of the namespace variables. However, please remember that global objects in the workspace or in other namespaces are not instanced and will effectively be shared by all clients although they are not directly accessible to them.

If RunMode is 'SingleUse', OLE will load a separate copy of Dyalog APL and a separate copy of the appropriate workspace into memory for each OLE client. Each OLE client operates directly on the namespace associated with the object and not an instance of it.

If RunMode is 'RunningObject', OLE will load a single copy of Dyalog APL and the appropriate workspace into memory. All OLE client processes will communicate with the same Dyalog APL session and indeed with the same namespace. The namespace is not instanced and all objects, including exported variables, are shared by all clients.


SIPMode Property
Applies To: Form

Description

SIPMode applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies the behaviour of the Input Panel with respect to the Pocket APL GUI.

If SIPMode is 1, the Input Panel is automatically displayed when a GUI control that may receive character input (e.g. an Edit object) receives the input focus. The Input Panel is automatically hidden when the input focus moves to a control that does not receive character input.

If SIPMode is 0 (the default), the display of the Input Panel is not handled automatically, but may be controlled using the ShowSIP method.

Note that the user may display and hide the Input Panel manually, regardless of the value of SIPMode.


SIPResize Property
Applies To: Form

Description

SIPResize applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies the behaviour of a Form when the Input Panel is raised or lowered.

If SIPResize is 1 (the default), the Form generates a Configure event when the Input Panel is raised or lowered. Unless disabled or modified by a callback function, the Form is automatically resized to occupy the entire space above the Input Panel.

If SIPResize is 0, the Form does not generate a Configure event when the Input Panel is raised or lowered. This means that, at times, the lower part of the Form may be obscured by the Input Panel.


ScrollOpposite Property
Applies To: TabControl

Description

The ScrollOpposite property specifies that unneeded tabs scroll to the opposite side of a TabControl, when a tab is selected.

ScrollOpposite is a single number with the value 0 (normal scrolling) or 1 (scrolling to the opposite side); the default is 0.

The picture below illustrates a TabControl with ScrollOpposite set to 1, after the user has clicked Third Tab.

Setting ScrollOpposite to 1 implies that MultiLine is also 1. If you set ScrollOpposite to 1 in a ⎕WC statement, the MultiLine property will automatically be set to 1, even if you try to set MultiLine to 0 in the same statement. If you subsequently change MultiLine back to 0 using ⎕WS , this will work, but the effect is not useful and it is not supported.


SelDate Property
Applies To: Calendar

Description

The SelDate property identifies the range of dates that is currently selected in a Calendar object.

SelDate is a 2-element integer vector of IDN values that identifies the first and last dates that are currently selected.


SelImageIndex Property
Applies To: ComboEx TreeView

Description

The SelImageIndex property determines which bitmapped images in an ImageList correspond to items in a TreeView object when the item is selected. It is an integer vector whose length is the same as the number of items in the object and is ⎕IO dependent.

See also ImageIndex


SelItems Property
Applies To: Combo ComboEx Grid List ListView TreeView

Description

This property determines which (if any) of the items in an object are currently selected and highlighted. Except in a Grid, it is a Boolean vector with one element per item in the list. A value of 1 means "selected"; 0 means "not selected".

This property is used after a Select event to identify which item has been chosen. In a Combo or a List with Style 'Single' it will contain only a single 1.

SelItems should also be used to pre-set the contents of the edit field in a Combo box with Style 'Drop'. In Combo boxes with Style 'Simple' or 'DropEdit', the contents of the edit field may also be specified by the Text property. If you specify both, the value of Text takes precedence.

In a Grid SelItems is a 2-element vector of 2-element integer vectors that identifies the row and column coordinates of the first and last cells in the currently selected block of cells. If multiple selection is enabled, SelItems may be a vector of such arrays, specifying the coordinates of a number of non-contiguous blocks of selected cells.


SelRange Property
Applies To: TrackBar

Description

The SelRange property specifies the selected range in a TrackBar which has Style 'Selection'. It is a 2-element numeric vector.


SelText Property
Applies To: Combo ComboEx Edit RichEdit

Description

This property determines or identifies the portion of text in an object that is currently selected and highlighted. It can be used to pre-select all or part of the text to be replaced or deleted when the user starts typing. It can also be used to query the area of text that the user has highlighted. This can be useful if you want to implement your own cut/paste/replace features.

SelText is always a 2-element integer vector. If the field contents (defined by the Text property) is a vector, SelText is simple. Its first element is the index of the first selected character and its second element is 1 + the index of the last selected character. The length of the selected string is therefore obtained by subtracting the first element from the second.

If there are no characters selected, the two elements are equal and specify the current position of the input cursor.

If the contents is a vector of vectors or a matrix, each element of SelText is a 2-element vector. The first item in each of the elements indexes the vector (in a vector of vectors) or row (in a matrix). The second item in each element indexes the position of the character in the vector or along the row. Again, the value reported for the last character in the selected string is 1 + its index.


SelectionBorderWidth Property
Applies To: Grid

Description

The SelectionBorderWidth property specifies the width of the border that is drawn around the currently selected block of cells. It is expressed in pixels.


SelectionColor Property
Applies To: Grid

Description

The SelectionColor property specifies the colour used to highlight the currently selected block of cells and, if HighlightHeaders is 1, the corresponding row and column headings. See also SelectionColorAlpha.


SelectionColorAlpha Property
Applies To: Grid

Description

The SelectionColorAlpha property is a 2-element integer vector that specifies the degree of transparency or shade of the colour that is used to highlight the currently selected block of cells in a Grid. See SelectionColor.

The first element refers to the shade to be used when the Grid has the input focus; the second to when it doesn't. Each element is an integer in the range 0 (invisibly light) to 255 (fully dark).


ServerVersion Property
Applies To: OLEServer

Description

This property specifies the version number of an OLEServer object.

It is a 2-element integer vector that specifies the major and minor version numbers respectively.

The default value of ServerVersion is (1 0).


ShowCaptions Property
Applies To: ToolControl

Description

The ShowCaptions property specifies whether or not the captions of individual ToolButton objects are drawn. ShowCaptions is a property of the parent ToolControl object.

ShowCaptions is a single number with the value 0 (ToolButton captions are not shown) or 1 (ToolButton captions are shown); the default is 1

ShowCaptions allows you to toggle end-user preferences for the display of ToolButton captions, without having to set/clear individual captions one by one.


ShowCueWhenFocused Property
Applies To: ButtonEdit Edit

Description

This Boolean property specifies whether or not the text specified by the Cue property should be displayed once the user has tabbed into or clicked on the empty input field (and thus given it the focus). For an Edit object it applies only if the Style of the Edit obect is 'Single'.


ShowDropDown Property
Applies To: ColorButton ToolControl

Description

The ShowDropDown property specifies whether or not a drop-down menu symbol is drawn in a ColorButton or alongside ToolButton objects which have Style 'DropDown'.

ShowDropDown is a single number with the value 0 (drop-downs captions are not shown) or 1 (drop-downs are shown); the default is 1.

ShowDropDown also affects the behaviour of ToolButton objects which have Style 'DropDown'.

If the ShowDropDown property of the parent ToolControl is 0, clicking the ToolButton causes the popup menu to appear. In this case, the ToolButton itself does not itself generate a Select event; you must rely on the user selecting a MenuItem to specify a particular action.

If the ShowDropDown property of the parent ToolControl is 1, clicking the dropdown button causes the popup menu to appear; clicking the ToolButton itself generates a Select event, but does not display the popup menu.

The following picture illustrates a ToolControl with ShowDropDown set to 1.


ShowInput Property
Applies To: Grid

Description

This property specifies whether or not the cells in a Grid are displayed using their associated input objects.

The ShowInput property is either a single boolean value that applies to all the cells in a Grid, or it is a vector whose elements are mapped to individual cells via the CellTypes property. A value of 0 means that the corresponding cell is displayed normally. A value of 1 indicates that the cell is displayed using its associated input object, as it is when it is the current cell. ShowInput is relevant to cells displayed using Combo and Button objects.

The example below illustrates the appearance of a Grid in which ShowInput is set to 0 for the Job Title column and 1 for the Region and Permanent columns.

The appearance of the same Grid but with ShowInput set to 0 throughout is illustrated below:


ShowSession Property
Applies To: OLEServer

Description

This property specifies whether or not the APL Session window is displayed when an OLEServer object is started by an OLE client.

Its default value is 0 (hide Session).

Note that if RunMode is 'MultiUse', you may not in any way access the instances of the object that are being controlled by the client applications, even if only a single client is connected.


ShowThumb Property
Applies To: TrackBar

Description

The ShowThumb property specifies whether or not the thumb in a TrackBar object is visible. It is boolean with a default value of 1 and it may be toggled on and off using ⎕WS.


SingleClickExpand Property
Applies To: TreeView

Description

The SingleClickExpand property specifies whether or not an item in a TreeView control is expanded when the user selects the item.

SingleClickExpand is a single number with the value 0 (the user must select the expand icon to cause the item to expand) or 1 (the item is expanded when the text of the item is selected); the default is 0.


Size Property

Applies To

Description

This is a 2-element numeric vector specifying the height and width of the object.

For the Bitmap object, Size is set and reported in pixels. Setting the Size of a Bitmap causes it to be scaled (up or down).

For all other objects, Size is reported and set in units defined by the Coord property and, if Coord is 'User', the XRange and YRange properties of the object's parent.

For the Root object, if Coord is 'Prop' the value of Size is (100,100). If Coord is 'Pixel' the value of Size reports the number of pixels on the screen.

For a Form or SubForm, the Size property defines the area within the object, and excludes its title bar, menu bar and border if these are present.

For a Combo object with a "drop-down" list, the first element of Size (height) is ignored. The height of the edit field is determined by the height of the font, while the size of the list box is determined by the Rows property.

Otherwise the Size property defines the total size of the object, including borders, edges etc.

When specifying Size, you can set the height or width to a default value (⎕WC) or leave it unchanged (⎕WS) by giving the corresponding element a value of ⍬.


Sizeable Property

Applies To

Description

This property determines whether or not an object can be directly resized by the user once it has been created by ⎕WC.

It is a single number with the value 0 (the object cannot be resized by the user) or 1 (the object may be resized by the user). The default is 1.

For a Form or SubForm, the Sizeable property may only be set by ⎕WC and cannot subsequently be altered using ⎕WS. An attempt to do so generates a NONCE ERROR. For a Form, the default value is 1 and the Form occupies a standard resizeable window with a border. Note that the value of Sizeable is independent of the values of the MaxButton and MinButton properties, so that a Form with MaxButton 1 can be maximised even though its Sizeable property is 0.

For other objects, the default value of the Sizeable property is 0. However, setting it to 1 (which may be done dynamically using ⎕WS) allows the user to resize it with the mouse.

In all these cases, when the user resizes an object, the object will generate a Configure (31) event.

Sizeable also applies to the Locator object. In this case, a value of 1 implies "rubberbanding" and a value of 0 means "no rubberbanding". See Locator object for further details.


SocketNumber Property
Applies To: TCPSocket

Description

The SocketNumber property is an integer whose value is the Window handle of the socket attached to the TCPSocket object and is generally a read-only property.

The only time that SocketNumber may be specified is when a server replicates (clones) a listening socket to which a client has just connected.


SocketType Property
Applies To: TCPSocket

Description

The SocketType property is a character vector that specifies the type of the TCP/IP socket. This is either Stream (which is the default), or UDP.

SocketType must be defined when the object is created and may not be set or changed using ⎕WS.

For two Dyalog APL applications to communicate, their TCPSocket objects must have the same SocketType.


SortItems Property
Applies To: List

Description

The SortItems property specifies whether or not the items in a List object are sorted.

It is Boolean with a default value of 0. If SortItems is 1, the items are automatically sorted in alphabetical order and the object provides word recognition capabilities for selecting an item from the keyboard.

Note that the value of the Items property reflects the order of the items displayed in the List object rather than the order in the array that was used to assign it.

This property may only be initialised when the object is created and cannot subsequently be changed.


SplitObj1 Property
Applies To: Splitter

Description

The SplitObj1 property specifies the name of, or ref to, one ot up to two objects managed by a Splitter object. The object must be one of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If the Style property of the Splitter is 'Vert', the object specified by SplitObj1 is positioned at (0 0) and sized to occupy the space in its parent to the left of the Splitter, with the Splitter itself attached to its right edge.

If the Style property of the Splitter is 'Horz', the object specified by SplitObj1 is positioned at (0 0) and sized to occupy the space in its parent above the Splitter, with the Splitter itself attached to its bottom edge.

If SplitObj1 is empty, the Splitter manages the single object specified by SplitObj2 and the space to the left or above the Splitter is empty or controlled by another Splitter.


SplitObj2 Property
Applies To: Splitter

Description

The SplitObj2 property specifies the name of, or ref to, one of up to two objects managed by a Splitter object. The object must be one of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If the Style property of the Splitter is 'Vert', the object specified by SplitObj2 is initially positioned at (0 x), where x is half the width of the parent plus the Size of the Splitter, and sized to occupy the space in its parent to the right of the Splitter, with the Splitter itself attached to its left edge.

If the Style property of the Splitter is 'Horz', the object specified by SplitObj2 is initially positioned at (y 0), where y is half the height of the parent plus the Size of the Splitter, and sized to occupy the space in its parent below the Splitter, with the Splitter itself attached to its top edge.

If SplitObj2 is empty, the Splitter manages the single object specified by SplitObj1 and the space to the right or below the Splitter is empty or controlled by a second Splitter.


Start Property
Applies To: Circle Ellipse

Description

This property specifies one or more start-angles for an arc, pie-slice, or chord of a circle or ellipse. It may be used in conjunction with End which specifies end angles. Angles are measured counter-clockwise from the x-axis at the centre of the object.

If a single arc is being drawn, Start is a single number that specifies the start angle of the arc in radians (0 ⍎> ○2). If multiple arcs are being drawn, Start is either a single number as before (the start angle for several concentric arcs) or a numeric vector with one element per arc.

If End is not specified, the default value of Start is 0. Otherwise, the default value of Start is (0,¯1↓+\End).


StartIn Property
Applies To: BrowseBox

Description

The StartIn property is a character string that specifies the start point and root for a BrowseBox object.

Only the specified folder and its subfolders appear in the dialog box. The user cannot browse higher in the folder architecture than this folder.

The default value for StartIn is an empty vector which means that the root of the browse dialog is the desktop.


State Property
Applies To: Button Form SubForm TabButton ToolButton

Description

This property determines the state of a Button, TabButton, ToolButton, Form, or SubForm. It is a single number with the value 0 (the default), 1, or 2 (Form and SubForm).

If the Style property is 'Push', a State of 0 means that the pushbutton is displayed normally (out). If its State is 1, the pushbutton is displayed depressed (in).

If the Style property is 'Radio' or 'Check', 0 means "not selected" and 1 means "selected". Note that only one of a group of buttons with Style 'Radio' that share the same parent may have State 1. Setting State to 1 automatically deselects all the others in the group.

For a Form or SubForm, a value of State of 0 means that the Form is currently displayed in its "normal" state. 1 means that the Form is currently minimised (displayed as an icon). The value 2 indicates that the Form is maximised and displayed full-screen. The State of a Form can be changed using ⎕WS.


Step Property

Applies To

Description

This property determines the size of changes reported when the user clicks a scroll arrow (small change) or clicks on the body of the scrollbar (large change). The object's Thumb property increases or decreases by this amount.

For a Scroll object, Step is a 2-element numeric vector whose first element specifies the value of the "small change" and whose second element specifies the value of the "large change".

For a Form or SubForm, Step is a 4-element numeric vector. The first two elements refer to the Form's vertical scrollbar and the second two elements refer to the Form's horizontal scrollbar.

For the above objects, values of Step must be between 1 and the value of the Range property.

For a Locator object, Step is a 2-element integer vector (default value 1 1) that specifies the increments (in pixels) by which the size or position of the Locator changes in the Y and X directions respectively as the user moves the Locator.


Style Property

Applies To

Description

This property determines a particular style of object within the general category of Type. It is a character vector whose value depends upon the type of object.

For a Button, Style may be 'Push', 'Radio', 'Check', 'Toggle', 'CommandLink' or 'Split'.

'Push' specifies that the button appears and behaves like a pushbutton (sometimes also called a command button).

'Radio' means that the button is displayed as a small circle accompanied by a description. When the button is selected, the circle is filled in. In a group of buttons with Style 'Radio'that share the same parent, only one of them may be selected. This style of button is generally known as a "radio-button" or an "option button".

'Check' or 'Toggle'means that the button is displayed as a small box accompanied by a description. When the button is selected a cross appears in the box. This style of button is known as a "check-box".

'CommandLink'means that the button has an icon displayed to the left of its Caption. the appearance of which is controlled by the Elevated property. Note that this feature only apples if Native Look and Feel is enabled.

'Split' specifies a 'Push' button with an additional drop-down button, similar to that provided by a Combo object. Note that this feature only apples if Native Look and Feel is enabled.

For a Calendar object, The Style property may be either 'Single' (the default) or 'Multi'. If Style is 'Single', the user may select a single date. If Style is 'Multi', the user may select a contiguous range of dates.

For a Combo or ComboEx object, Style may be 'Simple''DropEdit'or 'Drop' (the default). 'Simple'specifies a simple combo box in which the associated list box is displayed at all times. The other two styles provide list boxes which "drop down" when the user clicks on a symbol displayed to the right of the Combo's edit field. A 'DropEdit' Style allows the user to type (anything) in the edit field.

A 'Drop'Style does not and forces the contents of the edit field to be either empty or one of the choices specified by Items.

For a DateTimePicker, Style may be either 'Combo' (the default) or 'UpDown'.

For an Edit object, Style may be 'Single'or 'Multi'. If Style is 'Single'the object displays only a single line of text and the user may not enter any more lines. If the Style is 'Multi' the number of lines displayed is governed by the Rows or Size property and the user may insert, add or delete lines as desired.

For FileBox, List, and ListView objects, Style may be 'Single'or 'Multi'. If the Style is 'Single'only one file or item can be selected. If Style is 'Multi', several files or items can be selected.

For an Icon, Style may be 'Large'(the default) or 'Small' and specifies the size of the icon (32x32 or 16x16) to be loaded from a file.

For a Locator, Style may be 'Point', 'Rect' (the default), 'Line'or 'Ellipse'. It specifies the shape that is drawn as the user moves the mouse.

For a MenuItem, Style may be 'Check'(the default) or 'Radio'. The latter specifies that within a contiguous block of such MenuItems, only one may have Checked set to 1. Setting Checked to 1 on any item in that group automatically sets Checked to 0 on the others. A radio style MenuItem that is checked has a small radio dot drawn to the left of its Caption.

For a MsgBox, the Style property determines the type of icon which is displayed in it. This is a character vector with one of the following values :

'Msg' | no icon (the default)
'Info' | information message icon
'Query' | query (question) icon
'Warn' | warning icon
'Error' | critical error icon

For a Static object, Style defines its appearance, and may be one of:

'BlackFrame' | 'BlackBox'
'GreyFrame' or 'GrayFrame' | 'GreyBox' or 'GrayBox'
'WhiteFrame' | 'WhiteBox'

A StatusField may be used to monitor the state of a key on the keyboard. If so, its Style property determines the key it monitors and may be one of the following:

CapsLock | Monitors state of Caps Lock key
ScrollLock | Monitors state of Scroll Lock key
NumLock | Monitors state of Num Lock key
KeyMode | Monitors the keyboard mode (APL/ASCII)
InsRep | Monitors the state of the Insert key

For a Splitter, the Style property specifies the orientation of the Splitter and may be 'Vert' (the default) or 'Horz' .

For a TabControl, the Style property determines the appearance of its TabButton children, and may be 'Tabs' (the default), 'Buttons' or 'FlatButtons'.

For aTCPSocket, Style is a character vector that specifies the type of data transmitted or received by the socket; it may be 'Char', 'Raw', or 'APL'. The value APL is valid only if the SocketType is 'Stream'.

For a ToolButton, the Style property specifies the behaviour of the button and may be 'Push'(the default), 'Check', 'Radio', 'DropDown', or 'Separator'.

For a ToolControl, the Style property determines the appearance of its ToolButton children and may be 'Buttons', 'FlatButtons' (the default), 'List' or 'FlatList'.

For a TrackBar, the Style property determines the appearance and behaviour of the TrackBar and may be 'Standard'(the default) or 'Selection'.


SysMenu Property
Applies To: Form SubForm

Description

This property determines whether or not a Form or SubForm has a "System Menu " box in the top-left corner of its border. Pressing the left mouse button in this box brings up the standard window control menu for the Form. Double clicking the box closes the Form.

SysMenu is a single number with the value 0 (no System menu box) or 1 (System Menu box is provided). The default is 1.

If any of the SysMenu, MaxButton, MinButton and Moveable properties are set to 1, the Form or SubForm has a title bar.


TabFocus Property
Applies To: TabControl

Description

The TabFocus property specifies the focus behaviour for the TabControl object and may

TabFocus is a character vector that may be 'Normal' (the default), 'Never' or 'ButtonDown'.

If TabFocus is 'Normal', the tabs or buttons in a TabControl do not immediately receive the input focus when clicked, but only when clicked a second time. This means that, normally, when the user circulates through the tabs, the input focus will be given to the appropriate control in the associated SubForm. However, if the user clicks twice in succession on the same tab or button, the TabControl itself will receive the input focus.

If TabFocus is 'ButtonDown', the tabs or buttons in a TabControl receive the input focus when clicked.

If TabFocus is 'Never', the tabs or buttons in a TabControl never receive the input focus. This allows the user to circulate through a set of tabbed SubForms without ever losing the input focus to the TabControl itself.


TabIndex Property

Applies To

Description

The TabIndex property reports the ⎕IO-dependant relative position of a child object within the list of child objects owned by its parent. If N is the number of children owned by an object, TabIndex is an integer between ⎕IO and (N-~⎕IO). The sequence of objects in this list is also used as the tabbing sequence, i.e. if the input focus is on the first child in the list, pressing Tab moves the input focus to the next child in the list.

When you create a child object, it is inserted in the list at the position specified by its TabIndex property. If TabIndex is omitted, it is appended to the end of the list.

If you subsequently change TabIndex, the object is moved to the corresponding position in the list.

Naturally, if you specify a value of TabIndex that is greater than the number of existing children, the object is inserted at or moved to the end of the list.


TabJustify Property
Applies To: TabControl

Description

The TabJustify property specifies, the positions at which the picture and caption are drawn within each tab or button implemented by a TabButton in a TabControl object.

TabJustify is a character vector that may be 'Centre', 'Edge', or 'IconEdge'. Its default value is 'Centre'.

If TabJustify is 'Centre', the picture and caption are arranged in the centre of the TabButton.

If TabJustify is 'Edge', the picture and caption are together aligned to the appropriate edge of the TabButton according to the value of Align.

If TabJustify is set to 'IconEdge', the caption is drawn centrally and only picture is aligned to the edge.

TabJustify is only honoured if fixed size tabs are in effect.


TabObj Property
Applies To: SubForm TabBar TabBtn TabButton TabControl

Description

TabObj is a ref or a character vector.

For a SubForm, it specifies the name of , or ref to, a TabBtn or TabButton object that is associated with the SubForm. Selecting the TabBtn or TabButton causes the SubForm to be given the input focus.

For TabBtn and TabButton objects, TabObj is a read-only property that contains the name of, or ref to, the associated SubForm.

For a TabBar or TabControl, TabObj is a read-only property that contains the name of, or ref to, the currently selected TabBtn or TabButton.


TabSize Property
Applies To: TabControl

Description

The TabSize property specifies the size of fixed size tabs or buttons in a TabControl object.

By default, the size of the tabs may vary from one to another. Fixed size tabs may be obtained by setting the TabSize property.

TabSize is a 2-element numeric vector that specifies the height and width of the tab. The first element of TabSize may be set to ⍬ which means "default height".

To obtain fixed sized tabs with MultiLine set to 1, you must however also set the Justify property to 'None'.

If MultiLine is 1 and Justify is 'Right', TabSize is ignored.


Target Property
Applies To: BrowseBox

Description

The Target property is a read-only character string that specifies the chosen folder or other resource selected by the user in a BrowseBox object.

If the BrowseFor is 'Directory', Target will contain a directory name followed by the character "\". Otherwise, Target just contains the name.


TargetState Property
Applies To: TCPSocket

Description

The TargetState property reflects the intended final state of a TCPSocket object. Its possible values are as follows:

Stream | UDP
Client | Open
Server | Bound
Closed | Closed

Setting TargetState to Closed is the recommended way to close a socket. It informs APL that you want the socket to be closed, but only when it is safe to do so. When all the data has been sent, the TCPSocket will generate a TCPClose event which, unless a callback function decides otherwise, will cause the TCPSocket object to disappear.

To control socket closure, you may execute the following steps:

  1. Set TargetState to Closed
  2. Either:
    1. continue processing or
    2. wait (using ⎕DQ) for the TCPSocket to disappear or
    3. wait (using ⎕DQ) for the TCPClose event


Text Property

Applies To

Description

This property is associated with the text contents of an object and is a character array.

In a ButtonEdit, Combo, StatusField, Spinner, or a single-line Edit object, Text may be a simple scalar or a simple vector.

In a RichEdit , a multi-line Edit field or in a MsgBox, the value of Text may also be a simple matrix, or a vector of vectors. If so, "new-line" characters are appended to each row of the matrix, or to each vector in a vector of vectors, before being displayed. The user may insert or add a "new-line" character in a multi-line Edit by pressing Ctrl-Enter (Enter itself is used to press Buttons).

Note that if word-wrapping is in effect in a multi-line Edit object, the structure of Text does not correspond to the lines displayed.

In a Text object, the value of the Text property may be a simple scalar, an enclosed vector or matrix, a simple vector, a simple matrix, or a vector of enclosed vectors or matrices.

In general, the value of Text returned by ⎕WG has the same structure that was assigned to it by ⎕WC or by the most recent call to ⎕WS. New-Line characters are removed.

You can copy text into the Windows Clipboard by using ⎕WS to set Text for a Clipboard object. In this case you may specify a simple character scalar, vector or matrix, or a vector of character vectors. If you are retrieving data from the clipboard that has been stored by another application, Text will be either a character vector or a vector of character vectors.

The Text property of a StatusField is updated automatically if its Style property is set to monitor the status of a key.


TextSize Property

Applies To

Description

This property has been replaced by the GetTextSize method, which should be used instead. TextSize is retained only for compatibility with previous versions of Dyalog APL.

TextSize is a "read-only" property that reports the size of the bounding rectangle of a text item in a given font. The result is given in the co-ordinate system of the object in question. This property is useful for positioning Text objects.

When you query TextSize you give the text item in whose size you are interested and, optionally, the name of a Font object. The text item may be a simple scalar, a vector or a matrix. If the Font is omitted, the result is given using the current font for the object in question. When you query TextSize on its own, you must enclose the argument to ⎕WG. This is because APL would otherwise not be able to distinguish between the text string and font name associated with 'TextSize' and other properties with the same name as these items.

Examples:

      '.' ⎕WG ⊂'TextSize' 'Hello World'
2.666666746 9.625

      'FNT1' ⎕WC 'FontObj' 'Arial' 72
      '.' ⎕WG ⊂'TextSize' 'Hello World' 'FNT1'
12 41.875

      '.' ⎕WS 'Coord' 'Pixel'
      '.' ⎕WG ('TextSize' (3 11⍴'Hello World')) 'Coord'
39 55  Pixel


Thumb Property

Applies To

Description

This property determines and reports the position of the thumb in an object.

For a Scroll object, the value of Thumb is a single integer whose minimum value is 1 and whose maximum value is defined by the Range property.

For ProgressBar, Spinner, UpDown and TrackBar objects, Thumb is a single numeric value in the range specified by the Limits property.

For a Form or SubForm object, Thumb is a 2-element vector whose elements refer to the position of the thumb in the object's own built-in vertical and horizontal scrollbars respectively.

For other objects, Thumb is a single numeric value in the range defined by the Limits property.


ThumbRect Property
Applies To: TrackBar

Description

ThumbRect is a read-only property that reports the position and size of the bounding rectangle of the thumb in a TrackBar object. It is a 4-element integer vector containing:

[1] | Vertical position of the top-left corner of the bounding rectangle
[2] | Horizontal position of the top-left corner of the bounding rectangle
[3] | Height of the bounding rectangle
[4] | Width of the bounding rectangle


TickAlign Property
Applies To: TrackBar

Description

TickAlign determines the position of the tick marks in a TrackBar object. For a horizontal TrackBar, TickAlign may be either 'Bottom' (the default), 'Top' or 'Both'. If TickAlign is 'Bottom', the ticks are drawn below the slider. If TickAlign is 'Top', the ticks are drawn above it. If TickAlign is 'Both', the ticks are drawn above and below.

For a vertical TrackBar, TickAlign may be either 'Right' (the default), 'Left', or 'Both' and similarly specifies to which side of the slider bar the ticks are drawn. Note that TickAlign may only be set when the TrackBar is created with ⎕WC and may not subsequently be altered using ⎕WS.

Note that ticks are not drawn if the value of HasTicks is 0


TickSpacing Property
Applies To: TrackBar

Description

The TickSpacing property specifies the spacing between each tick mark in a TrackBar object. It is an integer between 1 and the maximum value of the TrackBar which is defined by the 2nd element of the Limits property.

For example, if you set ('Limits' 10 50) and you specify ('TickSpacing' 10) you will obtain 5 ticks corresponding to the values 10, 20, 30, 40 and 50 along the slider bar.


Tip Property

Applies To

Description

The Tip property is a character vector or character matrix that specifies a "help" message which is to be displayed when the user positions the mouse pointer over the object. The Tip is displayed in a pop-up TipField object specified by the TipObj property.


TipObj Property

Applies To

Description

The TipObj property is a character vector or ref that specifies the name of, or ref to, a TipField object in which the "help" message defined by the Tip property is to be displayed. This message is displayed when the user positions the mouse pointer over the object.

Note that if TipObj is empty, its value is inherited from its parent. Thus setting TipObj on a Form defines the default TipField (and thus the default appearance of all Tips) for all the controls in that Form. Setting TipObj on Root defines the default TipField for the entire application.


TitleHeight Property
Applies To: Grid

Description

This property is a single number that specifies the height of the column titles displayed in a Grid object. It is expressed in the units specified by the Coord property of the Grid.


TitleWidth Property
Applies To: Grid

Description

This property is a single number that specifies the width of the row titles displayed in a Grid object. It is expressed in the units specified by the Coord property of the Grid.


Today Property
Applies To: Calendar DateTimePicker

Description

The Today property is an IDN that specifies today's date in a Calendar or DateTimePicker object. Its default value is the current date that is set on your computer.

See also CircleToday and HasToday properties.


ToolboxBitmap Property
Applies To: ActiveXControl OCXClass

Description

For an ActiveXControl, the ToolboxBitmap property is a character vector or ref that specifies the name of, or ref to, a Bitmap object that may be used by a host application to represent the ActiveXControl when its complete visual appearance is not required. For example, if you add an ActiveX control to the Microsoft Visual Basic development environment, its bitmap is added to the toolbox. The Bitmap should therefore be of an appropriate size, usually 24 x 24 pixels.

For an OCXClass, The ToolboxBitmap is a read-only property that reports a bitmap image associated with an OLE Control. This is intended for use by a GUI design tool. Its value is a 2-element vector. The first element is an integer matrix of pixel colours corresponding to the Bits property of a Bitmap object. The second element is a 3-column integer matrix specifying the colour map and corresponds to the CMap property of a Bitmap object.

Thus you can construct a Bitmap object directly from this property with an expression such as:

      'BM'⎕WC'Bitmap' '','GAUGE' ⎕WG'ToolboxBitmap'

where GAUGE is the name of an OCXClass.


TrackRect Property
Applies To: TrackBar

Description

TrackRect is a read-only property that reports the position and size of the bounding rectangle of the slider in a TrackBar object. It is a 4-element integer vector containing:

[1] | Vertical position of the top-left corner of the bounding rectangle
[2] | Horizontal position of the top-left corner of the bounding rectangle
[3] | Height of the bounding rectangle
[4] | Width of the bounding rectangle


Translate Property

Applies To

Description

This property applies to the Classic Edition only. In the Unicode Edition, its value is ignored.

This property specifies whether or not character data is to be translated. Translate is a character vector whose values may be 'Inherit', 'Translate', 'ANSI'or 'None'.

A value of 'Translate' means that all character property values and event parameters are translated to and from ⎕AVusing the current output translation table (WIN.DOT).

'None' means that character data is passed between APL and the object with no translation.

If you set the value of the Translate property to 'ANSI', APL does not attempt to resolve characters as they are typed by the user via the Input Translate Table. Using Translate 'ANSI'in combination with the appropriate value of CharSet and the corresponding National Language keyboard, will permit users to enter strings in non-western languages.

'Inherit' means that the object inherits its translation from its parent.

The default value for the Root and Printer objects is 'Translate', and for most other objects it is 'Inherit'.


Transparent Property
Applies To: Animation ButtonEdit ToolControl

Description

The Transparent property specifies whether or not a ToolControl is transparent.

Transparent is a single number with the value 0 (the default) or 1.

If Transparent is 1, the visual effect is as if the ToolButtons (and other controls owned by the ToolControl) were drawn directly on the parent Form as illustrated below.


Type Property

Applies To

Description

This property determines the type of an object. Its value is a character vector containing a valid object type. The Type property is set by ⎕WC and reported by ⎕WG, but may not be altered using ⎕WS.


TypeLibFile Property
Applies To: ActiveXControl OLEServer

Description

The TypeLibFile property is a read-only property that reports the name of the file in which the Type Library associated with a COM object is stored.


TypeLibID Property
Applies To: ActiveXControl OLEServer

Description

The TypeLibID property is a read-only property that reports the value of the globally unique identifier (GUID) of the Type Library associated with a COM object.


TypeList Property
Applies To: OCXClass OLEClient

Description

This property reports the names of all the special data types defined for a particular COM object. It is a vector of character vectors returned by ⎕WG. It may not be set using ⎕WC or ⎕WS. Further information about each data type may be obtained using GetTYpeInfo.

Note that TypeList reports all of the data type names recorded in the .OCX file associated with the COM object. If several COM objects are provided within a single .OCX file, the entire set of data types reported may not necessarily be applicable to the Control in question.


Underline Property
Applies To: Font

Description

This property specifies whether or not the characters in the font associated with a Font object are underlined or not. It is either 0 (normal) or 1 (underlined). There is no default; the value of this property reflects the underline characteristic of the font allocated by Windows.


UndocksToRoot Property
Applies To: CoolBand Form SubForm ToolControl

Description

Specifies the parent adopted by an object when its Type changes to a Form as a result of an undocking operation.

UndocksToRoot is a single number with the value 0 or 1.

If UndocksToRoot is 1, the object becomes a Form that is a child of Root and therefore becomes completely independent of the Form in which it was previously docked.

If UndocksToRoot is 0, the object becomes a Form that is a child of the Form in which it was previously docked and is therefore always displayed on top of it. This setting is appropriate for a dockable toolbar.

The default value of UndocksToRoot is 1 if the object was originally created as a child of Root; otherwise it is 0.


UpperCase Property
Applies To: Root

Description

This property specifies whether or not property names returned by ⎕WG and event names supplied by ⎕DQ and ⎕NQ are converted to uppercase or not. It is a boolean property where 1 means convert to upper case and 0 means not. The default is 0. For example :

      '.' ⎕WG 'Type'

Root

      '.' ⎕WS 'UpperCase' 1
      '.' ⎕WG 'Type'
ROOT

In Dyalog APL Version 6, property names were always reported in upper case. This was changed in Version 7. The UpperCase property is provided to enable applications developed prior to Dyalog APL/W Version 7 to function with minimal alteration.


VAlign Property
Applies To: Text

Description

This property determines the vertical alignment of text in the Text object. It is either a single integer value, or, if the Text object has several components, a corresponding vector of such values.

These may be :

0 | base aligned | the base line of the character is aligned on the y-coordinate specified by the Points property.
1 | half aligned | the centre of the character is aligned on the y-coordinate specified by the Points property.
2 | cap aligned | the top of the character is aligned on the y-coordinate specified by the Points property.
3 | bottom aligned | the bottom of the character cell is aligned on the y-coordinate specified by the Points property.
4 | top aligned | the top of the character cell is aligned on the y-coordinate specified by the Points property. This is the default.


VScroll Property

Applies To

Description

This property determines whether or not an object has a vertical scrollbar. It is a single integer with the value ¯2, ¯1, or 0.

VScroll may only be set when the object is created with ⎕WC and may not subsequently be changed with ⎕WS or assignment.

For a Form object, the value ¯1 specifies that the Form has a vertical scrollbar. A value of 0 (which is the default) means that it does not.

When applied to an Edit object, the value ¯2 specifies that the data is scrollable vertically, but only by using the cursor keys; a scrollbar is not provided. A value of ¯1 causes a scrollbar to be displayed (whether or not one is needed).

When applied to a List object, the value ¯2 specifies that the data is scrollable vertically, but only by using the cursor keys; a scrollbar is not provided. A value of ¯1 causes a scrollbar to be displayed if required (when the list of items exceeds the height of the object).

When applied to a Combo or ComboEx object, a value of ¯1 or ¯2 causes a scrollbar to be displayed, whether or not one is required.

For all these objects, a value of 0 inhibits scrolling altogether.

For a Scroll object, VScroll may be ¯1 or 0. If it is ¯1 the direction of the scrollbar is vertical. If both HScroll and VScroll are set to ¯1, HScroll takes precedence and forces VScroll back to 0.

For a StatusBar, TabBar or ToolBar with Align set to Left or Right, VScroll determines whether or not a vertical scrollbar is provided and how the object positions its children. If VScroll is 0 (the default) the object organises its children in multiple columns and does not provide a scrollbar. If VScroll is ¯1 or ¯2, the object organises its children in a single column and provides a mini scrollbar to allow those positioned beyond the bottom edge of the object to be scrolled into view. If VScroll is ¯1, the scrollbar is always shown. If VScroll is ¯2, it is only shown when needed.

For a Grid, VScroll may be 0 (no vertical scrollbar), ¯1 (scrollbar is displayed when required), ¯2 (same as ¯1) or ¯3 (scrollbar is always displayed).


ValidIfEmpty Property
Applies To: ButtonEdit Edit Spinner

Description

This property applies to an Edit object with Style Single and specifies whether or not an empty field is considered to be valid. It also applies to a Spinner. Its value is either 0 (an empty field is not valid) or 1 (an empty field is valid. If the FieldType is Numeric, LongNumeric, Currency, Date or Time, the default value for ValidIfEmpty is 0. Otherwise, its default value is 1.

If ValidIfEmpty is 0 and the user attempts to leave the Edit object by shifting the input focus to another control, or by selecting a Button or MenuItem, the Edit object will generate a BadValue event. The Text property will reflect the appearance of the field and be empty, but the Value property will not be changed.

If ValidIfEmpty is 1 and the FieldType is Numeric, LongNumeric, Currency, date or Time, the Value property will be set to ⍬ when the user clears the field and leaves it.


Value Property
Applies To: ButtonEdit Edit Label Spinner

Description

This property specifies or reports the numeric value associated with an Edit or Label object whose FieldType property is set to Numeric, LongNumeric, Date, LongDate or Time.

If the FieldType is Numeric or LongNumeric, the Value property contains a scalar number. If the FieldType is Date or LongDate, the Value property is an integer representing the date as the number of days since 1st January 1900. If the FieldType is Time, the Value property is an integer that contains the number of seconds since midnight.


Values Property
Applies To: Grid

Description

This property specifies the data values for the cells in a Grid object. Values must be a matrix whose elements are either single numbers, character scalars, character vectors or character matrices. This property is updated as the user moves around the Grid changing data.


VariableHeight Property
Applies To: CoolBar

Description

The VariableHeight property specifies whether or not a CoolBar displays bands at the minimum required height, or all the same height (that of the largest).

VariableHeight is a single number with the value 0 (same height) or 1 (variable height). The default is 1.


View Property
Applies To: ListView

Description

The View property specifies how the items in a ListView object are displayed. It is a character vector which may have one of the following values; 'Icon' (the default), 'SmallIcon', 'List' or 'Report'.

When View is 'Icon' or 'SmallIcon', the items are arranged row-wise with large or small icons as appropriate. When View is set to 'List', the items are arranged column-wise using small icons. When View is set to 'Report', the items are displayed in a single column using small icons but with the matrix specified by ReportInfo displayed alongside. In this format, the ListView also provides column headings which are specified by the ColTitles property. The alignment of these titles (and of the data in the columns beneath them) is defined by the ColTitleAlign property. Examples of different views are illustrated below.


Visible Property

Applies To

Description

This property specifies whether or not an object is currently visible. It is a single number with the value 0 (object is invisible) or 1 (object is visible). The default is 1. Setting Visible on and off is a way to pop a dialog box up and down as required.

Note that an invisible object is not necessarily inactive, and is capable of generating events. For example, a Button with a Cancel property of 1 will generate a Select (30) event (if enabled) whether or not it is visible. An invisible object will also respond to methods and events sent to it by ⎕NQ.


WantsReturn Property
Applies To: Edit RichEdit

Description

This boolean property specifies the behaviour of the Enter key for a multi-line Edit (Style 'Multi') and a RichEdit object.

A value of 0 means that the Enter key is ignored by the Edit or RichEdit. Instead, the Enter key will (if appropriate) cause a Select event on a Button in the same Form. The user must press Ctrl+Enter to input a new line.

A value of 1 means that pressing the Enter key will introduce a new line into the object.

WantsReturn must be established when the object is created by ⎕WC and may not subsequently be altered using ⎕WS. Its default value is 0 in an Edit and 1 in a RichEdit.


WeekNumbers Property
Applies To: Calendar DateTimePicker

Description

The WeekNumbers property specifies whether or not a Calendar object displays week numbers.

WeekNumbers is a single number with the value 0 (week numbers are not shown) or 1 (week numbers are shown); the default is 0.


Weight Property
Applies To: Font

Description

This property specifies the degree of boldness of a font associated with a Font object. It is a number in the range 0 to 1000, where 0 represents very faint and 1000 represents very bold. There is no default; the value of this property reflects the degree of boldness of the font allocated by Windows.

In general, 400 means normal and 700 means bold.


WordFormat Property
Applies To: RichEdit

Description

The WordFormat property is identical to the CharFormat property except that it is used to apply formatting to the selected word or words in a RichEdit object. If the selection is empty but the insertion point is inside a word, the formatting is applied to the word. See CharFormat for further details.


Wrap Property
Applies To: ListView ProgressBar Spinner UpDown

Description

The Wrap property is boolean and has a default value of 1.

For a ListView it specifies whether or not long labels (specified by the Items property) may be wrapped or not.

For a ProgressBar object it determines whether or not the object starts over again when it reaches its upper limit. In particular, if Wrap is 1, the value obtained when you set the Thumb property is given by the expression: LIMITS[1]+THUMB|LIMITS[2] where THUMB is the value to which you set the Thumb property and LIMITS is the value of the Limits property.

For a Spinner , Wrap determines what happens when the value in the Spinner reaches its upper or lower limit. If Wrap is 1 the Spinner will wrap around to its opposite limit. Otherwise it will stick.


XRange Property

Applies To

Description

XRange and YRange together determine a user-defined co-ordinate system. These properties are effective on the object's children which have Coord set to 'User'.

XRange is a 2-element numeric vector containing the x-coordinate of the top left and bottom right interior corners of the object respectively. See Coord for further details.


YRange Property

Applies To

Description

XRange and YRange together determine a user-defined co-ordinate system. These properties are effective on the object's children which have Coord set to 'User'.

YRange is a 2-element numeric vector containing the y-coordinate of the top left and bottom right interior corners of the object respectively. See Coord for further details.


Yield Property
Applies To: Root

Description

This property specifies the frequency with which APL yields to Windows and applies mainly to Version 7. Multi-tasking in Windows 3.x is implemented by task switching between applications whenever any application requests a message from the queue. An application that is purely performing computational or file-handling tasks will therefore prevent all other applications from running. Well-behaved Windows applications should yield control by requesting a message periodically even though no user interaction is currently taking place. However, this operation takes a perceptible length of time, even if no other applications are running.

By default, Dyalog APL/W yields control to Windows approximately every 1/5th of a second. This is implemented by checking the time at the beginning of each line of executable APL code and yielding if 1/5th of a second or more has elapsed since the last yield. This mechanism also allows APL to detect user interrupts (which are simply Windows messages) during the execution of code.

In most circumstances yielding every 1/5th of a second produces "good" Windows behaviour with little impact on APL throughput. However, in some cases it may be beneficial to use the Yield property to explicitly control the yield frequency. An example is in an application that takes an appreciable time to redraw an existing graphical picture. If APL yields before the entire picture has been redrawn, some objects will be erased before others are redrawn, causing a flickering effect.

The value of Yield is an integer expressed in 1/1000's of a second. Its default value is 200. Yield defines the period of time allowed to elapse between the execution of successive lines of APL code before APL yields to Windows by requesting a message from the Windows queue. If Yield is set to zero APL does not explicitly yield.

Note that the value of this property only controls the yield frequency when APL is executing user-defined code. APL may also yield implicitly during ⎕DQ, ⎕NQ, ⎕WC, ⎕SR, ⎕WS and ⎕WG and in communicating with Auxiliary processors. Note that setting Yield to 0 (or to a very high value) during the execution of code that does not implicitly yield will effectively de-activate all other applications (including Program manager) and disable APL interrupts (Ctrl+Break). It should therefore be used with extreme caution.


ActivateApp Event

ActivateApp Event 137
Applies To: Root

Description

If enabled, this event is reported when the user switches to or from a Dyalog APL/W application.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ActivateApp' or 137
[3] | Activation flag | 0 or 1

The Activation flag is 0 when the user switches from Dyalog APL to another application.

The Activation flag is 1 when the user switches to Dyalog APL from another application.


AddCol Event

AddCol Event 153
Applies To: Grid

Description

If enabled, this event is reported by the Grid object if the user presses the Cursor Right key, and the current cell (CurCell) is within the last column on the Grid. The default action is to append a new column to the contents of the Grid. If you attach a callback function to this event and have it return a value of 0, a new column will not be appended to the Grid. Note that the event will not be generated unless the second element of the AutoExpand property is set to 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'AddCol' or 153
[3] | Column number | number of the new column (integer).

An application may insert a new column into a Grid by calling AddCol as a method. The argument is a 1 to 7-element array as follows:

[1] | Column number: | number of the new column (integer)
[2] | Column title: | character vector or matrix
[3] | Column width: | integer
[4] | Undo flag | 0 or 1
[5] | Resize flag | 0 or 1
[6] | Title colour | negative integer or 3-element RGB vector
[7] | Line type | integer

If you are using default column headings, Column title will be ignored and the columns will be re-labelled with the default titles. If you have set ColTitles, the title you specify will be inserted. If you omit Column title, a blank title will be inserted.

Similarly, if you have not previously set CellWidths, ResizeCols, ColTitleFCol or ColLineTypes, or if you have given them a scalar value, the corresponding parameter will be ignored. However, if you have specified CellWidths, ResizeCols, ColTitleFCol or ColLineTypes to be a vector, the number you specify in the corresponding parameter will be inserted into the appropriate property vector.

If you omit to specify Column width for the new column, it will be assigned a default value; new values for the other properties default to 0.

Undo flag (default 1) specifies whether or not the addition of the new column may subsequently be undone by an Undo event.

To insert a new column before the first one, you must specify the Column number as 1 (or 0 if ⎕IO is 0). To add a new column after the last one, you may specify any number greater than the current number of columns. The data in the new column will be set to 0 if the Values property is numeric, or to an empty character vector otherwise.


AddRow Event

AddRow Event 152
Applies To: Grid

Description

If enabled, this event is reported by the Grid object if the user presses the Cursor Down key, and the current cell (CurCell) is within the last row on the Grid. The default action is to append a new row to the contents of the Grid. If you attach a callback function to this event and have it return a value of 0, a new row will not be appended to the Grid.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'AddRow' or 152
[3] | Row number | integer.

An application may insert a new row into a Grid by calling AddRow as a method. The argument is a 1 to 7-element array as follows:

[1] | Row number: | integer
[2] | Row title: | character vector or matrix
[3] | Row height: | integer
[4] | Undo flag | 0 or 1
[5] | Resize flag | 0 or 1
[6] | Title colour | negative integer or 3-element RGB vector
[7] | Line type | integer

If you are using default row titles, Row title will be ignored and the rows will be re-labelled with default titles. If you have set RowTitles, the title you specify will be inserted. If you omit Row title, a blank title will be inserted.

Similarly, if you have not previously set CellHeights, ResizeRows, RowTitleFCol or RowLineTypes, or if you have given them a scalar value, the corresponding parameter will be ignored. However, if you have specified CellHeights, ResizeRows, RowTitleFCol or RowLineTypes to be a vector, the number you specify in the corresponding parameter will be inserted into the appropriate property vector. If you omit Row height, it will be assigned a default value; new values for the other properties default to 0.

Undo flag (default 1) specifies whether or not the addition of the new row may subsequently be undone by an Undo event.

To insert a new row before the first one, you must specify the Row numberas 1 (or 0 if ⎕IO is 0). To add a new row after the last one, you may specify any number greater than the current number of rows. The data in the new row will be set to 0 if the Values property is numeric, or to an empty character vector otherwise.


AmbientChanged Event

AmbientChanged Event 533
Applies To: ActiveXContainer ActiveXControl

Description

If enabled, this event is reported when any of the ambient properties change in an application hosting an ActiveXControl object. The new values of the ambient properties are available from the FontObj, Fcol and Bcol properties of the ActiveXContainer.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'AmbientChanged' or 533
[3] | Property code | integer
[4] | Description | character vector

For properties supported by Dyalog APL, Property code and Description may be one of the following:

Note that other ambient properties may be reported, although these have no corresponding Dyalog APL property.


AnimStarted Event

AnimStarted Event 294
Applies To: Animation

Description

If enabled, this event is reported by an Animation object just before an AVI clip starts playing

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'AnimStarted' or 294

This event is reported for information only and cannot be disabled or modified in any way.


AnimStopped Event

AnimStopped Event 295
Applies To: Animation

Description

If enabled, this event is reported by an Animation object just after an AVI clip has stopped playing

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'AnimStopped' or 295

This event is reported for information only and cannot be disabled or modified in any way.


BadValue Event

BadValue Event 180
Applies To: ButtonEdit Edit Spinner

Description

If enabled, this event is reported by an Edit or Spinner object when the user enters invalid data into the object and then switches focus to another control or to another application. Data is invalid if it conflicts with the FieldType property, or for a Spinner if it is outside the range specified by the Limits property.

The default action of the event is to sound the bell (beep). You can disable this action by returning 0 from a callback function or by setting its action code to ¯1. Note that in neither case is the Value property of the object updated. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BadValue' or 180
[3] | Object name | character vector

The third element of the event message is either the name of the control to which the user has switched the focus, or is an empty vector if the focus has gone to another application.


BalloonHide Event

BalloonHide Event 862
Applies To: SysTrayItem

Description

If enabled, this event is reported by an SysTrayItem object when a BalloonTip disappears for any reason other than it is dismissed by a timeout or because the user clicked the mouse.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BalloonHide' or 862

This event is reported for information only and cannot be disabled or modified in any way


BalloonShow Event

BalloonShow Event 861
Applies To: SysTrayItem

Description

If enabled, this event is reported by an SysTrayItem object when a BalloonTip is displayed using the ShowBalloonTip method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BalloonShow' or 861

This event is reported for information only and cannot be disabled or modified in any way


BalloonTimeout Event

BalloonTimeout Event 863
Applies To: SysTrayItem

Description

If enabled, this event is reported by an SysTrayItem object when a BalloonTip is dismissed by a timeout or because the user clicked the close (X) button..

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BalloonTimeout' or 863

This event is reported for information only and cannot be disabled or modified in any way


BalloonUserClick Event

BalloonUserClick Event 864
Applies To: SysTrayItem

Description

If enabled, this event is reported by an SysTrayItem object when a BalloonTip is dismissed because the user clicked the mouse in the body of the BalloonTip. It is not reported when the user clicks the close (X) button.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BalloonUserClick' or 864

This event is reported for information only and cannot be disabled or modified in any way


BeginEditLabel Event

BeginEditLabel Event 300
Applies To: ListView TreeView

Description

If enabled, this event is reported when the user clicks on an item in a ListView or TreeView object that has the focus, and signals the start of an edit operation. The default processing for the event is to display a pop-up edit box around the item and to permit the user to change its text.

You may disable the operation by setting the action code for the event to ¯1. You may prevent a particular item from being edited by returning 0 from a callback function. You may also initiate the edit operation by calling BeginEditLabel as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'BeginEditLabel' or 300
[3] | Item number | Integer. The index of the item.


CalendarDblClick Event

CalendarDblClick Event 273
Applies To: Calendar

Description

If enabled, this event is reported when the user double-clicks the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CalendarDblClick' or 273
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CalendarDown Event

CalendarDown Event 271
Applies To: Calendar

Description

If enabled, this event is reported when the user depresses the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CalendarDown' or 271
[3] | Item Number | integer (see below)
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer (see below)

The 6th element of the event message is one of the following values:

If the value of the 6th element of the event message is 2 (CALENDARDATE), the 3rd element is the corresponding date reported as an IDN.

If the value of the 6th element of the event message is 5 (CALENDARDAY), the 3rd element is the index of the corresponding weekday (0-6).

If the value of the 6th element of the event message is 6 (CALENDARWEEKNUM), the 3rd element is the date of the first (leftmost) day in the corresponding week, reported as an IDN.

Otherwise, the 3rd element of the event message is 0.


CalendarMove Event

CalendarMove Event 274
Applies To: Calendar

Description

If enabled, this event is reported when the user moves the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CalendarMove' or 274
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CalendarUp Event

CalendarUp Event 272
Applies To: Calendar

Description

If enabled, this event is reported when the user releases the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CalendarUp' or 272
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CellChange Event

CellChange Event 150
Applies To: Grid

Description

If enabled, this event is reported when the user changes the contents of a cell in a Grid object and then attempts to move to another cell or to another control outside the Grid.

The purpose of this event is to give the application the opportunity to perform additional validation before the update occurs (and to prevent it if necessary) or to update other cells in the Grid as a result of the change.

The default action for the CellChange event is to update the appropriate element of the Values property with the new data. This action can be disabled by returning 0 from the attached callback function. Notice however, that the user is not prevented from moving away from the cell. If you are using this event to perform additional validation and you require the user to correct the data before moving away, you must force the user back to the cell in question by generating a CellMove event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 8-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'CellChange' or 150
[3] | Cell row | integer
[4] | Cell column | integer
[5] | New data | number or character array
[6] | Object name | character vector (name of object to which the user has transferred focus)
[7] | New cell (row) | integer
[8] | New cell (column) | integer

If the user moves to another cell in the Grid, the 6th element of the event message is the name of the Grid object and elements 7 and 8 specify the new cell address (⎕IO dependent).

If the user switches the input focus to another control or selects a MenuItem, the 6th element of the event message contains the name of that control or MenuItem. If the user switches to another application, the 6th element of the event message is an empty character vector. In all these cases, the 7th and 8th elements are 0.

The 5th element of the event message contains the data value that will be used to update the Values property. This will be numeric if the FieldType of the associated Edit object is Numeric, LongNumeric, Date, LongDate or Time. Otherwise, it will be a character array.

An application can update an individual cell in the Grid under program control by calling CellChange as a method. If so, the New object, New cell row and New cell column parameters may be omitted.


CellChanged Event

CellChanged Event 164
Applies To: Grid

Description

If enabled, this event is reported after the user has changed the contents of a cell in a Grid object and then moved to another cell or to another control outside the Grid. The purpose of this event is to give the application the opportunity to perform calculations, and perhaps to update other cells in the Grid as a result of the change.

Note that this event is reported after the change has taken place, and after the Values property has been updated. Furthermore, neither setting the event action code to ¯1 nor returning 0 from a callback function has any effect. If you wish to validate the new data you should use the CellChange (150) event instead.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 5-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'CellChanged' or 164
[3] | Cell row | integer
[4] | Cell column | integer
[5] | New data | number or character array

The 5th element of the event message contains the data value that has been used to update the Values property. This will be numeric if the FieldType of the associated Edit object is Numeric, LongNumeric, Date, LongDate or Time. Otherwise, it will be a character array.

If you want to update an individual cell under program control, you may call CellChange , but not CellChanged, as a method.


CellDblClick Event

CellDblClick Event 163
Applies To: Grid

Description

If enabled, this event is reported when the user double-clicks a mouse button whilst over a cell in a Grid. The purpose of this event is to allow an application to enable some special action on double-click. This event may not be disabled.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CellDblClick' or 163
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.


CellDown Event

CellDown Event 161
Applies To: Grid

Description

If enabled, this event is reported when the user presses a mouse button down whilst over a cell in a Grid. The purpose of this event is to allow an application to display a pop-up Menu or a Locator over a cell in a Grid or to take some other special action.

The default action is to generate a CellMove event which will then position the user on the new cell. This action can be prevented by returning 0 from the callback function, in which case the normally ensuing CellMove event will not occur.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 9 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CellDown' or 161
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.

An application can position the user on a particular cell in a Grid by calling CellDown as a method, but it is recommended that a CellMove event is used instead.


CellError Event

CellError Event 157
Applies To: Grid

Description

If enabled, this event is reported when the user inserts invalid data into the Edit object associated with a cell in a Grid object and then attempts to move to another cell or to another control outside the Grid. It is also reported if the user selects a MenuItem.

The default action for the CellError event is to sound the bell (beep). This action can be disabled by returning 0 from the attached callback funtion. Whatever the result of the callback, the user will be prevented from moving to another cell in the Grid and the CurCell and Values properties will remain unchanged. The user is not prevented from switching to any other control or to another application. However, if and when the user returns to the Grid, the current cell (CurCell) remains the invalid one and the user may not select a different one until the invalid data in the cell has been corrected. If you wish to allow the user to move to another cell without correcting the data, you may do so by generating a CellMove event explicitly. However, the Values property will remain unchanged and the invalid contents of the Edit object will simply be discarded.

The event message reported as the result of ⎕DQ or supplied as the right argument to your callback function, is an 8-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'CellError' or 157
[3] | Cell row | integer
[4] | Cell column | integer
[5] | Invalid data | character vector
[6] | Object name | character vector (name of object to which the user has transferred focus)
[7] | New cell (row) | integer
[8] | New cell (column) | integer

If the user moves to another cell in the Grid, the 6th element of the event message is the name of the Grid object and elements 7 and 8 specify the cell address (⎕IO dependent).

If the user switches the input focus to another control or selects a MenuItem, the 6th element of the event message contains the name of that control or MenuItem. If the user switches to another application, the 6th element of the event message is an empty character vector. In all these cases, the 7th and 8th elements are 0.

The 5th element of the event message contains the character vector in the Text property of the associated Edit object which is inconsistent with its FieldType.


CellMove Event

CellMove Event 151
Applies To: Grid

Description

If enabled, this event is reported when the user attempts to position the cursor over a cell in a Grid by clicking the left mouse button or by pressing a cursor movement key. The purpose of this event is to allow an application to perform some action prior to the user entering a cell, or to inhibit entry to a cell.

The default action is to position the user on the new cell. This action can be prevented by returning a 0 from the callback function attached to the event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CellMove' or 151
[3] | New cell (row) | integer
[4] | New cell (column) | integer
[5] | Scroll flag | 0 or 1
[6] | Selection flag | 0, 1 or 2
[7] | Mouse flag | 0 or 1

The 5th element of the event message is 1 if switching to the new cell would cause the Grid to scroll.

The 6th element of the event message is 1 if the user is moving to the new cell by extending the selection. It is 2 if the user selects an entire row or column (by clicking on a title), which moves the current cell to the first one in the selection.

The 7th element of the event message is 1 if the mouse is used to switch to a new cell.

An application can position the user on a particular cell in a Grid by calling CellMove as a method. If so, the argument need contain only the New cell row and New cell column parameters.


CellOver Event

CellOver Event 160
Applies To: Grid

Description

If enabled, this event is reported when the user moves the mouse poimter whilst over a cell in a Grid.

There is no default action for this event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 9 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CellOver' or 160
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user moves the mouse pointer over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.


CellUp Event

CellUp Event 162
Applies To: Grid

Description

If enabled, this event is reported when the user releases a mouse button down whilst over a cell in a Grid. This event is a companion to the CellDown event and could be used to hide a pop-up which was displayed in response to the CellDown. The CellUp event performs no default action and may not be disabled.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CellUp' or 162
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent .

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.

An application can position the user on a particular cell in a Grid by calling CellDown event as a method, but it is recommended that a CellMove event is used instead.


Change Event

Change Event 36
Applies To: ButtonEdit Combo Edit RichEdit Spinner

Description

If enabled, this event is reported when the user alters the text in a Combo or Edit object (by typing). The event is not applicable for a Combo with Style 'Drop' because this Style does not allow the user to alter data. The Change event is not reported repeatedly as the user edits the data. Instead, it is reported when the user indicates that he has finished with the field by :

  1. clicking on another object, or
  2. causing an event on another object (without altering the input focus) which will fire a callback function or cause ⎕DQ to terminate. This can occur if the user chooses a MenuItem, or fires a Button with the Default or Cancel property by pressing Enter or Esc, or selects an object using an accelerator key.

The purpose of the Change event is to allow the application to validate data which has been newly entered to the field, before proceeding with another action. It is for this reason that the event is fired not just when the input focus changes, but also when the user takes some action that could cause the application to do something else.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Change' or 36
[3] | Object name | character vector (name of object that is to receive the focus or generate an event)

If the focus is transferred to an external application, the third element is an empty vector.

The default processing for this event is to allow the focus to change (if applicable) and to reset the internal flag that indicates that the data in the field has changed.

If you disable the event by setting the "action" code to ¯1, or inhibit it by returning 0 from a callback, the focus change (if applicable) is allowed to proceed, but the internal flag is not reset. If you wish to prevent the focus change you must explicitly reset the focus back onto the object that generated the event.

If the event was generated because the user switched to another application, and you return a 0 from your callback (because the data was not valid), the flag marking the Combo or Edit as having been changed remains set. If the user returns to your application by re-focusing on the same Combo or Edit, nothing happens immediately, but because the field is marked as changed (the flag was not reset) you will get another Change event when he leaves it. However, if the user returns to your application in some other way, e.g. by focusing on another object or by selecting a MenuItem, a second Change event will be generated immediately.

The following function illustrates how Change events can be processed. The Check function referred to in line[4] is assumed to return 1 if the data is valid and 0 if not.

[0]   R←VALIDATE Msg
[1]  ⍝ Validates field contents after Change event
[2]
[3]  ⍝ Normal exit (R←1) if data is valid
[4]    →(R←Check⊃Msg)/Exit
[5]
[6]  ⍝ R now 0, so field remains marked as "changed"
[7]
[8]  ⍝ If user has switched to another application,
[9]  ⍝ we need take no further action because we will
[10] ⍝ get a second Change event when he returns.
[11]  →(''≡3⊃Msg)/Exit
[12]
[13] ⍝ Display error box (prepared earlier)
[14]   'ERR' ⎕WS 'Text' 'Data is invalid'
[15]   ⎕DQ'ERR'
[16]
[17] ⍝ Restore focus to bad field
[18]   ⎕NQ(⊃Msg)40
[19]
[20] Exit:


ClickComment Event

ClickComment Method 225
Applies To: Grid

Description

If enabled, a ClickComment event is generated when the user clicks the mouse in a comment window of a Grid.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ClickComment' or 225
[3] | Row | integer
[4] | Column | integer

The event message reports the co-ordinates of the cell. The default action is to raise the comment window so that it appears above all other, potentially overlapping, comment windows.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.


ClipChange Event

ClipChange Event 120
Applies To: Clipboard

Description

If enabled, this event is reported when another application changes the contents of the Windows clipboard.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ClipChange' or 120


Close Event

Close Event 33

Applies To

Description

A Close event is generated when an object is destroyed. For a Form or SubForm, the event may be generated by the user selecting "Close" from its System Menu. In this case, the event is reported before the window is destroyed, and you may prevent it from going ahead by associating a callback function which returns a result of 0.

By trapping this event you can control termination of your application in many different ways. For example, you could:

  • automatically close all Forms in your application when the master Form is closed.
  • prevent the user from terminating the application if it is inappropriate at that time.
  • display an "Are you sure ?" MsgBox.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Close' or 33


CloseUp Event

CloseUp Event 46
Applies To: DateTimePicker

Description

If enabled, this event is reported by a DateTimePicker object just before the drop-down calendar is hidden. It applies only if the Style of the DateTimePicker is 'Combo'.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'CloseUp' or 46

This event is reported for information only and cannot be disabled or modified in any way.


ColorChange Event

ColorChange Event 430
Applies To: ColorButton

Description

If enabled, this event is reported by a ColorButton object when the user chooses a colour from the colour selection drop-down.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ColorChange' or 430
[3] | New Colour | 3-element integer vector

The 3rd element of the event message contains the RGB value for the selected colour.

Note that the event is reported when the user chooses a colour, whether or not the newly selected colour differs from the one that was previously selected.

This event is reported for information only and cannot be disabled or modified in any way.


ColumnClick Event

ColumnClick Event 320
Applies To: ListView

Description

If enabled, this event is reported when the user clicks on the column heading in a ListView object. This event may not be disabled or affected by a callback function in any way.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ColumnClick' or 320
[3] | Column number | Integer
[4] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[5] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down


Configure Event

Configure Event 31

Applies To

Description

If enabled, this event is generated when the configuration of an object (position and/or size) is about to change.

For a Form, the event is generated when the Form is resized or moved by the user.

For any object other than a Form, it can occur in one of two ways. Firstly, whenever a Form is resized, the system (by default) re-arranges its children so as to maintain their relative position and size. This generates a Configure event (if enabled) for each one of them.

Secondly, it can occur as a result of the user resizing the object directly. This facility is enabled by setting the object's Sizeable property to 1.

Note that a Configure event is not reported when an object is moved using "drag & drop". See Dragable (property) and DragDrop (event) for details of this operation.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Configure' or 31
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of object
[6] | W | width of object

For any object, the operation can be prevented by returning a scalar 0 from the callback function associated with the Configure event.

Full-Drag Considerations

The user may choose a system option, described here as full-drag, whereby the contents of the window are re-arranged during a resize operation.

If you manage the geometry of your controls using the Attach property, APL honours full drag during resize, changing the size and position of your controls dynamically for you.

However, if you manage the geometry of controls using Configure event callbacks, you should consider the following.

  1. If full drag is in enabled, APL generates Configure events duringthe resize operation, allowing you to dynamically alter the geometry of controls as you wish. However, the following restrictions apply:

  2. Configure callbacks will only be executed when the interpreter is idle. For example during a ⎕DQ or during Session input (6-space prompt). If the user attempts to move/resize a window that has Configure callbacks attached when the interpreter is busy, the move/resize is not started. This is similar to the operation in non full drag mode, where the move/resize is allowed but the callback does not execute until the interpreter again becomes idle.

  3. The callback cannot be traced. It is necessary to debug the callback code with full drag disabled.

  4. Any untrapped errors in the Configure callback will not halt execution in the normal way, but will instead be reported in the Status Window. Note that it is also not possible to trap such errors higher up the SI stack than the Configure Callback.

  5. There are some programming styles to be avoided if full dragConfigure callbacks are to be processed correctly. For example events generated by monadic ⎕NQ within a Configure callback will not be processed until the entire resize operation has been completed.

  6. It is not possible to save a workspace from within a Configure Callback in full drag mode.

The above restrictions apply to Configure events when full drag is enabled, but only when full drag is enabled. The behaviour of Configure callbacks with full drag disabled is the same as for other events.


ContextMenu Event

ContextMenu Event 410

Applies To

Description

If enabled, this event is reported when the user performs the standard Windows action to display a ContextMenu. These include clicking/releasing the right mouse button and pressing F10.

If the object has its own standard context menu, for example an Edit object, the default action is to display this menu. If the object is dockable (see Docking Property), the default action is to display the standard (English) Dyalog APL docking menu.

You may use this event to display your own pop-up context menu, by ⎕DQ'ing it within a callback function. In this case, your callback function should return 0 to disable the standard context menu.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ContextMenu' or 410
[3] | (reserved) | Empty character vector
[4] | Y | y-position of the mouse (number)
[5] | X | x-position of the mouse (number)


Create Event

Create Event 34

Applies To

Description

If enabled, this event is reported after an object has been created. You may not nullify or modify the event with a 0-returning callback, nor may you generate the event using ⎕NQ, or call it as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Create' or 34
[3] | Flag | 1 = object was created by ⎕WC 0 = object was created by )LOAD, )COPY or ⎕OR

This event also applies to the Session object ⎕SE and may be used to fire a start-up function (in the ⎕SE namespace) when APL initialises.


DDE Event

DDE Event 50
Applies To: Root

Description

If enabled, a DDE event is generated whenever a DDE message is received by Dyalog APL. This will occur whenever a server notifies APL that the value of a shared variable has changed, and whenever a client application requests data from APL. If you have several shared variables, you can determine which of them has changed or whose value has been requested using ⎕SVS.

This event only applies to the Root object ".", so to enable it you must execute one of the following statements :

      '.' ⎕WS 'Event' 50 1

or

      '.' ⎕WS 'Event' 50 fn

or

      '.' ⎕WS 'Event' 50 fn larg

The first statement would cause ⎕DQ to terminate on receipt of a DDE event. The second would cause it to call "fn" each time. The third would do likewise but the value in "larg" would be supplied as its left argument.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DDE' or 50

Note: Due to the nature of DDE "conversations" messages may be received when in fact no change in the value of any shared variables has occurred. Your application code must therefore be prepared to cater for this situation.


DateTimeChange Event

DateTimeChange Event 267
Applies To: DateTimePicker

Description

If enabled, this event is reported by a DateTimePicker object when the user changes the DateTime value. This occurs when the user selects a new date from the drop-down calendar, or increments or decrements a date time element using the spinner buttons, or edits a datetime element using the keyboard. In the latter case, the event may not be generated until the input focus leaves the corresponding date time element.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DateTimeChange' or 267
[3] | IDN | integer
[4] | Hour | integer
[5] | Minute | integer
[6] | Second | integer

This event is reported for information only and cannot be disabled or modified in any way.


DisplayChange Event

DisplayChange Event 137
Applies To: Root

Description

If enabled, this event is reported when the user changes the screen resolution or number of colours. The event is reported for information only; you cannot prevent the change from occurring.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DisplayChange' or 137
[3] | Height | Integer. Number of pixels in the y-direction
[4] | Width | Integer. Number of pixels in the x-direction
[5] | Number of colours | Integer.


DockAccept Event

DockAccept Event 483
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a host object just before it accepts a client object docking operation. This event is reported (by the host) immediately after the DockRequest is reported (by the client).

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockAccept' or 483
[3] | Client Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | 4-element nested

Elements 4-7 of this event message are the same as those reported by DockMove, and the effect of a callback function is identical. See DockMove for further information.


DockCancel Event

DockCancel Event 485
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a client object when the user aborts a docking operation by pressing Escape.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockCancel' or 485

This event is reported for information only and cannot be cancelled or inhibited in any way.


DockEnd Event

DockEnd Event 484
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a client object after it has been successfully docked in a host object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockEnd' or 484

This event is reported for information only and cannot be cancelled or inhibited in any way.


DockMove Event

DockMove Event 481
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a host object when a dockable object (the client) is dragged over it. The event will only be reported if the name of the client object is included in the list of objects that the host object will accept, which is defined by its DockChildren property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockMove' or 481
[3] | Client Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | (see below)

The 4th element of the event message Edge is a character vector that indicates along which edge of the host object the client object will be docked if the mouse button is released. It is either 'Top', 'Bottom', 'Left', 'Right' or 'None'. The latter indicates that the object will not be docked. An object will dock only if the mouse pointer is inside, and sufficiently near to an edge of, the host.

The 5th and 6th elements of the event message report the position of the mouse pointer in the host object.

The 7th element of the event message is a 4-element nested vector containing the y-position, x-position, height and width of a rectangle. If Edge is 'None', this is the bounding rectangle of the client object. Otherwise, the rectangle describes a docking zone in the host that the client object will occupy when the mouse button is released.

If a callback function returns 0, the system displays the bounding rectangle and not a docking zone, and the docking operation is inhibited. You could use this mechanism to prohibit docking along one or more edges, whilst allowing it along others.

A callback function may modify the event message to cause a different sized docking zone to be displayed, or to force docking along a particular edge.

The DockMove event is generated repeatedly as the docking object is dragged.


DockRequest Event

DockRequest Event 482
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a client object just before it is docked in a host object, when the user releases the mouse button.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockRequest' or 482
[3] | Host Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | 4-element nested

Elements 4-7 of this event message are the same as those reported by DockMove, and the effect of a callback function is identical. See DockMove for further information.


DockStart Event

DockStart Event 480
Applies To: CoolBand CoolBar Form SubForm ToolControl

Description

If enabled, this event is reported by a dockable object (one whose Dockable property is set to 1) when the user starts to drag it using the mouse.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DockStart' or 480

A callback function may prevent the docking operation from starting by returning 0.


DragDrop Event

DragDrop Event 11

Applies To

Description

If enabled, this event is reported when the user drops one object over another. It is generated by the object which is being dropped on.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DragDrop' or 11
[3] | Object name | character vector (name of dragged object)
[4] | Y | y-position of mouse pointer
[5] | X | x-position of mouse pointer
[6] | H | height of dragged object
[7] | W | width of dragged object
[8] | Shift State | numeric scalar containing the sum of the values associated with the Shift(1), Ctrl(2) and Alt(4) keys when the object was dropped.

Y, H, X and W are reported relative to the object being dropped on.


DropDown Event

DropDown Event 45

Applies To

Description

If enabled, this event is reported when the user clicks the drop-down button in a Combo, ComboEx, ColorButton, DateTimePicker or Menu object, just before the drop-down list, colour selection, calendar or -menu is displayed.

For a Button this event only applies if the Style of the Button is Split. For such a Button and for the ButtonEdit object there is no default processsing for the event and it is the responsibility of the programmer to take appropriate action in a call-back function.

For a DateTimePicker this event only applies if the Style of the DateTimePicker is 'Combo'.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DropDown' or 45

This event is reported for information only and cannot be disabled or modified in any way.


DropFiles Event

DropFiles Event 450

Applies To

Description

If enabled, this event is reported when the user drags a file icon or a set of file icons and drops them onto the object. The system takes no action other than to report the event.

Note that the event is only reported if AcceptFiles is set to 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DropFiles' or 450
[3] | Files | Vector of character vectors containing the file names.
[4] | Item number | Integer. The index of the item within the object onto which the file(s) was dropped. Applies only to objects that have an Items property such as List, ListView and TreeView.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key


DropObjects Event

DropObjects Event 455

Applies To

Description

If enabled, this event is reported when the user drags an object icon or a set of object icons from the Explorer Tool or Find Objects Tool (which are part of the Dyalog APL Session) and drops them onto the object. The system takes no action other than to report the event. You can use this event to extend drag-drop functionality in your Session. For example, you could perform an operation by drag-dropping an APL object icon onto a Button in the Session toolbar.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DropObjects' or 455
[3] | Objects | Vector of character vectors containing the object names.
[4] | Item number | Integer. The index of the item within the object onto which the file(s) was dropped. Applies only to objects that have an Items property such as List, ListView and TreeView. Otherwise this value is -1.
[5] | Shift state | Integer. Sum of 1=Shift key, 2=Ctrl key, 4=Alt key


DyalogCustomMessage1 Event

DyalogCustomMessage1 Event 95
Applies To: Form

Description

This event allows external applications and dynamic link libraries to insert events into the Dyalog APL/W message queue.

DyalogCustomMessage1 may be invoked from a C program as follows:

msg=RegisterWindowMessage("DyalogCustomMessage1");
SendMessage(hWnd,msg,wParam,lParam);

where hWnd is the window handle of the object in the Dyalog APL Workspace. If the object is a Form, this may be obtained using FindWindow(). If not, hwnd may be passed to the external process as an argument to a function.

The parameters wParam and lParam are reported as numeric arguments to the APL callback function.

NOTE: It is not possible to pass pointers to data in wParam or lParam. When the APL callback executes the pointers may not be valid.

If a callback function is attached to the event, the callback function will be run when the event reaches the top of the queue.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1or by returning 0 from a callback function.

The result of a callback function is not returned to the external application.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'DyalogCustomMessage1' or 95
[3] | wparam | integer
[4] | lparam | integer


EndEditLabel Event

EndEditLabel Event 301
Applies To: ListView TreeView

Description

If enabled, this event is reported when the user signals completion of an edit operation in a ListView or TreeView object. This occurs when the item being edited loses the focus or when the user presses the Enter key. The default processing for the event is to update the item label (string) with the edited text in the pop-up edit box.

You may disable the update operation by setting the action code for the event to ¯1. You may also prevent the update from occurring by returning 0 from a callback function. You may specify the text used to update the item by returning the event message (containing the desired text) from a callback function. Finally, you may change the text of any item dynamically by calling EndEditLabel as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'EndEditLabel' or 301
[3] | Item number | Integer. The index of the item.
[4] | Text | character vector containing the text that will be used to update the item's label.


EndSplit Event

EndSplit Event 282
Applies To: Splitter

Description

If enabled, this event is reported when the user releases the left mouse button to signify the end of a drag operation on a Splitter object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'EndSplit' or 282
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of the Splitter
[6] | W | width of the Splitter

See also StartSplit, Splitting.


ExitApp Event

ExitApp Event 132
Applies To: Root

Description

If enabled, this event is reported when the user attempts to terminate a Dyalog APL/W application from the Windows Task List.

The Windows Task list displays the names of all running applications. The name displayed for a Dyalog APL/W application is defined by the Caption property of the system object Root. If you fail to define this property, there will be no entry for the application in the Task List.

If you wish to prevent the user from terminating your application from the Windows Task List, you may disable this event by setting its action code to ¯1. However, if you do this, your user may be puzzled as to why the operation does not work as expected. An alternative is to attach a callback function to the event which displays a message box. Not only does this allow you to provide user feedback, but you can provide confirm/cancel options. If your callback function returns a zero, your application will not be terminated.

Note that this event only provides for termination via the Windows Task List. See also the ExitWindows event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ExitApp' or 132


ExitWindows Event

ExitWindows Event 131
Applies To: Root

Description

If enabled, this event is reported when the user attempts to terminate the Windows Operating System. When this is done, Windows gives all running applications the opportunity to prevent it. Typically, an application that has unsaved changes will display a dialog box warning the user of this situation and offering the opportunity to cancel the termination. The default action for this event is to allow Windows to close. You can prevent this by returning a zero from a callback function. You can also prevent the user from closing Windows down by disabling the event altogether. This is achieved by setting its action code to ¯1. In most cases this is less preferable than the callback method as it does not allow you to inform the user as to why Windows won't terminate.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ExitWindows' or 131
[3] | Flag | 0 or 1


Expanding Event

Expanding Event 302
Applies To: Grid TreeView

Description

If enabled, this event is reported by a Grid or a TreeView object just before it is about to expand to show additional rows or children of the current item.

In a Grid, this occurs when the user clicks the picture or tree line in the row title.

In a Treeview, this occurs when the user double-clicks the item label or clicks in the button or on the tree line to the left of the item label.

The default processing for the event is to expand the tree at the corresponding point.

You may disable the expand operation by setting the action code for the event to ¯1. You may also prevent the expand from occurring by returning 0 from a callback function. You may expand an object dynamically under program control by calling Expanding as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Expanding' or 302
[3] | Item number | Integer. The index of the row or item.


Expose Event

Expose Event 32

Applies To

Description

If enabled, this event is reported when part or all of the object's window is exposed to view. Under normal circumstances, APL repaints the exposed region automatically. However, if you have drawn unnamed graphical objects (which are not managed by APL) you should use this event to redraw them when required. Note that APL will itself repaint any named objects in the region before reporting the event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Expose' or 32
[3] | Y | y-position of top-left corner of exposed region
[4] | X | x-position of top-left corner of exposed region
[5] | H | height of exposed region
[6] | W | width of exposed region

This event cannot be disabled by setting its action code to ¯1. Similarly, setting the result of a callback function to 0 has no effect on it.


FileBoxCancel Event

FileBoxCancel Event 72
Applies To: BrowseBox FileBox

Description

If enabled, this event is reported when a FileBox is closed because the user has pressed the "Cancel" button or closed it.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'FileBoxCancel' or 72
[3] | File name | character vector containing the name of the currently selected file (empty if none)


FileBoxOk Event

FileBoxOk Event 71
Applies To: BrowseBox FileBox

Description

If enabled, this event is reported when a FileBox is closed because the user has pressed the "OK" button.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'FileBoxOk' or 71
[3] | File name | character vector containing the name of the currently selected file (empty if none)


FontCancel Event

FontCancel Event 242

Applies To

Description

If enabled, this event is reported when the user has pressed the Cancel button or closed the font selection dialog box that is displayed by the ChooseFont method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'FontCancel' or 242


FontOK Event

FontOK Event 241

Applies To

Description

If enabled, this event is reported when the user has pressed the OK button in the font selection dialog box that is displayed by the ChooseFont method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'FontOK' or 241
[3] | Font | nested vector
[4] | Colour | RGB triplet

The font specification in the 3rd element of the event message is a 7-element nested vector that describes the chosen font. See Font Object for further details.

The colour specification in the 4th element of the event message is a 3-element integer vector of RGB values for the colour chosen by the user.


FrameContextMenu Event

FrameContextMenu Event 411
Applies To: Form SubForm

Description

If enabled, this event is reported when the user clicks and releases the right mouse button over the non-client area of an object, e.g. the title bar in a Form.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'FrameContextMenu' or 411
[3] | Y | y-position of the mouse (number)
[4] | X | x-position of the mouse (number)

For further details, see ContextMenu Event.


GetDayStates Event

GetDayStates Event 266
Applies To: Calendar

Description

If enabled, this event is reported when a Calendar object requires the APL program to provide day state information for the range of dates it is about to display.

The Calendar object displays day numbers using either the normal or the bold font attribute. However, it does not store this information beyond the month or months currently displayed.

When the Calendar control scrolls (and potentially at other times), it generates a GetDayStates event to ask you (the APL program) to tell it which of the dates that are about to be shown, should be displayed using the bold font attribute.

If you wish any dates to be displayed using the bold font attribute, you must attach a callback function to this event which returns day state information in its result.

By default, all dates are displayed using the normal font attribute, so you need only do this if you want any dates highlighted in bold.

You may not disable or nullify the operation that caused GetDayStates to fire by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GetDayStates' or 266
[3] | First Date | an integer (IDN)
[4] | Last Date | an integer (IDN)
[5] | Bold Dates | an integer vector of IDNs.

When the callback function is invoked, the 3rd and 4th elements of the event message contain IDNs for the first and last date in the range of dates that the Calendar object is about to display. The 5th element of the event message contains those IDNs within this range of dates that the Calendar control already knows are to be displayed using the bold font attribute. This will typically be empty.

The result of your callback function should be the same event message with only the 5th element modified in any way. This should contain the IDNs of the dates (within the range specified by the 3rd and 4th elements) that are to be displayed using the bold font attribute.

Example:

Suppose that you keep a variable BOLD_DATES in the Calendar object. This variable is a vector of IDN values that defines those dates that the user has somehow identified as special and that you wish to display in bold, The following callback function could be applied:

    ∇ MSG←DAYSTATES MSG;MASK;⎕IO
[1]   ⍝ Callback function for the GetDayStates event
[2]   ⍝ Object (⊃MSG) contains a variable BOLD_DATES
[3]   ⍝ that defines ALL the IDNs that are to be displayed in bold
[4]   ⍝ We need to return only those that fall within the range
[5]   ⍝ of dates that are about to be displayed by the Calendar
[6]    ⎕CS⊃MSG
[7]    ⎕IO←1
[8]    MASK←BOLD_DATES≥3⊃MSG
[9]    MASK←MASK∧BOLD_DATES≤4⊃MSG
[10]   MSG[5]←⊂MASK/BOLD_DATES
     ∇

You may also set the font attribute for particular days by calling GetDayStates as a method.

For example, to set the bold attribute for IDN 36048 (11 September 1998) in a Calendar object called 'F.CAL1', you could execute the expression:

      F.CAL1.CetDayStates 36048 36048 36048

To clear the bold attribute for the same day:

      F.CAL1.CetDayStates 36048 36048 <⌈>

Note that the Calendar object will ignore any IDNs you specify that are outside the range of dates that it is currently displaying.


GetTipText Event

GetTipText Event 325
Applies To: ListView TreeView

Description

If enabled, this event is reported by a TreeView or ListView object just before it displays a tip for a specific row.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GetTipText' or 325
[3] | Item index | Integer (⎕IO dependant)
[4] | SubItem index | Integer (⎕IO dependant, currently always equal to ⎕IO)
[5] | TipText | The text to be displayed.

Modifying and returning the 5th element of the argument to the callback function allows the application to change the displayed tip.

The text can be set to a character array of rank 2 or less.

The default processing for the event is to display the default tip (if there is one).


GotFocus Event

GotFocus Event 40

Applies To

Description

If enabled, this event is generated when the user has moved the keyboard focus to a new object by clicking the left mouse button, pressing TAB, or using a cursor key.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GotFocus' or 40
[3] | Object name | character vector (name of object which previously had the focus)

The third element (object name) is empty if the focus was obtained from another application window.

The GotFocus event is generated after the focus has changed. The default processing is therefore to take no action. However, if you disable the event by setting its action code to ¯1, or inhibit it by returning a 0 from your callback function, the focus is automatically restored to the object (or external application) that had lost it.


GridCopy Event

GridCopy Event 191
Applies To: Grid

Description

If enabled, this event is reported when the user presses Ctrl+Insert and there are selected cells in the Grid. The default action of the event is to copy the contents of the selected block of cells to the clipboard. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the copy operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'GridCopy' or 191
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block
[5] | Values | 2-element nested vector. The first element is a matrix containing the values of the selected block(s) of cells. This is the data that will be copied to the clipboard. The second element is a Boolean matrix containing the values of the CellSet property for the selected block(s) of cells.

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks, and Data is the contents of the selected blocks catenated along the appropriate dimension according to their relative positions in the Grid.

You may copy cells under program control by calling GridCopy as a method.

To copy a specific block of cells to the clipboard whether or not they are selected, you must specify the Start and End parameters. For example, the following expression will copy the 3x3 block of cells in the top-left of the Grid (⎕IO is 1) to the clipboard:

     Gridname.GridCopy (1 1) (3 3)

If you omit these parameters, the currently selected block of cells will be copied to the clipboard. If no cells are selected, the entire contents of the Grid will be copied. i.e.

     Gridname.GridCopy ⍬

The data copied to the clipboard is registered in Dyalog (APL internal), Wk3 (Lotus), XlTable (Excel) and tab/new-line delimited text formats.


GridCopyError Event

GridCopyError Event 196
Applies To: Grid

Description

If enabled, this event is reported when the user presses Ctrl+Insert and there is more than one block of selected cells in the Grid and the blocks are non-conformable. The default action of the event is to generate a Beep. Setting the action code of this event to ¯1, or returning a 0 from a callback function attached to it, disables the Beep.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'GridCopyError' or 196
[3] |  | Zilde
[4] |  | Zilde
[5] | Start | A 2-column integer matrix whose rows identify the address of the first cell (row, column) of each of the selected blocks of cells.
[6] | End | A 2-column integer matrix whose rows identify the address of the last cell (row, column) of each of the selected blocks of cells.

Note that the values of Start and End are sensitive to the index origin, ⎕IO.


GridCut Event

GridCut Event 190
Applies To: Grid

Description

If enabled, this event is reported when the user presses Shift+Delete and there are selected cells in the Grid. The default action of the event is to copy the contents of the selected block(s) of cells to the clipboard and then to empty the selected cells. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the cut operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'GridCut' or 190
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell in the selected block
[5] | Data | 2-element nested vector. The first element is a matrix containing the values of the selected block(s) of cells. This is the data that will be copied to the clipboard. The second element is a Boolean matrix containing the values of the CellSet property for the selected block(s) of cells.

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks, and Data is the contents of the selected blocks catenated along the appropriate dimension according to their relative positions in the Grid.

The data copied to the clipboard is registered in Dyalog (APL internal), Wk3 (Lotus), XlTable (Excel) and tab/new-line delimited text formats.


GridDelete Event

GridDelete Event 193
Applies To: Grid

Description

If enabled, this event is reported when the user presses Delete and there are selected cells in the Grid. The default action of the event is to empty the selected cells. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the delete operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'GridDelete' or 193
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block(s)

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks.


GridDropSel Event

GridDropSel Event 195
Applies To: Grid

Description

If enabled, this event is reported when the user drag/drops a selected block of cells in the Grid. The default action is that the contents of the selected cells replace the values in the block of cells onto which they are dropped and this block now becomes selected.

You may disable the drag/drop facility entirely by setting the action code of the event to ¯1. You may also disable an individual drag/drop operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GridDropSel' or 195
[3] | Start | 2-element integer vector containing the row, column address of the top left cell in the selected block
[4] | Size | 2-element integer vector containing the number of rows and columns in the selected block
[5] | Target | 2-element integer vector containing the row/column address of the top left cell onto which the selected block is being dropped
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down
[7] | Undo flag | 0 or 1
[8] | Values | Matrix containing the values of the selected block of cells. This is the data that will replace the values in the target cells.
[9] | CellSet flags | Boolean Matrix containing the values of the CellSet property for the selected block of cells. This will replace the values of the CellSet property of the target cells.

The shift state in element 6 is intended to allow the APL programmer to implement an insert operation instead of a copy or move operation if required.

You may copy the contents of one block of cells to another by calling GridDropSel as a method. If so, you need only specify the Start, Size and Target parameters. Note that the result block becomes selected.

The Undo flag is always 1 if the event was generated by the user.


GridKeyPress Event

GridKeyPress Event 24
Applies To: Grid

Description

If enabled, this event is generated when the user presses and releases a key in a Grid cell.

The GridKeyPress is reported on the Grid, after the KeyPress event, which is reported on the Input object associated with the current cell.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GridKeyPress' or 24
[3] | Input Code | character scalar or vector
[4] | ASCII code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift State | integer scalar
[7] | Input Object | character vector

For a full description of elements [3-6], see KeyPress event.

The 7th element of the event message contains the name of the Input object associated with the current cell and on which the corresponding KeyPress event has been reported.

If a callback function on the KeyPress event returns 0, the GridKeyPress event is not fired. If a callback function on the KeyPress event returns a modified KeyPress message, the GridKeyPress event is fired with the modified message and not the original one.

The default action of the GridKeyPress event is to pass its message back to the appropriate Input object to be actioned. If a callback on GridKeyPress returns 0, the keystroke will be ignored.


GridPaste Event

GridPaste Event 192
Applies To: Grid

Description

If enabled, this event is reported when the user presses Shift+Insert and there is data in the clipboard that is in a suitable format for the Grid. The default action of the event is to copy the contents of the clipboard into the currently selected block of cells, or, if no cells are selected, into the block of cells starting at the current cell (CurCell). Note that if there is a selected range of cells and the shape of the data being pasted does not exactly match the size of the selected range, the system generates a GridPasteError event in addition to the GridPaste event.

You may disable the paste facility entirely by setting the action code of the event to ¯1. You may also disable an individual paste operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GridPaste' or 192
[3] | Values | New values (taken from the clipboard) which are to replace the existing values of the block of cells defined by Start and End.
[4] | CellSet flags | Boolean Matrix containing the new values of the CellSet property for the block of cells defined by Start and End.
[5] | Start | 2-element integer vector containing the row, column address of the top left cell the selected block. If there is no selection, this is the address of the current cell(CurCell).
[6] | End | 2-element integer vector containing the row, column address of the bottom right cell in the selected block. If there is no selection, this is the address of the bottom right cell of the block starting at the current cell that will be overwritten

You can replace the contents of a contiguous block of cells with the data in the clipboard, or with an arbitrary matrix of values, by calling GridPaste as a method.

If you call GridPaste with an argument of ⍬, the data is taken from the clipboard; otherwise the data to be pasted is specified by the Values and CellSet flags parameters.. If you omit Start, data is pasted into the currently selected range of cells. If there are no cells selected, data is pasted starting at the current cell (CurCell). In either case, the block of replaced cells becomes selected.


GridPasteError Event

GridPasteError Event 194
Applies To: Grid

Description

If enabled, this event is reported when the user presses Shift+Insert and there is data in the clipboard, but the system is unable to paste the data into the Grid. This occurs if there is a currently selected block of cells whose shape does not match the shape of the data in the clipboard. It also occurs if there is no selected block of cells, and pasting the data in starting at the current cell (CurCell) would overflow the Grid. Setting the action code of this event to ¯1, or returning a 0 from a callback function attached to it, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'GridPasteError' or 194
[3] | Values | Contents of the clipboard.
[4] | CellSet flags | Boolean array indicating which elements of the clipboard data are empty.
[5] | Start | 2-element integer vector containing the row, column address of the top left cell in the selected block. If there is no selection, this is the address of the current cell (CurCell).
[6] | End | 2-element integer vector containing the row, column address of the bottom right cell in the selected block. If there is no selection, this is the address of the bottom right cell of the block starting at the current cell that will be overwritten
[7] | Error Number | 4 (RANK ERROR) or 5 (LENGTH ERROR)


GridSelect Event

GridSelect Event 165
Applies To: Grid

Description

If enabled, this event is reported when the user performs or cancels the selection of a block of cells in a Grid object. This event is reported after the selection has changed. Setting its action code to ¯1 has no effect and the result of a callback function cannot be used to alter the selection that has been made. You may however control the user's ability to make selections using the CellSelect property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'GridSelect' or 165
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If the selection is made with the mouse, the GridSelect event is reported when the left mouse button is released. If the selection is made using the cursor keys, the GridSelect event is reported when the Shift key is released.

The GridSelect event is also generated when the current selection is cancelled by clicking on a cell with the mouse or by pressing a cursor key.


HScroll Event

HScroll Event 39
Applies To: Form SubForm

Description

If enabled, this event is generated when the user attempts to move the thumb in a horizontal scrollbar in a Form or SubForm. This event occurs only in a Form whose HScroll property is set to ¯1 and is distinct from the Scroll event that is generated by a Scroll object. The event may be generated in one of three ways:

  • dragging the thumb.
  • clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[3].
  • clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[4].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'HScroll' or 39
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however, that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


HThumbDrag Event

HThumbDrag Event 442
Applies To: Form SubForm

Description

If enabled, this event is generated when the user attempts to drag the thumb in a horizontal scrollbar in a Form or SubForm. This event occurs only in a Form or SubForm whose HScroll property is set to ¯1 and is distinct from the Scroll event that is generated by a Scroll object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'HThumbDrag' or 442
[3] | Position | numeric

The value of Position is the new (requested) position of the Thumb. Setting the action code of this event to ¯1, or returning a 0 from a callback function attached to it, has no effect.


Help Event

Help Event 400

Applies To

Description

If enabled, this event is reported when the user clicks on an object which has a callback defined for this event, the user having previously clicked on the Question (?) button in the title bar of the parent Form. The presence of the Question (?) button is determined by the value of the HelpButton property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Help or 400
[3] | Y-coordinate | Number
[4] | X-coordinate | Number

The y and x-coordinates refer to the position of the mouse pointer in the object which was clicked on, and are reported in the coordinate system of that object.


HideComment Event

HideComment Event 220
Applies To: Grid

Description

If enabled, a HideComment event is generated just before a comment window is hidden as a result of the user moving the mouse-pointer away from a commented cell.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'HideComment' or 224
[3] | Row | integer
[4] | Column | integer

You may prevent the comment from being hidden by returning 0 as the result of a callback function.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.

Invoked as a method, HideComment is used to hide a comment that has previously been displayed by ShowComment. For example, the following expression hides the comment associated with the cell at row 2, column 1.

      F.G.HideComment 2 1

If HideComment is called with an argument of ⍬, all comments are hidden.


Idle Event

Idle Event 130
Applies To: Root

Description

If enabled, this event is generated whenever APL looks to see if there is an event on the queue and finds it empty. Its purpose is to allow an application to perform some background processing when the user is not doing anything. It is unwise to use this event directly from the Session as it will occur repeatedly and may lock you out.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'Idle' or 130


IndexChanged Event

IndexChanged Event 210
Applies To: Grid

Description

If enabled, this event is reported when the value of the Index property of a Grid has changed as a result of user interaction. The event is reported after the Grid has been scrolled. You may not modify or nullify the operation with a 0-return callback and you may not call IndexChanged as a method or generate this event using ⎕NQ. To cause a Grid to scroll, use ⎕WS to set its Index property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'IndexChanged or 210
[3] | Row | Integer.
[4] | Column | Integer.


ItemDblClick Event

ItemDblClick Event 342
Applies To: ListView TreeView

Description

If enabled, this event is reported when the user double-clicks a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ItemDblClick' or 342
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), or 16 (over the symbol).


ItemDown Event

ItemDown Event 340
Applies To: ListView TreeView

Description

If enabled, this event is reported when the user depresses a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ItemDown' or 340
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), 16 (over the symbol) or 32 (to the right of the label).


ItemUp Event

ItemUp Event 341
Applies To: ListView TreeView

Description

If enabled, this event is reported when the user releases a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ItemUp' or 341
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), or 16 (over the symbol).


KeyError Event

KeyError Event 23
Applies To: ButtonEdit Edit Spinner

Description

If enabled, this event is generated when the user presses and releases a key on the keyboard that is invalid for the FieldType of the object and has been ignored. This event is reported for information only and you may not disable it or modify it in any way.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'KeyError' or 23
[3] | Character | character scalar
[4] | Character code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift state | integer scalar

In the Classic Edition, the resolution of the keystroke to a character (in ⎕AV) is performed using the Input Translate Table. In the Unicode Edition, the resolution is performed by the Operating System.

In the Unicode Edition, the Character Code is the Unicode code point of the character that the user entered. In the Classic Edition, it is a number in the range 0-255 which specifies the ASCII character that would normally be generated by the keystroke, and is independent of the Input Translate Table. If there is no corresponding ASCII character, the ASCII code reported is 0.

The key number is the physical key number reported by Windows when the key is pressed.

The Shift State indicates which (if any) of the Shift, Ctrl and Alt keys are down at the same time as the key is pressed. It is the sum of the following numbers :

Thus a Shift State of 3 indicates that the user has pressed the key in conjunction with both the Shift and Ctrl keys. A Shift State of 0 indicates that the user pressed the key on its own.


KeyPress Event

KeyPress Event 22

Applies To

Description

If enabled, this event is generated when the user presses and releases a key on the keyboard. It is reported for whichever object has the keyboard focus at the time.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'KeyPress' or 22
[3] | Input Code | character scalar or vector
[4] | Character code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift state | integer scalar

If the keystroke resolves to a character, the Input Code is a character scalar.

If the keystroke resolves to a command recognised by Dyalog APL, such as UC (Up Cursor) or ER (Enter) the Input Code contains the corresponding 2-element character vector.

In the Classic Edition, the resolution of the keystroke to a character (in ⎕AV) or to a command, is performed using the Input Translate Table.

In the Unicode Edition, the resolution is performed by the Operating System. However, if the keystroke resolves to a navigation or control key (such as Cursor Up or Enter), the same 2-character "command" is reported. Note however that commands that are purely internal to Dyalog APL (such as Trace, commonly Ctrl+Enter) are not reported as such and the Input Code will be empty.

In the Unicode Edition, the Character Code is the Unicode code point of the character that the user entered. In the Classic Edition, it is a number in the range 0-255 which specifies the ASCII character that would normally be generated by the keystroke, and is independent of the Input Translate Table. If there is no corresponding ASCII character, the ASCII code reported is 0.

The key number is the physical key number reported by Windows when the key is pressed.

The Shift State indicates which (if any) of the Shift, Ctrl and Alt keys are down at the same time as the key is pressed. It is the sum of the following numbers :

Thus a Shift State of 3 indicates that the user has pressed the key in conjunction with both the Shift and Ctrl keys. A Shift State of 0 indicates that the user pressed the key on its own.

Example

     ∇ Key;Form1
[1]    'Form1'⎕WC'Form'('Event' 'KeyPress' 'Keycb')
[2]    ⎕DQ'Form1'
     ∇

     ∇ Keycb msg
[1]    DISPLAY msg
     ∇

On running function Key, the following output will be displayed as a result of the user pressing the following 5 keys in succession:

  1. "a"
  2. Shift+"a"
  3. Cursor Up
  4. β ("b" using a Greek keyboard)
  5. ⍳ (Ctrl+"i" using a UK APL keyboard)

Unicode Edition

.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| a 97 65 0 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| A 65 65 1 |
| '-----' '--------' -         |
'∊-----------------------------'

.→-------------------------------.
| .→----. .→-------. .→-.        |
| |Form1| |KeyPress| |UC| 0 38 0 |
| '-----' '--------' '--'        |
'∊-------------------------------'
.→------------------------------.
| .→----. .→-------.            |
| |Form1| |KeyPress| β 946 66 0 |
| '-----' '--------'            |
'∊------------------------------'
.→-------------------------------.
| .→----. .→-------.             |
| |Form1| |KeyPress| ⍳ 9075 73 2 |
| '-----' '--------' -           |
'∊-------------------------------'

Classic Edition

.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| a 97 65 0 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| A 65 65 1 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-------------------------------.
| .→----. .→-------. .→-.        |
| |Form1| |KeyPress| |UC| 0 38 0 |
| '-----' '--------' '--'        |
'∊-------------------------------'
.→--------------------------------.
| .→----. .→-------. .⊖.          |
| |Form1| |KeyPress| | | 223 66 0 |
| '-----' '--------' '-'          |
'∊--------------------------------'
.→----------------------------.
| .→----. .→-------.          |
| |Form1| |KeyPress| ⍳ 9 73 2 |
| '-----' '--------' -        |
'∊----------------------------'


Locator Event

Locator Event 80
Applies To: Locator

Description

If enabled, this event is generated when the user releases a mouse button, or presses any key (other than a cursor movement key) during a ⎕DQ on a Locator object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Locator' or 80
[3] | Y | y-position of Locator after ⎕DQ
[4] | X | x-position of Locator after ⎕DQ
[5] | H | height of Locator after ⎕DQ
[6] | W | width of Locator after ⎕DQ
[7] | Mouse Button | number of the button which was released (0 if keystroke)
[8] | Keystroke | character scalar or vector containing the "Input Code" for the key that terminated the operation
[9] | Shift state | integer scalar


LostFocus Event

LostFocus Event 41

Applies To

Description

If enabled, this event is generated when the user transfers the keyboard focus away from the object in question.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'LostFocus' or 41
[3] | Object name | character vector (name of object that has received the focus)

If the focus is transferred to a window that is not part of the Dyalog APL GUI Interface, the third element is an empty vector.

The LostFocus event is generated after the focus has changed. The default processing is therefore to take no action. However, if you inhibit the event by returning a 0 from your callback function, the focus is automatically restored to the object that had lost it.


MDIActivate Event

MDIActivate Event 42
Applies To: SubForm

Description

This event is generated when the user activates a particular SubForm that is the child of an MDIClient. This occurs when the user clicks the left mouse button in the SubForm or selects it from the menu nominated for this purpose (see MDIMenu property). You may also call MDIActivate as a method.

Note that this event is reported after the action has taken place and cannot be disabled by returning 0 from a callback function or by setting its action code to ¯1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MDIActivate' or 42
[3] | Object name | character vector

Note that the 3rd element of the event message is either an empty vector or contains the name of the SubForm that was previously the active one in the same MDIClient.


MDIDeactivate Event

MDIDeactivate Event 43
Applies To: SubForm

Description

This event is generated when the user activates a different SubForm that is the child of an MDIClient, thereby de-activating the current one which causes this event. This occurs when the user clicks the left mouse button in another SubForm or selects it from the menu nominated for this purpose (see MDIMenu property). You may also call MDIDeactivate as a method.

Note that this event is reported after the action has taken place and cannot be disabled by returning 0 from a callback function or by setting its action code to ¯1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MDIDeactivate' or 43
[3] | Object name | character vector

Note that the 3rd element of the event message contains the name of the SubForm that has now been made the active one in the same MDIClient.


MouseDblClick Event

MouseDblClick Event 5

Applies To

Description

If enabled, this event is reported when the user presses and then releases a mouse button twice within a short space of time. The duration of this time is set through the Windows Control Panel.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseDblClick' or 5
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button double clicked (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.

If you enable MouseDown and MouseUp events in addition to MouseDblClick events, double-clicking a mouse button will generate the following sequence of events :

  1. MouseDown
  2. MouseUp
  3. MouseDblClick
  4. MouseUp


MouseDown Event

MouseDown Event 1

Applies To

Description

If enabled, this event is reported when the user presses one of the mouse buttons. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseDown' or 1
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

If you enable this event it is advisable that you ALSO enable MouseUp events. Otherwise, the slight delay in running your callback function will cause the down and up sequence to be reversed.

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.


MouseEnter Event

MouseEnter Event 6

Applies To

Description

If enabled, this event is reported when the user moves the mouse pointer into (over) an object. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseEnter' or 6
[3] | Object name | character vector (name of previous object)

This event is generated when the user moves the mouse pointer across the boundary and into an object. The first element of the event message is the name of the object over which the mouse pointer now resides. The 3rd element of the event message contains the name of the object that was previously under the mouse pointer, or is an empty vector if the mouse pointer was not previously over a Dyalog APL/W object.


MouseLeave Event

MouseLeave Event 7

Applies To

Description

If enabled, this event is reported when the user moves the mouse pointer out of an object. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseLeave' or 7
[3] | Object name | character vector (name of new object)

This event is generated when the user moves the mouse pointer across the boundary and away from an object. The first element of the event message contains the name of the object that previously contained the mouse pointer and which generated the event when it crossed its boundary. The third element contains the name of the object which now contains the mouse pointer or is an empty vector if the mouse pointer is not now over a Dyalog APL/W object.


MouseMove Event

MouseMove Event 3

Applies To

Description

If enabled, this event is reported when the user moves the mouse. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseMove' or 3
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.

Note that rapid movement of the mouse will not necessarily cause an overwhelming number of MouseMove events to be reported, as several small movements are automatically combined into one large one.


MouseUp Event

MouseUp Event 2

Applies To

Description

If enabled, this event is reported when the user releases one of the mouse buttons. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseUp' or 3
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.


MouseWheel Event

MouseWheel Event 8

Applies To

Description

If enabled, this event is reported when the user rotates the mouse wheel.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'MouseWheel' or 8
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down
[7] | Delta | integer
[8] | Lines | integer
[9] | Wheel Delta | integer

The value of Delta indicates the distance that the wheel is rotated, expressed in multiples or divisions of Wheel Delta. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user.

Lines specifies the number of lines to scroll when the wheel is rotated by I Mouse Delta unit. A value of ¯1 indicates that a whole screen is to be scrolled. These values are defined by the user's preferences (Control Panel/Mouse)


MsgBtn1 Event

MsgBtn1 Event 61
Applies To: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its first (leftmost) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'MsgBtn1' or 61


MsgBtn2 Event

MsgBtn2 Event 62
Applies To: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its second (from the left) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'MsgBtn2' or 62


MsgBtn3 Event

MsgBtn3 Event 63
Applies To: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its third (from the left) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'MsgBtn3' or 63


PageActivate Event

PageActivate Event 360
Applies To: PropertyPage

Description

If enabled, this event is reported when the user switches from one PropertyPage to another in a PropertySheet object. This event is reported by the new page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageActivate' or 360

You may select a particular page by calling PageActivate as a method, or by setting the PageActive or PageActiveObject property of the PropertySheet.


PageApply Event

PageApply Event 350
Applies To: PropertyPage

Description

If enabled, this event is reported when the user clicks the Apply button in a PropertySheet. Note however, that the event is actually reported by each of its PropertyPage objects whose Changed property is currently 1, i.e. the event is reported by each of the pages that the user has changed.

The default processing for this event is to set the Changed property of the PropertyPage to 0. If you disable the event or return a 0 from a callback function, the Changed property is not reset. Note that the Apply button in a PropertySheet is active if the value of the Changed property of any of the PropertyPage objects is 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageApply' or 350


PageBack Event

PageBack Event 353
Applies To: PropertyPage

Description

If enabled, this event is reported when the user switches from one PropertyPage to another in a Wizard PropertySheet object by clicking its Back button. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageBack' or 353


PageCancel Event

PageCancel Event 351
Applies To: PropertyPage

Description

If enabled, this event is reported when the user presses the Cancel button in a PropertySheet object and is reported by the current PropertyPage. This event is reported for information only and may not be disabled by a callback function. However, the operation will also generate a Close event reported by the PropertySheet itself that may be disabled by a callback.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageCancel' or 351


PageChanged Event

PageChanged Event 356
Applies To: PropertyPage

Description

If enabled, this event is reported when the Changed property of a PropertyPage is altered by user action. It is not reported if you reset the Changed property using ⎕WS.

The Changed property is reset by two separate user actions. It is set to 1 when the user alters any of the controls on the PropertyPage. It is reset to 0 when the user clicks the Apply button, although this action may be disabled by a callback function on the PageApply event.

The PageChanged event is reported for information only and may not itself be disabled or affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageChanged' or 356
[3] | Changed value | New value for the Changed property (0 or 1).


PageDeactivate Event

PageDeactivate Event 361
Applies To: PropertyPage

Description

If enabled, this event is reported when the user switches from one PropertyPage to another in a PropertySheet object. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageDeactivate' or 361


PageFinish Event

PageFinish Event 355
Applies To: PropertyPage

Description

If enabled, this event is reported when the user clicks the Finish button in a Wizard PropertySheet. This event is reported by current (last) PropertyPage. The event is reported for information only and cannot be affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageFinish' or 355


PageHelp Event

PageHelp Event 352
Applies To: PropertyPage

Description

If enabled, this event is reported when the user clicks the Help button in a Wizard PropertySheet. This event is reported by current PropertyPage. The event is reported for information only and cannot be affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageHelp' or 352


PageNext Event

PageNext Event 354
Applies To: PropertyPage

Description

If enabled, this event is reported when the user switches from one PropertyPage to another in a Wizard PropertySheet object by clicking its Next button. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PageNext' or 354


PreCreate Event

PreCreate Event 534
Applies To: ActiveXControl

Description

If enabled, this event is reported when an instance of an ActiveXControl is created. The PreCreate event is generated at the point the instance is made.

An ActiveXControl also generates a Create event, which occurs after the PreCreate event at the point when the host application requires the instance to appear visually.

Note that at the time that PreCreate is generated, the ActiveXControl does not have a window.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'PreCreate' or 534


Protected Event

Protected Event 470
Applies To: RichEdit

Description

If enabled, this event is reported when the user attempts to alter protected text in a RichEdit. See CharFormat property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Protected' or 470


Retracting Event

Retracting Event 304
Applies To: Grid TreeView

Description

If enabled, this event is reported by a Grid or a TreeView object just before it is about to retract to hide the children of the current item.

In a Grid, this occurs when the user clicks the picture or tree line in the row title.

In a TreeView, this occurs when the user double-clicks the item label or clicks in the button or on the tree line to the left of the item label, when the item is in its expanded state.

The default processing for the event is to retract the tree at the corresponding point.

You may disable the retract operation by setting the action code for the event to ¯1. You may also prevent the retraction from occurring by returning 0 from a callback function. You may retract Grid a or a TreeView dynamically under program control by calling Retracting as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Retracting' or 304
[3] | Item number | Integer. The index of the item.


Scroll Event

Scroll Event 37
Applies To: Scroll TrackBar

Description

If enabled, this event is generated when the user attempts to move the thumb in a scrollbar. This can be done in one of three ways :

  1. dragging the thumb.
  2. clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[1].
  3. clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[2].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Scroll' or 37
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however, that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


SelDateChange Event

SelDateChange Event 265
Applies To: Calendar

Description

If enabled, this event is reported when the user changes the date, or range of dates, that is selected in a Calendar object. This event is also reported when the Calendar object is scrolled and the selection changes automatically to another month.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SelDateChange' or 265
[3] | First Date | an integer (IDN)
[4] | Last Date | an integer (IDN)


Select Event

Select Event 30

Applies To

Description

For a Button with Style 'Push' this event is generated when the user "pushes" the button. This can be done by clicking the left mouse button, or by pressing the Enter key or the space bar when the Button has the focus. The Select event can also be generated when the Button does not have the focus, by pressing the Enter key when its Default property is 1 or by pressing the ESC key when its Cancel property is 1.

For a Button with Style 'Radio' or 'Check' this event is generated when the user toggles the button from one state to another. This can be achieved by clicking the left mouse button or by pressing the space bar when the Button has the focus.

For a Combo or List object, a Select event is generated when the user selects an item from the list, whether by pressing the arrow keys or by clicking the left mouse button.

For a MenuItem, a Select event is generated when the user chooses the item.

For all other objects, this event is generated when the user presses the keys associated with the object's Accelerator property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | Event code


SetColSize Event

SetColSize Event 176
Applies To: Grid ListView

Description

If enabled, this event is reported when the user changes the width of a column in a Grid or ListView object, or changes the width of the row titles in a Grid. This may be done by dragging a border with the mouse or by double-clicking over a border. In the former case, the default action is to adjust the width of the appropriate column or the width of the row title area to the size selected by the user. In the latter case, the default action is to adjust the width to the maximum required to display all the data.

In either case, you can disable the default action by setting the event action code to ¯1 or you can selectively prevent a particular resize operation from taking place by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SetColSize' or 176
[3] | Column number | Integer. This is sensitive to the index origin, ⎕IO, but is ¯1 if the user has resized the row titles in a Grid.
[4] | Width | Integer containing the value of the (new)column width. This is ¯3 if the user has double-clicked to request automatic width adjustment.
[5] | Undo flag | 0 or 1

You can resize a column or resize the row titles under program control by calling SetColSize as a method. If you specify ¯1 as the Width parameter, the column will be resized to its default width .. If you specify a value of ¯2 the column will be resized to fit the data. The following expression will size the first NCOLS columns of a Grid called F.G to fit the data and the column titles:

      {F.G.SetColSize⍵ ¯3}¨⍳NCOLS

The Undo flag is applicable only to a Grid object and is always 1 if the event was generated by the user.


SetItemPosition Event

SetItemPosition Event 322
Applies To: ListView

Description

If enabled, this event is reported when the user drag-drops an item within a ListView object. This operation may be disabled by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SetItemPosition' or 322
[3] | Item number | Integer. The index of the item.
[4] | Y-position | Integer. New y-position of the item.
[5] | X-position | Integer. New x-position of the item.
[6] | Button number | Integer. The mouse button used to perform the drag.
[7] | Shift State | Integer: Sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down


SetRowSize Event

SetRowSize Event 175
Applies To: Grid

Description

If enabled, this event is reported when the user changes the height of a row or changes the height of the column titles. This may be done by dragging a border with the mouse or by double-clicking over a border. In the former case, the default action is to adjust the height of the appropriate row or the height of the column title area to the size selected by the user. In the latter case, the default action is to adjust the height to the maximum required to display all the data.

In either case, you can disable the default action by setting the event action code to ¯1 or you can selectively prevent a particular resize operation from taking place by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SelRowSize' or 175
[3] | Row number | Integer. This is sensitive to the index origin, ⎕IO, but is ¯1 if the user has resized the column titles.
[4] | Height | Integer containing the value of the (new) row height. This is ¯3 if the user has double-clicked to request automatic height adjustment.
[5] | Undo flag | 0 or 1

You can resize a row or resize the column titles under program control by calling SetRowSize as a method. If you specify ¯1 as the Height parameter, the row will be resized to its default height .. If you specify a value of ¯2 the row will be resized to fit the data. The following expression will set the heights of first NROWS rows of a Grid called F.G to fit the data and the row titles.

      {F.G.SetRowSize⍵ ¯3}¨⍳NROWS

The Undo flag is always 1 if the event was generated by the user.


SetSpinnerText Event

SetSpinnerText Event 421
Applies To: Spinner

Description

If enabled, this event is generated when the user clicks one of the spin buttons in a Spinner object. The event is reported after the value of the Thumb property has been updated but before the Text property has been changed. You may use this event to set the text in the Spinner dynamically instead of relying on it being updated automatically.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SetSpinnerText' or 421
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user pressing one of the spin buttons.
[4] | Text | The text that is about to be put into the edit field.

The SetSpinnerText event is designed to allow you to dynamically set the text in the Spinner in response to a spin button. It might be used in circumstances where the set of items you wish to present to your user is not predictable in advance.


SetWizard Event

SetWizard Event 365
Applies To: PropertyPage

Description

If enabled, this event is reported when the user has clicked the Next or Back button in a PropertySheet with Style 'Wizard'. This action also generates PageNext (or PageBack) and PageDeactivate and PageActivate events. The SetWizard event is the final event to be reported as a result of this action, and is the only one that is affected by the result of a callback function. The event message reports the active/inactive state of the 3 page changing buttons (Back, Next and Finish) that should result from the action. Note that the Next and Finish buttons occupy the same position and are mutually exclusive.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SetWizard' or 365
[3] | Active state Back | 0 or 1
[4] | Active state Next | 0 or 1
[5] | Active state Finish | 0 or 1
[6] | Finish caption | character vector

You may alter the state of the buttons by changing elements [3-5] of the event message and returning it as a result of your callback. You may also set the state of the buttons at any time by calling SetWizard as a method.

When the event is reported by ⎕DQ, element 6 is an empty vector. If you modify it and return it in the result of a callback, the caption of the Finish button changes accordingly and the Back and Next buttons disappear. This happens regardless of the states you specified in elements [3-5].


ShowComment Event

ShowComment Event 223
Applies To: Grid

Description

If enabled, a Grid will generate a ShowComment event when the user rests the mouse pointer over a commented cell. You may use this event to modify the appearance of the comment dynamically.

The event message reported as the result of ⎕DQ or supplied as the right argument to your callback function is an 8-element vector containing the following:

[1] | Object | ref or character vector
[2] | Event | 'ShowComment' or 223
[3] | Cell row | integer
[4] | Cell column | integer
[5] | Comment text | character vector
[6] | Window height | integer, pixels
[7] | Window width | integer, pixels
[8] | Tip behaviour flag | (1 = yes; 0 = no)

A callback function may modify the standard behaviour. You may prevent the comment from being displayed by returning 0 as the result of the callback. Alternatively, you may modify the comment text, its window size, or its pop-up behaviour by changing the appropriate element(s) of the event message and returning the new event message as the result.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.

You may display the comment associated with a particular cell under program control by calling ShowComment as a method. In this case, only the Cell row and Cell column parameters need be specified. If however, you wish to override the comment text and/or its window size, you may do so (temporarily) by specifying the corresponding parameters. By default, a comment displayed under program control does not exhibit tip behaviour but remains visible until it is explicitly removed using the HideComment method.

Note that a comment will only be displayed if the specified cell is marked as a commented cell.


Spin Event

Spin Event 420
Applies To: Spinner UpDown

Description

If enabled, this event is generated when the user clicks one of the spin buttons in a Spinner object. The event is reported before the value of the Thumb property has been updated. You may disable the operation of the spin buttons by disabling this event. You may selectively prevent the user selecting a particular value by returning 0 from a callback function. You may also return a modified event message as a result in order to set the Thumb property to a different value.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Spin' or 420
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user pressing one of the spin buttons.
[4] | Adjustment | Integer. The amount by which the new value of the Thumb differs from its previous value.


Splitting Event

Splitting Event 281
Applies To: Splitter

Description

If enabled, this event is reported while a Splitter object is being dragged, between a StartSplit and an EndSplit. This event is only reported if full-drag is enabled.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Splitting' or 281
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of the Splitter
[6] | W | width of the Splitter

See also StartSplit, EndSplit.


StartSplit Event

StartSplit Event 280
Applies To: Splitter

Description

If enabled, this event is reported when the user depresses the left mouse button over a Splitter object to signify the beginning of a drag operation.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'StartSplit' or 280

See also EndSplit, Splitting.


StateChange Event

StateChange Event 35
Applies To: Form SubForm

Description

This event is generated by a Form or SubForm when the user attempts to change the State of a Form, by minimising it, maximising it, or restoring it from a minimised or maximised state. The event is reported before the window changes state. You may prevent the state change by disabling the event (action code ¯1) or by returning a 0 result from an attached callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'StateChange' or 35
[3] | Window state | 0 (about to be restored) 1 (about to be minimised) 2 (about to be maximised)


SysColorChange Event

SysColorChange Event 134
Applies To: Root

Description

If enabled, this event is reported when the user or another application updates the system colour palette. The event is reported after the change has taken place and cannot be disabled or inhibited in any way. If you want your application to respond to colour palette changes, this event gives you the opportunity of doing so.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'SysColorChange' or 134


TCPAccept Event

TCPAccept Event 371
Applies To: TCPSocket

Description

If enabled, this event is reported when a client connects to a server TCPSocket object.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPAccept as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPAccept' or 371
[3] | Socket handle | an integer

The socket handle reported by this event is the socket handle for the original listening socket that was associated with the TCPSocket before the client connected.

If you want your server to remain available for other clients, you must create a new TCPSocket object in a callback function attached to this event. The new TCPSocket object must be created by cloning the original listening socket. This is done by specifying the socket handle as the value of its SocketNumber property. You may not specify any other properties (except Event and Data) in the ⎕WC statement that creates the new clone object.

The default processing for this event is to close the socket handle reported by the 3rd element of the event message unless it has been associated with a new TCPSocket object by the callback function as described above. You may prevent this from occurring by returning 0 from a callback function. This may be necessary in a multithreaded application.

You may not call TCPClose as a method or generate this event artificially using ⎕NQ.


TCPClose Event

TCPClose Event 374
Applies To: TCPSocket

Description

If enabled, this event is reported when the remote end of a TCP/IP connection breaks the connection.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPClose as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPClose' or 374


TCPConnect Event

TCPConnect Event 372
Applies To: TCPSocket

Description

If enabled, this event is reported when a server accepts the connection of a client TCPSocket object and is reported by the client.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPConnect as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPConnect' or 372


TCPError Event

TCPError Event 370
Applies To: TCPSocket

Description

This event is generated when a fatal TCP/IP error occurs and is reported by a TCPSocket object.

The default processing for this event is to display a message box containing details of the TCP/IP error. You may disable the display of this message box by setting the action code for the event to ¯1 or by returning 0 from a callback function attached to it.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPError' or 370
[3] | Error code | a number
[4] | Error text | a character vector


TCPGotAddr Event

TCPGotAddr Event 377
Applies To: TCPSocket

Description

If enabled, this event is reported when a host name (specified by the RemoteAddrName or LocalAddrName property) is resolved to an IP address.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPGotAddr as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPGotAddr' or 377

Note that the IP address is not reported in the event message but may be obtained from RemoteAddr or LocalAddr as appropriate.


TCPGotPort Event

TCPGotPort Event 378
Applies To: TCPSocket

Description

If enabled, this event is reported when a port name (specified by the RemotePortName or LocalPortName property) is resolved to a port number.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPGotPort as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPGotPort' or 378

Note that the port number is not reported in the event message but may be obtained from RemotePort or LocalPort as appropriate.


TCPReady Event

TCPReady Event 379
Applies To: TCPSocket

Description

If enabled, this event is reported when the TCP/IP buffers are free and there is no data waiting to be sent in the internal APL queue.

This event is provided to enable you to control the transmission of a large amount of data that cannot be handled in a single call to TCPSend.

The amount of data that the system can handle in one go is limited by TCP/IP buffers, the speed of the network, and the amount of Windows memory and disk space available for buffering.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. However, you may call TCPReady as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPReady' or 379


TCPRecv Event

TCPRecv Event 373
Applies To: TCPSocket

Description

If enabled, this event is reported when data is received by a TCPSocket object.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPRecv as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'TCPRecv' or 373
[3] | Data | the data received
[4] | IP address | character vector
[5] | Port number | integer

Elements [4-5] refer to the IP address and port number of the remote process that sent the data.

If the SocketType is 'Stream', this information will be identical to the values of the RemoteAddr and RemotePort respectively.

If the SocketType is 'UDP'and there is potentially more than one partner sending you data, the IP address and port number information provided by the TCPRecv event is more reliable than the current values of RemoteAddr and RemotePort as these may already have changed.


ThumbDrag Event

ThumbDrag Event 440
Applies To: Scroll TrackBar

Description

If enabled, this event is generated when the user drags the thumb in a TrackBar object. The event is reported after the value of the Thumb property has been updated and is reported continuously as the thumb is dragged. You may not disable this event or alter its effect with a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'ThumbDrag' or 440
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user dragging the thumb.


Timer Event

Timer Event 140
Applies To: Timer

Description

This event is generated at regular intervals by a Timer object and is typically used to fire a callback function to perform a task repeatedly. Returning a 0 from a callback function attached to a Timer event has no effect. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2 element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'Timer' or 140


VScroll Event

VScroll Event 38
Applies To: Form SubForm

Description

If enabled, this event is generated when the user attempts to move the thumb in a vertical scrollbar in a Form or SubForm. This event occurs only in a Form whose VScroll property is set to ¯1 and is distinct from the Scroll event which is generated by a Scroll object. The event may be generated in one of three ways :

  1. dragging the thumb
  2. clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[1].
  3. clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[2].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'VScroll' or 38
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


VThumbDrag Event

VThumbDrag Event 441
Applies To: Form SubForm

Description

If enabled, this event is generated when the user attempts to drag the thumb in a vertical scrollbar in a Form or SubForm. This event occurs only in a Form or SubForm whose HScroll property is set to ¯1 and is distinct from the Scroll event that is generated by a Scroll object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows:

[1] | Object | ref or character vector
[2] | Event | 'VThumbDrag' or 441
[3] | Position | numeric

The value of Position is the new (requested) position of the Thumb. Setting the action code of this event to ¯1, or returning a 0 from a callback function attached to it, has no effect.


WinIniChange Event

WinIniChange Event 133
Applies To: Root

Description

If enabled, this event is reported when another application changes relevant registry settings using the standard API calls. The event is reported after the change has taken place and cannot be disabled or inhibited in any way. If your application depends upon registry settings, this event gives you the opportunity of refreshing these parameters if they are changed.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'WinIniChange' or 133


Abort Method

Abort Method 103
Applies To: Printer

Description

This method causes the print job to be aborted and all pending output to be discarded.

The Abort method is niladic.

If you attach a callback function to this method and have it return a value of 0, the print job will continue.


AddChildren Method

AddChildren Method 310
Applies To: TreeView

Description

This method is used to add child items to an item in a TreeView object

The argument to AddChildren is a 3, 4 or 5 element array as follows:

[1] | Item number | Integer.
[2] | New items | Vector of character vectors.
[3] | Depth vector | Integer vector.
[4] | Picture vector | Integer vector.
[5] | Selected picture vector | Integer vector.

Item number specifies the index of the item to which the child items are to be added.

New items is a vector of character vectors containing the labels for the new child items.

Depth vector is an integer vector specifying the depth of each of the new items relative to the parent item to which they are being added. The first element of this array must be 0.

Picture vector and Selected picture vector are optional and specify values of ImageIndex and SelImageIndex respectively for each of the new items.

The result is the index at which the first new item has been inserted.


AddComment Method

AddComment Method 220
Applies To: Grid

Description

This method is used to add a new comment to a Grid.

The argument to AddComment is a 3, 4 or 5 element array as follows:

[1] | Row | integer
[2] | Column | integer
[3] | Comment text | character array
[4] | Height in pixels | integer
[5] | Width in pixels | integer

For example, the following statement associates a comment with the cell at row 2, column 1; the text of the comment is "Hello", and the size of the comment window is 50 pixels (high) by 60 pixels (wide).

      F.G.AddComment 2 1 'Hello' 50 60

Note that if you specify a row number of ¯1, the comment is added to the corresponding column title. Similarly, if you specify a column number of ¯1, the comment is added to the corresponding row title.

The height and width of the comment window, specified by the last 2 elements of the argument are both optional. If the cell already has an associated comment, the new comment replaces it.

You can use a Dynamic Function to add several comments in one statement; for example:

      (1 2)(2 3){F.G.AddComment ⍺,⊂⍵}¨'Hello' 'Goodbye'

Note that just before the comment is displayed, the Grid generates a ShowComment event which gives you the opportunity to (temporarily) change the text and/or window size of a comment dynamically.

The comment text specified by the 5th element of the argument to ⎕NQ must be a simple character scalar, vector, matrix or vector of vectors. Text specified by a simple character vector will be wrapped automatically if necessary. A matrix or vector of vectors may be used to explicitly specify multi-line text. If the array is a vector whose first element is an opening brace ({), the text is assumed to be in rich-text format (RTF) and is displayed accordingly. Note that there is no way for the user to scroll the text in the comment window and it is entirely your responsibility to ensure that the size of the window is appropriate for its contents.


AddItems Method

AddItems Method 308
Applies To: TreeView

Description

This method is used to add items to a TreeView object

The argument to AddItems is a 3, 4 or 5-element array as follows:

[1] | Item number | Integer.
[2] | New items | Vector of character vectors.
[3] | Depth vector | Integer vector.
[4] | Picture vector | Integer vector.
[5] | Selected picture vector | Integer vector.

Item number specifies the index of the item to which the child items are to be added.

New items is a vector of character vectors containing the labels for the new child items.

Depth vector is an integer vector specifying the depth of each of the new items relative to the parent item to which they are being added. The first element of this array must be 0. This element may be omitted. If so, it is assumed to be all 0s.

Picture vector and Selected picture vector are optional and specify values of ImageIndex and SelImageIndex respectively for each of the new items.

The new items are inserted with the first one being placed at the same level in the hierarchy as the item specified in element [1].

The result is an integer that reports the index position at which the first of the new items has been inserted.


AnimClose Method

AnimClose Method 291
Applies To: Animation

Description

The AnimClose method closes the AVI file that is currently loaded in an Animation object. The display is reset to the object's background colour.

The AnimClose method is niladic.


AnimOpen Method

AnimOpen Method 290
Applies To: Animation

Description

The AnimOpen method opens an AVI file in an Animation object.

The argument to AnimOpen is a 1 or 2-element array as follows:

[1] | File | character vector
[2] | Resource id | integer

If a single element is specified, it represents the name of a .AVI file.

If 2 elements are specified, the first element specifies the name of a DLL or EXE and the second element identifies the particular AVI resource stored in that file. The identifier may be its name (a character string) or its resource id (a non-zero positive integer).

If the AutoPlay property is set to 1, the animation will play immediately. Otherwise, only the first frame will be displayed.

Note that the Animation object can only play AVI files or resources that have no sound and can only display uncompressed AVI files or .AVI files that have been compressed using Run-Length Encoding (RLE). If you attempt to open an inappropriate AVI file, the operation will fail with a DOMAIN ERROR and the following message will be displayed in the Status Window:

AVI file includes sound data or is in a format not supported by the Animation object


AnimPlay Method

AnimPlay Method 292
Applies To: Animation

Description

The AnimPlay method plays an AVI clip in an Animation object.

The argument to AnimPlay is a 3-element array as follows:

[1] | Repeat | integer
[2] | From | integer
[3] | To | integer

Repeat specifies the number of times the clip is repeated. A value of -1 causes the clip to be repeated indefinitely.

From is a 0-based index of the frame where playing begins and must be less than 65536. A value of zero means begin with the first frame in the AVI clip

To is a 0-based index of the frame where playing ends and must be less than 65536. A value of -1 means end with the last frame in the AVI clip

The last frame remains displayed until the clip is unloaded using AnimClose or until another clip is loaded.


AnimStop Method

AnimStop Method 293
Applies To: Animation

Description

The AnimStop method stops playing an AVI clip in an Animation object.

AnimStop is niladic.

The last frame remains displayed until the clip is unloaded using AnimClose or until another clip is loaded.


Animate Method

Animate Method 29

Applies To

Description

The Animate method enables you to produce special effects when showing or hiding objects. There are three types of animation: roll, slide, and alpha-blended fade.

The argument to Animate is a 1 or 2-element array as follows:

[1] | Effects | integer
[2] | Play time | integer

The value of the Effects parameter is the sum of the following flags:

Flag | Value | Description
AW_HOR_POSITIVE | 1 | Animates the window from left to right. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_HOR_NEGATIVE | 2 | Animates the window from right to left. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_VER_POSITIVE | 4 | Animates the window from top to bottom. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_VER_NEGATIVE | 8 | Animates the window from bottom to top. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_CENTER | 16 | Makes the window appear to collapse inward if being hidden or expand outward if being displayed
AW_SLIDE | 262144 | Uses slide animation. By default, roll animation is used. This flag is meaningless on its own but is ignored when used with the AW_CENTER flag.
AW_BLEND | 524288 | Uses a fade effect. This flag can be used only for a Form.

The Playtime parameter is optional and specifies the length of time over which the animation is played in milliseconds. The default value depends upon the animation but is typically 200 milliseconds.


Browse Method

Browse Method 585
Applies To: OCXClass OLEClient

Description

The Browse method is retained for compatibility with previous versions of Dyalog APL, but is no longer relevant and has no effect.


CancelToClose Method

CancelToClose Method 367
Applies To: PropertySheet

Description

This method is used to change the buttons in a PropertySheet object. Its effect is to disable the Cancel button and, if the Style of the PropertySheet is 'Standard', it changes the text of the OK button to "Close". There is no result.

The CancelToClose method is niladic.


CellFromPoint Method

CellFromPoint Method 200
Applies To: Grid

Description

This method converts from Grid co-ordinates to cell co-ordinates.

The argument to CellFromPoint is a 2-element array as follows:

[1] | y-coordinate | number in Grid co-ordinates
[2] | x-coordinate | number in Grid co-ordinates

The result is a 2-element vector containing the following:

[1] | y-coordinate | number in cell co-ordinates
[2] | x-coordinate | number in cell co-ordinates


ChooseFont Method

ChooseFont Method 240

Applies To

Description

This method is used to display the standard Windows font selection dialog box.

The argument to ChooseFont is ⍬ or a 1 or 2-element array as follows:

[1] | Printer name | character scalar or vector.
[2] | Modify flag | 0 or 1.

If the argument is ⍬ or the first element of the argument is '', the user is offered a list of fonts suitable for use on the screen. If not, the user is offered a choice of fonts suitable for the specified Printer object. If you omit the 2nd element, the modify flag defaults to 0.

The dialog box is initialised with the properties of the Font object specified in the first element of the event message.

When the user presses the "OK" button, the "Cancel" button or closes the dialog box, ChooseFont terminates. Its result is either 0 (user pressed "Cancel") or a 2-element vector. In the latter case, the first element is an 8-element array that describes the selected font as described below, and the second element is a 3-element RGB colour vector.

[1] | Face name of selected font (character vector)
[2] | Character height in pixels (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

If the modify flag was 1, the Font object is redefined to match the user's selections and all the objects that reference the Font are redrawn.


ColChange Method

ColChange Method 159
Applies To: Grid

Description

This method is used to change the data in a column of a Grid.

The argument to ColChange is a 2-element array as follows:

[1] | Column number | integer
[2] | Column data | array

Note that the Column data must be a scalar or a vector whose length is equal to the number of rows in the Grid. Its elements may be scalar numbers, character vectors or matrices.


ColSorted Method

ColSorted Method 174
Applies To: Grid

Description

This method is used to specify that an image is to be displayed in a Grid column title to indicate the column has been sorted.

The argument to ColSorted is a 2-element array as follows:

[1] | Column number | Integer.
[2] | Sorted state | Integer. -1 = Sorted Down 0 = Unsorted 1 = Sorted Up

The column title for the appropriate column is redrawn to include the appropriate image.

If you wish to use your own images, you may specify them using the ColSortImages property.

      'F'⎕WC'Form' 'Grid: ColSorted Method'
      'F.G'⎕WC'Grid'('Posn' 0 0)(100 100)
      F.G.Values←(COUNTRIES,POPULATION,[1.5]AREA)
      F.G.ColTitles←'Country' 'Population' 'Area'
      F.G.TitleWidth←0

      F.G.Values←(Values[⍋Values[;2];])
      F.G.ColSorted 2 1

      F.G.(Values←Values[⍒↑Values[;1];])
      F.G.ColSorted 2 0
      F.G.ColSorted 1 ¯1


DateToIDN Method

DateToIDN Method 264
Applies To: Calendar DateTimePicker Root

Description

This method is used to convert a date from ⎕TS format into an IDN suitable for use in a Calendar object.

The argument to DateToIDN is a 3-element array as follows:

[1] | Year | Integer
[2] | Month | Integer
[3] | Day | Integer

DateToIDN will also accept a single enclosed argument containing these values. In either case, if you specify more than 3 numbers, excess elements they will be ignored.

Examples

      F.C.DateToIDN 1998 9 11
36048
      F.C.DateToIDN ⊂1998 9 11
36048
      F.C.DateToIDN ⎕TS
36048
      F.C.DateToIDN,⎕TS
36048


DelCol Method

DelCol Method 155
Applies To: Grid

Description

This method is used to delete a specified column from a Grid object.

The argument to DelCol is a 1 or 2-element vector as follows:

[1] | Column number | number of the column (integer) to delete
[2] | Undo flag | 0 or 1 (optional; default 0)

If the Undo flag 1, the column may subsequently be restored by invoking the Undo method. If the Undo flag is omitted or is 0, the operation may not be undone.


DelComment Method

DelComment Method 221
Applies To: Grid

Description

This method is used to delete a comment from a Grid.

The argument to DelComment is a 2 array as follows or ⍬:

[1] | Row | integer
[2] | Column | integer

For example, the following expression removes the comment associated with the cell at row 2, column 1.

      F.C.DelComment 2 1

Note that to delete a comment associated with a row or column title, the appropriate element in the argument should be ¯1.

If the argument is ⍬, all comments are deleted.


DelRow Method

DelRow Method 154
Applies To: Grid

Description

This method is used to delete a specified row from a Grid object.

The argument to DelRow is a 1 or 2-element array as follows:

[1] | Row number | number of the row (integer) to delete
[2] | Undo flag | 0 or 1 (optional; default 0)

If the Undo flag is 1, the column may subsequently be restored by invoking the Undo method. If the Undo flag is omitted or is 0, the operation may not be undone.


DeleteChildren Method

DeleteChildren Method 311
Applies To: TreeView

Description

This method is used to delete child items from a parent item in a TreeView object.

The argument to DeleteChildren is a scalar or 1 element array as follows:

[1] Item number Integer.

Item number specifies the index of the parent item from which the child items are to be removed.

The result is an integer that indicates the number of children that have been removed from the parent item.


DeleteItems Method

DeleteItems Method 309
Applies To: TreeView

Description

This method is used to delete items from a TreeView object.

The argument to DeleteItems is a 2-element array as follows:

[1] | Item number | Integer.
[2] | Number of Items | Integer.

Item number specifies the index of the first item to be removed.

Number of items specifies the number of items to be removed and refers to those items at the same level in the TreeView hierarchy as the Item number. Number of items is optional and defaults to 1.

Note that any children of these items will also be removed.

The result is an integer that indicates the total number of items, including children, that have been removed from the TreeView.


DeleteTypeLib Method

DeleteTypeLib Method 521
Applies To: Root

Description

The DeleteTypeLib method removes a loaded Type Library from the workspace.

The argument to DeleteTypeLib is as follows:

[1] TypeLib character vector

The Type Library may be identified by its name or by its class id.

The result is 0, 1 or ¯1.

If successful, the specified Type Library, and all dependant Type Libraries not referenced by any other currently loaded Type Libraries, are removed from the active workspace. The result is 1.

If the specified Type Library is in use, no action is taken and the result is 0.

If the argument is not the name or CLSID of a loaded Type Library, no action is taken and the result is ¯1.


Detach Method

Detach Method 270

Applies To

Description

This method is used to detach the GUI component from an object without losing the functions, variables and sub-namespaces that it may contain.

The Detach method is niladic.

The effect of this method is to remove the GUI component associated with the named object, leaving behind a plain namespace of the same name. All non-GUI child objects are retained. GUI child objects are either destroyed, or similarly converted to plain namespaces depending upon the values of their KeepOnClose properties.


DuplicateColumn Method

DuplicateColumn Method 178
Applies To: Grid

Description

This method is used to duplicate a column in a Grid object.

The argument to DuplicateColumn is a 2, 3, 4 or 5-element vector as follows:

[1] | Source Column number | number of the column (integer) to be duplicated
[2] | Target Column number | new column number (integer)
[3] | Comment flag | 0 or 1 (optional, default 1)
[4] | Lock flag | 0 or 1 (optional, default 1)
[5] | Undo flag | 0 or 1 (optional; default 0)

If the Comment flag is 1 (the default), any Comments associated with cells in the source column are duplicated in the target column.

If the Lock flag is 1 (the default), the lock state of the column is duplicated; otherwise, the new column is not locked.

If the Undo flag is 1, the column may subsequently be restored by invoking the Undo method. If this element is omitted or is 0, the operation may not be undone.


DuplicateRow Method

DuplicateRow Method 177
Applies To: Grid

Description

This method is used to duplicate a row in a Grid object.

The argument to DuplicateRow is a 2, 3, 4 or 5-element vector as follows:

[1] | Source Row number | number of the row (integer) to be duplicated
[2] | Target Row number | new row number (integer)
[3] | Comment flag | 0 or 1 (optional, default 1)
[4] | Lock flag | 0 or 1 (optional, default 1)
[5] | Undo flag | 0 or 1 (optional; default 0)

If the Comment flag is 1 (the default), any Comments associated with cells in the source row are duplicated in the target row.

If the Lock flag is 1 (the default), the lock state of the row is duplicated; otherwise, the new row is not locked.

If the Undo flag is 1, the row may subsequently be restored by invoking the Undo method. If this element is omitted or is 0, the operation may not be undone.


FileRead Method

FileRead Method 90
Applies To: Bitmap Cursor Icon Metafile RichEdit

Description

This method causes the object to be recreated from the file named in its File property.

The FileRead method is niladic.

[1] | Object | ref or character vector
[2] | Event | 'FileRead' or 90

If you attach a callback function to this event and have it return a value of 0, the object will not be recreated from file.


FileWrite Method

FileWrite Method 91
Applies To: Bitmap Cursor Icon Metafile RichEdit

Description

This method causes the object to be written to the file named in its File property. For the Bitmap and Icon objects this method will write a file of type .BMP and .ICO to a file with the appropriate extension. If File specifies any other extension, the method will fail with a DOMAIN ERROR:

 DOMAIN ERROR: This object cannot be saved to this type of file.

The FileWrite method is niladic.

If you attach a callback function to this event and have it return a value of 0, the object will not be written to file. You could use this to avoid overwriting an existing file.


Flush Method

Flush Method 135
Applies To: Root

Description

This method forces any objects that have been created but not yet shown to be displayed. Normally, Dyalog APL/W buffers the display of new objects unless they are being created by a callback function. This event can be used to override the bufferring.

The Flush method is niladic.


GetBuildID Method

GetBuildID Method 192
Applies To: Root

Description

This method is used to obtain the Build ID of a Dyalog APL executable.

The argument to GetBuildID is ⍬ or a single item as follows:

[1] File name character vector

The (shy) result is an 8-element character vector of hexadecimal digits that represents the Build ID.

If the argument is ⍬, the build id is that of the current version of Dyalog APL that is running the expression.

Note that although this method is designed to uniquely identify different versions of Dyalog APL by its check-sum, it may be used to obtain a check-sum for any arbitrary file.

Examples:

      GetBuildID ⍬
38091b76
      GetBuildID 'E:\DYALOG81\DYALOG.EXE'
cbf0d376
      GetBuildID 'C:\AUTOEXEC.BAT'
4a29334d

Note that if the file does not exist, the result is 00000000.


GetCellRect Method

GetCellRect Method 201
Applies To: Grid

Description

This method returns the rectangle associated with a particular cell in a Grid.

The argument to GetCellRect is a 2-element vector as follows:

[1] | Row | integer
[2] | Column | integer

The result is a 2-element nested vector. The first element contains the y and x-coordinate of the top-left corner of the cell. The second element contains the height and width of the cell.

The result is reported in terms of the coordinate system of the Grid object.


GetCommandLine Method

GetCommandLine Method 145
Applies To: Root

Description

The GetCommandLine method returns the command line that was used to start the current Dyalog APL session or application.

The GetCommandLine method is niladic.

The result is a character vector.

Examples

      GetCommandLine
"C:\Program Files\Dyalog\Dyalog APL-64 13.2 Unicode\dyalog.exe"
      ⎕←2 ⎕NQ '.' 'GetCommandLine'
"C:\Program Files\Dyalog\Dyalog APL-64 13.2 Unicode\dyalog.exe"

Note

GetCommandLine only works on Windows, and its use is deprecated in favour of GetCommandLineArgs, which works on all platforms.


GetCommandLineArgs Method

GetCommandLineArgs Method 148
Applies To: Root

Description

The GetCommandLineArgs method returns the command and the arguments to the command that was used to start the current Dyalog APL session or application.

The GetCommandLineArgs method is niladic.

The result is a vector of character vectors. For example:

      GetCommandLineArgs
 C:\Dyalog10\dyalog.exe  -Dw  YY_WINDOW=-30
      DISPLAY 2 ⎕NQ '.' 'GetCommandLineArgs'
.→-----------------------------------------------.
| .→---------------------. .→--. .→------------. |
| |C:\Dyalog10\dyalog.exe| |-Dw| |YY_WINDOW=-30| |
| '----------------------' '---' '-------------' |
'∊-----------------------------------------------'


GetComment Method

GetComment Method 222
Applies To: Grid

Description

This method is used to retrieve the comment associated with a cell in a Grid.

The argument to GetComment is a 2-element array as follows:

[1] | Row | integer
[2] | Column | integer

For example, the following expression retrieves the comment associated with the cell at row 3, column 1.

      F.C.GetComment 3 1
 1 3  Hello  175 100

Note that to retrieve a comment associated with a row or column title, the appropriate element in the argument should be ¯1.

If there is no comment associated with the specified cell, the result is a scalar 1.


GetEnvironment Method

GetEnvironment Method 510
Applies To: Root

Description

This method is used to obtain information about one or more parameters that were specified in the APL command line, your Windows registry, or defined as environment variables. If a value is defined in several places (for example, MAXWS in the command line overriding MAXWS in the registry), GetEnvironment follows exactly the same logic as is used by Dyalog APL itself and so obtains the same value.

The argument to GetEnvironment is a single item as follows:

[1] Parameter name(s) see below

Parameter names is simple character vector or vector of character vectors specifying one or more parameters.

The result is a simple character vector or a vector of character vectors.

Examples:

      GetEnvironment 'DYALOG'
C:\Dyalog82
     GetEnvironment ⊂'DYALOG' 'APLNID'
 C:\Dyalog82  0

Note that you may use GetEnvironment to obtain the values of your own arbitrary parameters given on the APL command line, defined in APL.INI, or specified as environment variables.

GetEnvironment is not supported by DYALOG.DLL because it does not use parameters.


GetEventInfo Method

GetEventInfo Method 551
Applies To: OCXClass OLEClient

Description

This method is used to obtain information about a particular event or set of events supported by a COM object.

For each event supported by a COM object, the author will have registered the data type of its result (if it has a result), a help message or description of the event (optional) and the name and data type of each of its parameters. These event parameters make up the array returned by ⎕DQ or supplied as an argument to your callback function. The GetEventInfo method returns this information.

The argument to GetEventInfo is a single item as follows:

[1] Event name(s) see below

Event name(s) is a simple character vector or a vector of character vectors specifying one or more names of events supported by the object.

The result is a nested vector with one element per event name. Each element of this vector is itself a vector of 2-element character vectors. For each event, the first item describes the help message or description (if any) registered for the event and the data type of its result. Each of the remaining elements contains a parameter name and its corresponding data type.

Example:

      CLNAME←'Microsoft Multimedia Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.EventList
 Done  BackClick  PrevClick  NextClick  PlayClick  ...
      DISPLAY ↑MM.GetEventInfo 'Done'
.→---------------------------------------------------.
↓ .→-----------------------------. .→------.         |
| |Occurs when an MCI command ...| |VT_VOID|         |
| '------------------------------' '-------'         |
| .→---------.                     .→--------------. |
| |NotifyCode|                     |VT_PTR to VT_I2| |
| '----------'                     '---------------' |
'∊---------------------------------------------------'

Note that if the event does not produce a result, the data type of the result is reported as 'VT_VOID'.


GetFocus Method

GetFocus Method 511

Applies To

Description

This method is used to obtain the name of the object that currently has the input focus.

The GetFocus method is niladic.

The result is a simple character vector. An empty result indicates that no Dyalog APL GUI object has the input focus.


GetItemHandle Method

GetItemHandle Method 313
Applies To: TreeView

Description

This method is used to obtain the window handle of a particular item in a TreeView object.

The argument for GetItemHandle is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is an integer containing the window handle of the item.


GetItemPosition Method

GetItemPosition Method 323
Applies To: ListView

Description

This method is used to obtain the position of a particular item in a ListView object.

The argument for GetItemPosition is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is a 2-element vector containing the position of the item.


GetItemState Method

GetItemState Method 306
Applies To: ListView TreeView

Description

This method is used to obtain the status of a particular item in a ListView or TreeView object.

The argument for GetItemState is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned. It is Index Origin dependent.

The result indicates the state of the item as the sum of one or more of the following codes:

¯1 | Error (most likely that the Item number is invalid)
1 | Item has the focus
2 | Item is selected
8 | Item is highlighted for dropping
16 | Item is displayed in bold text
32 | Item is expanded
64 | Item is or has been expanded
4096 | Item is checked. See CheckBoxes


GetMethodInfo Method

GetMethodInfo Method 552
Applies To: OCXClass OLEClient

Description

This method is used to obtain information about a particular method or set of methods supported by a COM object.

For each method supported by a COM object the author will have registered a help message or description of the method (this is in fact optional), the data type of its result (if it has a result), and the name and data type of each of the parameters that must be supplied when you invoke it. The GetMethodInfo method returns this information.

The argument to GetMethodInfo is a single item as follows:

[1] Method name(s) see below

Method name(s) is a simple character vector or a vector of character vectors specifying one or more names of methods supported by the object.

The result is a nested vector with one element per method name. Each element of this vector is itself a vector of 2-element character vectors. For each method, the first item describes the help message or description (if any) registered for the method and the data type of its result. Note that if the event does not produce a result, the data type of the result is reported as 'VT_VOID'. Each of the remaining elements contains a parameter name and its corresponding data type.

Example

      CLNAME←'Microsoft Multimedia Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.MethodList
 AboutBox  Refresh  OLEDrag

      DISPLAY ↑ MM.GetMethodInfo 'AboutBox'
.→--------------.
↓ .⊖. .→------. |
| | | |VT_VOID| |
| '-' '-------' |
'∊--------------'


GetMinSize Method

GetMinSize Method 275
Applies To: Calendar

Description

This method is used to obtain the minimum size that you must specify for a Calendar object for it to display a complete month.

The GetMinSize method is niladic.

The (shy) result of the method is a 2-element numeric vector containing the minimum height and width required for the object to display a complete month.


GetParentItem Method

GetParentItem Method 312
Applies To: TreeView

Description

This method is used to obtain the index of the parent of a particular item in a TreeView object.

The argument for GetParentItem is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is an integer containing the index of the parent item.


GetPropertyInfo Method

GetPropertyInfo Method 550
Applies To: OCXClass OLEClient

Description

This method is used to obtain information about a particular property or set of properties supported by a COM object.

For each property supported by a COM object, the author will have registered the property name, its data type, and an optional help message or description of the property. GetPropertyInfo returns this information.

The argument to GetPropertyInfo is a single item as follows:

[1] Property name(s) see below

Property name(s) is a simple character vector or a vector of character vectors specifying one or more names of properties supported by the object.

The result is a nested vector with one element per property name. Each element of this vector is itself a 2-element vector of character vectors containing the data type and help message for the corresponding property.

Example

      CLNAME←'Microsoft Multimedia Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.PropList
 Type  DeviceType  AutoEnable  PrevVisible ...

      DISPLAY ↑MM.GetPropertyInfo 'PrevVisible'
.→------------------------------------------------------.
↓ .→----------------------------------------. .→------. |
| |Determines if the Prev button is visible.| |VT_VOID| |
| '-----------------------------------------' '-------' |
| .→-.                                        .→------. |
| |⌈P|                                        |VT_BOOL| |
| '--'                                        '-------' |
'∊------------------------------------------------------'

If the data type of a property is VT_USERDEFINED, it means that the property may assume one of a set of values defined by a type list. In this case, the name of the type list is returned in place of the string "VT_USERDEFINED". Further information can be obtained using GetTypeInfo with this name as a parameter.


GetTextSize Method

GetTextSize Method 92

Applies To

Description

The GetTextSize method obtains the size of the bounding rectangle of a text item in a given font. The result is given in the co-ordinate system of the object in question. This method is useful for positioning Text objects.

GetTextSize duplicates the functionality of the TextSize property. It is recommended that you use GetTextSize instead of TextSize which may be removed in a future release of Dyalog APL.

The argument to GetTextSize is a 1 or 2-element array as follows:

[1] | Text item | character array
[2] | Font name | character vector

When you invoke GetTextSize you give the text item in whose size you are interested and, optionally, the name of a Font object. The text item may be a simple scalar, a vector or a matrix. If the Font is omitted, the result is given using the current font for the object in question.

Examples

      'F'⎕WC'Form'
      F.GetTextSize'Hello World'
3.385416667 10.7421875
      'FNT1' ⎕WC 'Font' 'Arial' 72
      F.GetTextSize'Hello World'  '#.FNT1'
18.75 65.4296875
      F.Coord←'Pixel'
      F.FontObj←'FNT1'
      F.GetTextSize'Hello World'
16 77


GetTypeInfo Method

GetTypeInfo Method 553
Applies To: OCXClass OLEClient

Description

This method is used to obtain information about a type list supported by a COM object.

The argument to GetTypeInfo is a single item as follows:

[1] | Type List name(s) | see below
[2] | Value | (usually) numeric
[3] | Description | character vector

Type List name(s) is a simple character vector or a vector of character vectors specifying one or more names of type lists supported by the object.

The result is a nested vector with one element per Type List. Each element of this vector is itself a 3-element vector of character vectors made up as follows:

[1] | Name of Constant | character vector
[2] | Value | (usually) numeric
[3] | Description | character vector


GetVisibleRange Method

GetVisibleRange Method 262
Applies To: Calendar

Description

This method is used to obtain the range of dates that is currently visible in a Calendar object.

The GetVisibleRange method is niladic.

The result is a 2-element integer vector containing the first and last dates currently displayed by the object, reported as IDNs.


GreetBitmap Method

GreetBitmap Method 138
Applies To: Root

Description

This method is used to display or remove a bitmap, typically during initialisation of a Dyalog APL runtime application.

The argument to GreetBitMap is ⍬ or a 2 element vector as follows:

[1] | Display | 0 = off, 1 = on.
[2] | Bitmap file name | Character vector.

If the argument is ⍬, the bitmap is removed.

The image may also be displayed initially by setting parameter: greet_bitmapon the command line, e.g.:

c:\myapp\dyalogrt greet_bitmap=mylogo myws

The image is displayed until either an untrapped error occurs, causing the interpreter to (attempt to) display the session window, or the GreetBitmap method is called.


IDNToDate Method

IDNToDate Method 263
Applies To: Calendar DateTimePicker Root

Description

This method is used to convert a date from an IDN into ⎕TS format (year, month, day). The corresponding day of the week is also obtained.

The argument to IDNToDate is a single item as follows:

[1] IDN Integer

The result is a 4-element integer vector containing the year, month, day, and weekday corresponding to the IDN that was specified.

The value of the 4th element, weekday, is an integer in the range 0-6 that specifies on which day of the week the specified date falls (0=Monday).

Example

      F.C.IDNToDate 36048
1998 9 11 4


ListTypeLibs Method

ListTypeLibs Method 520
Applies To: Root

Description

The ListTypeLibs method reports the names and CLSIDs of all the loaded Type Libraries.

The ListTypeLibs method is niladic.

The result is a nested vector with one element per loaded Type Library.

Each element is a vector of 2-element charcater vectors. The first is the name of the Type Library; the second is its class identifier or CLSID.

Example:

      'EX'⎕WC'OLEClient' 'Excel.Application'
      ⍴ListTypeLibs
3
      ↑⊃ListTypeLibs
Microsoft Excel 9.0 Object Library
{00020813-0000-0000-C000-000000000046}

      ↑⊃¨ListTypeLibs
Microsoft Excel 9.0 Object Library
Microsoft Visual Basic for Applications Extensibility 5.3
Microsoft Office 9.0 Object Library


LockColumns Method

LockColumns Method 227
Applies To: Grid

Description

This method is used to lock one or more columns of a Grid object. However, LockColumns is not supported in combination with hierarchical column titles as specified by the ColTitleDepth property.

The argument to LockColumns is a 1 or 2-element vector as follows.

[1] | Column(s) | integer scalar, vector or matrix
[2] | Lock flag | 0 or 1

Column(s) may be a scalar or a vector specifying the column or columns to be locked or unlocked. Alternatively, it may be a matrix whose first row specifies the columns to be locked and whose second row specifies wherethey are to be locked.

If the Lock flag is 1, the corresponding columns are locked. This is the default and may be omitted. If the Lock flag is 0, the corresponding columns are unlocked

Examples:

      F.G.LockColumns 3         ⍝Lock 3rd column
      F.G.LockColumns 3 0       ⍝Unlock 3rd column
      F.G.LockColumns (4 5)     ⍝Lock 4th & 5th cols
      F.G.LockColumns (2 1⍴8 4) ⍝Lock 8 at 4
      F.G.LockColumns 3         ⍝Lock 3rd column
      F.G.LockColumns 3 0       ⍝Unlock 3rd column
      F.G.LockColumns (4 5)     ⍝Lock 4th & 5th cols
      F.G.LockColumns (2 1⍴8 4) ⍝Lock 8 at 4

The result is an integer matrix containing the indices of all locked columns and the positions at which they are currently locked.

The expression:

      F.G.LockColumns ⊂⍬

may therefore be used to obtain the indices of the locked columns, and:

      F.G.LockColumns(F.G.LockColumns ⊂⍬) 0

unlocks all currently locked columns.

Locks are additive. If column 4 is locked, locking column 5 results in both columns 4 and 5 being locked.

A locked column remains fixed in position and does not scroll sideways. The user may enter and edit cells in a locked column in the normal way, but the behaviour of the various cell movement keys (Tab, left and right cursor, and so forth) differs when a locked column is encountered. As a general rule, if a keystroke attempts to move the cursor into a locked column from an adjacent column, and the adjacent column has been scrolled, it is unscrolled and the cursor remains in the (new) column adjacent to the fixed column. If not, the cursor moves into the locked column.

When you lock a column, the position you specify for it to be locked at is a position in the data and not the physical position of the column as displayed in the Grid . The physical column in the Grid depends upon the value of the Index property at the time it was locked.

If C is the value specified for where a given column is to be locked, the value of the physical column Pat which it will be displayed in the Grid named GRIDis:

      P←C-(2⊃GRID ⎕WG 'Index')-⎕IO

Furthermore, the position of a locked column given by the result of the LockColumns method changes (with the Index property) as the Grid is scrolled.


LockRows Method

LockRows Method 226
Applies To: Grid

Description

This method is used to lock one or more Rows of a Grid. However, LockRows is not supported in combination with hierarchical row titles as specified by the RowTitleDepth property.

The argument to LockRows is a 1 or 2-element vector as follows.

[1] | Row(s) | integer scalar, vector or matrix
[2] | Lock flag | 0 or 1

Row(s) may be a scalar or a vector specifying the row or rows to be locked or unlocked. Alternatively, it may be a matrix whose first row specifies the data rows to be locked and whose second row specifies where in the Grid they are to be locked

If the Lock flag is 1, the corresponding rows are locked. This is the default and may be omitted. If the Lock flag is 0, the corresponding rows are unlocked.

Examples:

      F.G.LockRows 3         ⍝Lock 3rd row
      F.G.LockRows 3 0       ⍝Unlock 3rd row
      F.G.LockRows (4 5)     ⍝Lock 4th and 5th rows
      F.G.LockRows (2 1⍴8 4) ⍝Lock row 8 at 4
      F.G.LockRows 3         ⍝Lock 3rd row
      F.G.LockRows 3 0       ⍝Unlock 3rd row
      F.G.LockRows (4 5)     ⍝Lock 4th and 5th rows
      F.G.LockRows (2 1⍴8 4) ⍝Lock row 8 at 4

The result is an integer matrix containing the indices of all locked rows and the positions at which they are currently locked.

The expression:

      F.G.LockRows ⊂⍬

may therefore be used to obtain the indices of the locked rows, and

      F.G.LockRows(F.G.LockRows ⊂⍬) 0

unlocks all currently locked rows.

Locks are additive. If row 4 is locked, locking row 5 results in both rows 4 and 5 being locked.

A locked row remains fixed in position and does not scroll vertically. The user may enter and edit cells in a locked row in the normal way, but the behaviour of the various cell movement keys (Tab, up and down cursor, and so forth) differs when a locked row is encountered. As a general rule, if a keystroke attempts to move the cursor into a locked row from an adjacent row, and the adjacent row has been scrolled, it is unscrolled and the cursor remains in the (new) row adjacent to the fixed row. If not, the cursor moves into the locked row.

When you lock a row, the position you specify for it to be locked at is a position in the data and not the physical position of the column as displayed in the Grid. The physical column in the Grid depends upon the value of the Index property at the time it was locked.

If R is the value specified for where a given row is to be locked, the value of the physical row Pat which it will be displayed in the Grid named GRIDis given by the expression:

P←R-(⊃GRID ⎕WG 'Index')-⎕IO

Furthermore, the position of a locked row given by the result of the LockRows method changes (with the Index property) as the Grid is scrolled.


MDIArrange Method

MDIArrange Method 112
Applies To: MDIClient

Description

This method causes the MDIClient object to organise the icons associated with any minimised child Forms into regimented rows and columns. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call MDIArrange.

The MDIArrange method is niladic.


MDICascade Method

MDICascade Method 110
Applies To: MDIClient

Description

This method causes the MDIClient object to organise its child Forms in an overlapping fashion. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call MDICascade.

The MDICascade method is niladic.


MDITile Method

MDITile Method 111
Applies To: MDIClient

Description

This method causes the MDIClient object to organise its child Forms as a row or column. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call the MDITile method.

Note that because there are restrictions concerning the minimum height and width of a window, MS-Windows does not necessarily respond as requested. If the MDIClient is itself of insufficient size, or if it contains a large number of child Forms, Windows may choose to tile the Forms in a row when a column was specified or vice versa. It may also choose to ignore the event entirely.

The argument to MDITile is ⍬, or a single item as follows:

[1] Tile Mode 0 (vertical)
1 (horizontal)

If the argument is ⍬, the Tile Modedefaults to 0.


MakeGIF Method

MakeGIF Method 261
Applies To: Bitmap

Description

This method is used to generate a GIF representation of a picture from a Bitmap object suitable for display by a Web browser.

The MakeGIF method is niladic.

The result is an integer vector containing the encoded GIF image.

Example:

      ⍴GIF←BM.MakeGIF
19620


MakePNG Method

MakePNG Method 260
Applies To: Bitmap

Description

This method is used to generate a PNG (Portable Network Graphics) representation of a picture from a Bitmap object suitable for display by a Web browser.

The MakePNG method is niladic.

The result is an integer vector containing the encoded PNG image.

Example:

      ⍴PNG←BM.MakePNG
4930


NameFromHandle Method

NameFromHandle Method 136
Applies To: Root

Description

This method is used to obtain the name of a particular object from the value of its Handle property.

The argument to NameFromHandle is a single item as follows:

[1] Handle The value of the Handle property from an existing object.

The result is a character vector containing the name of the object.


NewPage Method

NewPage Method 102
Applies To: Printer

Description

This method causes a Printer to start a new page

The NewPage method is niladic.

If you attach a callback function to this event and have it return a value of 0, the page throw will not occur.


OLEAddEventSink Method

OLEAddEventSink Method 540
Applies To: OCXClass OLEClient

Description

This method connects a named event sink to a COM object and adds the events defined by that event sink to the EventList property of the associated namespace.

The argument to OLEAddEventSink is a single item as follows:

[1] Event sink name character vector

The result is a number that represents the handle of the event sink. This may be subsequently required.


OLEDeleteEventSink Method

OLEDeleteEventSink Method 541
Applies To: OCXClass OLEClient

Description

This method disconnects a named event sink from a COM object and removes the events defined by that event sink from the EventList property of the associated namespace.

This method may be used to remove an event sink that was established automatically when the OLE object was created.

The argument to OLEDeleteEventSink is a single item as follows:

[1] Event sink name character vector


OLEListEventSinks Method

OLEListEventSinks Method 542
Applies To: OCXClass OLEClient

Description

This method returns the names of event sinks that are currently connected to a COM object.

The list contains the names of all the event sinks that were connected automatically when the object was created, together with any that you have added subsequently using OLEAddEventSink.

The OLEListEventSinks method is niladic.

The result is a vector of character vectors containing the names of the event sinks connected to the object.


OLEQueryInterface Method

OLEQueryInterface Method 543
Applies To: ActiveXContainer OLEClient

Description

This method is used to obtain the methods and properties associated with a particular interface that is provided by a COM object. An interface is simply a pointer to a table of methods (not properties) that are exported by an object.

Note that methods and properties exported using the standard IDispatch interface are established automatically when the object is created. OLEQueryInterface is required only to support alternative or additional interfaces that the object may implement.

The argument to OLEQueryInterface is a single item as follows:

[1] Interface name character vector

The result is a namespace.

It is normal, although not strictly required, that the new namespace be a child of the one for which the method is run.

Note that if the object does not support a type library, the new namespace will be empty and you will have to establish functions corresponding to the methods exported by the interface using SetMethodInfo.


OLERegister Method

OLERegister Method 530
Applies To: OLEServer

Description

This method is used to register an OLEServer object and may be used to install Dyalog APL OLE Servers as part of a run-time installation.

The OLERegister method is niladic.


OLEUnregister Method

OLEUnregister Method 531
Applies To: OLEServer

Description

This method is used to unregister an OLEServer object that has previously been saved by Dyalog APL.

The OLEUnregister method is niladic.

This method removes all traces of the object from the Windows registry and erases its Type Library file.

Note that the name of the object removed from the registry is the name of the OLEServer object prefixed by the string "dyalog."


Print Method

Print Method 100
Applies To: Printer

Description

This method causes any spooled output to be printed.

The Print method is niladic.

If you attach a callback function to this event and have it return a value of 0, the printout will not be spooled.


ProgressStep Method

ProgressStep Method 250
Applies To: ProgressBar

Description

This method is used to increment the thumb in a ProgressBar object.

The ProgressStep method is niladic.

The ProgressStep method causes the ProgressBar to attempt to increment its thumb by the value of its Step property, taking into account the settings of its Limits and Wrap properties.

If the values of the Thumb, Step and Limits properties are THUMB, STEP and LIMITS respectively, the new value of Thumb (and the corresponding position of the highlit bar) is:

if Wrap is 0:

      LIMITS[2]⌊THUMB+STEP

if Wrap is 1:

      LIMITS[1]+(1+LIMITS[2]-LIMITS[1])|THUMB+STEP-LIMITS[1]


RTFPrint Method

RTFPrint Method 461
Applies To: RichEdit

Description

This method is used to print the contents (RTFText) of a RichEdit object.

The argument to RTFPrint is ⍬, or a 1 to 4-element array as follows:

[1] | Printer name | Optional - character vector (see below)
[2] | Print range | Optional - (see below)
[3] | Number of copies | Optional - Integer.
[4] | Collate | Optional - 0 or 1

Printer name may be the name of an existing Printer object, or the (Windows) name of an installed printer. If you use the latter, the document will be spooled immediately. An empty vector implies the default printer.

Print range may be a simple character vector containing 'All', 'Pages', or 'Selection'. Alternatively, it may be a 3 or 4-element nested vector containing:

[1] | 'All', 'Pages', or 'Selection'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum pages (ignored)


RTFPrintSetup Method

RTFPrintSetup Method 460
Applies To: Printer RichEdit

Description

This method is used to display a print set-up dialog box. The dialog box allows the user to select a particular printer, the pages to be printed and other information. The user's choices are returned in the result.

The argument to RTFPrintSetup is ⍬, or a 1 to 3-element array as follows:

[1] | Print range | Optional - (see below)
[2] | Number of copies | Optional - Integer.
[3] | Collate | Optional - 0 or 1

Print range may be a simple character vector containing 'All', 'Pages', or 'Selection'.

Alternatively, it may be a 3 or 4-element nested vector containing:

[1] | 'All', 'Pages', or 'Selection'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum pages

Maximum pages (4th element of Print range) may be an integer number, or the name of a reference object. The latter allows the system to calculate the total number of pages required. If the object to which the RTFPrintSetup event is sent is a RichEdit, this is the name of a printer object. If the object to which the RTFPrintSetup event is sent is a Printer, this is the name of a RichEdit object. Both are required because the number of pages of a printed document is dependent upon both the content of the document and the characteristics of the device upon which it will be printed.

If the user presses OK, the result is a 4-element vector containing the user's choices as follows:

[1] | Printer name | character vector
[2] | Print range | (see above)
[3] | Number of copies | Integer
[4] | Collate | 0 or 1

Example:

      F.T.RTFPrintSetup ('All' 1 1 'PR')
 IBM 4039 LaserPrinter PS   Pages  2 3 3  1 0


RowChange Method

RowChange Method 158
Applies To: Grid

Description

This method is used to change the data in a row of a Grid object.

The argument to RowChange is a 2-element array as follows.

[1] | Row number | integer
[2] | Row data | array

Row data must be a scalar or a vector whose length is equal to the number of columns in the Grid. Its elements may be scalar numbers, character vectors or matrices.


RowSetVisibleDepth Method

RowSetVisibleDepth Method 173
Applies To: Grid

Description

This method is used to set the maximum visible depth of data in rows of a Grid.

The argument to RowSetVisibleDepth is a numeric scalar as follows

[1] Depth integer

All rows in the grid that have a value of RowTreeDepth less that or equal to Depth are expanded. Rows with a value of RowTreeDepth greater than Depth are collapsed.

Note:Expanding and Retracting events are not generated when this method is called.

Examples

      'F'⎕WC'Form' 'Grid: TreeView Feature'
      'F.G'⎕WC'Grid'(30 2⍴2/⍳30)
      F.G.RowTreeDepth←30⍴0 1 2 2

      F.G.RowSetVisibleDepth 1

      F.G.RowSetVisibleDepth 99


SetCellSet Method

SetCellSet Method 171
Applies To: Grid

Description

The SetCellSet method sets the value of the CellSet property of a Grid for a particular cell.

The argument to SetCellSet is a 3-element array as follows:

[1] | Row | integer
[2] | Column | integer
[3] | Value | 0 or 1


SetCellType Method

SetCellType Method 156
Applies To: Grid

Description

This method is used to change the type of a particular cell in a Grid.

The argument to SetCellType is a 3-element vector as follows :

[1] | Cell row | integer
[2] | Cell column | integer
[3] | Cell type | integer


SetEventInfo Method

SetEventInfo Method 547
Applies To: ActiveXControl OLEServer

Description

This method is used to register an event that may be generated by an ActiveXControl or OLEServer object.

A host application that wishes to attach a callback function to an event in a Dyalog APL ActiveXControl or OLEServer, needs to know the name of the event and the number and data types of any parameters that the event may supply. It also needs to know the data type (if any) of the result that the callback function may be expected to pass back to the control.

An ActiveXControl or OLEServer generates an event in the host application using 4 ⎕NQ. The right argument is a vector whose first 2 elements are character vectors containing the names of the ActiveXControl or OLEServer and the event respectively. The parameters for the event are passed as additional elements in the argument.

Another way to think about it is that when you generate an event using 4 ⎕NQ, you are effectively calling a function, of your specification, in the host application. To enable the host application to accept the function call, it needs to know the number of parameters that you will supply and their data types.

A further consideration is that if you specify that the data type of a parameter is a pointer (e.g. 'VT_PTR TO I4') this will allow a callback function to modify the parameter in-situ. If so, the result returned by 4 ⎕NQ will be the modified values of any such parameters; this is a similar mechanism to ⎕NA.

The argument to SetEventInfo is a 1, 2 or 3-element array as follows:

[1] | Event name | character vector
[2] | Event info | nested array (see below)
[3] | Help ID | integer

Event info

Event info, specifies an optional help string which describes what the event does, the data type of the result (if any) and the names and data types of its arguments.

If the event is fully described, each element of Event Info is a 2-element vector of character vectors. The first element contains the help string and the COM data type of the result that the callback function in the host application is expected to supply. Subsequent elements contain the name and COM data type of each of the parameters supplied by the event.

However, both the help string and the names of the parameters are optional and may be omitted. If so, one or more elements of Event Info may be a simple character vector.

Help ID

This is an integer value that identifies the help context id for the event within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.

Example

The example Dual ActiveXControl, that is fully described elsewhere, generates a ChangeValue1 event. This event occurs when the user moves the thumb in a TrackBar that is internal to an instance of the ActiveXControl.

The external ChangeValue1 event is fired by an internal APL callback function (called ChangeValue) that is attached to ThumbDrag and Scroll events on the TrackBar object. The internal callback function is :

[0]   ChangeValue MSG
[1]   ⍝ Callback for ThumbDrag and Scroll
[2]   Value1←4 ⎕NQ'' 'ChangeValue1'(⊃¯1↑MSG)
[3]   CalcValue2
[4]   'V1'⎕WS'Text'(⍕Value1)
[5]   'V2'⎕WS'Text'(⍕Value2)

Note that ChangeValue[2] generates the external ChangeValue1 event by invoking 4 ⎕NQ, passing it the new value provided by the TrackBar. However, the host application is permitted to modify that value, returning it in the result of 4 ⎕NQ. This result, rather than the TrackBar value itself, is then used to update other (Label) controls in the object.

The following statements were used to declare the ChangeValue1 event The event provides a single parameter named Value1 that may be modified in-situ by a callback function in the host application. The callback is not, otherwise, expected to return a result.

      INFO←⊂'Occurs when the value of the control is changed' 'VT_VOID'
      INFO,←⊂'Value1' 'VT_PTR TO VT_I4'
      F.Dual.SetEventInfo 'ChangeValue1' INFO

If the host application was Visual Basic, a suitable callback function might be:

Private Sub Dual1_ChangeValue1(Value1 As Long)
Value1=2*(Value1\2)
End Sub

This callback function receives the proposed new value of the control as the parameter Value1, and modifies it, forcing it to be an even number.


SetFinishText Method

SetFinishText Method 366
Applies To: PropertySheet

Description

The SetFinishText method sets the caption of the Finish button in a Wizard-style PropertySheet.

The argument to SetFinishText is a single item as follows:

[1] Finish button text character vector


SetFnInfo Method

SetFnInfo Method 545
Applies To: ActiveXControl OLEServer

Description

This method is used to describe an APL function that is to be exported as a method, a Property Get Function, or a Property Put Function of an ActiveXControl or OLEServer object.

An exported function must be a niladic or monadic defined function (dynamic functions and derived functions are not allowed) and may optionally return a result. Ambivalent functions (functions with optional left argument) are allowed, but will be called monadically by the host application.

COM syntax differs from APL syntax in many ways and the SetFnInfo method is required to declare an APL function to COM in terms that COM understands. In particular, although monadic APL functions take just one argument, COM functions may take several parameters, and some may be optional.

A function exported by SetFnInfo will be called by a host application with the number of parameters that SetFnInfo has described. The argument received when the function is called by a host application, will be a nested vector of this length.

The argument to SetFnInfo is a 2, 3 or 4-element array as follows:

[1] | Function name | character vector
[2] | Function info | nested array (see below)
[3] | Help ID | integer
[4] | Function type | integer
[5] | Property name | character vector

Function info

This specifies an optional help string which describes what the function does, the data type of the result (if any) and the names and data types of its arguments.

If the function syntax is fully described, each element of Function Info is a 2-element vector of character vectors. The first element contains the help string and the COM data type of the function's result. Subsequent elements contain the name and COM data type of each parameter.

However, both the help string and the names of the parameters are optional and may be omitted. If so, one or more elements of Function Info may be a simple character vector.

Consider a very basic function ADD in an ActiveXControl called F.dbase, that is designed to add a record to a personnel database. The database consists only of a list of names, ages and addresses.

Function ADD expects to be called with a name (character string), age (number) and address (character string), and returns a result 0 or 1 (Boolean) according to whether the record was successfully added. This function could be declared as follows:

      HELP←'Adds a new record to the personnel database'
      SPEC←⊂(HELP 'VT_BOOL')      ⍝ Result is boolean
      SPEC,←⊂('Name' 'VT_BSTR')   ⍝ 1st param called 'Name' is a string
      SPEC,←⊂('Age' 'VT_I4')      ⍝ 2nd param called 'Age' is an integer
      SPEC,←⊂('Address' 'VT_BSTR')⍝ 3rd param called 'Address' is a string

      F.dbase.SetFnInfo 'ADD' SPEC

Alternatively, but much less helpfully, the function could be declared to take a single unnamed nested argument, leaving it to the host application programmer to guess at its structure :

      SPEC←⊂('' 'VT_BOOL')              ⍝ No help string, result is boolean
      SPEC,←⊂('' 'VT_ARRAY OF VT_VARIANT') ⍝ Param is a nested array
      F.dbase.SetFnInfo 'ADD'SPEC

Help ID

This is an integer value that identifies the help context id within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.

Function type

This specifies the type of function being exported. This is an integer with one of the following values:

In both these last two cases, the name of the property, which is totally independent of the name of the APL function, is given as Property name.

If omitted, the function type is method.


SetItemImage Method

SetItemImage Method 315
Applies To: TreeView

Description

This method is used to allocate a picture icon to a particular item in a TreeView object.

The argument to SetItemImage is a 2-element array as follows:

[1] | Item number | Integer.
[2] | Picture index | Integer.

Item number is the index of the item concerned.

Picture index is an index into the array of bitmapped images in the corresponding ImageList object which is referenced via the ImageListObj property.


SetItemState Method

SetItemState Method 307
Applies To: ListView TreeView

Description

This method is used to set the status of a particular item in a ListView or TreeView object.

The argument to SetItemState is a 2-element array as follows:

[1] | Item number | Integer. The index of the item concerned.
[2] | Status | Integer

The status of an item is calculated as the sum of one or more of the following state codes:

¯1 | Error (most likely that the Item number is invalid)
1 | Item has the focus
2 | Item is selected
8 | Item is highlighted for dropping
16 | Item is displayed in bold text
32 | Item is expanded
64 | Item is or has been expanded
4096 | Item is checked. See CheckBoxes


SetMethodInfo Method

SetMethodInfo Method 556
Applies To: OCXClass OLEClient

Description

This method is used to redefine the arguments or data types associated with a method that is exported by a COM object. SetMethodInfo is used to override the information provided by the object's Type Library.

The argument to SetMethodInfo is a 2 or 3-element array as follows:

[1] | Method name | character vector
[2] | Method info | nested vector (see below)
[3] | Method index | integer

If you wish to describe the method completely, the structure of Method info should be identical to the structure returned by GetMethodInfo, although abbreviated formats are also allowed.

If the object exports the method directly, and not through the standard IDispatch interface, you must also specify Method Index, which is the index of the method in the object's virtual table (vtable). This information may be available in printed documentation or in a C-language header file.

For example, the InchesToPoint method exported by Excel.Application takes a single argument whose name is Arg1 and whose data type is VT_R8. The function returns a result of the same data type. The details provided in the Excel.Application Type Library are in fact correct, but if you wanted to redefine them, the following statements could be used to describe the InchesToPoints method.

      'EX' ⎕WC 'OLEClient' 'Excel.Application' ('AutoBrowse' 0)

      methodinfo← ('' 'VT_R8')('Arg1' 'VT_R8')
      EX.SetMethodInfo 'InchesToPoints' methodinfo

Note that the structure of variable methodinfo is identical to the result of the GetMethodInfo method.

      DISPLAY methodinfo
.→-----------------------------------.
| .→------------. .→---------------. |
| | .⊖. .→----. | | .→---. .→----. | |
| | | | |VT_R8| | | |Arg1| |VT_R8| | |
| | '-' '-----' | | '----' '-----' | |
| '∊------------' '∊---------------' |
'∊-----------------------------------'

      DISPLAY EX.GetMethodInfo 'InchesToPoints'
.→-----------------------------------.
| .→------------. .→---------------. |
| | .⊖. .→----. | | .→---. .→----. | |
| | | | |VT_R8| | | |Arg1| |VT_R8| | |
| | '-' '-----' | | '----' '-----' | |
| '∊------------' '∊---------------' |
'∊-----------------------------------'

Unless you are going to call the method using the names of its arguments, these names are clearly superfluous and may be omitted, for example:

      methodinfo← 'VT_R8' 'VT_R8'
      EX.SetMethodInfo 'InchesToPoints' methodinfo


SetPropertyInfo Method

SetPropertyInfo Method 554
Applies To: OCXClass OLEClient

Description

This method is used to redefine a property that is exported by a COM object. SetPropertyInfo is used to override the information provided by the object's Type Library.

The argument to SetPropertyInfo is a 2 or 3-element array as follows:

[1] | Property name | character vector
[2] | Property info | nested vector
[3] | Property function | integer

For example, the Visible property exported by Excel.Application has the data type VT_BOOL and may be declared as follows:

      'EX' ⎕WC 'OLEClient' 'Excel.Application'
      EX.SetPropertyInfo 'Visible' 'VT_BOOL'

Property function may be required if the property value is retrieved or set via a function. This typically applies if the property takes parameters and will result in the property being fixed as a function rather than as a variable. Such properties may have a PropertyGet function, a PropertyPut function and/or a PropertyPutByReference function. If so, it is necessary to say to which of these three functions the details apply. The value of Property function is an integer 2 (PropertyGet), 4 (PropertyPut), or 8 (PropertyPutByReference).

For example, the following statement declares the PropertyGet function for the Item property of the Fields collection of the OLE object DAO.DBEngine. This property takes an index (into the collection) and returns an object.

      Fields.SetPropertyInfo 'Item'('VT_DISPATCH' 'VT_I4')2


SetVarInfo Method

SetVarInfo Method 546
Applies To: ActiveXControl OLEServer

Description

This method is used to describe an APL variable that is to be exported as a property of an ActiveXControl or OLEServer object.

The argument to SetVarInfo is a 2 or 3-element array as follows:

Variable info is either a simple character vector that specifies the COM data type of the variable, or a 2-element vector of character vectors whose first element specifies a help string and whose second element specifies the COM data type.

Help ID is an optional integer value that identifies the help context id within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.


Setup Method

Setup Method 101
Applies To: Printer

Description

This method causes the system to display a standard Printer Setup dialog box and thereby allows the user to alter the printer settings. This is a "modal" dialog box that must be closed before the APL application can continue.

The Setup method is niladic.

If you attach a callback function to this event and have it return a value of 0, the dialog box will not appear.


ShowBalloonTip Method

ShowBalloonTip Method 860
Applies To: SysTrayItem

Description

The ShowBalloonTip method displays a BalloonTip in a SysTrayItem object.

The argument to ShowBalloonTip is a 1, 2, 3 or 4-element array as follows:

[1] | Title | character vector
[2] | Text | character vector or matrix
[3] | Icon | Integer scalar, a character vector or a ref
[4] | Flags | Integer

The Title parameter is the text to be displayed in the BalloonTip title (maximum length 64).

The Text parameter is the text (maximum length 256) to be displayed in the BalloonTip. If omitted or empty, the BalloonTip is not displayed.

If the Icon parameter is an integer, it means:

0 | No icon
1 | Information icon
2 | Warning icon
3 | Error icon

Other values represent the name or a ref to an Icon object. If the Icon parameter is omitted, no icon is displayed in the BalloonTip.

If the Icon parameter specifies a large Icon object (32 x 32 bits) the Flags parameter must be 32. Otherwise this parameter is not used.

Windows XP

Under Windows XP, only small (16x16) icons are supported. Furthermore, the BalloonTip uses the icon associated with the SysTrayItem itself regardless of the custom icon specified by ShowBalloonTip. However, the following code provides a workaround, which is to switch the icon for the SysTrayItem itself to the desired icon temporarily, just for the invocation of the ShowBalloonTip method.

Example (XP)

     ∇ XPBalloonTip;tmpIcon;text;title
[1]    's'⎕WC'SysTrayItem' ⍝ default (APL) icon
[2]    'star'⎕WC'Icon'('Shell32.dll' ¯43)
[3]    tmpIcon←s.IconObj
[4]    s.IconObj←star
[5]    text←'Hello World'
[6]    title←'Custom BalloonTip icon under XP'
[7]    s.ShowBalloonTip title text star
[8]    s.IconObj←tmpIcon
     ∇


ShowHelp Method

ShowHelp Method 580
Applies To: OCXClass OLEClient

Description

This method is used to display the Windows help file for aCOM object or the help topic associated with one of its properties, events or methods.

The argument to ShowHelp is ⍬, or a single item as follows :

[1] Topic character vector.

Topic specifies the name of a property, event or method.

In the case of an OLE Control, the Obect name may be the name of the OCXClass or an instance of the OCXClass.


ShowItem Method

ShowItem Method 316
Applies To: TreeView

Description

This method is used to display a particular item in a TreeView object.

The argument to ShowItem is a single item as follows:

[1] Item number Integer.

Item number specifies the index of the item concerned.

In order to display the requested item, the parent item (if any) will be opened and the object will be scrolled if necessary.


ShowProperties Method

ShowProperties Method 560
Applies To: OCXClass

Description

This method is used to display the PropertySheet for an instance of an OLE Control. The user may then modify some or all of the properties of the control by changing values in the property sheet. This facility is intended to be used in the context of a GUI design tool but may also be useful in certain end-user applications.

The ShowProperties method is niladic.


ShowSIP Method

ShowSIP Method 25

Applies To

Description

ShowSIP applies only to PocketAPL.. In versions of Dyalog APL for other platforms, it has no effect.

This method displays and hides the Input Panel.

The argument to ShowSIP is 1 (display the Input Panel) or 0 (hide the Input Panel).

The argument to ShowSIP is 0 or 1 as follows :

[1] Mode Boolean
0 = hide the Input Panel.
1 = display the Input Panel

The result of ShowSIP is 1 if the Input Panel was previously displayed, or 0 if it was previously hidden.


TCPGetHostID Method

TCPGetHostID Method 376
Applies To: Root TCPSocket

Description

This method is used to obtain the IP Address of your PC.

The TCPGetHostID method is niladic.

The (shy) result is a character string containing your IP address. If you have more than one, it will return the first.

For example:

      TCPCetHostID
193.32.236.43


TCPSend Method

TCPSend Method 375
Applies To: TCPSocket

Description

This method is used to send data to a remote process connected to a TCPSocket object

The argument to TCPSend is a 1 or 3-element array as follows:

[1] | Data | the data to be sent
[2] | IP address | character vector
[3] | Port number | integer

If Style is 'Char', the data to be sent must be a character vector. If Style is 'Raw', the data to be sent must be an integer vector whose elements are in the range -128 to 255. If Style is 'APL', any array may be transmitted.

The optional IP address and Port number parameters specify the intended recipient of the message and apply only if the SocketType is 'UDP', in which case they are mandatory. If the SocketType is 'Stream', these parameters will be ignored and should be omitted.


TCPSendPicture Method

TCPSendPicture Method 380
Applies To: TCPSocket

Description

This method is used to transmit a picture represented by a Bitmap object to a TCP/IP socket. The picture may be transmitted in GIF or in PNG format.

The argument to TCPSendPicture is a 1 or 2-element array as follows:

[1] | Bitmap name | character vector
[2] | Picture format | character vector, 'GIF' or 'PNG'

If Picture format is omitted, the default is GIF format.

Note that the Style of the TCPSocket object must be set to 'Raw' before you execute the TCPSendPicture method.

The (shy) result of the method is an integer that reports the number of bytes that were transmitted.

Example:

      S1.TCPSendPicture 'BM' 'PNG'
4930

Note: Although PNG is recognised as the latest graphics standard for displaying pictures, not all Web browsers support it.

See also: MakeGIF, MakePNG


Undo Method

Undo Method 170
Applies To: Grid

Description

This method is used to undo the previous change in a Grid object.

The Grid object maintains a buffer of the most recent 8 changes made by the user since the Values property was last set by ⎕WC or ⎕WS.

Your application can restore these changes one by one by calling the Undo method on the Grid. The Undo method restores the most recent change made by the user and removes that change from the undo stack.

It is therefore not possible to "undo an undo".

The argument to Undo is ⍬, or a single item as follows :

[1] Number of changes integer

If called with an argument of ⍬, the default value for the Number of changes is 1. This restores the most recent change.


Wait Method

Wait Method 147

Applies To

Description

The Wait method is the same as executing ⎕DQ on the object.

The Wait method is niladic.

      'F'⎕WC'Form'
...
      Z←F.Wait


Version 13.2 Key Features

Key Features

Dyalog APL Version 13.2 provides the following new features, enhancements and changes:

General Enhancements and Improvements

  • Performance Improvements
  • Extensions to Selective Assignment
  • Extensions to 2000⌶ (Memory Manager Statistics)
  • ⎕FREAD has been extended to allow you to read a vector of components in a single atomic operation.

New GUI Features

  • New ButtonEdit Object. See ButtonEdit
  • New CommandLink and Split Button Styles. See New Button Styles
  • Cue Property for the Edit and ButtonEdit Objects
  • ShowBalloonTip Method for the SysTrayItem Object
  • HeaderImageList, HeaderImageIndex, ReportImageIndex, and ReportBCol Properties for the ListView Object. See ListView Enhancements
  • SelectionColor, SelectionColorAlpha, SelectionBorderWidth, RowHiddenDepth and HighLightHeaders Properties for the Grid Object
  • ButtonsAcceptFocus Property for the ToolControl Object
  • PageSize Property for the Form, SubForm and Scroll Objects and HThumbDrag and VThumbDrag Events for the Form and SubForm Objects
  • In previous Versions of Dyalog APL, a manifest file was required to enable Native Look and Feel. This is no longer needed. See Native Look and Feel
  • Under all supported versions of Windows except XP, the colours of Grid lines and row and column headers now respects the user's choice of theme if Native Look and Feel is enabled. See Change to Grid appearance (not XP)

Other

  • Version 13.2 Unicode Edition includes the Array Editor which allows you to edit arbitrary arrays, including nested arrays. In the Unicode Edition the [image] icon in the Session now invokes the Array Editor rather than the numeric editor which was provided in previous Versions. The Classic Edition continues to use the numeric editor. See Array Editor
  • Version 13.2 includes Conga 2.3 which provides support for Integrated Windows Authentication

Announcements

From Version 14.0 the following features will cease to be supported or will change:

  • Support for Version 12.1 and Version 13.0. See Support for Version 12.1 and 13.0
  • 32-bit component files. See Deprecation of 32-bit component files
  • Auxiliary Processors. See Auxiliary Processors
  • Default random number generator. See Random Number Generator


Version 13.2 System Requirements

System Requirements

Microsoft Windows

Dyalog APL Version 13.2 supports versions of Windows from Windows XP up to and including Windows 8 and Windows Server 2012.

Dyalog APL Version 13.2 is not supported for versions of Windows prior to Windows XP , such as Windows 2000, Windows 98, Windows 95, Windows ME and Windows NT4.

Microsoft .Net Interface

Dyalog APL Version 13.2 .Net Interface requires Version 2.x or greater of the Microsoft .Net Framework. It does not operate with .Net Version 1.0.

Unix and Linux

For AIX, Version 13.2 requires AIX6.1 or higher, and a POWER5 chip or higher.

Version 13.2 is built on RedHat5, and runs on all recent distributions, including Ubuntu 12.04 and openSUSE 12.2. Contact Dyalog for other platforms.


Array Editor

The Array EditorArray Editor Version 1 Release 1 © Copyright davidliebtag.com 2012, 2013 1 allows you to edit arbitrary arrays. It is invoked by either:

  • Clicking the [image] icon in the Session toolbar when the mouse pointer is over the name of a suitable variable.
  • Calling the User Command ]aedit, specifying the name of a suitable variable as its argument.
  • Calling it directly via ⎕NA

The Array Editor draws data using a format that is similar to the output of the DISPLAY function. For example:

Documentation

Full documentation for the Array Editor, including a list of the keystrokes it uses, is available from the Help menu in the Array Editor's window.

Supported Arrays

The Array Editor supports arrays that consist solely of characters and/or numbers. You may not use it to edit an array that contains an object reference or a ⎕OR.

Reject unsupported data

The way that the Arrays Editor reacts to unsupported arrays is determined by the value of the Reject unsupported data option which is accessed by the Options/Reject unsupported data menu item on the Array Editor menubar.

If this is set to true (the default), and you try to edit an array containing an object reference, the Array Editor will refuse the start and the system will generate an error message.

⎕SE.NumEd.numed: Unexpected error in array editor:
        DOMAIN ERROR  Argument contained data that is neither simple or nested.

If this option is cleared, the Array editor will start but you will not be able to do anything. It is therefore advisable that you leave this option set.

Notes

  • The Array Editor is supplied only with Unicode Editions of Dyalog APL/W. Please visit www.davidliebtag.com for details about availability and support for Classic Editions of Dyalog APL/W.
  • Namespaces are not supported.
  • Internal representations returned by ⎕OR are not supported.
  • Only one instance of the Array Editor may be executed at a time.
  • All calls to interpreter primitives use a value of 3 for ⎕ML.
  • Negative numbers must be represented using high minus signs. For example, ¯3 not -3.

Implementation

The Array Editor is implemented by a DLL named dlaedit.dll (32-bit) or dlaedit64.dll (64-bit).

The DLL exports two functions: DyalogEditArray and DyalogEditArrayTitle. The latter is used when you click the the [image] icon in the Session toolbar (via the APL function ⎕SE.NumEd.numed) and by the User Command ]aedit

Calling the Array Editor Directly

If you wish to use the Array Editor directly, you may do so as follows using ⎕NANote that these are not standard ⎕NA calls, but rather use an extension to ⎕NA, called Direct Workspace Access. Dyalog does not intend to make this feature generally available at present: if you are interested in this feature please contact sales@dyalog.com. 2.

For both DyalogEditArray and DyalogEditArrayTitle the first argument is the array to be edited, while the second argument is a place holder and should always be 0

For DyalogEditArrayTitle the 3rd argument is a character vector whose contents are displayed in the caption of the array editor window.

The result is the newly altered array.

Examples

⎕NA'dlaedit.dll|DyalogEditArray <pp >pp'              ⍝ 32-bit

⎕NA'dlaedit.dll|DyalogEditArrayTitle <pp >pp <0C2[]'  ⍝ 32-bit
⎕NA'dlaedit64.dll|DyalogEditArray <pp >pp'            ⍝ 64-bit
⎕NA'dlaedit64.dll|DyalogEditArrayTitle <pp >pp <0C2[]'⍝ 64-bit
New←DyalogEditArray Old 0
New←DyalogEditArrayTitle Old 0 Name


Performance Improvements

Reduction Operator

The performance of certain reductions on non-vector numeric arrays has been improved. +/, ×/, ⌈/, and ⌊/ on floating point numbers are faster by a factor of 6 while +⌿, ×⌿, ⌈⌿, and ⌊⌿ are faster by a factor of 2. In addition, ⌈/ and ⌊/ are faster by the same factors on other numeric types, and likewise ⌈⌿ and ⌊⌿.

Scan Operator

The time taken for ≤\, >\, ≥\, ⍱\, and ⍲\ has reduced from order n2 to order n, where n is the length of the argument.

Miscellaneous

The performance of the following expressions, which mostly involve operations on Boolean arrays, has been improved. The degree of performance improvement is indicated in the column labelled Factor.

The meaning of the symbols used in the expressions is as follows:

n | integer scalar
i | integer array
b | Boolean array
x | array
Expression | Factor | Comments
n|i | 19-34 | When n is a power of 2.
2⊥b | 17-21 |
⌽b and ⊖b | 2-93 |
(n⍴2)⊤i | 19-21 |
x[b;...;] | 2-17 |
⍳n | 1-2 |
⌽x | 4-230 |
?i⍴2 | 2-30 | when ⎕IO←0
b/⍳⍴b and b/⍳n | 3.5 |

Search and Replace

⎕R and ⎕S operate significantly faster than before for simple searches – essentially, those without regular expressions, function transformations, options other than Mode or nested input documents.

Pick in Selective Assignment

The performance Pick (⊃) in selective assignment expressions is substantially faster than before.

Stranding of Arrays

The performance of the stranding of named arrays, as in expressions such as:

       A B C D E F

has been improved. The time taken has been reduced from being an order of n2 to an order of n, where n is the number of names in the strand.

Account Name

The value of ⎕AN is now cached in the workspace rather than being obtained dynamically every time it is referenced. Since ⎕AN is used internally whenever a function is fixed applications which fix a very large number of functions will benefit from this caching.


Selective Specification

Selective Assignment

Selective Assignment has been extended so that:

The Each Operator may now be used in selection expressions.

The syntax of selective assignment expressions is extended from

(EXP X)←Y

to

(EXP X)[I]←Y ⍝ Case 1
(EXP X[I])←Y ⍝ Case 2

where:

  • EXP is a selection expression using primitive functions from the table Functions for Selective Assignment
  • X is the name of a variable
  • Y is an array of items that replace the selected items in X.
  • [I] is square-bracket (simple, choose, reach) indexing.

These enhancements bring Dyalog into line with mainframe IBM®APL2®.

For further details and examples, see Assignment (Selective):


Memory Manager Statistics

Function 2000⌶ (Memory Manager Statistics) has been extended to provide:

  1. The ability to determine an application's peak memory usage so that its minimum value for MAXWS can be determined.
  2. The ability to set an upper limit on the amount of workspace actually committed by the Operating System to prevent code which grabs as much workspace as it can from skewing the peak usage result.
  3. The ability to set a lower limit on the workspace allocation to avoid repeatedly committing and releasing memory to the Operating System when memory usage is fluctuating.

For further details and examples, see Memory Manager Statistics:


Enhancements for Icon and Bitmap Objects

Bitmap and Icon objects can now be created from files of type GIF, JPG and PNG in addition to the file types previously supported (BMP and ICO respectively). However, they may only be written (using the FileWrite method) to BMP and ICO files as before.

The size of the image displayed by an Icon object was previously determined by its Style property which was either 'Small' (16x16) or 'Large' (32x32). The image size is now overridden by the value of the Size property which may contain any appropriate value. Note that a ICO file can contain images of multiple sizes.

The Icon object now supports 32-bit icons (24-bit images with an 8-bit alpha channel) using the CBits property instead of the Bits, CMap and Mask properties. The Bitmap object also supports the same type of transparent images.

The Masked property of the ImageList object has been extended to support high-colour transparent images.


ListView Enhancements

The ListView object may now display icons against column titles and items in Report View.

In Report View, the HeaderImageList property identifies the ImageList object containing the icons, and the HeaderImageIndex property specifies which icons from this ImageList are to be displayed in which column headings.

In the example shown below, the ImageList identified by HeaderImageList contains 4 icons for the 4 different times of day shown in the column headings and HeaderImageIndex is ¯2 0 1 2 3 4. The value ¯2 specifies the standard sort down symbol.

In Report View, the ReportImageIndex property now overrides the ImageIndex property and additionally specifies which icons, from the ImageList specified by ImageListObj, are to be displayed against each item in the matrix specified by ReportInfo.

ReportImageIndex is a matrix whose first column specifies the indices of the icons to be displayed against the Items of the ListView, and whose subsequent columns specify the indices of the icons to be displayed against the elements of ReportInfo.

i.e. if non-scalar, (⍴ReportImageIndex)←→(0 1+⍴ReportInfo)

In the example shown below, the ImageList associated with ImageListObj contains icons for each country's flag, followed by icons for the different types of weather.

ReportImageIndex[;1] is ⍳⍴COUNTRIES

ReportImageIndex[;2] is 0

ReportImageIndex[3 4 5 6;] is a set of integers (>⍳⍴COUNTRIES) which index the weather icons

The ReportBCol property optionally specifies the background colours for each element in Report View. Its first column refers to the Items themselves, and subsequent columns to the elements of ReportInfo.

i.e. if non-scalar, (⍴ReportBCol)←→(0 1+⍴ReportInfo)


New Button Styles

There are two new Styles for the Button Object, namely 'CommandLink' and 'Split'. These apply only to Windows Vista and later and require Native Look and Feel. See Native Look and Feel. Otherwise the use of these Styles will produce a Button with Style 'Push'.

CommandLink Style

The CommandLink button has an icon displayed to the left of its Caption.

'F'⎕WC'Form' 'CommandLink Button'
 F.clb'⎕WC'Button' 'Visit Us'('Style' 'CommandLink')

In addition to the caption, additional text may be defined by its Note property. If provided, this is displayed below the Caption.

F.clb.Size←80 200
F.clb.Note←'www.dyalog.com'

The Elevated property is a Boolean scalar which when set to 1, changes the icon on the CommandLink button. This is intended to convey to the user that the action associated with the Button requires Elevation, a feature of User Account Control in Windows 7.

F.clb.Elevated←1

Split Style

The Split Button has a drop-down button, similar to that provided by a Combo object. The user can interact with the Button by clicking it, which generates a Select Event as before, or by clicking the drop-down.which generates a DropDown Event. It is up to the programmer to handle the DropDown Event as appropriate.

'F'⎕WC'Form' 'Split Button'
'F.sb'⎕WC'Button' 'Select File'('Style' 'Split')


Grid Appearance Change

Change to Grid appearance (not XP)

In order to make it more consistent with current Windows conventions, the default appearance of the Grid now respects the user's chosen theme when Native Look and Feel is enabled. In particular, the default colour of the grid lines and the shading of the row and column headings is determined by the user's theme.

This change applies to all supported Versions of Windows except Windows XP.

Windows 8 default theme, Native Look and Feel NOT enabled.

Windows 8 default Theme, Native Look and Feel enabled.

The change is more noticeable when a more colourful Theme is in use. The following pictures illustrate a Grid with and without Native Look and Feel when a Windows 8 High Contrast Theme is used.

Windows 8 High Contrast Theme, Native Look and Feel NOT enabled.

Windows 8 High Contrast Theme, Native Look and Feel enabled.

GridFCol, RowTitleFCol and ColTitleFCol

If Native Look and Feel is enabled, the values of the GridFCol, RowTitleFCol and ColTitleFCol properties are ignored in deference to the colours defined by the chosen theme. You may however override the theme derived colours of the grid lines using GridLineFCol.


Miscellaneous Enhancements

Dyalog APL Version 13.2 provides the following miscellaneous enhancements and changes:

⎕FLIB Limitation Removed

Component files that are exclusively tied were not previously reported by ⎕FLIB. In Version 13.2 they are included in the result.

APL_FHIST_TIE

From Version 13.2 onwards, support for the APL_FHIST_TIE parameter has been removed. Component file tie time is not recorded and ⎕FHIST always reports 0 for user ID and time in the 4th row of its result.

⎕PROFILE

⎕PROFILE'data' and ⎕PROFILE'tree' have been enhanced to take an optional left argument specifying which columns of data to return.

Workspace Save

0 ⎕SAVE wsid no longer fails with DOMAIN ERROR if there are threads running or Edit/Trace windows open. These restrictions continue to apply to monadic ⎕SAVE and )SAVE.

)SAVE and ⎕SAVE now insist that you explicitly specify a filename. Previously if you specified just the name of a directory, the workspace was saved with the name .DWS.

Keyboard Shortcuts

Windows allows users to control the visibility of keyboard shortcuts.

Under Windows XP this is done from the Display Properties dialog box. Select the Appearance tab, then click the Effects button. Then select or clear the option labelled Hide underlined letters for keyboard navigation until I press the Alt key.

In Windows 7, open Control Panel / Ease of Access Center / Make the Keyboard easier to use.The option is labelled Underline keyboard shortcuts and access keys

The Dyalog APL GUI now honours this option. This means that the underscores in the captions of certain objects, including Label, MenuItem and Button objects, may or may not be shown until the user presses the Alt key.

Note that the actual behaviour obtained by the option is controlled by Windows and not by Dyalog.

SessionOnTop Parameter

In Classic Dyalog mode, it is now possible to specify whether or not the Session window may appear on top of Edit and Trace windows. To enable this setting, check the option box as shown in the picture below.

Find Objects Tool

The Find Objects dialog box now saves all your option settings between invocations and between APL sessions.

MakeGIF and MakePNG Methods

In Version 13.2, these methods are implemented using GDI+. This means that MakeGIF now generates compressed GIF files. In previous versions it generated uncompressed GIFs.

Find/Replace Tool

In previous versions of Dyalog APL the Find/Replace window was dockable. However, the resulting Window was in general unusable, with many of the fields and buttons not visible. In Version 13.2 the Find/Replace window is no longer dockable.


Announcements

Support for Version 12.1 and 13.0

Version 12.1 and Version 13.0 will continue to be supported until Version 14.0 is released, at which point both these Versions will cease to be supported.

Deprecation of 32-bit component files

Since Version 10.1, Dyalog APL has supported large span (64-bit) component files, and since Version 12.0 ⎕FCREATE has created these by default. Existing small span (32-bit) component files are still supported and 32-bit component files may still be created if suitable options are specified, but they have restrictions which 64-bit files do not, including:

  • The maximum file size is 4GB.
  • The files are not fully architecture-independent meaning that there are limitations sharing them between, for example, Windows or Linux and AIX machines.
  • Components may not contain Unicode data.

As announced on the Release of Version 13.0, Dyalog intends to withdraw support for 32-bit component files in the next Release which will be Version 14.0.

If you have any existing 32-bit component files, or applications which create and/or use them, Dyalog recommends that you prepare for this in the following ways:

  • Ensure that Dyalog is not started with the command-line option -F32. This option sets the default component file type which is created to 32-bit.
  • Ensure that no ⎕FCREATE within your applications explicitly specifies that 32-bit files are to be created.
  • Make plans to convert any existing 32-bit component files to 64-bit using ⎕FCOPY. ⎕FCOPYwill create a 64-bit copy even if the file being copied is 32-bit. You may use the new user command ]Fto64 to locate existing small span files and convert them to the 64-bit architecture. Ths user command is included with Version 13.2, and can be downloaded for earlier versions as well (users of Version 13.1 can use the]UUPDATE command to download updated user commands).

Note: in order to allow the use of legacy files retrieved from backups etc., Dyalog will continue to provide read-only support for 32-bit files in Version 14.0, and in subsequent releases for a minimum of 10 years.

Auxiliary Processors

It is intended that in the next major release, Version 14.0, all Dyalog-supplied Auxiliary Processors, namely qfsck, strand and xutils will be removed from the product, although the interfaces for user-written Auxiliary Processors will continue to be supported. Instead Dyalog will supply equivalent DLLs/shared libararies (operating system dependent).

Random Number Generator

The Version 13.0 random number generator, that is used by Roll and Deal, is based upon the Lehmer linear congruential generator. This has several limitations, most notably that it has a limited value range of (2*31). Mindful of the need to support applications that rely on the current mechanism, and the ability to generate specific repeatable random series using ⎕RL, Dyalog provided two additional random number generators in Version 13.1. Both the new algorithms support 64-bit values and both may be considered to be an improvement (in terms of randomness) over the existing mechanism. The new mechanisms were:

  • Mersenne Twister random number generator. This algorithm produces 64-bit values with good distribution.
  • Operating System random number generator. Under Windows APL this uses the CryptGenRandom() function. Under Unix/Linux it uses /dev/urandom[3].

You may select the random number generator in use using 16807⌶. This allows you to switch dynamically between the different algorithms if required.

In Versions 13.1 and 13.2 the default random number generator in a CLEAR WS is 0 (Lehmer linear congruential). The default will be changed to 1 (Mersenne Twister) in the next release of Dyalog APL (Version 14.0). In preparation for this change, avoid writing code which assumes that ⎕RL will be a scalar integer.

Note: the change to the default will only impact applications if they are rebuilt from a clear workspace; saved workspaces will be unaffected.


Native Look and Feel

Windows Native Look and Feel is an optional feature of Windows from Windows XP onwards.

If Native Look and Feel is enabled, user-interface controls such as Buttons take on a different appearance and certain controls (such as the ListView) provide enhanced features.

The following pictures illustrate the appearance of a simple Button created with and without Native Look and Feel under Windows XP and Windows 7.

Dyalog Session

During development, both the Dyalog Session and the Dyalog APL GUI will display native style buttons, combo boxes, and other GUI components if Native Look and Feel is enabled. The option is provided in the General tab of the Configuration dialog.

Applications

There are two ways to enable Native Look and Feel in end-user applications.

If you use the File/Export… menu item on the Session MenuBar to create a bound executable, an OLE Server (in-process or out-of-process), an ActiveX Control or a .Net Assembly, check the option box labelled Enable Native Look and Feel in the create bound file dialog box. See User Guide.

If not, set the XPLookandFeel parameter to 1, when you run the program. For example:

dyalogrt.exe XPLookAndFeel=1 myws.dws

Note that to have effect, Native Look and Feel must also be enabled at the Windows level.


Documentation

New Documentation

Previously, Dyalog maintained all product documentation in various different formats, including Microsoft Word and HTML, depending upon the target publication media. The duplication of source material lead to inconsistencies in the different forms of publication.

Dyalog has now invested in a single-source solution for the documentation and has converted the bulk of the existing documentation to the new platform from which the Version 13.1 documentation has been produced.

The new platform will enable Dyalog to improve the quality of the documentation and the range of formats in which it can be published. It will also allow the documentation to be more easily maintained and to be updated in a more timely fashion.

Due to the nature of the conversion process, there are currently a number of typographical errors, particularly formatting errors, which Dyalog is still working to correct. For this reason, the Version 13.1 manuals may not yet be ordered in perfect bound printed form from Lulu.


Version 13.1 Key Features

Key Features

Dyalog APL Version 13.1 provides the following enhancements and changes:

Enhancements

  • New system function ⎕FHIST
  • New system constant ⎕DMX
  • New Random Number Generators
  • Performance Improvements

Other Changes

  • New defaults for component file properties
  • Large Component Support
  • Compatibility checking
  • PrintList property
  • New parameter to control numeric appearance
  • Miscellaneous


File History

New System Function ⎕FHIST

The new File History system function provides information about certain file events. This includes information about which user created the file and when, which user last tied the file and when, and which user updated the file and when.

This feature has been added to support users migrating from the SHAREFILE/AP system.

For details, see ⎕FHIST.


Extended Diagnostic Message

Extended Diagnostic Message: R←⎕DMX

Version 13.1 adds significant new error reporting functionality, in the form of a system variable which has been named ⎕DMX. ⎕DMX is designed to make error handling simpler, more complete and more accurate.

  • More Information: ⎕DMX is a namespace with a number of properties, which provide much more information about errors than did the old variables (in version 13.1, only a few primitives and system functions take advantage of this; full support will evolve over the next several releases). Application code can also provide more error information, as ⎕SIGNAL has been extended accordingly.
  • Thread Safe: ⎕DMX is local to each APL thread: An error occurring in one thread will not change the value of ⎕DMX in other threads. This is not the case for ⎕DM and ⎕EN.
  • Isolation of Handled Errors: ⎕DMX is local to the code which is invoked to handle an error, in such a way that successfully handled (trapped) errors will leave no trace of the handled event.
  • Backwards compatibility: The behavior of the existing variables ⎕DM (Diagnostic Message) and ⎕EN (Event Number) is unchanged. Dyalog recommends that applications which reference the old variables be modified to use ⎕DMX, as soon as this is convenient

More Information

The default output following an error has been changed in Version 13.1, to display most of this information. For example:

      'c:\no\such\folder\output.txt' ⎕FCREATE 0
FILE NAME ERROR: Unable to create file ("The system cannot find the path specified.")
      'c:\no\such\folder\output.txt'⎕FCREATE 0
     ∧

In addition to the FILE NAME ERROR which would also have been displayed by earlier versions, Version 13.1 displays the text Unable to create file, which is a more detailed message originating in the file system, and in parentheses (The system cannot find the file specified.), which is a message originating in the underlying operating system.

The menu item Options|Configure|Help / DMX (See User Guide) allows you to decide whether this additional information should be displayed in the session (as above), and/or in the status window. Note that ⎕DM is not affected by these settings; it only contains the original APL error message as in previous releases:

      ↑⎕DM
FILE NAME ERROR
      'c:\no\such\folder\output.txt'⎕FCREATE 0
     ∧

Thread safe copies of the values of ⎕EN and ⎕DM are available as the properties ⎕DMX.EN and ⎕DMX.DM.

A number of properties within the ⎕DMX space can be inspected, to extract the additional information. The detailed message is in a property called Message:

      ⎕DMX.Message
Unable to create file

The new messages also have “extended error numbers”, which are unique within each category of errors:

      ⎕DMX.(ENX Category Vendor)
10  Component file system  Dyalog

At present, Vendor will always contain the character vector 'Dyalog', but it is envisaged that external components will eventually be able to make use of this mechanism. Finally, if the error was a direct result of a problem reported by the operating system, the OSError property will be populated with this information:

      ⎕DMX.OSError
1 3  The system cannot find the path specified.

Currently the first item is either 0 or 1:

  • 0 means that the error number is the value of errno(),
  • 1 means that the error number is the result of GetLastError().

The second contains the error number and the third element is the corresponding text.

Finally, the InternalLocation property identifies the line of the interpreter source code that issued the error, which may be useful for the Dyalog support team when analyzing particularly tricky errors:

      ⎕DMX.InternalLocation
 qfile1.c  3614

Thread Safe

The old system variables ⎕EN and ⎕DM have workspace scope, which means that they are shared by all threads. This means that, if two (or more) threads encounter errors in rapid succession, error handling code which references these variables might pick up values which are unrelated to the error being handled. ⎕DMX, on the other hand, has thread scope: Each thread has its own copy of the variable. As server applications become more common, it is rapidly becoming more important to write code which is “thread safe”. Dyalog strongly recommends that all references to ⎕EN and ⎕DM in current application code be replaced by references to ⎕DMX.EN and ⎕DMX.DM, respectively.

Isolation of Handled Errors

In version 13.1, ⎕DMX cannot be explicitly localised in the header of a function. However, for all trapped errors, the interpreter creates an environment which effectively makes the current instance of ⎕DMX local to, and available only for the duration of, the trap-handling code.

In particular ⎕DMX is localised within:

  • Any function which explicitly localises ⎕TRAP
  • The :Case[List] or :Else clause of a :Trap control structure.
  • The right hand side of a D-function Error-Guard.

This localisation uses the standard shadow/un-shadow mechanism, so that an existing value of ⎕DMX will be hidden on entry to the trap-handling code (or localisation of ⎕TRAP) and restored afterwards. The benefit of the localization strategy is that code which uses error trapping as a standard operating procedure (such as a file utility which traps FILE NAME ERROR and creates missing files when required) will not pollute the environment with irrelevant error information.

In particular, it becomes easier to implement tools to handle errors by logging them or displaying additional information to end users, without worrying that trapped errors within the tool code will interfere with current state of the application.

Examples

The effect of automatic localisation of ⎕DMX is illustrated by the following examples. In each case, assume the existence of a "Global" value of ⎕DMX, whose EN field is 0, following a )RESET.

Example[1] :Trap control structure:

      ⎕DMX.EN=0       ⍝ Global ⎕DMX visible here
     :Trap 11         ⍝ Catch error 11
         ⎕DMX.EN=0    ⍝ Global ⎕DMX visible here
         ÷0           ⍝ Generate error 11
     :Else            ⍝ Error-handling code:
         ⎕DMX.EN=11   ⍝ Local ⎕DMX for ÷0 error visible here
     :EndTrap         ⍝ ⎕DMX unshadowed after Else-clause
     ⎕DMX.EN=0        ⍝ Global ⎕DMX visible here

Example[2] ⎕TRAP system variable:

    ∇ foo;⎕TRAP
[1]  ⍝ ⎕DMX is shadowed and un-shadowed @ the same time as ⎕TRAP
[2]  ⍝ The local value of ⎕DMX is initialised to a copy of the
[3]  ⍝ calling function's value ("pass-through localisation").
[4]  ⍝ This local value will be changed if an error occurs. On
[5]  ⍝ exit from the function, the calling environment's value
[6]  ⍝ will be restored (along with that of ⎕TRAP) as normal.
[7]   ⎕DMX.EN=0           ⍝ passed-through from calling env
[8]   ⎕TRAP←0 'c' '→next' ⍝ sets trap; does not change or
[9]                       ⍝ localise ⎕DMX
[10]  ⎕DMX.EN=0           ⍝ passed-through from calling env
[11]  ⍎'÷0'               ⍝ updates local ⎕DMX; jumps to next:
[12] next: ⎕DMX.EN=11	   ⍝ Error number has been set to 11
[13]  ⎕TRAP←0 'c' '→end'  ⍝ sets trap; does not change or
[14]                      ⍝ localise  ⎕DMX
[15]  ⎕DMX.EN=11          ⍝ Error number is 11, as before
[16] end:                 ⍝ on return, calling envt's ⎕DMX.EN
[17]                      ⍝ will be 0
     ∇

Example[3] Dfn Error-guard:

      ⎕←⎕DMX.EN=0          ⍝ Global ⎕DMX visible here
      {
          ⎕←⎕DMX.EN=0      ⍝ Global ⎕DMX visible here
          11               ⍝ trap DOMAIN
      }⍬::{                ⍝ Error :: Guard
          ⎕←⎕DMX.EN=11     ⍝ Local ⎕DMX for ÷0 error visible here
      }⍵
      ⎕←⎕DMX.EN=0          ⍝ Global ⎕DMX visible here
      ÷0                   ⍝ Generate error 11

Example[4] Nested localisation of ⎕DMX

     ⎕DMX.EN=0             ⍝ Global ⎕DMX
     :Trap 11              ⍝ Trap DOMAIN ERROR
         :Trap 5           ⍝ Trap LENGTH ERROR
             2 3+4 5 6     ⍝ Generate LENGTH ERROR
         :Else             ⍝ ⎕DMX localised for following clause:
             ⎕DMX.EN=5     ⍝ EN set to LENGTH in local ⎕DMX
             ÷0            ⍝ Generate DOMAIN ERROR
         :End              ⍝
     :Else                 ⍝ ⎕DMX localised for following line
         ⎕DMX.EN=11        ⍝ EN set to DOMAIN in local ⎕DMX
     :End                  ⍝ ⎕DMX un-shadowed here
     ⎕DMX.EN=0             ⍝ Global ⎕DMX restored.

Clarification

Whenever ⎕TRAP is localised explicitly, ⎕DMX will be localised at the same time. This means only that any subsequent changes to ⎕DMX will be reverted as ⎕TRAP is unshadowed. In particular, the assignment of ⎕TRAP has no effect on ⎕DMX; only its localisation. Explicit localisation means the appearance in the header of a trad-fn or as the argument of ⎕SHADOW. It does not include the implicit localisation, which takes place at :Trap or dfn error-guard setting time. The examples above illustrate these cases.

The timing of the setting of the values within the ⎕DMX mechanism is important:

  1. When an error occurs, the values and properties needed to populate ⎕DMX are collected
  2. If a trap is in effect, the stack is cut back appropriately.
  3. Within the error-handling code, ⎕DMX is populated with the values collected in step 1.

This means that lexically and dynamically nested error handling code will behave "as expected". See example[4] above.

For further details, see ⎕DMX


New Random Number Generators

The Version 13.0 random number generator, that is used by Roll and Deal, is based upon the Lehmer linear congruential generator. This has several limitations, most notably that it has a limited value range of (2*31). Mindful of the need to support applications that rely on the current mechanism, and the ability to generate specific repeatable random series using ⎕RL, Dyalog has decided to provide two additional random number generators in Version 13.1. Both the new algorithms support 64-bit values and both may be considered to be an improvement (in terms of randomness) over the current mechanism. The new mechanisms are:

  • Mersenne Twister random number generator. This algorithm produces 64-bit values with good distribution.
  • Operating System random number generator. Under Windows APL this uses the CryptGenRandom() function. Under Unix/Linux it uses /dev/urandom[3].

You may select the random number generator in use using 16807⌶. This allows you to switch dynamically between the different algorithms if required.

For further information, see Random Number Generator.


Performance Improvements

Empty-Line Processing

The interpreter now requires less time to process empty lines in functions, i.e. those that contain only comments or have no content at all. Functions documented with a block of leading comment lines, in particular, will benefit from this optimisation.

This improvement is also implemented in Version 13.0 from 3rd January 2012 onwards.

Dyadic Iota

The code for dyadic iota (Index Of) has been optimised, giving a small performance improvement in most cases. This improvement is independent of the use of retained hash tables, which delivers additional performance benefits as before.

This improvement is also implemented in Version 13.0 from 3rd January 2012 onwards.

For further information see Search Functions and Hash Tables.

New Idioms

Two new idioms have been added. These are:

0=⊃⍴ | Is first dimension empty (⎕ML<2)
0≠⊃⍴ | Is first dimension not empty (⎕ML<2)

Note that these idioms were also added to Version 13.0 from 22nd December 2011 onwards.

Take

The performance of an expression such as (N↑1) has been improved significantly in Version 13.1 compared to previous versions.


Component File Changes

New Defaults for File Properties

When you create a new component file, the default levels of checksum and journaling are now both 1. These defaults may be changed using the APL_FCREATE_PROPS_J and APL_FCREATE_PROPS_C parameters (see User Guide).

The new default will cause the creation of component files which are significantly more robust in the face of network and other system failures, and often more repairable using ⎕FCHK. However, depending upon the way in which the application uses component files, there may be a noticeable reduction in system performance. Dyalog recommends the use of the new settings, however it is possible to configure the system to use a different default if necessary.

For further information, see ⎕FPROPS

Support for Larger Components

In Version 13.1, the maximum size of a component on a component file is 264 bytes. Previously it was 232 bytes.

Note: All builds of Version 12.0, 12.1 and 13.0 created after 24th November 2010 will refuse to read components greater than 232 bytes in size. Builds prior to this date will not handle large components correctly.


Compatibility Checking

The mechanism used to avoid backwards compatibilty issues has been improved. Prior to this change, it would have been possible for an older version of Dyalog APL to attempt to fix the ⎕OR of a function from a later version that contained a "new" system function or idiom. This would typically cause a system error at that point, or worse still, some time later in the application.

The new mechanism, which has been implemented in Version 13.1, prevents this happening by changing the internal format of a ⎕OR so that it is unrecognisable by older Versions.

This means that henceforth if you attempt to access an incompatible ⎕OR the operation will fail with a DOMAIN ERROR, rather than potentially cause a system error. (Note that builds of Version 12.1 dated before November 11th 2011 report FILE COMPONENT DAMAGED instead of DOMAIN ERROR).


Change to PrintList Property

Change to PrintList

The mechanism used to generate the contents of the PrintList property has been updated to better support network printers and the current versions of Windows. The new mechanism uses a different set of Windows API calls. This means that in Version 13.1, the list is likely to include printers which were not included in previous versions and the names of the printers reported may be slightly different.

For further information, see PrintList.


APL_CODE_E_MAGNITUDE Parameter

Version 13.0 introduced decimal floating point numbers which have greater precision than IEEE floating point numbers. This increased the maximum allowable print precision from 17 to 34 and this had the side effect of changing the way numbers in function bodies are descannedDescanning refers to the internal process used to convert the internal representation of APL code into a character array. For numbers in function statements, this process uses the maximum value of Print Precision. 1. For example, the number one sextillion (1021) in a function is descanned by Version 12.1 as 1E21 and by Version 13.0 as 1000000000000000000000.

Note that only numbers X in the range (10*17) ≤ X <(10*34) are affected.

Whilst this change has no other deleterious effect, it means that code that contains such numbers is harder to read, and the result of ⎕CR (and other character representations) of the same function may have changed between Version 12.1 and Version 13.0 causing undesired affects in code management systems.

The APL_CODE_E_MAGNITUDE parameter allows the user to choose between current (Version 13.0 and onwards) and earlier behaviour.

If the APL_CODE_E_MAGNITUDE parameter is undefined or set to 0 (the default), numbers are descanned and displayed as normal.

If APL_CODE_E_MAGNITUDE is ¯1, numbers greater than or equal to 1017 will be displayed using exponential format, as in Version 12.1.

The effect of setting this parameter to any other value is undefined.


Miscellaneous

Component Checksum Validation

There is a new function 3002⌶ which controls whether or not components read by ⎕FREAD are subject to checksum validation.

For further information, see.Component Checksum Validation .

Core to APLCore

There is a new function 685⌶ that extracts an aplcore file from a UNIX core file.

For further information see Core to APLCore.

Windows: Associating workspaces etc. with specific Version

Under Windows, when Dyalog APL is installed, all Dyalog-specific files are associated with that version. A new User Command, ]EFA, has been included which allows the user to select which of the versions of Dyalog APL installed on the PC should be associated with Dyalog files. See the SALT-UCMD release notes for more details.

GetAvailableWorkspace

This undocumented method of Root has been removed. It is superceded by 2000⌶.

For further information see Memory Management Statistics.

Change to :Hold

If APL detects a deadlock situation, it now executes the :Else clause in preference to generating an error.

For further information, see Hold Statement.

COM Interface Changes

In Version 13.0 and earlier the Dyalog APL COM (OLE) interface converted incoming values of type VT_CY (a 64 bit value, sometimes referred to as VT_CURRENCY) to a two element vector containing the high 32 bits of the value and the low 32 bits of the value.

As Version 13.1 supports the DECF element type the OLE interface now converts incoming VT_CY values to DECFs, which means the value can be stored as a single scalar numeric value.

In Version 13.0 and earlier, VT_DECIMAL types were converted to 8 byte floating point values, which could have resulted in a loss of precision. Version 13.1 converts VT_DECIMALS to DECFs, which will not result in a loss of precision.

Note that ⎕FR should be set appropriately if arithmetic is to be performed on the resultant arrays.

Component Numbers

Previously, the component number passed as an argument to a component file function was not properly validated, and was simply rounded downto an integer. In Version 13.1 the component number must be an integer, or the function will report DOMAIN ERROR.

Enlist and Selective Assignment

Enlist (∊ with ⎕ML>0) may be used in selective assignment expressions.

Example:

      ⎕ml←1
      names←'Andy' 'Karen' 'Liam'
      (('a'=∊names)/∊names)←'*'
      names
 Andy  K*ren  Li*m

URL Strings

In Windows versions valid URLs are identified when in the session or in the editor/tracer. When the mouse pointer is over a URL, the URL is underscored and the following items appear in the context menu:

  • Open link: this causes the URL to be opened in the default application appropriate for the URL. Ctrl+Left Mouse performs the same operation
  • Copy link to clipboard: this causes the URL to be copied to the clipboard

This feature can be enabled or disabled by selecting or unselecting the Underline URLs and links checkbox on the General tab in the Configure box. This is saved as the registry entry URLHighlight.

Issue 8146: (⍬⌷mat)←0 should not change the shape of mat

In Version 13.0

      mat←2 3⍴⍳6
      (⍬⌷mat)←0

resulted in

      mat
0
      ⍴mat

This is incorrect. In Version 13.1 this had been corrected so that

      mat
0 0 0
0 0 0

Dyalog Script Compiler

The default value of ⎕WX for the script compiler is now 3. If you require a different value for ⎕WX you can specify it on the command line using the /wx option, or assign it in your script. See the DotNet Interface Guide.

Change to path with ⎕USING and :Using

In previous versions if a .Net Assembly was referred to without a path, it would only be loaded if it was located in the .Net installation directory. With 13.1 Dyalog APL will first look in the directory in which the Dyalog program (or host application) is located, and then the .Net installation directory.

Support for changing between .Net versions

Dyalog APL has improved support for changing between .Net versions; see the .Net Framework Tab in the User Guide for more information.

Clipboard Format support

Dyalog APL now includes support (currently inbound only) for XMLSpreadSheet format.

2-digit years and yy_window

Dyalog APL now adheres to the 2-digit year rules which appear in the Windows Region and Language settings. These can be overridden using the yy_window parameter.

Enhancement to ⎕MONITOR

⎕MONITOR has been enhanced so that it now correctly allocates time to diamondised lines where the line start with :Case and similar constructs.


Interoperability and Compatibility

Interoperability

Introduction

Workspaces and component files are stored on disk in a binary format (illegible to text editors). This format differs between machine architectures and among versions of Dyalog. For example a file component written by a PC may well have an internal format that is different from one written by a UNIX machine. Similarly, a workspace saved from Dyalog Version 13.1 will differ internally from one saved by a previous version of Dyalog APL.

It is convenient for versions of Dyalog APL running on different platforms to be able to interoperate by sharing workspaces and component files. From Version 11.0, component files and workspaces can generally be shared between Dyalog interpreters running on different platforms. However, this is not always possible, for example:

  • Component files created by Version 10.1 can often not be shared across platforms, even when used by later versions.
  • Small-span (32-bit) component files become read-only when opened on a different architecture from that on which they were created.

Note however that the system function ⎕FCOPY can be used to make a logically identical copy of an old file, which is fully inter-operable.

The following sections describe other limitations in inter-operability:

Code

Code which is saved in workspaces, or embedded within ⎕ORs stored in component files, can generally only be read by the version which saved them and later versions of the interpreter. In the case of workspaces, a load (or copy) into an older version would fail with the message:

this WS requires a later version of the interpreter.

Every time a ⎕OR object is read by a Version later than that which created it, time may be spent in converting the internal representation into the latest form. Dyalog recommends that ⎕OR should not be used as a mechanism for sharing code or objects between different versions of APL

"Ordinary" Arrays

With the exception of the Unicode restrictions described in the following paragraphs, Dyalog APL provides inter-operability for arrays which only contain (nested) character and numeric data. Such arrays can be stored in component files - or transmitted using TCPSocket objects and Conga connections, and shared between all versions and across all platforms.

As mentioned in the introduction, full cross-platform interoperability of component files is only available for large-span component files (see the following section), and for small-span component files created by Version 11.0 or later.

32 vs. 64-bit Component Files

Large-span (64-bit-addressing) component files are inaccessible to versions of the interpreter that pre-dated their introduction (versions earlier than 10.1).

The second item in the right argument of ⎕FCREATE determines the addressing type of the file.

      'small'⎕fcreate 1 32 ⍝ create small-span file.
      'large'⎕fcreate 1 64 ⍝ create large-span file.

If the second item is missing, the file type defaults to 64-bit-addressing. In versions prior to 12.0, the default was 32-bit-addressing.

Note that small-span (32-bit-addressing) component files cannot contain Unicode data. Unicode editions of Dyalog APL can only write character data which would be readable by a Classic edition (consisting of elements of ⎕AV).

External Variables

External variables are implemented as small-span (32-bit-addressing) component files, and subject to the same restrictions as these files. External variables are unlikely to be developed further; Dyalog recommends that applications which use them should switch to using mapped files or traditional component files. Please contact Dyalog if you need further advice on this topic.

32 vs. 64-bit Interpreters

From Dyalog APL Version 11.0 onwards, there are two separate versions of programs for 32-bit and 64-bit machine architectures (the 32-bit versions will also run on 64-bit machines running 64-bit operating systems). There is complete inter-operability between 32- and 64-bit interpreters, except that 32-bit interpreters are unable to work with arrays or workspaces greater than 2GB in size.

Unicode vs. Classic Editions

From Version 12.0 onwards, a Unicode edition is available, which is able to work with the entire Unicode character set. Classic editions (a term which includes versions prior to 12.0) are limited to the 256 characters defined in the atomic vector, ⎕AV).

Component files have a Unicode property. When this is enabled, all characters will be written as Unicode data to the file. The Unicode property is always off for small-span (32-bit addressing) files, which may not contain Unicode data. For large-span (64-bit addressing) component files, the Unicode property is on by default but can be toggled on and off using ⎕FPROPS.

When a Unicode edition writes to a component file which may not contain Unicode data, character data is mapped using ⎕AVU, and can therefore be read without problems by Classic editions.

A TRANSLATION ERROR will occur if a Unicode edition writes to a non-Unicode component (that is either a 32-bit file, or a 64-bit file when the Unicode property is currently off) if the data being written contains characters which are not in ⎕AVU.

Likewise, a Classic edition (Version 12.0 or later) will issue a TRANSLATION ERROR if it attempts to read a component containing Unicode data not in ⎕AVU from a component file. Version 11.0 cannot read components containing Unicode data and issues a NONCE ERROR.

A TRANSLATION ERROR will also be issued when a Classic edition )LOADs or )COPYs a workspace containing Unicode data which cannot be mapped to ⎕AV using the ⎕AVU in the recipient workspace.

TCPSocket objects have an APL property which corresponds to the Unicode property of a file, if this is set to Classic (the default) the data in the socket will be restricted to ⎕AV, if Unicode it will contain Unicode character data. As a result, TRANSLATION ERRORs can occur on transmission or reception in the same way as when updating or reading a file component.

AVU changes

The implementation of the function Right in Version 13.0 led to the discovery that ⎕AVU incorrectly defined ⎕AV[59+⎕IO] as ¤ (⎕UCS 164) rather than ⊢ (Right Tack, ⎕UCS 8866). This error has been corrected in the default ⎕AVU and in workspace AVU.dws. If you are operating in a mixed Unicode/Classic environment, this error will have caused earlier Classic editions to map ⎕AV[59+⎕IO] to the wrong Unicode character (¤). This may cause TRANSLATION ERRORs when a Version 13.0 Classic system attempts to read the data, as it will not be able to represent ¤ in the Atomic Vector.

DECFs and Complex numbers

Version 13.0 introduced two new data types; DECFs and Complex numbers. Attempts to read components of these types in earlier interpreters will result in a DOMAIN ERROR.

Very large array components

The maximum size (in bytes) of a component written by Version 12.1 and prior is 2GB. This is the size of the component as held on disk which may be different than the size reported by ⎕SIZE. In Version 13.0 the maximum size of a component written by a 64-bit interpreter is 4GB. From Version 13.1 onwards, the limit on the size of arrays or components is so large that for most practical purposes, there is effectively no limit.

An attempt to read a component greater than 2GB in 32-bit interpreters will result in a WS FULL. An attempt to read such a component in 64-bit Versions 12.0 and 12.1 patched after 1st April 2011 will result in a NONCE ERROR; earlier patches generate a FILE COMPONENT DAMAGED error.

File Journaling

Version 12.0 introduced File Journaling (level 1), and 12.1 added journaling levels 2 and 3 and checksumming. Versions earlier than 12.0 cannot tie files which have any form of journaling or checksumming enabled. Version 12.0 cannot tie files with journaling levels greater than 1, or checksumming enabled. Attempting to tie such files will result in a FILE NAME ERROR. Files can be shared with earlier versions by using ⎕FPROPS to amend the journaling and checksumming levels.

TCPSockets

TCPSockets used to communicate between differing versions of Dyalog APL are subject to similar limitations to those described above for component files. In particular TCPSockets with 'Style' 'APL' will only be able to pass arrays that are supported by both versions.

Auxiliary Processors

A Dyalog APL process is restricted to starting an AP of exactly the same architecture. In other words, the AP must share the same word-width and byte-ordering as its interpreter process.

Session Files

Session (.dse) files may only be used on the platform on which they were created and saved.


Version 13.0 Key Features

Key Features

Dyalog APL Version 13.0 provides the following new features and enhancements:

Major New Features

  • Support for Complex Numbers
  • Support for 128-bit Decimal Floating-Point Numbers
  • New regular expression operators
  • New Input Method Editor (IME)

Language Improvements

  • New primitive functions ⊣ (left tack) and ⊢ (right tack).
  • Short left arguments for Take (↑), Drop (↓) and Index (⌷)
  • New system function ⎕RSI.

Performance improvements.

  • New system function ⎕PROFILE for profiling applications
  • New Idioms
  • Retained hash table for Grade
  • Speedy interface for the ADO.Net DataTable object.

Miscellaneous

  • Implementation changes to Format ⍕and ⎕FMT.
  • Change to the result of ⍳⍬.
  • OLE Interface changes for default indexers.
  • INTERNAL ERROR (99)
  • New parameters to control the defaults for component file checksum and journaling, and the accidental input of complex constants.
  • Advance notice of the withdrawal of support for 32-bit Component Files.
  • New I-beam functions for certain system operations under UNIX.


Version 13.0 System Requirements

System Requirements

Microsoft Windows

Dyalog APL Version 13.0 supports all current versions of Windows from Windows 2000 up to and including Windows 7 and Windows Server 2008.

Dyalog APL Version 13.0 is not supported for versions of Windows prior to Windows 2000, such as Windows 95, Windows 98, Windows ME and Windows NT4.

Microsoft .Net Interface

Dyalog APL Version 13.0 ,Net Interface requires Version 2.x or greater of the Microsoft .Net Framework. It does not operate with .Net Version 1.0.

Unix and Linux

For an up-to-date list of supported Unix and Linux platforms, please contact support@dyalog.com.


Interoperability and Compatibility

Interoperability

Introduction

Workspaces and component files are stored on disk in a binary format (illegible to text editors). This format differs between machine architectures and among versions of Dyalog. For example a file component written by a PC may well have an internal format that is different from one written by a UNIX machine. Similarly, a workspace saved from Dyalog Version 13.1 will differ internally from one saved by a previous version of Dyalog APL.

It is convenient for versions of Dyalog APL running on different platforms to be able to interoperate by sharing workspaces and component files. From Version 11.0, component files and workspaces can generally be shared between Dyalog interpreters running on different platforms. However, this is not always possible. For example, component files created by Version 10.1 can often not be shared across platforms, even when used by later versions (the system function ⎕FCOPY can be used to make a logically identical copy of an old file, which is fully inter-operable).

The following sections describe other limitations in inter-operability:

Code

Code which is saved in workspaces, or embedded within ⎕ORs stored in component files, can generally only be read by the version which saved them and later versions of the interpreter. In the case of workspaces, a load (or copy) from an older version would fail with the message:

this WS requires a later version of the interpreter.

In the case of ⎕OR, unpredictable behaviour may result if an older version reads a ⎕OR saved by a later version of the system. In addition each time that a ⎕OR object is read into a later interpreter time will be spent in converting the internal representation into the latest form. Dyalog recommends that ⎕OR should not be used as a mechanism for sharing code or objects between different versions of APL

"Ordinary" Arrays

With the exception of the Unicode restrictions described in the following paragraphs, Dyalog APL provides inter-operability for arrays which only contain (nested) character and numeric data. Such arrays can be stored in component files - or transmitted using TCPSocket objects and Conga connections, and shared between all versions and across all platforms.

As mentioned in the introduction, full cross-platform interoperability of component files is only available for large component files (see the following section), and for small component files created by Version 11.0 or later.

32 vs. 64-bit Component Files

Large (64-bit-addressing) component files are inaccessible to versions of the interpreter that pre-dated their introduction (versions earlier than 10.1).

The second item in the right argument of ⎕FCREATE determines the addressing type of the file.

      'small'⎕fcreate 1 32 ⍝ create small file.
      'large'⎕fcreate 1 64 ⍝ create large file.

If the second item is missing, the file type defaults to 64-bit-addressing. In versions prior to 12.0, the default was 32-bit-addressing. It is possible to override these defaults on the command line.

Note that small (32-bit-addressing) cannot contain Unicode data. Unicode editions of Dyalog APL can only write character data which would be readable by a Classic edition (consisting of elements of ⎕AV).

External Variables

External variables are implemented as small (32-bit-addressing) component files, and subject to the same restrictions as these files. External variables are unlikely to be developed further; Dyalog recommends that applications which use them should switch to using mapped files or traditional component files. Please contact Dyalog if you need further advice on this topic.

32 vs. 64-bit Interpreters

From Dyalog APL Version 11.0 onwards, there are two separate versions of programs for 32-bit and 64-bit machine architectures (the 32-bit versions will also run on 64-bit machines running 64-bit operating systems). There is complete inter-operability between 32- and 64-bit interpreters, except that 32-bit interpreters are unable to work with arrays greater than 2GB in size.

Unicode vs. Classic Editions

From Version 12.0 onwards, a Unicode edition is available, which is able to work with the entire Unicode character set. Classic editions (a term which includes versions prior to 12.0) are limited to the 256 characters defined in the atomic vector, ⎕AV).

Large (64-bit-addressing) component files have a Unicode property; when this is enabled (it is the default), all characters will be written as Unicode data to the file. The Unicode property is always off for small (32-bit addressing) files, which may not contain Unicode data. The Unicode property can be toggled on and off using ⎕FPROPS.

When a Unicode edition writes to a component file which may not contain Unicode data, character data is mapped to ⎕AV, and can therefore be read without problems by Classic editions.

A TRANSLATION ERROR will occur if a Unicode edition writes to a non-Unicode component ( that is either a 32-bit file, or a 64-bit file when the Unicode property is currently off) if the data being written contains characters which are not in ⎕AV(see ⎕AVU for more details).

Likewise, a Classic edition (Version 12.0 or later) will issue a TRANSLATION ERROR if it attempts to read a component containing Unicode data from a component file. Version 11.0 cannot read components containing Unicode data and issues a NONCE ERROR.

A TRANSLATION ERROR will also issued when a Classic edition )LOADs or )COPYs a workspace containing Unicode data which cannot be mapped to ⎕AV.

TCPSocket objects have an APL property which corresponds to the Unicode property of a file, if this is set to Classic (the default) the data in the socket will be restricted to ⎕AV, if Unicode it will contain Unicode character data. As a result, TRANSLATION ERRORs can occur on transmission or reception in the same way as

AVU changes

The implementation of the function "Right" in Version 13.0 led to the discovery that ⎕AVUincorrectly defined ⎕AV[59+⎕IO] as ¤ (⎕UCS 164) rather than ⊢ (Right Tack, ⎕UCS 8866). This error has been corrected in the default ⎕AVU and in workspace AVU.dws. If you are operating in a mixed Unicode/Classic environment, this error will have caused earlier Classic editions to map ⎕AV[59+⎕IO] to the wrong Unicode character (¤). This may cause TRANSLATION ERRORs when a Version 13.0 Classic system attempts to read the data, as it will not be able to represent ¤ in the Atomic Vector.

DECFs and Complex numbers

Version 13.0 introduces two new data types; DECFs and Complex numbers. Attempts to read components of these types in earlier interpreters will result in a DOMAIN ERROR.

Very large array components

The maximum size of a component written by Version 12.1 and prior is 2GB. This is the size of the component as held on disk; the maximum size of an array in APL will be slightly smaller. In Version 13.0 the maximum size of a component written by a 64 bit interpreter is 4GB. An attempt to read a component greater than 2GB in 32-bit interpreters will result in a WS FULL. An attempt to read such a component in 64-bit Versions 12.0 and 12.1 patched after 1st April 2011 will result in a NONCE ERROR; earlier patches generate a FILE COMPONENT DAMAGED error.

File Journaling

Version 12.0 introduces File Journaling (level 1), and 12.1 adds levels 2 and 3. Versions earlier than 12.0 cannot tie files which have any form of journaling enabled. Version 12.0 cannot tie files with journaling levels other than 1. Files can be shared with earlier versions by using ⎕FPROPS to switch journaling off.

TCPSockets

TCPSockets used to communicate between differing versions of Dyalog APL are subject to similar limitations to those described above for component files. In particular TCPSockets with 'Style' 'APL' will only be able to pass arrays that are supported by both versions.

Auxiliary Processors

A Dyalog APL process is restricted to starting an AP of exactly the same architecture. In other words, the AP must share the same word-width and byte-ordering as its interpreter process.

Session Files

Session (.dse) files may only be used on the platform on which they were created and saved.


Version 13.0 IME Overview

Overview

The mechanism for entering APL characters using the keyboard has been completely revised.

  • A brand-new Input Method Editor, the Dyalog Unicode IME, replaces all previous mechanisms in the Unicode Edition. The Dyalog Unicode IME can be used with previous Unicode Editions of Dyalog APL provided that they are patched to a Version created on or after 1st April 2011.
  • The Ctrl and AltGr keyboards that were created using the Microsoft Keyboard Layout Creator (MSKLC) and introduced with Version 12.0 are no longer supplied nor formally supported for use with Version 13.0.
  • The Comfort On-Screen keyboard is no longer included with nor supported by Version 13.0.

The Dyalog Unicode IME uses the same Microsoft Input Method Editor technology as the previous version of the IME, but differs in the following respects:

  • It maps keystrokes to Unicode code points (as opposed to positions in the Dyalog Atomic Vector)
  • It specifies only the keystrokes for entering APL (and potentially other special) symbols. It does not define or redefine characters entered using the standard keyboard conventions.

This means that the Dyalog Unicode IME acts effectively as an overlay to whatever keyboard is employed, and may be used to enter APL symbols in any application that supports IME technology, i.e. most Windows applications.

Input Translate Tables

The Dyalog Unicode IME is driven by one of a set of Input Translate tables installed in Program Files\Dyalog\UnicodeIME directory. For example, the US-English Input table is named:

    Program Files\Dyalog\UnicodeIME\en_US.din

The tables contain entries each of which maps a keystroke to the Unicode code point of an APL symbol. For example, the following entries (from en_US.din) map:

  • ⋄ (Unicode 8900) to Ctrl+`
  • ¨ (Unicode 168) to Ctrl+1
  • and so forth.
+UNI Desc		   Shift  Key	+ Name
 8900=Ctrl+` :		2	192	+ Diamond
  168=Ctrl+1 :		2	49	+ Diaeresis (Each)
  175=Ctrl+2 :		2	50	+ Overbar (High Minus)
   60=Ctrl+3 :		2	51	+ Less Than

The Dyalog Unicode IME supplied with Version 13.0 includes support for Danish, Finnish, French, German, Italian, Swedish and British and American English keyboards, based on the Version 12.1 Dyalog Ctrl layouts.

The Dyalog Unicode IME also has support for the Danish, British and American English physical keyboards, which are available from Dyalog Ltd.

The default keyboard mapping for unsupported languages is American English.

To differentiate the new from the old, the Dyalog Unicode IME uses a different icon to that used by the old IME as shown below:

The Dyalog Unicode IME
The old APL IME

See the new IME User Guide for further details.

See Also: | Special Commands
 | Configuration


Version 13.0 IME Configuration

Configuring the Dyalog APL IME

The following description uses screenshots taken from a Windows 7 PC with three Input Languages configured for the current user: English (United Kingdom) - the default Input Language, Danish (Denmark) and English (United States).

The Dyalog Unicode IME is added as an additional service to all keyboards defined to the user and the administrator at the time that the IME was installed.

For each IME the underlying keyboard layout file will be the same as that defined for the base keyboard. The layout file is a DLL created by Microsoft.

The language specified in the description of the IME is the name of the IME translate table that has been associated with the IME for the specific keyboard. In the case of languages not supported by the IME the keyboard will default to en-US. With the IME as supplied with Version 13.2 altering this text requires editing the appropriate Registry value.

The IME may be configured from within APL or from Windows.

From within Dyalog APL

To change the properties of the IME go to Options/Configure/Unicode Input tab and select Configure Layout:

From Windows

Right click on either the Input Language icon or the Keyboard layout icon in the TaskBar and select Settings:

To alter the configuration of any of the installed IMEs, select that IME and click on Properties:

Input translate table:

The translate table defines the mapping between APL characters and the keystrokes that generate those APL characters. It is possible to alter the mapping or to create support for new keyboards by altering the translate table, or by selecting a different translate table. See the IME User Guide for more details.

Overstrikes:

In the original implementations of APL, many of the special symbols could only be generated by overstriking one character on top of another as is reflected in the appearance of the glyphs. For example, the symbol for Grade Up (⍋) is actually the symbol for delta (∆) superimposed on the symbol for vertical bar (|)

In Dyalog APL such symbols can be generated either by a single keystroke, or (in Replace mode) by overtyping one symbol with another. For example ⍋ may be generated using Shift+Ctrl+4, or by switching to Replace mode and typing the three keystrokes Ctrl+h, Left-Cursor, Ctrl+m.

Using the Dyalog Unicode IME the character can also be entered by pressing Ctrl+Bksp, Ctrl+m, Ctrl+h. Note that Ctrl+Bksp is the default Overstrike Introducer Key (key code OS).

Use Overstrike popup:

With this option selected, when the character following the Overstrike Introducer Key is pressed, a popup box displays all the overstrikes which contain the last character typed: in the example below Ctrl+Bksp has been followed by Ctrl+h:

Note the fine (red) line under the ∆ in the Session window. This indicates that an overstrike creation operation is in progress.

The input of the symbol ⍋ can be completed by pressing Ctr+m, or by moving the selection up and down the pop-up list using Cursor-Up or Cursor-Down

Overstrikes do not require the OS introducer key (experimental):

With this option selected, the IME identifies characters which are part of a valid overstrike, and when such a character is entered into the session, begins an overstrike creation operation. This mode is experimental in the IME supplied with Version 13.2.


Version 13.0 IME Commands

IME Commands

The special commands used by Dyalog APL for Windows Unicode Edition are mapped to keystrokes under Options/Configure/Keyboard Shortcuts (see User Guide Chapter 2).

However, the Dyalog Unicode IME translate tables also include default mappings for the special command keystrokes used by Dyalog APL. This mechanism is intended primarily for use by terminal emulators used for running UNIX-based versions of Dyalog APL,

These commands are defined in

    Program Files\Dyalog\UnicodeIME\special_keys.din

For example the command ER (execute) is mapped to the Enter key, ED (edit) to Shift+Enter, and so forth

+ER=Enter:		        13	+ Enter
 ED=Shift+Enter:	      1 13 	+ Edit
 TC=Ctrl+Enter:		      2 13	+ Trace
 FD=Ctrl+Shift+Enter:	      3 13	+ Forward.

These command keystroke mappings are ignored by applications unless the application is explicitly named by the WantsSpecialKeys parameter.


Complex Numbers

A complex number is a number consisting of a real and an imaginary part which is usually written in the form a+ bi, where a and b are real numbers, and i is the standard imaginary unit with the property i2= −1.

Dyalog APL adopts the J notation introduced in IBM APL2 to represent the value of a complex number which is written as aJb or ajb (without spaces). The former representation (with a capital J) is always used to display a value.

Notation

      2+¯1*.5
2J1

      .3j.5
0.3J0.5

      1.2E5J¯4E¯4
120000J¯0.0004

Arithmetic

The arithmetic primitive functions handle complex numbers in the appropriate way.

      2j3+.3j.5 ⍝ (a+bi)+(c+di) = (a+c)+(b+d)i
2.3J3.5

      2j3-.3j5  ⍝ (a+bi)-(c+di) = (a-c)+(b-d)i
1.7J¯2

      2j3×.3j.5 ⍝ (a+bi)(c+di)= ac+bci+adi+bdi2
                ⍝             = (ac-bd)+(bc+ad)i
¯0.9J1.9

The absolute value, or magnitude of a complex number is naturally obtained using the Magnitude function

      |3j4
5

Monadic + of a complex number (a+bi) returns its conjugate (a-bi) ...

      +3j4
3J¯4

... which when multiplied by the complex number itself, produces the square of its magnitude.

       3j4×3j¯4
25

Furthermore, adding a complex number and its conjugate produces a real number:

       3j4+3j¯4
6

The famous Euler's Identity Euler's Identity may be expressed as follows:

      1+*○0j1 ⍝ Euler Identity
0

Different Result for Power

From Version 13.0 onwards, the implementation of X*Y (Power) gives a different answer for negative real X than in all previous Versions of Dyalog APL. This change is however in accordance with the ISO/EEC 13751 Standard for Extended APL.

In Version 13.0 onwards, the result is the principal value; whereas in previous Versions the result is a negative or positive real number or DOMAIN ERROR. The following examples illustrate this point:

      ¯8 * 1 2 ÷ 3          ⍝ Version 12.1
¯2 4
      ¯8 * 1 2 ÷ 3          ⍝ Version 13.0
1J1.732050808 ¯2J3.464101615

      * (1 2 ÷ 3) × ⍟ ¯8    ⍝ Version 13.0
1J1.732050808 ¯2J3.464101615

Circular functions

The basic set of circular functions X○Y cater for complex values in Y, while the following extended functions provide specific features for complex arguments. Note that a and b are the real and imaginary parts of Y respectively and θ is the phase of Y..

(-X) ○ Y | X | X ○ Y
-8○Y | 8 | (-1+Y*2)*0.5
Y | 9 | a
+Y | 10 | |Y
Y×0J1 | 11 | b
*Y×0J1 | 12 | θ

Note that 9○Y and 11○Y return the real and imaginary parts of Y respectively:

      9 11○3.5J¯1.2
3.5 ¯1.2

      9 11∘.○3.5J¯1.2 2J3 3J4
 3.5 2 3
¯1.2 3 4

Comparison

In comparing two complex numbers X and Y, X=Y is 1 if the magnitude of X-Y does not exceed ⎕CT times the larger of the magnitudes of X and Y; geometrically, X=Y if the number smaller in magnitude lies on or within a circle centred on the one with larger magnitude, having radius ⎕CT times the larger magnitude.

As with real values, complex values sufficiently close to Boolean or integral values are accepted by functions which require Boolean or integral values. For example:

      2j1e¯14 ⍴ 12
12 12
      0 ⍱ 1j1e¯15
0

Note that Dyalog APL always stores complex numbers as a pair of 64-bit binary floating-point numbers, regardless of the setting of ⎕FR. Comparisons between complex numbers and decimal floating-point numbers will require conversion of the decimal number to binary to allow the comparison. When ⎕FR=1287, comparisons are always subject to ⎕DCT, not ⎕CT - regardless of the data type used to represent a number.

This only really comes into play when determining whether the imaginary part of a complex number is so small that it can be considered to be on the real plane. However, Dyalog recommends that you do not mix the use of complex and decimal numbers in the same component of an application.


128-bit Decimal Numbers

Introduction

The original IEE-754 64-bit binary floating point (FP) data type (also known as type number 645), that is used internally by Dyalog APL to represent floating-point values, does not have sufficient precision for certain financial computations - typically involving large currency amounts. The binary representation also causes errors to accumulate even when all values involved in a calculation are "exact" (rounded) decimal numbers, since many decimal numbers cannot be accurately represented regardless of the precision used to hold them. To reduce this problem, Version 13.0 introduces support for the 128-bit decimal data type described by IEEE-754-2008 as an alternative representation for floating-point values.

New System Variable: Floating-Point Representation

Computations using 128-bit decimal numbers require twice as much space for storage, and run more than an order of magnitude more slowly on platforms which do not provide hardware support for the type. At this time, hardware support is only available from IBM (Power chips starting with the "P6", and recent "z" series mainframes). Even with hardware support, a slowdown of a factor of 4 can be expected. For this reason, Dyalog Version 13 allows users to decide whether they need the higher-precision decimal representation, or prefer to stay with the faster and smaller binary representation.

A new system variable ⎕FR (for Floating-point Representation) can be set to the value 645 (the installed default) to indicate 64-bit binary FP, or 1287 for 128-bit decimal FP. The default value of ⎕FR is configurable.

More...

Conversion between Decimal and Binary

Conversion of data from Binary to Decimal is logically equivalent to formatting, and the reverse conversion is equivalent to evaluating input. These operations are performed according to the same rules that are used when formatting (and evaluating) numbers with ⎕PP set to 17 (guaranteeing that the decimal value can be converted back to the same binary bit pattern). Because the precision of decimal floating-point numbers is much higher, there will always be a large number of potential decimal values which map to the same binary number: As with formatting, the rule is that the SHORTEST decimal number which maps to a particular binary value will be used as its decimal representation.

Data in component files will be stored without conversion, and only converted when a computation happens. It should be stored in decimal form if it will repeatedly be used by application code in which ⎕FR has the value 1287. Even in applications which use decimal floating point everywhere, reading old component files containing arrays of type 645, or receiving data via ⎕NA, the .Net interface or other external sources, will allow binary floating-point values to enter the system and require conversion.

Decimal Comparison Tolerance

When ⎕FR has the value 1287, the new system variable ⎕DCT will be used to specify comparison tolerance.

The default value of ⎕DCT is 1E¯28, and the maximum value is 2.3283064365386962890625E¯10 (the value is chosen to avoid fuzzy comparison of 32-bit integers).

More...

Passing floating-point values to DLLs

⎕NA now supports a new data type "D" to represent the Densely Packed Decimal (DPD) form of 128-bit decimal numbers, as specified by the IEEE-754 2008 standard. Dyalog has decided to use DPD, which is the format used by IBM for hardware support, on ALL platforms, although "Binary Integer Decimal" (BID) is the format that Intel libraries use to implement software libraries to do decimal arithmetic. Experiments have shown that the performance of 128-bit DPD and BID libraries are very similar on Intel platforms. In order to avoid the added complication of having two internal representations, Dyalog has elected to go with the hardware format, which is expected to be adopted by future hardware implementations.

The support libraries for writing AP's and DLL's include new functions to extract the contents of a value of type D as a string or double-precision binary "float" - and convert data to D format.

Decimal Floats and Microsoft.NET

The Microsoft.NET framework contains a type named System.Decimal, which implements decimal floating-point numbers. However, it uses a different internal format from that defined by IEEE-754 2008.

Version 13.0 includes a Microsoft.NET class (called Dyalog.Dec128), which will perform arithmetic on data represented using the "Binary Integer Decimal" format. All computations performed by the Dyalog.Dec128 class will produce exactly the same results as if the computation was performed in APL. A "DCT" property allows setting the comparison tolerance to be used in comparisons, Ceiling/Floor, etc).

The Dyalog class is modelled closely after the existing System.Decimal type, providing the same methods (Add, Ceiling, Compare, CompareTo, Divide, Equals, Finalize, Floor, FromOACurrency, GetBits, GetHashCode, GetType, GetTypeCode, MemberwiseClone, Multiply, Negate, Parse, Remainder, Round, Subtract, To*, Truncate, TryParse) and operators (Addition, Decrement, Division, Equality, Explicit, GreaterThan, GreaterThanOrEqual, Implicit, Increment, Inequality, LessThan, LessThanOrEqual, Modulus, Multiply, Subtraction, UnaryNegation, UnaryPlus).

The "bridge" between Dyalog and .NET is able to cast floating-point numbers to or from System.Double, System.Decimal and Dyalog.Dec128 (and perform all other reasonable casts to integer types etc). Casting a Dyalog.Dec128 to or from strings will perform a "lossless" conversion.

The .Net type System.Int64 will now always be cast to a 128-bit decimal number when entering Dyalog APL, regardless of the setting of ⎕FR. So long as no 64-bit arithmetic is performed on such a value, it will remain a 128-bit number and can be passed back to .Net without loss.


PCRE Overview

PCRE (Perl Compatible Regular Expressions) is an open source library used by the ⎕R and ⎕S system operators. The regular expression syntax which the library supports is not unique to APL nor is it an integral part of the language. Its documentation is reproduced verbatim in this Appendix.

There are two named sections: pcrepattern, which describes the full syntax and semantics); and prcresyntax, a quick reference summary.


PCRE Regular Expression Details

PCREPATTERN(3)                                                  PCREPATTERN(3)

NAME
       PCRE - Perl-compatible regular expressions

PCRE REGULAR EXPRESSION DETAILS

       The  syntax and semantics of the regular expressions that are supported
       by PCRE are described in detail below. There is a quick-reference  syn-
       tax summary in the pcresyntax page. PCRE tries to match Perl syntax and
       semantics as closely as it can. PCRE  also  supports  some  alternative
       regular  expression  syntax (which does not conflict with the Perl syn-
       tax) in order to provide some compatibility with regular expressions in
       Python, .NET, and Oniguruma.

       Perl's  regular expressions are described in its own documentation, and
       regular expressions in general are covered in a number of  books,  some
       of  which  have  copious  examples. Jeffrey Friedl's "Mastering Regular
       Expressions", published by  O'Reilly,  covers  regular  expressions  in
       great  detail.  This  description  of  PCRE's  regular  expressions  is
       intended as reference material.

       The original operation of PCRE was on strings of  one-byte  characters.
       However,  there is now also support for UTF-8 character strings. To use
       this, PCRE must be built to include UTF-8 support, and  you  must  call
       pcre_compile()  or  pcre_compile2() with the PCRE_UTF8 option. There is
       also a special sequence that can be given at the start of a pattern:

         (*UTF8)

       Starting a pattern with this sequence  is  equivalent  to  setting  the
       PCRE_UTF8  option.  This  feature  is  not Perl-compatible. How setting
       UTF-8 mode affects pattern matching  is  mentioned  in  several  places
       below.  There  is  also  a  summary of UTF-8 features in the section on
       UTF-8 support in the main pcre page.

       The remainder of this document discusses the  patterns  that  are  sup-
       ported  by  PCRE when its main matching function, pcre_exec(), is used.
       From  release  6.0,   PCRE   offers   a   second   matching   function,
       pcre_dfa_exec(),  which matches using a different algorithm that is not
       Perl-compatible. Some of the features discussed below are not available
       when  pcre_dfa_exec()  is used. The advantages and disadvantages of the
       alternative function, and how it differs from the normal function,  are
       discussed in the pcrematching page.

NEWLINE CONVENTIONS

       PCRE  supports five different conventions for indicating line breaks in
       strings: a single CR (carriage return) character, a  single  LF  (line-
       feed) character, the two-character sequence CRLF, any of the three pre-
       ceding, or any Unicode newline sequence. The pcreapi page  has  further
       discussion  about newlines, and shows how to set the newline convention
       in the options arguments for the compiling and matching functions.

       It is also possible to specify a newline convention by starting a  pat-
       tern string with one of the following five sequences:

         (*CR)        carriage return
         (*LF)        linefeed
         (*CRLF)      carriage return, followed by linefeed
         (*ANYCRLF)   any of the three above
         (*ANY)       all Unicode newline sequences

       These  override  the default and the options given to pcre_compile() or
       pcre_compile2(). For example, on a Unix system where LF is the  default
       newline sequence, the pattern

         (*CR)a.b

       changes the convention to CR. That pattern matches "a\nb" because LF is
       no longer a newline. Note that these special settings,  which  are  not
       Perl-compatible,  are  recognized  only at the very start of a pattern,
       and that they must be in upper case.  If  more  than  one  of  them  is
       present, the last one is used.

       The  newline  convention  does  not  affect what the \R escape sequence
       matches. By default, this is any Unicode  newline  sequence,  for  Perl
       compatibility.  However, this can be changed; see the description of \R
       in the section entitled "Newline sequences" below. A change of \R  set-
       ting can be combined with a change of newline convention.

CHARACTERS AND METACHARACTERS

       A  regular  expression  is  a pattern that is matched against a subject
       string from left to right. Most characters stand for  themselves  in  a
       pattern,  and  match  the corresponding characters in the subject. As a
       trivial example, the pattern

         The quick brown fox

       matches a portion of a subject string that is identical to itself. When
       caseless  matching is specified (the PCRE_CASELESS option), letters are
       matched independently of case. In UTF-8 mode, PCRE  always  understands
       the  concept  of case for characters whose values are less than 128, so
       caseless matching is always possible. For characters with  higher  val-
       ues,  the concept of case is supported if PCRE is compiled with Unicode
       property support, but not otherwise.   If  you  want  to  use  caseless
       matching  for  characters  128  and above, you must ensure that PCRE is
       compiled with Unicode property support as well as with UTF-8 support.

       The power of regular expressions comes  from  the  ability  to  include
       alternatives  and  repetitions in the pattern. These are encoded in the
       pattern by the use of metacharacters, which do not stand for themselves
       but instead are interpreted in some special way.

       There  are  two different sets of metacharacters: those that are recog-
       nized anywhere in the pattern except within square brackets, and  those
       that  are  recognized  within square brackets. Outside square brackets,
       the metacharacters are as follows:

         \      general escape character with several uses
         ^      assert start of string (or line, in multiline mode)
         $      assert end of string (or line, in multiline mode)
         .      match any character except newline (by default)
         [      start character class definition
         |      start of alternative branch
         (      start subpattern
         )      end subpattern
         ?      extends the meaning of (
                also 0 or 1 quantifier
                also quantifier minimizer
         *      0 or more quantifier
         +      1 or more quantifier
                also "possessive quantifier"
         {      start min/max quantifier

       Part of a pattern that is in square brackets  is  called  a  "character
       class". In a character class the only metacharacters are:

         \      general escape character
         ^      negate the class, but only if the first character
         -      indicates character range
         [      POSIX character class (only if followed by POSIX
                  syntax)
         ]      terminates the character class

       The following sections describe the use of each of the metacharacters.

BACKSLASH

       The backslash character has several uses. Firstly, if it is followed by
       a non-alphanumeric character, it takes away any  special  meaning  that
       character  may  have.  This  use  of  backslash  as an escape character
       applies both inside and outside character classes.

       For example, if you want to match a * character, you write  \*  in  the
       pattern.   This  escaping  action  applies whether or not the following
       character would otherwise be interpreted as a metacharacter, so  it  is
       always  safe  to  precede  a non-alphanumeric with backslash to specify
       that it stands for itself. In particular, if you want to match a  back-
       slash, you write \\.

       If  a  pattern is compiled with the PCRE_EXTENDED option, whitespace in
       the pattern (other than in a character class) and characters between  a
       # outside a character class and the next newline are ignored. An escap-
       ing backslash can be used to include a whitespace  or  #  character  as
       part of the pattern.

       If  you  want  to remove the special meaning from a sequence of charac-
       ters, you can do so by putting them between \Q and \E. This is  differ-
       ent  from  Perl  in  that  $  and  @ are handled as literals in \Q...\E
       sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
       tion. Note the following examples:

         Pattern            PCRE matches   Perl matches

         \Qabc$xyz\E        abc$xyz        abc followed by the
                                             contents of $xyz
         \Qabc\$xyz\E       abc\$xyz       abc\$xyz
         \Qabc\E\$\Qxyz\E   abc$xyz        abc$xyz

       The  \Q...\E  sequence  is recognized both inside and outside character
       classes.

   Non-printing characters

       A second use of backslash provides a way of encoding non-printing char-
       acters  in patterns in a visible manner. There is no restriction on the
       appearance of non-printing characters, apart from the binary zero  that
       terminates  a  pattern,  but  when  a pattern is being prepared by text
       editing, it is  often  easier  to  use  one  of  the  following  escape
       sequences than the binary character it represents:

         \a        alarm, that is, the BEL character (hex 07)
         \cx       "control-x", where x is any character
         \e        escape (hex 1B)
         \f        formfeed (hex 0C)
         \n        linefeed (hex 0A)
         \r        carriage return (hex 0D)
         \t        tab (hex 09)
         \ddd      character with octal code ddd, or back reference
         \xhh      character with hex code hh
         \x{hhh..} character with hex code hhh..

       The  precise  effect of \cx is as follows: if x is a lower case letter,
       it is converted to upper case. Then bit 6 of the character (hex 40)  is
       inverted.   Thus  \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
       becomes hex 7B.

       After \x, from zero to two hexadecimal digits are read (letters can  be
       in  upper  or  lower case). Any number of hexadecimal digits may appear
       between \x{ and }, but the value of the character  code  must  be  less
       than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is,
       the maximum value in hexadecimal is 7FFFFFFF. Note that this is  bigger
       than the largest Unicode code point, which is 10FFFF.

       If  characters  other than hexadecimal digits appear between \x{ and },
       or if there is no terminating }, this form of escape is not recognized.
       Instead,  the  initial  \x  will  be interpreted as a basic hexadecimal
       escape, with no following digits, giving a  character  whose  value  is
       zero.

       Characters whose value is less than 256 can be defined by either of the
       two syntaxes for \x. There is no difference in the way  they  are  han-
       dled. For example, \xdc is exactly the same as \x{dc}.

       After  \0  up  to two further octal digits are read. If there are fewer
       than two digits, just  those  that  are  present  are  used.  Thus  the
       sequence \0\x\07 specifies two binary zeros followed by a BEL character
       (code value 7). Make sure you supply two digits after the initial  zero
       if the pattern character that follows is itself an octal digit.

       The handling of a backslash followed by a digit other than 0 is compli-
       cated.  Outside a character class, PCRE reads it and any following dig-
       its  as  a  decimal  number. If the number is less than 10, or if there
       have been at least that many previous capturing left parentheses in the
       expression,  the  entire  sequence  is  taken  as  a  back reference. A
       description of how this works is given later, following the  discussion
       of parenthesized subpatterns.

       Inside  a  character  class, or if the decimal number is greater than 9
       and there have not been that many capturing subpatterns, PCRE  re-reads
       up to three octal digits following the backslash, and uses them to gen-
       erate a data character. Any subsequent digits stand for themselves.  In
       non-UTF-8  mode,  the  value  of a character specified in octal must be
       less than \400. In UTF-8 mode, values up to  \777  are  permitted.  For
       example:

         \040   is another way of writing a space
         \40    is the same, provided there are fewer than 40
                   previous capturing subpatterns
         \7     is always a back reference
         \11    might be a back reference, or another way of
                   writing a tab
         \011   is always a tab
         \0113  is a tab followed by the character "3"
         \113   might be a back reference, otherwise the
                   character with octal code 113
         \377   might be a back reference, otherwise
                   the byte consisting entirely of 1 bits
         \81    is either a back reference, or a binary zero
                   followed by the two characters "8" and "1"

       Note  that  octal  values of 100 or greater must not be introduced by a
       leading zero, because no more than three octal digits are ever read.

       All the sequences that define a single character value can be used both
       inside  and  outside character classes. In addition, inside a character
       class, the sequence \b is interpreted as the backspace  character  (hex
       08),  and the sequences \R and \X are interpreted as the characters "R"
       and "X", respectively. Outside a character class, these sequences  have
       different meanings (see below).

   Absolute and relative back references

       The  sequence  \g followed by an unsigned or a negative number, option-
       ally enclosed in braces, is an absolute or relative back  reference.  A
       named back reference can be coded as \g{name}. Back references are dis-
       cussed later, following the discussion of parenthesized subpatterns.

   Absolute and relative subroutine calls

       For compatibility with Oniguruma, the non-Perl syntax \g followed by  a
       name or a number enclosed either in angle brackets or single quotes, is
       an alternative syntax for referencing a subpattern as  a  "subroutine".
       Details  are  discussed  later.   Note  that  \g{...} (Perl syntax) and
       \g<...> (Oniguruma syntax) are not synonymous. The  former  is  a  back
       reference; the latter is a subroutine call.

   Generic character types

       Another use of backslash is for specifying generic character types. The
       following are always recognized:

         \d     any decimal digit
         \D     any character that is not a decimal digit
         \h     any horizontal whitespace character
         \H     any character that is not a horizontal whitespace character
         \s     any whitespace character
         \S     any character that is not a whitespace character
         \v     any vertical whitespace character
         \V     any character that is not a vertical whitespace character
         \w     any "word" character
         \W     any "non-word" character

       Each pair of escape sequences partitions the complete set of characters
       into  two disjoint sets. Any given character matches one, and only one,
       of each pair.

       These character type sequences can appear both inside and outside char-
       acter  classes.  They each match one character of the appropriate type.
       If the current matching point is at the end of the subject string,  all
       of them fail, since there is no character to match.

       For  compatibility  with Perl, \s does not match the VT character (code
       11).  This makes it different from the the POSIX "space" class. The  \s
       characters  are  HT  (9), LF (10), FF (12), CR (13), and space (32). If
       "use locale;" is included in a Perl script, \s may match the VT charac-
       ter. In PCRE, it never does.

       In  UTF-8 mode, characters with values greater than 128 never match \d,
       \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
       code  character  property  support is available. These sequences retain
       their original meanings from before UTF-8 support was available, mainly
       for  efficiency  reasons. Note that this also affects \b, because it is
       defined in terms of \w and \W.

       The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to
       the  other  sequences, these do match certain high-valued codepoints in
       UTF-8 mode.  The horizontal space characters are:

         U+0009     Horizontal tab
         U+0020     Space
         U+00A0     Non-break space
         U+1680     Ogham space mark
         U+180E     Mongolian vowel separator
         U+2000     En quad
         U+2001     Em quad
         U+2002     En space
         U+2003     Em space
         U+2004     Three-per-em space
         U+2005     Four-per-em space
         U+2006     Six-per-em space
         U+2007     Figure space
         U+2008     Punctuation space
         U+2009     Thin space
         U+200A     Hair space
         U+202F     Narrow no-break space
         U+205F     Medium mathematical space
         U+3000     Ideographic space

       The vertical space characters are:

         U+000A     Linefeed
         U+000B     Vertical tab
         U+000C     Formfeed
         U+000D     Carriage return
         U+0085     Next line
         U+2028     Line separator
         U+2029     Paragraph separator

       A "word" character is an underscore or any character less than 256 that
       is  a  letter  or  digit.  The definition of letters and digits is con-
       trolled by PCRE's low-valued character tables, and may vary if  locale-
       specific  matching is taking place (see "Locale support" in the pcreapi
       page). For example, in a French locale such  as  "fr_FR"  in  Unix-like
       systems,  or "french" in Windows, some character codes greater than 128
       are used for accented letters, and these are matched by \w. The use  of
       locales with Unicode is discouraged.

   Newline sequences

       Outside  a  character class, by default, the escape sequence \R matches
       any Unicode newline sequence. This is a Perl 5.10 feature. In non-UTF-8
       mode \R is equivalent to the following:

         (?>\r\n|\n|\x0b|\f|\r|\x85)

       This  is  an  example  of an "atomic group", details of which are given
       below.  This particular group matches either the two-character sequence
       CR  followed  by  LF,  or  one  of  the single characters LF (linefeed,
       U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage
       return, U+000D), or NEL (next line, U+0085). The two-character sequence
       is treated as a single unit that cannot be split.

       In UTF-8 mode, two additional characters whose codepoints  are  greater
       than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-
       rator, U+2029).  Unicode character property support is not  needed  for
       these characters to be recognized.

       It is possible to restrict \R to match only CR, LF, or CRLF (instead of
       the complete set  of  Unicode  line  endings)  by  setting  the  option
       PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.
       (BSR is an abbrevation for "backslash R".) This can be made the default
       when  PCRE  is  built;  if this is the case, the other behaviour can be
       requested via the PCRE_BSR_UNICODE option.   It  is  also  possible  to
       specify  these  settings  by  starting a pattern string with one of the
       following sequences:

         (*BSR_ANYCRLF)   CR, LF, or CRLF only
         (*BSR_UNICODE)   any Unicode newline sequence

       These override the default and the options given to  pcre_compile()  or
       pcre_compile2(),  but  they  can  be  overridden  by  options  given to
       pcre_exec() or pcre_dfa_exec(). Note that these special settings, which
       are  not  Perl-compatible,  are  recognized only at the very start of a
       pattern, and that they must be in upper case. If more than one of  them
       is present, the last one is used. They can be combined with a change of
       newline convention, for example, a pattern can start with:

         (*ANY)(*BSR_ANYCRLF)

       Inside a character class, \R matches the letter "R".

   Unicode character properties

       When PCRE is built with Unicode character property support, three addi-
       tional  escape sequences that match characters with specific properties
       are available.  When not in UTF-8 mode, these sequences are  of  course
       limited  to  testing characters whose codepoints are less than 256, but
       they do work in this mode.  The extra escape sequences are:

         \p{xx}   a character with the xx property
         \P{xx}   a character without the xx property
         \X       an extended Unicode sequence

       The property names represented by xx above are limited to  the  Unicode
       script names, the general category properties, and "Any", which matches
       any character (including newline). Other properties such as "InMusical-
       Symbols"  are  not  currently supported by PCRE. Note that \P{Any} does
       not match any characters, so always causes a match failure.

       Sets of Unicode characters are defined as belonging to certain scripts.
       A  character from one of these sets can be matched using a script name.
       For example:

         \p{Greek}
         \P{Han}

       Those that are not part of an identified script are lumped together  as
       "Common". The current list of scripts is:

       Arabic,  Armenian,  Balinese,  Bengali,  Bopomofo,  Braille,  Buginese,
       Buhid,  Canadian_Aboriginal,  Cherokee,  Common,   Coptic,   Cuneiform,
       Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, Glagolitic,
       Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew,  Hira-
       gana,  Inherited,  Kannada,  Katakana,  Kharoshthi,  Khmer, Lao, Latin,
       Limbu,  Linear_B,  Malayalam,  Mongolian,  Myanmar,  New_Tai_Lue,  Nko,
       Ogham,  Old_Italic,  Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician,
       Runic,  Shavian,  Sinhala,  Syloti_Nagri,  Syriac,  Tagalog,  Tagbanwa,
       Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Yi.

       Each  character has exactly one general category property, specified by
       a two-letter abbreviation. For compatibility with Perl, negation can be
       specified  by  including a circumflex between the opening brace and the
       property name. For example, \p{^Lu} is the same as \P{Lu}.

       If only one letter is specified with \p or \P, it includes all the gen-
       eral  category properties that start with that letter. In this case, in
       the absence of negation, the curly brackets in the escape sequence  are
       optional; these two examples have the same effect:

         \p{L}
         \pL

       The following general category property codes are supported:

         C     Other
         Cc    Control
         Cf    Format
         Cn    Unassigned
         Co    Private use
         Cs    Surrogate

         L     Letter
         Ll    Lower case letter
         Lm    Modifier letter
         Lo    Other letter
         Lt    Title case letter
         Lu    Upper case letter

         M     Mark
         Mc    Spacing mark
         Me    Enclosing mark
         Mn    Non-spacing mark

         N     Number
         Nd    Decimal number
         Nl    Letter number
         No    Other number

         P     Punctuation
         Pc    Connector punctuation
         Pd    Dash punctuation
         Pe    Close punctuation
         Pf    Final punctuation
         Pi    Initial punctuation
         Po    Other punctuation
         Ps    Open punctuation

         S     Symbol
         Sc    Currency symbol
         Sk    Modifier symbol
         Sm    Mathematical symbol
         So    Other symbol

         Z     Separator
         Zl    Line separator
         Zp    Paragraph separator
         Zs    Space separator

       The  special property L& is also supported: it matches a character that
       has the Lu, Ll, or Lt property, in other words, a letter  that  is  not
       classified as a modifier or "other".

       The  Cs  (Surrogate)  property  applies only to characters in the range
       U+D800 to U+DFFF. Such characters are not valid in UTF-8  strings  (see
       RFC 3629) and so cannot be tested by PCRE, unless UTF-8 validity check-
       ing has been turned off (see the discussion  of  PCRE_NO_UTF8_CHECK  in
       the pcreapi page). Perl does not support the Cs property.

       The  long  synonyms  for  property  names  that  Perl supports (such as
       \p{Letter}) are not supported by PCRE, nor is it  permitted  to  prefix
       any of these properties with "Is".

       No character that is in the Unicode table has the Cn (unassigned) prop-
       erty.  Instead, this property is assumed for any code point that is not
       in the Unicode table.

       Specifying  caseless  matching  does not affect these escape sequences.
       For example, \p{Lu} always matches only upper case letters.

       The \X escape matches any number of Unicode  characters  that  form  an
       extended Unicode sequence. \X is equivalent to

         (?>\PM\pM*)

       That  is,  it matches a character without the "mark" property, followed
       by zero or more characters with the "mark"  property,  and  treats  the
       sequence  as  an  atomic group (see below).  Characters with the "mark"
       property are typically accents that  affect  the  preceding  character.
       None  of  them  have  codepoints less than 256, so in non-UTF-8 mode \X
       matches any one character.

       Matching characters by Unicode property is not fast, because  PCRE  has
       to  search  a  structure  that  contains data for over fifteen thousand
       characters. That is why the traditional escape sequences such as \d and
       \w do not use Unicode properties in PCRE.

   Resetting the match start

       The escape sequence \K, which is a Perl 5.10 feature, causes any previ-
       ously matched characters not  to  be  included  in  the  final  matched
       sequence. For example, the pattern:

         foo\Kbar

       matches  "foobar",  but reports that it has matched "bar". This feature
       is similar to a lookbehind assertion (described  below).   However,  in
       this  case, the part of the subject before the real match does not have
       to be of fixed length, as lookbehind assertions do. The use of \K  does
       not  interfere  with  the setting of captured substrings.  For example,
       when the pattern

         (foo)\Kbar

       matches "foobar", the first substring is still set to "foo".

   Simple assertions

       The final use of backslash is for certain simple assertions. An  asser-
       tion  specifies a condition that has to be met at a particular point in
       a match, without consuming any characters from the subject string.  The
       use  of subpatterns for more complicated assertions is described below.
       The backslashed assertions are:

         \b     matches at a word boundary
         \B     matches when not at a word boundary
         \A     matches at the start of the subject
         \Z     matches at the end of the subject
                 also matches before a newline at the end of the subject
         \z     matches only at the end of the subject
         \G     matches at the first matching position in the subject

       These assertions may not appear in character classes (but note that  \b
       has a different meaning, namely the backspace character, inside a char-
       acter class).

       A word boundary is a position in the subject string where  the  current
       character  and  the previous character do not both match \w or \W (i.e.
       one matches \w and the other matches \W), or the start or  end  of  the
       string if the first or last character matches \w, respectively. Neither
       PCRE nor Perl has a separte "start of word" or "end  of  word"  metase-
       quence.  However,  whatever follows \b normally determines which it is.
       For example, the fragment \ba matches "a" at the start of a word.

       The \A, \Z, and \z assertions differ from  the  traditional  circumflex
       and dollar (described in the next section) in that they only ever match
       at the very start and end of the subject string, whatever  options  are
       set.  Thus,  they are independent of multiline mode. These three asser-
       tions are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options, which
       affect  only the behaviour of the circumflex and dollar metacharacters.
       However, if the startoffset argument of pcre_exec() is non-zero,  indi-
       cating that matching is to start at a point other than the beginning of
       the subject, \A can never match. The difference between \Z  and  \z  is
       that \Z matches before a newline at the end of the string as well as at
       the very end, whereas \z matches only at the end.

       The \G assertion is true only when the current matching position is  at
       the  start point of the match, as specified by the startoffset argument
       of pcre_exec(). It differs from \A when the  value  of  startoffset  is
       non-zero.  By calling pcre_exec() multiple times with appropriate argu-
       ments, you can mimic Perl's /g option, and it is in this kind of imple-
       mentation where \G can be useful.

       Note,  however,  that  PCRE's interpretation of \G, as the start of the
       current match, is subtly different from Perl's, which defines it as the
       end  of  the  previous  match. In Perl, these can be different when the
       previously matched string was empty. Because PCRE does just  one  match
       at a time, it cannot reproduce this behaviour.

       If  all  the alternatives of a pattern begin with \G, the expression is
       anchored to the starting match position, and the "anchored" flag is set
       in the compiled regular expression.

CIRCUMFLEX AND DOLLAR

       Outside a character class, in the default matching mode, the circumflex
       character is an assertion that is true only  if  the  current  matching
       point  is  at the start of the subject string. If the startoffset argu-
       ment of pcre_exec() is non-zero, circumflex  can  never  match  if  the
       PCRE_MULTILINE  option  is  unset. Inside a character class, circumflex
       has an entirely different meaning (see below).

       Circumflex need not be the first character of the pattern if  a  number
       of  alternatives are involved, but it should be the first thing in each
       alternative in which it appears if the pattern is ever  to  match  that
       branch.  If all possible alternatives start with a circumflex, that is,
       if the pattern is constrained to match only at the start  of  the  sub-
       ject,  it  is  said  to be an "anchored" pattern. (There are also other
       constructs that can cause a pattern to be anchored.)

       A dollar character is an assertion that is true  only  if  the  current
       matching  point  is  at  the  end of the subject string, or immediately
       before a newline at the end of the string (by default). Dollar need not
       be  the  last  character of the pattern if a number of alternatives are
       involved, but it should be the last item in  any  branch  in  which  it
       appears. Dollar has no special meaning in a character class.

       The  meaning  of  dollar  can be changed so that it matches only at the
       very end of the string, by setting the  PCRE_DOLLAR_ENDONLY  option  at
       compile time. This does not affect the \Z assertion.

       The meanings of the circumflex and dollar characters are changed if the
       PCRE_MULTILINE option is set. When  this  is  the  case,  a  circumflex
       matches  immediately after internal newlines as well as at the start of
       the subject string. It does not match after a  newline  that  ends  the
       string.  A dollar matches before any newlines in the string, as well as
       at the very end, when PCRE_MULTILINE is set. When newline is  specified
       as  the  two-character  sequence CRLF, isolated CR and LF characters do
       not indicate newlines.

       For example, the pattern /^abc$/ matches the subject string  "def\nabc"
       (where  \n  represents a newline) in multiline mode, but not otherwise.
       Consequently, patterns that are anchored in single  line  mode  because
       all  branches  start  with  ^ are not anchored in multiline mode, and a
       match for circumflex is  possible  when  the  startoffset  argument  of
       pcre_exec()  is  non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if
       PCRE_MULTILINE is set.

       Note that the sequences \A, \Z, and \z can be used to match  the  start
       and  end of the subject in both modes, and if all branches of a pattern
       start with \A it is always anchored, whether or not  PCRE_MULTILINE  is
       set.

FULL STOP (PERIOD, DOT)

       Outside a character class, a dot in the pattern matches any one charac-
       ter in the subject string except (by default) a character  that  signi-
       fies  the  end  of  a line. In UTF-8 mode, the matched character may be
       more than one byte long.

       When a line ending is defined as a single character, dot never  matches
       that  character; when the two-character sequence CRLF is used, dot does
       not match CR if it is immediately followed  by  LF,  but  otherwise  it
       matches  all characters (including isolated CRs and LFs). When any Uni-
       code line endings are being recognized, dot does not match CR or LF  or
       any of the other line ending characters.

       The  behaviour  of  dot  with regard to newlines can be changed. If the
       PCRE_DOTALL option is set, a dot matches  any  one  character,  without
       exception. If the two-character sequence CRLF is present in the subject
       string, it takes two dots to match it.

       The handling of dot is entirely independent of the handling of  circum-
       flex  and  dollar,  the  only relationship being that they both involve
       newlines. Dot has no special meaning in a character class.

MATCHING A SINGLE BYTE

       Outside a character class, the escape sequence \C matches any one byte,
       both  in  and  out  of  UTF-8 mode. Unlike a dot, it always matches any
       line-ending characters. The feature is provided in  Perl  in  order  to
       match  individual bytes in UTF-8 mode. Because it breaks up UTF-8 char-
       acters into individual bytes, what remains in the string may be a  mal-
       formed  UTF-8  string.  For this reason, the \C escape sequence is best
       avoided.

       PCRE does not allow \C to appear in  lookbehind  assertions  (described
       below),  because  in UTF-8 mode this would make it impossible to calcu-
       late the length of the lookbehind.

SQUARE BRACKETS AND CHARACTER CLASSES

       An opening square bracket introduces a character class, terminated by a
       closing square bracket. A closing square bracket on its own is not spe-
       cial by default.  However, if the PCRE_JAVASCRIPT_COMPAT option is set,
       a lone closing square bracket causes a compile-time error. If a closing
       square bracket is required as a member of the class, it should  be  the
       first  data  character  in  the  class (after an initial circumflex, if
       present) or escaped with a backslash.

       A character class matches a single character in the subject.  In  UTF-8
       mode, the character may be more than one byte long. A matched character
       must be in the set of characters defined by the class, unless the first
       character  in  the  class definition is a circumflex, in which case the
       subject character must not be in the set defined by  the  class.  If  a
       circumflex  is actually required as a member of the class, ensure it is
       not the first character, or escape it with a backslash.

       For example, the character class [aeiou] matches any lower case  vowel,
       while  [^aeiou]  matches  any character that is not a lower case vowel.
       Note that a circumflex is just a convenient notation for specifying the
       characters  that  are in the class by enumerating those that are not. A
       class that starts with a circumflex is not an assertion; it still  con-
       sumes  a  character  from the subject string, and therefore it fails if
       the current pointer is at the end of the string.

       In UTF-8 mode, characters with values greater than 255 can be  included
       in  a  class as a literal string of bytes, or by using the \x{ escaping
       mechanism.

       When caseless matching is set, any letters in a  class  represent  both
       their  upper  case  and lower case versions, so for example, a caseless
       [aeiou] matches "A" as well as "a", and a caseless  [^aeiou]  does  not
       match  "A", whereas a caseful version would. In UTF-8 mode, PCRE always
       understands the concept of case for characters whose  values  are  less
       than  128, so caseless matching is always possible. For characters with
       higher values, the concept of case is supported  if  PCRE  is  compiled
       with  Unicode  property support, but not otherwise.  If you want to use
       caseless matching in UTF8-mode for characters 128 and above,  you  must
       ensure  that  PCRE is compiled with Unicode property support as well as
       with UTF-8 support.

       Characters that might indicate line breaks are  never  treated  in  any
       special  way  when  matching  character  classes,  whatever line-ending
       sequence is in  use,  and  whatever  setting  of  the  PCRE_DOTALL  and
       PCRE_MULTILINE options is used. A class such as [^a] always matches one
       of these characters.

       The minus (hyphen) character can be used to specify a range of  charac-
       ters  in  a  character  class.  For  example,  [d-m] matches any letter
       between d and m, inclusive. If a  minus  character  is  required  in  a
       class,  it  must  be  escaped  with a backslash or appear in a position
       where it cannot be interpreted as indicating a range, typically as  the
       first or last character in the class.

       It is not possible to have the literal character "]" as the end charac-
       ter of a range. A pattern such as [W-]46] is interpreted as a class  of
       two  characters ("W" and "-") followed by a literal string "46]", so it
       would match "W46]" or "-46]". However, if the "]"  is  escaped  with  a
       backslash  it is interpreted as the end of range, so [W-\]46] is inter-
       preted as a class containing a range followed by two other  characters.
       The  octal or hexadecimal representation of "]" can also be used to end
       a range.

       Ranges operate in the collating sequence of character values. They  can
       also   be  used  for  characters  specified  numerically,  for  example
       [\000-\037]. In UTF-8 mode, ranges can include characters whose  values
       are greater than 255, for example [\x{100}-\x{2ff}].

       If a range that includes letters is used when caseless matching is set,
       it matches the letters in either case. For example, [W-c] is equivalent
       to  [][\\^_`wxyzabc],  matched  caselessly,  and  in non-UTF-8 mode, if
       character tables for a French locale are in  use,  [\xc8-\xcb]  matches
       accented  E  characters in both cases. In UTF-8 mode, PCRE supports the
       concept of case for characters with values greater than 128  only  when
       it is compiled with Unicode property support.

       The  character types \d, \D, \p, \P, \s, \S, \w, and \W may also appear
       in a character class, and add the characters that  they  match  to  the
       class. For example, [\dABCDEF] matches any hexadecimal digit. A circum-
       flex can conveniently be used with the upper case  character  types  to
       specify  a  more  restricted  set of characters than the matching lower
       case type. For example, the class [^\W_] matches any letter  or  digit,
       but not underscore.

       The  only  metacharacters  that are recognized in character classes are
       backslash, hyphen (only where it can be  interpreted  as  specifying  a
       range),  circumflex  (only  at the start), opening square bracket (only
       when it can be interpreted as introducing a POSIX class name - see  the
       next  section),  and  the  terminating closing square bracket. However,
       escaping other non-alphanumeric characters does no harm.

POSIX CHARACTER CLASSES

       Perl supports the POSIX notation for character classes. This uses names
       enclosed  by  [: and :] within the enclosing square brackets. PCRE also
       supports this notation. For example,

         [01[:alpha:]%]

       matches "0", "1", any alphabetic character, or "%". The supported class
       names are

         alnum    letters and digits
         alpha    letters
         ascii    character codes 0 - 127
         blank    space or tab only
         cntrl    control characters
         digit    decimal digits (same as \d)
         graph    printing characters, excluding space
         lower    lower case letters
         print    printing characters, including space
         punct    printing characters, excluding letters and digits
         space    white space (not quite the same as \s)
         upper    upper case letters
         word     "word" characters (same as \w)
         xdigit   hexadecimal digits

       The  "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
       and space (32). Notice that this list includes the VT  character  (code
       11). This makes "space" different to \s, which does not include VT (for
       Perl compatibility).

       The name "word" is a Perl extension, and "blank"  is  a  GNU  extension
       from  Perl  5.8. Another Perl extension is negation, which is indicated
       by a ^ character after the colon. For example,

         [12[:^digit:]]

       matches "1", "2", or any non-digit. PCRE (and Perl) also recognize  the
       POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
       these are not supported, and an error is given if they are encountered.

       In UTF-8 mode, characters with values greater than 128 do not match any
       of the POSIX character classes.

VERTICAL BAR

       Vertical  bar characters are used to separate alternative patterns. For
       example, the pattern

         gilbert|sullivan

       matches either "gilbert" or "sullivan". Any number of alternatives  may
       appear,  and  an  empty  alternative  is  permitted (matching the empty
       string). The matching process tries each alternative in turn, from left
       to  right, and the first one that succeeds is used. If the alternatives
       are within a subpattern (defined below), "succeeds" means matching  the
       rest of the main pattern as well as the alternative in the subpattern.

INTERNAL OPTION SETTING

       The  settings  of  the  PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
       PCRE_EXTENDED options (which are Perl-compatible) can be  changed  from
       within  the  pattern  by  a  sequence  of  Perl option letters enclosed
       between "(?" and ")".  The option letters are

         i  for PCRE_CASELESS
         m  for PCRE_MULTILINE
         s  for PCRE_DOTALL
         x  for PCRE_EXTENDED

       For example, (?im) sets caseless, multiline matching. It is also possi-
       ble to unset these options by preceding the letter with a hyphen, and a
       combined setting and unsetting such as (?im-sx), which sets  PCRE_CASE-
       LESS  and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED,
       is also permitted. If a  letter  appears  both  before  and  after  the
       hyphen, the option is unset.

       The  PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and PCRE_EXTRA
       can be changed in the same way as the Perl-compatible options by  using
       the characters J, U and X respectively.

       When  one  of  these  option  changes occurs at top level (that is, not
       inside subpattern parentheses), the change applies to the remainder  of
       the pattern that follows. If the change is placed right at the start of
       a pattern, PCRE extracts it into the global options (and it will there-
       fore show up in data extracted by the pcre_fullinfo() function).

       An  option  change  within a subpattern (see below for a description of
       subpatterns) affects only that part of the current pattern that follows
       it, so

         (a(?i)b)c

       matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
       used).  By this means, options can be made to have  different  settings
       in  different parts of the pattern. Any changes made in one alternative
       do carry on into subsequent branches within the  same  subpattern.  For
       example,

         (a(?i)b|c)

       matches  "ab",  "aB",  "c",  and "C", even though when matching "C" the
       first branch is abandoned before the option setting.  This  is  because
       the  effects  of option settings happen at compile time. There would be
       some very weird behaviour otherwise.

       Note: There are other PCRE-specific options that  can  be  set  by  the
       application  when  the  compile  or match functions are called. In some
       cases the pattern can contain special leading sequences such as (*CRLF)
       to  override  what  the application has set or what has been defaulted.
       Details are given in the section entitled  "Newline  sequences"  above.
       There  is  also  the  (*UTF8)  leading sequence that can be used to set
       UTF-8 mode; this is equivalent to setting the PCRE_UTF8 option.

SUBPATTERNS

       Subpatterns are delimited by parentheses (round brackets), which can be
       nested.  Turning part of a pattern into a subpattern does two things:

       1. It localizes a set of alternatives. For example, the pattern

         cat(aract|erpillar|)

       matches  one  of the words "cat", "cataract", or "caterpillar". Without
       the parentheses, it would match  "cataract",  "erpillar"  or  an  empty
       string.

       2.  It  sets  up  the  subpattern as a capturing subpattern. This means
       that, when the whole pattern  matches,  that  portion  of  the  subject
       string that matched the subpattern is passed back to the caller via the
       ovector argument of pcre_exec(). Opening parentheses are  counted  from
       left  to  right  (starting  from 1) to obtain numbers for the capturing
       subpatterns.

       For example, if the string "the red king" is matched against  the  pat-
       tern

         the ((red|white) (king|queen))

       the captured substrings are "red king", "red", and "king", and are num-
       bered 1, 2, and 3, respectively.

       The fact that plain parentheses fulfil  two  functions  is  not  always
       helpful.   There are often times when a grouping subpattern is required
       without a capturing requirement. If an opening parenthesis is  followed
       by  a question mark and a colon, the subpattern does not do any captur-
       ing, and is not counted when computing the  number  of  any  subsequent
       capturing  subpatterns. For example, if the string "the white queen" is
       matched against the pattern

         the ((?:red|white) (king|queen))

       the captured substrings are "white queen" and "queen", and are numbered
       1 and 2. The maximum number of capturing subpatterns is 65535.

       As  a  convenient shorthand, if any option settings are required at the
       start of a non-capturing subpattern,  the  option  letters  may  appear
       between the "?" and the ":". Thus the two patterns

         (?i:saturday|sunday)
         (?:(?i)saturday|sunday)

       match exactly the same set of strings. Because alternative branches are
       tried from left to right, and options are not reset until  the  end  of
       the  subpattern is reached, an option setting in one branch does affect
       subsequent branches, so the above patterns match "SUNDAY"  as  well  as
       "Saturday".

DUPLICATE SUBPATTERN NUMBERS

       Perl 5.10 introduced a feature whereby each alternative in a subpattern
       uses the same numbers for its capturing parentheses. Such a  subpattern
       starts  with (?| and is itself a non-capturing subpattern. For example,
       consider this pattern:

         (?|(Sat)ur|(Sun))day

       Because the two alternatives are inside a (?| group, both sets of  cap-
       turing  parentheses  are  numbered one. Thus, when the pattern matches,
       you can look at captured substring number  one,  whichever  alternative
       matched.  This  construct  is useful when you want to capture part, but
       not all, of one of a number of alternatives. Inside a (?| group, paren-
       theses  are  numbered as usual, but the number is reset at the start of
       each branch. The numbers of any capturing buffers that follow the  sub-
       pattern  start after the highest number used in any branch. The follow-
       ing example is taken from the Perl documentation.  The  numbers  under-
       neath show in which buffer the captured content will be stored.

         # before  ---------------branch-reset----------- after
         / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
         # 1            2         2  3        2     3     4

       A  back  reference  to a numbered subpattern uses the most recent value
       that is set for that number by any subpattern.  The  following  pattern
       matches "abcabc" or "defdef":

         /(?|(abc)|(def))\1/

       In  contrast, a recursive or "subroutine" call to a numbered subpattern
       always refers to the first one in the pattern with  the  given  number.
       The following pattern matches "abcabc" or "defabc":

         /(?|(abc)|(def))(?1)/

       If  a condition test for a subpattern's having matched refers to a non-
       unique number, the test is true if any of the subpatterns of that  num-
       ber have matched.

       An  alternative approach to using this "branch reset" feature is to use
       duplicate named subpatterns, as described in the next section.

NAMED SUBPATTERNS

       Identifying capturing parentheses by number is simple, but  it  can  be
       very  hard  to keep track of the numbers in complicated regular expres-
       sions. Furthermore, if an  expression  is  modified,  the  numbers  may
       change.  To help with this difficulty, PCRE supports the naming of sub-
       patterns. This feature was not added to Perl until release 5.10. Python
       had  the  feature earlier, and PCRE introduced it at release 4.0, using
       the Python syntax. PCRE now supports both the Perl and the Python  syn-
       tax.  Perl  allows  identically  numbered subpatterns to have different
       names, but PCRE does not.

       In PCRE, a subpattern can be named in one of three  ways:  (?<name>...)
       or  (?'name'...)  as in Perl, or (?P<name>...) as in Python. References
       to capturing parentheses from other parts of the pattern, such as  back
       references,  recursion,  and conditions, can be made by name as well as
       by number.

       Names consist of up to  32  alphanumeric  characters  and  underscores.
       Named  capturing  parentheses  are  still  allocated numbers as well as
       names, exactly as if the names were not present. The PCRE API  provides
       function calls for extracting the name-to-number translation table from
       a compiled pattern. There is also a convenience function for extracting
       a captured substring by name.

       By  default, a name must be unique within a pattern, but it is possible
       to relax this constraint by setting the PCRE_DUPNAMES option at compile
       time.  (Duplicate  names are also always permitted for subpatterns with
       the same number, set up as described in the previous  section.)  Dupli-
       cate  names  can  be useful for patterns where only one instance of the
       named parentheses can match. Suppose you want to match the  name  of  a
       weekday,  either as a 3-letter abbreviation or as the full name, and in
       both cases you want to extract the abbreviation. This pattern (ignoring
       the line breaks) does the job:

         (?<DN>Mon|Fri|Sun)(?:day)?|
         (?<DN>Tue)(?:sday)?|
         (?<DN>Wed)(?:nesday)?|
         (?<DN>Thu)(?:rsday)?|
         (?<DN>Sat)(?:urday)?

       There  are  five capturing substrings, but only one is ever set after a
       match.  (An alternative way of solving this problem is to use a "branch
       reset" subpattern, as described in the previous section.)

       The  convenience  function  for extracting the data by name returns the
       substring for the first (and in this example, the only)  subpattern  of
       that  name  that  matched.  This saves searching to find which numbered
       subpattern it was.

       If you make a back reference to  a  non-unique  named  subpattern  from
       elsewhere  in the pattern, the one that corresponds to the first occur-
       rence of the name is used. In the absence of duplicate numbers (see the
       previous  section) this is the one with the lowest number. If you use a
       named reference in a condition test (see the section  about  conditions
       below),  either  to check whether a subpattern has matched, or to check
       for recursion, all subpatterns with the same name are  tested.  If  the
       condition  is  true for any one of them, the overall condition is true.
       This is the same behaviour as testing by number. For further details of
       the interfaces for handling named subpatterns, see the pcreapi documen-
       tation.

       Warning: You cannot use different names to distinguish between two sub-
       patterns  with  the same number because PCRE uses only the numbers when
       matching. For this reason, an error is given at compile time if differ-
       ent  names  are given to subpatterns with the same number. However, you
       can give the same name to subpatterns with the same number,  even  when
       PCRE_DUPNAMES is not set.

REPETITION

       Repetition  is  specified  by  quantifiers, which can follow any of the
       following items:

         a literal data character
         the dot metacharacter
         the \C escape sequence
         the \X escape sequence (in UTF-8 mode with Unicode properties)
         the \R escape sequence
         an escape such as \d that matches a single character
         a character class
         a back reference (see next section)
         a parenthesized subpattern (unless it is an assertion)
         a recursive or "subroutine" call to a subpattern

       The general repetition quantifier specifies a minimum and maximum  num-
       ber  of  permitted matches, by giving the two numbers in curly brackets
       (braces), separated by a comma. The numbers must be  less  than  65536,
       and the first must be less than or equal to the second. For example:

         z{2,4}

       matches  "zz",  "zzz",  or  "zzzz". A closing brace on its own is not a
       special character. If the second number is omitted, but  the  comma  is
       present,  there  is  no upper limit; if the second number and the comma
       are both omitted, the quantifier specifies an exact number of  required
       matches. Thus

         [aeiou]{3,}

       matches at least 3 successive vowels, but may match many more, while

         \d{8}

       matches  exactly  8  digits. An opening curly bracket that appears in a
       position where a quantifier is not allowed, or one that does not  match
       the  syntax of a quantifier, is taken as a literal character. For exam-
       ple, {,6} is not a quantifier, but a literal string of four characters.

       In UTF-8 mode, quantifiers apply to UTF-8  characters  rather  than  to
       individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-
       acters, each of which is represented by a two-byte sequence. Similarly,
       when Unicode property support is available, \X{3} matches three Unicode
       extended sequences, each of which may be several bytes long  (and  they
       may be of different lengths).

       The quantifier {0} is permitted, causing the expression to behave as if
       the previous item and the quantifier were not present. This may be use-
       ful  for  subpatterns that are referenced as subroutines from elsewhere
       in the pattern. Items other than subpatterns that have a {0} quantifier
       are omitted from the compiled pattern.

       For  convenience, the three most common quantifiers have single-charac-
       ter abbreviations:

         *    is equivalent to {0,}
         +    is equivalent to {1,}
         ?    is equivalent to {0,1}

       It is possible to construct infinite loops by  following  a  subpattern
       that can match no characters with a quantifier that has no upper limit,
       for example:

         (a?)*

       Earlier versions of Perl and PCRE used to give an error at compile time
       for  such  patterns. However, because there are cases where this can be
       useful, such patterns are now accepted, but if any  repetition  of  the
       subpattern  does in fact match no characters, the loop is forcibly bro-
       ken.

       By default, the quantifiers are "greedy", that is, they match  as  much
       as  possible  (up  to  the  maximum number of permitted times), without
       causing the rest of the pattern to fail. The classic example  of  where
       this gives problems is in trying to match comments in C programs. These
       appear between /* and */ and within the comment,  individual  *  and  /
       characters  may  appear. An attempt to match C comments by applying the
       pattern

         /\*.*\*/

       to the string

         /* first comment */  not comment  /* second comment */

       fails, because it matches the entire string owing to the greediness  of
       the .*  item.

       However,  if  a quantifier is followed by a question mark, it ceases to
       be greedy, and instead matches the minimum number of times possible, so
       the pattern

         /\*.*?\*/

       does  the  right  thing with the C comments. The meaning of the various
       quantifiers is not otherwise changed,  just  the  preferred  number  of
       matches.   Do  not  confuse this use of question mark with its use as a
       quantifier in its own right. Because it has two uses, it can  sometimes
       appear doubled, as in

         \d??\d

       which matches one digit by preference, but can match two if that is the
       only way the rest of the pattern matches.

       If the PCRE_UNGREEDY option is set (an option that is not available  in
       Perl),  the  quantifiers are not greedy by default, but individual ones
       can be made greedy by following them with a  question  mark.  In  other
       words, it inverts the default behaviour.

       When  a  parenthesized  subpattern  is quantified with a minimum repeat
       count that is greater than 1 or with a limited maximum, more memory  is
       required  for  the  compiled  pattern, in proportion to the size of the
       minimum or maximum.

       If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-
       alent  to  Perl's  /s) is set, thus allowing the dot to match newlines,
       the pattern is implicitly anchored, because whatever  follows  will  be
       tried  against every character position in the subject string, so there
       is no point in retrying the overall match at  any  position  after  the
       first.  PCRE  normally treats such a pattern as though it were preceded
       by \A.

       In cases where it is known that the subject  string  contains  no  new-
       lines,  it  is  worth setting PCRE_DOTALL in order to obtain this opti-
       mization, or alternatively using ^ to indicate anchoring explicitly.

       However, there is one situation where the optimization cannot be  used.
       When .*  is inside capturing parentheses that are the subject of a back
       reference elsewhere in the pattern, a match at the start may fail where
       a later one succeeds. Consider, for example:

         (.*)abc\1

       If  the subject is "xyz123abc123" the match point is the fourth charac-
       ter. For this reason, such a pattern is not implicitly anchored.

       When a capturing subpattern is repeated, the value captured is the sub-
       string that matched the final iteration. For example, after

         (tweedle[dume]{3}\s*)+

       has matched "tweedledum tweedledee" the value of the captured substring
       is "tweedledee". However, if there are  nested  capturing  subpatterns,
       the  corresponding captured values may have been set in previous itera-
       tions. For example, after

         /(a|(b))+/

       matches "aba" the value of the second captured substring is "b".

ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS

       With both maximizing ("greedy") and minimizing ("ungreedy"  or  "lazy")
       repetition,  failure  of what follows normally causes the repeated item
       to be re-evaluated to see if a different number of repeats  allows  the
       rest  of  the pattern to match. Sometimes it is useful to prevent this,
       either to change the nature of the match, or to cause it  fail  earlier
       than  it otherwise might, when the author of the pattern knows there is
       no point in carrying on.

       Consider, for example, the pattern \d+foo when applied to  the  subject
       line

         123456bar

       After matching all 6 digits and then failing to match "foo", the normal
       action of the matcher is to try again with only 5 digits  matching  the
       \d+  item,  and  then  with  4,  and  so on, before ultimately failing.
       "Atomic grouping" (a term taken from Jeffrey  Friedl's  book)  provides
       the  means for specifying that once a subpattern has matched, it is not
       to be re-evaluated in this way.

       If we use atomic grouping for the previous example, the  matcher  gives
       up  immediately  on failing to match "foo" the first time. The notation
       is a kind of special parenthesis, starting with (?> as in this example:

         (?>\d+)foo

       This kind of parenthesis "locks up" the  part of the  pattern  it  con-
       tains  once  it  has matched, and a failure further into the pattern is
       prevented from backtracking into it. Backtracking past it  to  previous
       items, however, works as normal.

       An  alternative  description  is that a subpattern of this type matches
       the string of characters that an  identical  standalone  pattern  would
       match, if anchored at the current point in the subject string.

       Atomic grouping subpatterns are not capturing subpatterns. Simple cases
       such as the above example can be thought of as a maximizing repeat that
       must  swallow  everything  it can. So, while both \d+ and \d+? are pre-
       pared to adjust the number of digits they match in order  to  make  the
       rest of the pattern match, (?>\d+) can only match an entire sequence of
       digits.

       Atomic groups in general can of course contain arbitrarily  complicated
       subpatterns,  and  can  be  nested. However, when the subpattern for an
       atomic group is just a single repeated item, as in the example above, a
       simpler  notation,  called  a "possessive quantifier" can be used. This
       consists of an additional + character  following  a  quantifier.  Using
       this notation, the previous example can be rewritten as

         \d++foo

       Note that a possessive quantifier can be used with an entire group, for
       example:

         (abc|xyz){2,3}+

       Possessive  quantifiers  are  always  greedy;  the   setting   of   the
       PCRE_UNGREEDY option is ignored. They are a convenient notation for the
       simpler forms of atomic group. However, there is no difference  in  the
       meaning  of  a  possessive  quantifier and the equivalent atomic group,
       though there may be a performance  difference;  possessive  quantifiers
       should be slightly faster.

       The  possessive  quantifier syntax is an extension to the Perl 5.8 syn-
       tax.  Jeffrey Friedl originated the idea (and the name)  in  the  first
       edition of his book. Mike McCloskey liked it, so implemented it when he
       built Sun's Java package, and PCRE copied it from there. It  ultimately
       found its way into Perl at release 5.10.

       PCRE has an optimization that automatically "possessifies" certain sim-
       ple pattern constructs. For example, the sequence  A+B  is  treated  as
       A++B  because  there is no point in backtracking into a sequence of A's
       when B must follow.

       When a pattern contains an unlimited repeat inside  a  subpattern  that
       can  itself  be  repeated  an  unlimited number of times, the use of an
       atomic group is the only way to avoid some  failing  matches  taking  a
       very long time indeed. The pattern

         (\D+|<\d+>)*[!?]

       matches  an  unlimited number of substrings that either consist of non-
       digits, or digits enclosed in <>, followed by either ! or  ?.  When  it
       matches, it runs quickly. However, if it is applied to

         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

       it  takes  a  long  time  before reporting failure. This is because the
       string can be divided between the internal \D+ repeat and the  external
       *  repeat  in  a  large  number of ways, and all have to be tried. (The
       example uses [!?] rather than a single character at  the  end,  because
       both  PCRE  and  Perl have an optimization that allows for fast failure
       when a single character is used. They remember the last single  charac-
       ter  that  is required for a match, and fail early if it is not present
       in the string.) If the pattern is changed so that  it  uses  an  atomic
       group, like this:

         ((?>\D+)|<\d+>)*[!?]

       sequences of non-digits cannot be broken, and failure happens quickly.

BACK REFERENCES

       Outside a character class, a backslash followed by a digit greater than
       0 (and possibly further digits) is a back reference to a capturing sub-
       pattern  earlier  (that is, to its left) in the pattern, provided there
       have been that many previous capturing left parentheses.

       However, if the decimal number following the backslash is less than 10,
       it  is  always  taken  as a back reference, and causes an error only if
       there are not that many capturing left parentheses in the  entire  pat-
       tern.  In  other words, the parentheses that are referenced need not be
       to the left of the reference for numbers less than 10. A "forward  back
       reference"  of  this  type can make sense when a repetition is involved
       and the subpattern to the right has participated in an  earlier  itera-
       tion.

       It  is  not  possible to have a numerical "forward back reference" to a
       subpattern whose number is 10 or  more  using  this  syntax  because  a
       sequence  such  as  \50 is interpreted as a character defined in octal.
       See the subsection entitled "Non-printing characters" above for further
       details  of  the  handling of digits following a backslash. There is no
       such problem when named parentheses are used. A back reference  to  any
       subpattern is possible using named parentheses (see below).

       Another  way  of  avoiding  the ambiguity inherent in the use of digits
       following a backslash is to use the \g escape sequence, which is a fea-
       ture  introduced  in  Perl  5.10.  This  escape  must be followed by an
       unsigned number or a negative number, optionally  enclosed  in  braces.
       These examples are all identical:

         (ring), \1
         (ring), \g1
         (ring), \g{1}

       An  unsigned number specifies an absolute reference without the ambigu-
       ity that is present in the older syntax. It is also useful when literal
       digits follow the reference. A negative number is a relative reference.
       Consider this example:

         (abc(def)ghi)\g{-1}

       The sequence \g{-1} is a reference to the most recently started captur-
       ing  subpattern  before \g, that is, is it equivalent to \2. Similarly,
       \g{-2} would be equivalent to \1. The use of relative references can be
       helpful  in  long  patterns,  and  also in patterns that are created by
       joining together fragments that contain references within themselves.

       A back reference matches whatever actually matched the  capturing  sub-
       pattern  in  the  current subject string, rather than anything matching
       the subpattern itself (see "Subpatterns as subroutines" below for a way
       of doing that). So the pattern

         (sens|respons)e and \1ibility

       matches  "sense and sensibility" and "response and responsibility", but
       not "sense and responsibility". If caseful matching is in force at  the
       time  of the back reference, the case of letters is relevant. For exam-
       ple,

         ((?i)rah)\s+\1

       matches "rah rah" and "RAH RAH", but not "RAH  rah",  even  though  the
       original capturing subpattern is matched caselessly.

       There  are  several  different ways of writing back references to named
       subpatterns. The .NET syntax \k{name} and the Perl syntax  \k<name>  or
       \k'name'  are supported, as is the Python syntax (?P=name). Perl 5.10's
       unified back reference syntax, in which \g can be used for both numeric
       and  named  references,  is  also supported. We could rewrite the above
       example in any of the following ways:

         (?<p1>(?i)rah)\s+\k<p1>
         (?'p1'(?i)rah)\s+\k{p1}
         (?P<p1>(?i)rah)\s+(?P=p1)
         (?<p1>(?i)rah)\s+\g{p1}

       A subpattern that is referenced by  name  may  appear  in  the  pattern
       before or after the reference.

       There  may be more than one back reference to the same subpattern. If a
       subpattern has not actually been used in a particular match,  any  back
       references to it always fail by default. For example, the pattern

         (a|(bc))\2

       always  fails  if  it starts to match "a" rather than "bc". However, if
       the PCRE_JAVASCRIPT_COMPAT option is set at compile time, a back refer-
       ence to an unset value matches an empty string.

       Because  there may be many capturing parentheses in a pattern, all dig-
       its following a backslash are taken as part of a potential back  refer-
       ence  number.   If  the  pattern continues with a digit character, some
       delimiter must  be  used  to  terminate  the  back  reference.  If  the
       PCRE_EXTENDED option is set, this can be whitespace. Otherwise, the \g{
       syntax or an empty comment (see "Comments" below) can be used.

   Recursive back references

       A back reference that occurs inside the parentheses to which it  refers
       fails  when  the subpattern is first used, so, for example, (a\1) never
       matches.  However, such references can be useful inside  repeated  sub-
       patterns. For example, the pattern

         (a|b\1)+

       matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-
       ation of the subpattern,  the  back  reference  matches  the  character
       string  corresponding  to  the previous iteration. In order for this to
       work, the pattern must be such that the first iteration does  not  need
       to  match the back reference. This can be done using alternation, as in
       the example above, or by a quantifier with a minimum of zero.

       Back references of this type cause the group that they reference to  be
       treated  as  an atomic group.  Once the whole group has been matched, a
       subsequent matching failure cannot cause backtracking into  the  middle
       of the group.

ASSERTIONS

       An  assertion  is  a  test on the characters following or preceding the
       current matching point that does not actually consume  any  characters.
       The  simple  assertions  coded  as  \b, \B, \A, \G, \Z, \z, ^ and $ are
       described above.

       More complicated assertions are coded as  subpatterns.  There  are  two
       kinds:  those  that  look  ahead of the current position in the subject
       string, and those that look  behind  it.  An  assertion  subpattern  is
       matched  in  the  normal way, except that it does not cause the current
       matching position to be changed.

       Assertion subpatterns are not capturing subpatterns,  and  may  not  be
       repeated,  because  it  makes no sense to assert the same thing several
       times. If any kind of assertion contains capturing  subpatterns  within
       it,  these are counted for the purposes of numbering the capturing sub-
       patterns in the whole pattern.  However, substring capturing is carried
       out  only  for  positive assertions, because it does not make sense for
       negative assertions.

   Lookahead assertions

       Lookahead assertions start with (?= for positive assertions and (?! for
       negative assertions. For example,

         \w+(?=;)

       matches  a word followed by a semicolon, but does not include the semi-
       colon in the match, and

         foo(?!bar)

       matches any occurrence of "foo" that is not  followed  by  "bar".  Note
       that the apparently similar pattern

         (?!foo)bar

       does  not  find  an  occurrence  of "bar" that is preceded by something
       other than "foo"; it finds any occurrence of "bar" whatsoever,  because
       the assertion (?!foo) is always true when the next three characters are
       "bar". A lookbehind assertion is needed to achieve the other effect.

       If you want to force a matching failure at some point in a pattern, the
       most  convenient  way  to  do  it  is with (?!) because an empty string
       always matches, so an assertion that requires there not to be an  empty
       string  must  always  fail.   The  Perl  5.10 backtracking control verb
       (*FAIL) or (*F) is essentially a synonym for (?!).

   Lookbehind assertions

       Lookbehind assertions start with (?<= for positive assertions and  (?<!
       for negative assertions. For example,

         (?<!foo)bar

       does  find  an  occurrence  of "bar" that is not preceded by "foo". The
       contents of a lookbehind assertion are restricted  such  that  all  the
       strings it matches must have a fixed length. However, if there are sev-
       eral top-level alternatives, they do not all  have  to  have  the  same
       fixed length. Thus

         (?<=bullock|donkey)

       is permitted, but

         (?<!dogs?|cats?)

       causes  an  error at compile time. Branches that match different length
       strings are permitted only at the top level of a lookbehind  assertion.
       This  is an extension compared with Perl (5.8 and 5.10), which requires
       all branches to match the same length of string. An assertion such as

         (?<=ab(c|de))

       is not permitted, because its single top-level  branch  can  match  two
       different lengths, but it is acceptable to PCRE if rewritten to use two
       top-level branches:

         (?<=abc|abde)

       In some cases, the Perl 5.10 escape sequence \K (see above) can be used
       instead  of  a  lookbehind  assertion  to  get  round  the fixed-length
       restriction.

       The implementation of lookbehind assertions is, for  each  alternative,
       to  temporarily  move the current position back by the fixed length and
       then try to match. If there are insufficient characters before the cur-
       rent position, the assertion fails.

       PCRE does not allow the \C escape (which matches a single byte in UTF-8
       mode) to appear in lookbehind assertions, because it makes it  impossi-
       ble  to  calculate the length of the lookbehind. The \X and \R escapes,
       which can match different numbers of bytes, are also not permitted.

       "Subroutine" calls (see below) such as (?2) or (?&X) are  permitted  in
       lookbehinds,  as  long as the subpattern matches a fixed-length string.
       Recursion, however, is not supported.

       Possessive quantifiers can  be  used  in  conjunction  with  lookbehind
       assertions to specify efficient matching of fixed-length strings at the
       end of subject strings. Consider a simple pattern such as

         abcd$

       when applied to a long string that does  not  match.  Because  matching
       proceeds from left to right, PCRE will look for each "a" in the subject
       and then see if what follows matches the rest of the  pattern.  If  the
       pattern is specified as

         ^.*abcd$

       the  initial .* matches the entire string at first, but when this fails
       (because there is no following "a"), it backtracks to match all but the
       last  character,  then all but the last two characters, and so on. Once
       again the search for "a" covers the entire string, from right to  left,
       so we are no better off. However, if the pattern is written as

         ^.*+(?<=abcd)

       there  can  be  no backtracking for the .*+ item; it can match only the
       entire string. The subsequent lookbehind assertion does a  single  test
       on  the last four characters. If it fails, the match fails immediately.
       For long strings, this approach makes a significant difference  to  the
       processing time.

   Using multiple assertions

       Several assertions (of any sort) may occur in succession. For example,

         (?<=\d{3})(?<!999)foo

       matches  "foo" preceded by three digits that are not "999". Notice that
       each of the assertions is applied independently at the  same  point  in
       the  subject  string.  First  there  is a check that the previous three
       characters are all digits, and then there is  a  check  that  the  same
       three characters are not "999".  This pattern does not match "foo" pre-
       ceded by six characters, the first of which are  digits  and  the  last
       three  of  which  are not "999". For example, it doesn't match "123abc-
       foo". A pattern to do that is

         (?<=\d{3}...)(?<!999)foo

       This time the first assertion looks at the  preceding  six  characters,
       checking that the first three are digits, and then the second assertion
       checks that the preceding three characters are not "999".

       Assertions can be nested in any combination. For example,

         (?<=(?<!foo)bar)baz

       matches an occurrence of "baz" that is preceded by "bar" which in  turn
       is not preceded by "foo", while

         (?<=\d{3}(?!999)...)foo

       is  another pattern that matches "foo" preceded by three digits and any
       three characters that are not "999".

CONDITIONAL SUBPATTERNS

       It is possible to cause the matching process to obey a subpattern  con-
       ditionally  or to choose between two alternative subpatterns, depending
       on the result of an assertion, or whether a specific capturing  subpat-
       tern  has  already  been matched. The two possible forms of conditional
       subpattern are:

         (?(condition)yes-pattern)
         (?(condition)yes-pattern|no-pattern)

       If the condition is satisfied, the yes-pattern is used;  otherwise  the
       no-pattern  (if  present)  is used. If there are more than two alterna-
       tives in the subpattern, a compile-time error occurs.

       There are four kinds of condition: references  to  subpatterns,  refer-
       ences to recursion, a pseudo-condition called DEFINE, and assertions.

   Checking for a used subpattern by number

       If  the  text between the parentheses consists of a sequence of digits,
       the condition is true if a capturing subpattern of that number has pre-
       viously  matched.  If  there is more than one capturing subpattern with
       the same number (see the earlier  section  about  duplicate  subpattern
       numbers), the condition is true if any of them have been set. An alter-
       native notation is to precede the digits with a plus or minus sign.  In
       this  case, the subpattern number is relative rather than absolute. The
       most recently opened parentheses can be referenced by (?(-1), the  next
       most  recent  by  (?(-2),  and so on. In looping constructs it can also
       make sense to refer  to  subsequent  groups  with  constructs  such  as
       (?(+2).

       Consider  the  following  pattern, which contains non-significant white
       space to make it more readable (assume the PCRE_EXTENDED option) and to
       divide it into three parts for ease of discussion:

         ( \( )?    [^()]+    (?(1) \) )

       The  first  part  matches  an optional opening parenthesis, and if that
       character is present, sets it as the first captured substring. The sec-
       ond  part  matches one or more characters that are not parentheses. The
       third part is a conditional subpattern that tests whether the first set
       of parentheses matched or not. If they did, that is, if subject started
       with an opening parenthesis, the condition is true, and so the yes-pat-
       tern  is  executed  and  a  closing parenthesis is required. Otherwise,
       since no-pattern is not present, the  subpattern  matches  nothing.  In
       other  words,  this  pattern  matches  a  sequence  of non-parentheses,
       optionally enclosed in parentheses.

       If you were embedding this pattern in a larger one,  you  could  use  a
       relative reference:

         ...other stuff... ( \( )?    [^()]+    (?(-1) \) ) ...

       This  makes  the  fragment independent of the parentheses in the larger
       pattern.

   Checking for a used subpattern by name

       Perl uses the syntax (?(<name>)...) or (?('name')...)  to  test  for  a
       used  subpattern  by  name.  For compatibility with earlier versions of
       PCRE, which had this facility before Perl, the syntax  (?(name)...)  is
       also  recognized. However, there is a possible ambiguity with this syn-
       tax, because subpattern names may  consist  entirely  of  digits.  PCRE
       looks  first for a named subpattern; if it cannot find one and the name
       consists entirely of digits, PCRE looks for a subpattern of  that  num-
       ber,  which must be greater than zero. Using subpattern names that con-
       sist entirely of digits is not recommended.

       Rewriting the above example to use a named subpattern gives this:

         (?<OPEN> \( )?    [^()]+    (?(<OPEN>) \) )

       If the name used in a condition of this kind is a duplicate,  the  test
       is  applied to all subpatterns of the same name, and is true if any one
       of them has matched.

   Checking for pattern recursion

       If the condition is the string (R), and there is no subpattern with the
       name  R, the condition is true if a recursive call to the whole pattern
       or any subpattern has been made. If digits or a name preceded by amper-
       sand follow the letter R, for example:

         (?(R3)...) or (?(R&name)...)

       the condition is true if the most recent recursion is into a subpattern
       whose number or name is given. This condition does not check the entire
       recursion  stack.  If  the  name  used in a condition of this kind is a
       duplicate, the test is applied to all subpatterns of the same name, and
       is true if any one of them is the most recent recursion.

       At  "top  level",  all  these recursion test conditions are false.  The
       syntax for recursive patterns is described below.

   Defining subpatterns for use by reference only

       If the condition is the string (DEFINE), and  there  is  no  subpattern
       with  the  name  DEFINE,  the  condition is always false. In this case,
       there may be only one alternative  in  the  subpattern.  It  is  always
       skipped  if  control  reaches  this  point  in the pattern; the idea of
       DEFINE is that it can be used to define "subroutines" that can be  ref-
       erenced  from elsewhere. (The use of "subroutines" is described below.)
       For example, a pattern to match an IPv4 address could be  written  like
       this (ignore whitespace and line breaks):

         (?(DEFINE) (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d) )
         \b (?&byte) (\.(?&byte)){3} \b

       The  first part of the pattern is a DEFINE group inside which a another
       group named "byte" is defined. This matches an individual component  of
       an  IPv4  address  (a number less than 256). When matching takes place,
       this part of the pattern is skipped because DEFINE acts  like  a  false
       condition.  The  rest of the pattern uses references to the named group
       to match the four dot-separated components of an IPv4 address,  insist-
       ing on a word boundary at each end.

   Assertion conditions

       If  the  condition  is  not  in any of the above formats, it must be an
       assertion.  This may be a positive or negative lookahead or  lookbehind
       assertion.  Consider  this  pattern,  again  containing non-significant
       white space, and with the two alternatives on the second line:

         (?(?=[^a-z]*[a-z])
         \d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

       The condition  is  a  positive  lookahead  assertion  that  matches  an
       optional  sequence of non-letters followed by a letter. In other words,
       it tests for the presence of at least one letter in the subject.  If  a
       letter  is found, the subject is matched against the first alternative;
       otherwise it is  matched  against  the  second.  This  pattern  matches
       strings  in  one  of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
       letters and dd are digits.

COMMENTS

       The sequence (?# marks the start of a comment that continues up to  the
       next  closing  parenthesis.  Nested  parentheses are not permitted. The
       characters that make up a comment play no part in the pattern  matching
       at all.

       If  the PCRE_EXTENDED option is set, an unescaped # character outside a
       character class introduces a  comment  that  continues  to  immediately
       after the next newline in the pattern.

RECURSIVE PATTERNS

       Consider  the problem of matching a string in parentheses, allowing for
       unlimited nested parentheses. Without the use of  recursion,  the  best
       that  can  be  done  is  to use a pattern that matches up to some fixed
       depth of nesting. It is not possible to  handle  an  arbitrary  nesting
       depth.

       For some time, Perl has provided a facility that allows regular expres-
       sions to recurse (amongst other things). It does this by  interpolating
       Perl  code in the expression at run time, and the code can refer to the
       expression itself. A Perl pattern using code interpolation to solve the
       parentheses problem can be created like this:

         $re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;

       The (?p{...}) item interpolates Perl code at run time, and in this case
       refers recursively to the pattern in which it appears.

       Obviously, PCRE cannot support the interpolation of Perl code. Instead,
       it  supports  special  syntax  for recursion of the entire pattern, and
       also for individual subpattern recursion.  After  its  introduction  in
       PCRE  and  Python,  this  kind of recursion was subsequently introduced
       into Perl at release 5.10.

       A special item that consists of (? followed by a  number  greater  than
       zero and a closing parenthesis is a recursive call of the subpattern of
       the given number, provided that it occurs inside that  subpattern.  (If
       not,  it  is  a  "subroutine" call, which is described in the next sec-
       tion.) The special item (?R) or (?0) is a recursive call of the  entire
       regular expression.

       This  PCRE  pattern  solves  the nested parentheses problem (assume the
       PCRE_EXTENDED option is set so that white space is ignored):

         \( ( [^()]++ | (?R) )* \)

       First it matches an opening parenthesis. Then it matches any number  of
       substrings  which  can  either  be  a sequence of non-parentheses, or a
       recursive match of the pattern itself (that is, a  correctly  parenthe-
       sized substring).  Finally there is a closing parenthesis. Note the use
       of a possessive quantifier to avoid backtracking into sequences of non-
       parentheses.

       If  this  were  part of a larger pattern, you would not want to recurse
       the entire pattern, so instead you could use this:

         ( \( ( [^()]++ | (?1) )* \) )

       We have put the pattern into parentheses, and caused the  recursion  to
       refer to them instead of the whole pattern.

       In  a  larger  pattern,  keeping  track  of  parenthesis numbers can be
       tricky. This is made easier by the use of relative references  (a  Perl
       5.10  feature).   Instead  of  (?1)  in the pattern above you can write
       (?-2) to refer to the second most recently opened parentheses preceding
       the  recursion.  In  other  words,  a  negative number counts capturing
       parentheses leftwards from the point at which it is encountered.

       It is also possible to refer to  subsequently  opened  parentheses,  by
       writing  references  such  as (?+2). However, these cannot be recursive
       because the reference is not inside the  parentheses  that  are  refer-
       enced.  They  are  always  "subroutine" calls, as described in the next
       section.

       An alternative approach is to use named parentheses instead.  The  Perl
       syntax  for  this  is (?&name); PCRE's earlier syntax (?P>name) is also
       supported. We could rewrite the above example as follows:

         (?<pn> \( ( [^()]++ | (?&pn) )* \) )

       If there is more than one subpattern with the same name,  the  earliest
       one is used.

       This  particular  example pattern that we have been looking at contains
       nested unlimited repeats, and so the use of a possessive quantifier for
       matching strings of non-parentheses is important when applying the pat-
       tern to strings that do not match. For example, when  this  pattern  is
       applied to

         (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()

       it  yields  "no  match" quickly. However, if a possessive quantifier is
       not used, the match runs for a very long time indeed because there  are
       so  many  different  ways the + and * repeats can carve up the subject,
       and all have to be tested before failure can be reported.

       At the end of a match, the values of capturing  parentheses  are  those
       from  the outermost level. If you want to obtain intermediate values, a
       callout function can be used (see below and the pcrecallout  documenta-
       tion). If the pattern above is matched against

         (ab(cd)ef)

       the  value  for  the  inner capturing parentheses (numbered 2) is "ef",
       which is the last value taken on at the top level. If a capturing  sub-
       pattern is not matched at the top level, its final value is unset, even
       if it is (temporarily) set at a deeper level.

       If there are more than 15 capturing parentheses in a pattern, PCRE  has
       to  obtain extra memory to store data during a recursion, which it does
       by using pcre_malloc, freeing it via pcre_free afterwards. If no memory
       can be obtained, the match fails with the PCRE_ERROR_NOMEMORY error.

       Do  not  confuse  the (?R) item with the condition (R), which tests for
       recursion.  Consider this pattern, which matches text in  angle  brack-
       ets,  allowing for arbitrary nesting. Only digits are allowed in nested
       brackets (that is, when recursing), whereas any characters are  permit-
       ted at the outer level.

         < (?: (?(R) \d++  | [^<>]*+) | (?R)) * >

       In  this  pattern, (?(R) is the start of a conditional subpattern, with
       two different alternatives for the recursive and  non-recursive  cases.
       The (?R) item is the actual recursive call.

   Recursion difference from Perl

       In  PCRE (like Python, but unlike Perl), a recursive subpattern call is
       always treated as an atomic group. That is, once it has matched some of
       the subject string, it is never re-entered, even if it contains untried
       alternatives and there is a subsequent matching failure.  This  can  be
       illustrated  by the following pattern, which purports to match a palin-
       dromic string that contains an odd number of characters  (for  example,
       "a", "aba", "abcba", "abcdcba"):

         ^(.|(.)(?1)\2)$

       The idea is that it either matches a single character, or two identical
       characters surrounding a sub-palindrome. In Perl, this  pattern  works;
       in  PCRE  it  does  not if the pattern is longer than three characters.
       Consider the subject string "abcba":

       At the top level, the first character is matched, but as it is  not  at
       the end of the string, the first alternative fails; the second alterna-
       tive is taken and the recursion kicks in. The recursive call to subpat-
       tern  1  successfully  matches the next character ("b"). (Note that the
       beginning and end of line tests are not part of the recursion).

       Back at the top level, the next character ("c") is compared  with  what
       subpattern  2 matched, which was "a". This fails. Because the recursion
       is treated as an atomic group, there are now  no  backtracking  points,
       and  so  the  entire  match fails. (Perl is able, at this point, to re-
       enter the recursion and try the second alternative.)  However,  if  the
       pattern is written with the alternatives in the other order, things are
       different:

         ^((.)(?1)\2|.)$

       This time, the recursing alternative is tried first, and  continues  to
       recurse  until  it runs out of characters, at which point the recursion
       fails. But this time we do have  another  alternative  to  try  at  the
       higher  level.  That  is  the  big difference: in the previous case the
       remaining alternative is at a deeper recursion level, which PCRE cannot
       use.

       To change the pattern so that matches all palindromic strings, not just
       those with an odd number of characters, it is tempting  to  change  the
       pattern to this:

         ^((.)(?1)\2|.?)$

       Again,  this  works  in Perl, but not in PCRE, and for the same reason.
       When a deeper recursion has matched a single character,  it  cannot  be
       entered  again  in  order  to match an empty string. The solution is to
       separate the two cases, and write out the odd and even cases as  alter-
       natives at the higher level:

         ^(?:((.)(?1)\2|)|((.)(?3)\4|.))

       If  you  want  to match typical palindromic phrases, the pattern has to
       ignore all non-word characters, which can be done like this:

         ^\W*+(?:((.)\W*+(?1)\W*+\2|)|((.)\W*+(?3)\W*+\4|\W*+.\W*+))\W*+$

       If run with the PCRE_CASELESS option, this pattern matches phrases such
       as "A man, a plan, a canal: Panama!" and it works well in both PCRE and
       Perl. Note the use of the possessive quantifier *+ to avoid  backtrack-
       ing  into  sequences of non-word characters. Without this, PCRE takes a
       great deal longer (ten times or more) to  match  typical  phrases,  and
       Perl takes so long that you think it has gone into a loop.

       WARNING:  The  palindrome-matching patterns above work only if the sub-
       ject string does not start with a palindrome that is shorter  than  the
       entire  string.  For example, although "abcba" is correctly matched, if
       the subject is "ababa", PCRE finds the palindrome "aba" at  the  start,
       then  fails at top level because the end of the string does not follow.
       Once again, it cannot jump back into the recursion to try other  alter-
       natives, so the entire match fails.

SUBPATTERNS AS SUBROUTINES

       If the syntax for a recursive subpattern reference (either by number or
       by name) is used outside the parentheses to which it refers,  it  oper-
       ates  like a subroutine in a programming language. The "called" subpat-
       tern may be defined before or after the reference. A numbered reference
       can be absolute or relative, as in these examples:

         (...(absolute)...)...(?2)...
         (...(relative)...)...(?-1)...
         (...(?+1)...(relative)...

       An earlier example pointed out that the pattern

         (sens|respons)e and \1ibility

       matches  "sense and sensibility" and "response and responsibility", but
       not "sense and responsibility". If instead the pattern

         (sens|respons)e and (?1)ibility

       is used, it does match "sense and responsibility" as well as the  other
       two  strings.  Another  example  is  given  in the discussion of DEFINE
       above.

       Like recursive subpatterns, a subroutine call is always treated  as  an
       atomic  group. That is, once it has matched some of the subject string,
       it is never re-entered, even if it contains  untried  alternatives  and
       there  is a subsequent matching failure. Any capturing parentheses that
       are set during the subroutine call  revert  to  their  previous  values
       afterwards.

       When  a  subpattern is used as a subroutine, processing options such as
       case-independence are fixed when the subpattern is defined. They cannot
       be changed for different calls. For example, consider this pattern:

         (abc)(?i:(?-1))

       It  matches  "abcabc". It does not match "abcABC" because the change of
       processing option does not affect the called subpattern.

ONIGURUMA SUBROUTINE SYNTAX

       For compatibility with Oniguruma, the non-Perl syntax \g followed by  a
       name or a number enclosed either in angle brackets or single quotes, is
       an alternative syntax for referencing a  subpattern  as  a  subroutine,
       possibly  recursively. Here are two of the examples used above, rewrit-
       ten using this syntax:

         (?<pn> \( ( (?>[^()]+) | \g<pn> )* \) )
         (sens|respons)e and \g'1'ibility

       PCRE supports an extension to Oniguruma: if a number is preceded  by  a
       plus or a minus sign it is taken as a relative reference. For example:

         (abc)(?i:\g<-1>)

       Note  that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are not
       synonymous. The former is a back reference; the latter is a  subroutine
       call.

CALLOUTS

       Perl has a feature whereby using the sequence (?{...}) causes arbitrary
       Perl code to be obeyed in the middle of matching a regular  expression.
       This makes it possible, amongst other things, to extract different sub-
       strings that match the same pair of parentheses when there is a repeti-
       tion.

       PCRE provides a similar feature, but of course it cannot obey arbitrary
       Perl code. The feature is called "callout". The caller of PCRE provides
       an  external function by putting its entry point in the global variable
       pcre_callout.  By default, this variable contains NULL, which  disables
       all calling out.

       Within  a  regular  expression,  (?C) indicates the points at which the
       external function is to be called. If you want  to  identify  different
       callout  points, you can put a number less than 256 after the letter C.
       The default value is zero.  For example, this pattern has  two  callout
       points:

         (?C1)abc(?C2)def

       If the PCRE_AUTO_CALLOUT flag is passed to pcre_compile(), callouts are
       automatically installed before each item in the pattern. They  are  all
       numbered 255.

       During matching, when PCRE reaches a callout point (and pcre_callout is
       set), the external function is called. It is provided with  the  number
       of  the callout, the position in the pattern, and, optionally, one item
       of data originally supplied by the caller of pcre_exec().  The  callout
       function  may cause matching to proceed, to backtrack, or to fail alto-
       gether. A complete description of the interface to the callout function
       is given in the pcrecallout documentation.

BACKTRACKING CONTROL

       Perl  5.10 introduced a number of "Special Backtracking Control Verbs",
       which are described in the Perl documentation as "experimental and sub-
       ject  to  change or removal in a future version of Perl". It goes on to
       say: "Their usage in production code should be noted to avoid  problems
       during upgrades." The same remarks apply to the PCRE features described
       in this section.

       Since these verbs are specifically related  to  backtracking,  most  of
       them  can  be  used  only  when  the  pattern  is  to  be matched using
       pcre_exec(), which uses a backtracking algorithm. With the exception of
       (*FAIL), which behaves like a failing negative assertion, they cause an
       error if encountered by pcre_dfa_exec().

       If any of these verbs are used in an assertion or subroutine subpattern
       (including  recursive  subpatterns),  their  effect is confined to that
       subpattern; it does not extend to the surrounding  pattern.  Note  that
       such  subpatterns are processed as anchored at the point where they are
       tested.

       The new verbs make use of what was previously invalid syntax: an  open-
       ing parenthesis followed by an asterisk. In Perl, they are generally of
       the form (*VERB:ARG) but PCRE does not support the use of arguments, so
       its  general  form is just (*VERB). Any number of these verbs may occur
       in a pattern. There are two kinds:

   Verbs that act immediately

       The following verbs act as soon as they are encountered:

          (*ACCEPT)

       This verb causes the match to end successfully, skipping the  remainder
       of  the pattern. When inside a recursion, only the innermost pattern is
       ended immediately. If (*ACCEPT) is inside  capturing  parentheses,  the
       data  so  far  is  captured. (This feature was added to PCRE at release
       8.00.) For example:

         A((?:A|B(*ACCEPT)|C)D)

       This matches "AB", "AAD", or "ACD"; when it matches "AB", "B"  is  cap-
       tured by the outer parentheses.

         (*FAIL) or (*F)

       This  verb  causes the match to fail, forcing backtracking to occur. It
       is equivalent to (?!) but easier to read. The Perl documentation  notes
       that  it  is  probably  useful only when combined with (?{}) or (??{}).
       Those are, of course, Perl features that are not present in  PCRE.  The
       nearest  equivalent is the callout feature, as for example in this pat-
       tern:

         a+(?C)(*FAIL)

       A match with the string "aaaa" always fails, but the callout  is  taken
       before each backtrack happens (in this example, 10 times).

   Verbs that act after backtracking

       The following verbs do nothing when they are encountered. Matching con-
       tinues with what follows, but if there is no subsequent match, a  fail-
       ure  is  forced.   The  verbs  differ  in  exactly what kind of failure
       occurs.

         (*COMMIT)

       This verb causes the whole match to fail outright if the  rest  of  the
       pattern  does  not match. Even if the pattern is unanchored, no further
       attempts to find a match by advancing the starting  point  take  place.
       Once  (*COMMIT)  has been passed, pcre_exec() is committed to finding a
       match at the current starting point, or not at all. For example:

         a+(*COMMIT)b

       This matches "xxaab" but not "aacaab". It can be thought of as  a  kind
       of dynamic anchor, or "I've started, so I must finish."

         (*PRUNE)

       This  verb causes the match to fail at the current position if the rest
       of the pattern does not match. If the pattern is unanchored, the normal
       "bumpalong"  advance to the next starting character then happens. Back-
       tracking can occur as usual to the left of (*PRUNE), or  when  matching
       to  the right of (*PRUNE), but if there is no match to the right, back-
       tracking cannot cross (*PRUNE).  In simple cases, the use  of  (*PRUNE)
       is just an alternative to an atomic group or possessive quantifier, but
       there are some uses of (*PRUNE) that cannot be expressed in  any  other
       way.

         (*SKIP)

       This  verb  is like (*PRUNE), except that if the pattern is unanchored,
       the "bumpalong" advance is not to the next character, but to the  posi-
       tion  in  the  subject where (*SKIP) was encountered. (*SKIP) signifies
       that whatever text was matched leading up to it cannot  be  part  of  a
       successful match. Consider:

         a+(*SKIP)b

       If  the  subject  is  "aaaac...",  after  the first match attempt fails
       (starting at the first character in the  string),  the  starting  point
       skips on to start the next attempt at "c". Note that a possessive quan-
       tifer does not have the same effect as this example; although it  would
       suppress  backtracking  during  the  first  match  attempt,  the second
       attempt would start at the second character instead of skipping  on  to
       "c".

         (*THEN)

       This verb causes a skip to the next alternation if the rest of the pat-
       tern does not match. That is, it cancels pending backtracking, but only
       within  the  current  alternation.  Its name comes from the observation
       that it can be used for a pattern-based if-then-else block:

         ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ...

       If the COND1 pattern matches, FOO is tried (and possibly further  items
       after  the  end  of  the group if FOO succeeds); on failure the matcher
       skips to the second alternative and tries COND2,  without  backtracking
       into  COND1.  If  (*THEN)  is  used outside of any alternation, it acts
       exactly like (*PRUNE).

SEE ALSO

       pcreapi(3), pcrecallout(3), pcrematching(3), pcresyntax(3), pcre(3).

AUTHOR

       Philip Hazel
       University Computing Service
       Cambridge CB2 3QH, England.

REVISION

       Last updated: 11 January 2010
       Copyright (c) 1997-2010 University of Cambridge.


PCRE Regular Expression Syntax Summary

The following is a summary of search pattern syntax.

PCRESYNTAX(3)                                                    PCRESYNTAX(3)

NAME
       PCRE - Perl-compatible regular expressions

PCRE REGULAR EXPRESSION SYNTAX SUMMARY

       The  full syntax and semantics of the regular expressions that are sup-
       ported by PCRE are described in  the  pcrepattern  documentation.  This
       document contains just a quick-reference summary of the syntax.

QUOTING

         \x         where x is non-alphanumeric is a literal x
         \Q...\E    treat enclosed characters as literal

CHARACTERS

         \a         alarm, that is, the BEL character (hex 07)
         \cx        "control-x", where x is any ASCII character
         \e         escape (hex 1B)
         \f         formfeed (hex 0C)
         \n         newline (hex 0A)
         \r         carriage return (hex 0D)
         \t         tab (hex 09)
         \ddd       character with octal code ddd, or backreference
         \xhh       character with hex code hh
         \x{hhh..}  character with hex code hhh..

CHARACTER TYPES

         .          any character except newline;
                      in dotall mode, any character whatsoever
         \C         one byte, even in UTF-8 mode (best avoided)
         \d         a decimal digit
         \D         a character that is not a decimal digit
         \h         a horizontal whitespace character
         \H         a character that is not a horizontal whitespace character
         \N         a character that is not a newline
         \p{xx}     a character with the xx property
         \P{xx}     a character without the xx property
         \R         a newline sequence
         \s         a whitespace character
         \S         a character that is not a whitespace character
         \v         a vertical whitespace character
         \V         a character that is not a vertical whitespace character
         \w         a "word" character
         \W         a "non-word" character
         \X         an extended Unicode sequence

       In  PCRE,  by  default, \d, \D, \s, \S, \w, and \W recognize only ASCII
       characters, even in UTF-8 mode. However, this can be changed by setting
       the PCRE_UCP option.

GENERAL CATEGORY PROPERTIES FOR \p and \P

         C          Other
         Cc         Control
         Cf         Format
         Cn         Unassigned
         Co         Private use
         Cs         Surrogate

         L          Letter
         Ll         Lower case letter
         Lm         Modifier letter
         Lo         Other letter
         Lt         Title case letter
         Lu         Upper case letter
         L&         Ll, Lu, or Lt

         M          Mark
         Mc         Spacing mark
         Me         Enclosing mark
         Mn         Non-spacing mark

         N          Number
         Nd         Decimal number
         Nl         Letter number
         No         Other number

         P          Punctuation
         Pc         Connector punctuation
         Pd         Dash punctuation
         Pe         Close punctuation
         Pf         Final punctuation
         Pi         Initial punctuation
         Po         Other punctuation
         Ps         Open punctuation

         S          Symbol
         Sc         Currency symbol
         Sk         Modifier symbol
         Sm         Mathematical symbol
         So         Other symbol

         Z          Separator
         Zl         Line separator
         Zp         Paragraph separator
         Zs         Space separator

PCRE SPECIAL CATEGORY PROPERTIES FOR \p and \P

         Xan        Alphanumeric: union of properties L and N
         Xps        POSIX space: property Z or tab, NL, VT, FF, CR
         Xsp        Perl space: property Z or tab, NL, FF, CR
         Xwd        Perl word: property Xan or underscore

SCRIPT NAMES FOR \p AND \P

       Arabic, Armenian, Avestan, Balinese, Bamum, Bengali, Bopomofo, Braille,
       Buginese, Buhid, Canadian_Aboriginal, Carian, Cham,  Cherokee,  Common,
       Coptic,   Cuneiform,  Cypriot,  Cyrillic,  Deseret,  Devanagari,  Egyp-
       tian_Hieroglyphs,  Ethiopic,  Georgian,  Glagolitic,   Gothic,   Greek,
       Gujarati,  Gurmukhi,  Han,  Hangul,  Hanunoo,  Hebrew,  Hiragana, Impe-
       rial_Aramaic, Inherited, Inscriptional_Pahlavi, Inscriptional_Parthian,
       Javanese,  Kaithi, Kannada, Katakana, Kayah_Li, Kharoshthi, Khmer, Lao,
       Latin,  Lepcha,  Limbu,  Linear_B,  Lisu,  Lycian,  Lydian,  Malayalam,
       Meetei_Mayek,  Mongolian, Myanmar, New_Tai_Lue, Nko, Ogham, Old_Italic,
       Old_Persian, Old_South_Arabian, Old_Turkic, Ol_Chiki,  Oriya,  Osmanya,
       Phags_Pa,  Phoenician,  Rejang,  Runic, Samaritan, Saurashtra, Shavian,
       Sinhala, Sundanese, Syloti_Nagri, Syriac,  Tagalog,  Tagbanwa,  Tai_Le,
       Tai_Tham,  Tai_Viet,  Tamil,  Telugu,  Thaana, Thai, Tibetan, Tifinagh,
       Ugaritic, Vai, Yi.

CHARACTER CLASSES

         [...]       positive character class
         [^...]      negative character class
         [x-y]       range (can be used for hex characters)
         [[:xxx:]]   positive POSIX named set
         [[:^xxx:]]  negative POSIX named set

         alnum       alphanumeric
         alpha       alphabetic
         ascii       0-127
         blank       space or tab
         cntrl       control character
         digit       decimal digit
         graph       printing, excluding space
         lower       lower case letter
         print       printing, including space
         punct       printing, excluding alphanumeric
         space       whitespace
         upper       upper case letter
         word        same as \w
         xdigit      hexadecimal digit

       In PCRE, POSIX character set names recognize only ASCII  characters  by
       default,  but  some  of them use Unicode properties if PCRE_UCP is set.
       You can use \Q...\E inside a character class.

QUANTIFIERS

         ?           0 or 1, greedy
         ?+          0 or 1, possessive
         ??          0 or 1, lazy
         *           0 or more, greedy
         *+          0 or more, possessive
         *?          0 or more, lazy
         +           1 or more, greedy
         ++          1 or more, possessive
         +?          1 or more, lazy
         {n}         exactly n
         {n,m}       at least n, no more than m, greedy
         {n,m}+      at least n, no more than m, possessive
         {n,m}?      at least n, no more than m, lazy
         {n,}        n or more, greedy
         {n,}+       n or more, possessive
         {n,}?       n or more, lazy

ANCHORS AND SIMPLE ASSERTIONS

         \b          word boundary
         \B          not a word boundary
         ^           start of subject
                      also after internal newline in multiline mode
         \A          start of subject
         $           end of subject
                      also before newline at end of subject
                      also before internal newline in multiline mode
         \Z          end of subject
                      also before newline at end of subject
         \z          end of subject
         \G          first matching position in subject

MATCH POINT RESET

         \K          reset start of match

ALTERNATION

         expr|expr|expr...

CAPTURING

         (...)           capturing group
         (?<name>...)    named capturing group (Perl)
         (?'name'...)    named capturing group (Perl)
         (?P<name>...)   named capturing group (Python)
         (?:...)         non-capturing group
         (?|...)         non-capturing group; reset group numbers for
                          capturing groups in each alternative

ATOMIC GROUPS

         (?>...)         atomic, non-capturing group

COMMENT

         (?#....)        comment (not nestable)

OPTION SETTING

         (?i)            caseless
         (?J)            allow duplicate names
         (?m)            multiline
         (?s)            single line (dotall)
         (?U)            default ungreedy (lazy)
         (?x)            extended (ignore white space)
         (?-...)         unset option(s)

       The following are recognized only at the start of a  pattern  or  after
       one of the newline-setting options with similar syntax:

         (*NO_START_OPT) no start-match optimization (PCRE_NO_START_OPTIMIZE)
         (*UTF8)         set UTF-8 mode (PCRE_UTF8)
         (*UCP)          set PCRE_UCP (use Unicode properties for \d etc)

LOOKAHEAD AND LOOKBEHIND ASSERTIONS

         (?=...)         positive look ahead
         (?!...)         negative look ahead
         (?<=...)        positive look behind
         (?<!...)        negative look behind

       Each top-level branch of a look behind must be of a fixed length.

BACKREFERENCES

         \n              reference by number (can be ambiguous)
         \gn             reference by number
         \g{n}           reference by number
         \g{-n}          relative reference by number
         \k<name>        reference by name (Perl)
         \k'name'        reference by name (Perl)
         \g{name}        reference by name (Perl)
         \k{name}        reference by name (.NET)
         (?P=name)       reference by name (Python)

SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)

         (?R)            recurse whole pattern
         (?n)            call subpattern by absolute number
         (?+n)           call subpattern by relative number
         (?-n)           call subpattern by relative number
         (?&name)        call subpattern by name (Perl)
         (?P>name)       call subpattern by name (Python)
         \g<name>        call subpattern by name (Oniguruma)
         \g'name'        call subpattern by name (Oniguruma)
         \g<n>           call subpattern by absolute number (Oniguruma)
         \g'n'           call subpattern by absolute number (Oniguruma)
         \g<+n>          call subpattern by relative number (PCRE extension)
         \g'+n'          call subpattern by relative number (PCRE extension)
         \g<-n>          call subpattern by relative number (PCRE extension)
         \g'-n'          call subpattern by relative number (PCRE extension)

CONDITIONAL PATTERNS

         (?(condition)yes-pattern)
         (?(condition)yes-pattern|no-pattern)

         (?(n)...        absolute reference condition
         (?(+n)...       relative reference condition
         (?(-n)...       relative reference condition
         (?(<name>)...   named reference condition (Perl)
         (?('name')...   named reference condition (Perl)
         (?(name)...     named reference condition (PCRE)
         (?(R)...        overall recursion condition
         (?(Rn)...       specific group recursion condition
         (?(R&name)...   specific recursion condition
         (?(DEFINE)...   define subpattern for reference
         (?(assert)...   assertion condition

BACKTRACKING CONTROL

       The following act immediately they are reached:

         (*ACCEPT)       force successful match
         (*FAIL)         force backtrack; synonym (*F)

       The  following  act only when a subsequent match failure causes a back-
       track to reach them. They all force a match failure, but they differ in
       what happens afterwards. Those that advance the start-of-match point do
       so only if the pattern is not anchored.

         (*COMMIT)       overall failure, no advance of starting point
         (*PRUNE)        advance to next starting character
         (*SKIP)         advance start to current matching position
         (*THEN)         local failure, backtrack to next alternation

NEWLINE CONVENTIONS

       These are recognized only at the very start of the pattern or  after  a
       (*BSR_...) or (*UTF8) or (*UCP) option.

         (*CR)           carriage return only
         (*LF)           linefeed only
         (*CRLF)         carriage return followed by linefeed
         (*ANYCRLF)      all three of the above
         (*ANY)          any Unicode newline sequence

WHAT \R MATCHES

       These  are  recognized only at the very start of the pattern or after a
       (*...) option that sets the newline convention or UTF-8 or UCP mode.

         (*BSR_ANYCRLF)  CR, LF, or CRLF
         (*BSR_UNICODE)  any Unicode newline sequence

CALLOUTS

         (?C)      callout
         (?Cn)     callout with data n

AUTHOR

       Philip Hazel
       University Computing Service
       Cambridge CB2 3QH, England.

REVISION

       Last updated: 21 November 2010
       Copyright (c) 1997-2010 University of Cambridge.


PCRE License

PCRE Licence

Part of the functionality of ⎕R and ⎕S is implemented using the PCRE library which is redistributed according to the following license.
PCRE LICENCE
------------

PCRE is a library of functions to support regular expressions whose syntax
and semantics are as close as possible to those of the Perl 5 language.

Release 8 of PCRE is distributed under the terms of the "BSD" licence, as
specified below. The documentation for PCRE, supplied in the "doc"
directory, is distributed under the same terms as the software itself.

The basic library functions are written in C and are freestanding. Also
included in the distribution is a set of C++ wrapper functions.

THE BASIC LIBRARY FUNCTIONS
---------------------------

Written by:       Philip Hazel
Email local part: ph10
Email domain:     cam.ac.uk

University of Cambridge Computing Service,
Cambridge, England.

Copyright (c) 1997-2009 University of Cambridge
All rights reserved.

THE C++ WRAPPER FUNCTIONS
-------------------------

Contributed by:   Google Inc.

Copyright (c) 2007-2008, Google Inc.
All rights reserved.
which is redistributed according to the following license:


Version 13.0 New Idioms

New Idioms

Expression | Description
A⍪←A | Catenate along first axis
⍪/PV | Join along first axis
⊣⌿A | First sub-array along first axis
⊣/A | First sub-array along last axis
⊢⌿A | Last sub-array along first axis
⊢/A | Last sub-array along last axis
**○N | Euler's idiom

Notes:

Existing idiom "Catenate To": V,←A has been generalised to allow arrays of higher rank on the left, so that its new template expression should be A,←A. This means, for example, that concatenating a new column to a matrix will be optimised.

New idiom A⍪←A is identical to A,←A except concatenation occurs along the first, rather than the last, axis.

Join along first axis: ⍪/PV is analogous to existing idiom Join (,/PV) except that conformable items of the argument vector are concatenated along their first, rather than last, axis.


Retained Hash Table for Grade

The expressions: alphabet∘⍋ and alphabet∘⍒ now retain the translate table in a similar way as do the set functions (⍳ ∊ etc)

      f←a∘⍋
      f x ⍝ first run builds the translate table
      f y ⍝ subsequent runs are significantly faster than a⍋y

Note that the expression (a∘⍋)¨x y does the same as the above example, without saving the derived function.


Format Changes

Monadic ⍕, Dyadic ⍕ and ⎕FMT now use 128-bit decimal representation internally when processing floating-point numbers. This has been done to improve the accuracy with which floating-point numbers are converted to text for display and printing.

As a result of this change, the APLFormatBias parameter is no longer supported and if defined will be ignored.

Monadic ⍕ formats complex numbers using J notation (always with a capital J).

Dyadic ⍕ and ⎕FMT will accept a right argument containing complex numbers, but the imaginary part of such numbers is ignored.

When ⎕FR is set to 1287, 40⍕1 and 'E50.40'⎕FMT 1, where the right hand side is an integer, will now print 34 "reliable" digits instead of 16 before filling in with underscores.

      40⍕1 ⍝ Version 12.1
1.000000000000000_________________________

      ⎕FR←1287 ⍝ Version 13.0
      40⍕1
1.000000000000000000000000000000000_______

Alignment (E Format)

The following rules of alignment apply to ⎕FMT (E format), and dyadic ⍕ with a negative left argument.

When ⎕FR is 1287, dyadic ⍕ (with negative precision) and dyadic ⎕FMT (E format) will try to move everything left two spaces, to leave room for an extra two digits in the exponent.

When ⎕FR is 645, the result is aligned so that there is room for three characters after the E:

      ⎕FR←645
      ]display 'E10.2'⎕FMT 1 1E10 1E100
┌→─────────┐
↓ 1.0E0    │
│ 1.0E10   │
│ 1.0E100   │
└──────────┘

When ⎕FR is 1287, the result is aligned to leave room for five characters after the E:

      ⎕FR←1287
      ]display 'E10.2'⎕FMT 1 1E10 1E100
┌→─────────┐
↓ 1.0E0    │
│ 1.0E10   │
│ 1.0E100  │
└──────────┘

This is done so that there is room for the largest negative exponent that decimal floating point supports:

      ]display 'E10.2'⎕FMT 1 1E10 1E100 1E¯6176
┌→─────────┐
↓ 1.0E0    │
│ 1.0E10   │
│ 1.0E100  │
│ 1.0E¯6176│
└──────────┘

However, if the field width isn't large enough to allow for the extra trailing spaces, they are truncated (rather than printing a line of asterisks):

      ]display 'E7.2'⎕FMT 1 1E10 1E100 1E¯1000
┌→──────┐
↓1.0E0  │
│1.0E10 │
│1.0E100│
│0.0E0  │
└───────┘


Correction to Index Generator

The result of the expression ⍳⍬ has been changed from ⎕IO to (⊂⍬). The previous behaviour was incorrect.

Version 12.1

      ⍳⍬
1
      ⎕IO←0
      ⍳⍬
0
      ⎕IO≡⍳⍬
1

Version 13.0

      ]display ⍳⍬
┌─────┐
│ ┌⊖┐ │
│ │0│ │
│ └~┘ │
└∊────┘
      (⊂⍬)≡⍳⍬1


OLE Interface Changes

Default indexers which are implemented as methods rather than as properties, must now be accessed using indexing and not using function calls. For example, to obtain the individual members of the Shapes collection of the Excel Work Sheet object, it was previously possible to call its Item() method as a function.

Version 12.1

      Excel.Application.ActiveSheet.Shapes.Item 1

Version 13.0

This syntax is no longer supported, and you must use indexing instead.

      Excel.Application.ActiveSheet.Shapes[1]


Internal Error 99

INTERNAL ERROR indicates a severe system error from which Dyalog APL has recovered; in the past such errors would always have resulted in a Syserror.

Should you encounter INTERNAL ERROR, Dyalog strongly recommends that you save your work(space) , and report the issue. No existing Syserror reports have yet been changed into INTERNAL ERROR.


Version 13.0 New Parameters

New Parameters

  • APL_FCREATE_PROPS_C
  • APL_FCREATE_PROPS_J
  • APL_FAST_FCHK
  • APL_EXTERN_DECF
  • APL_COMPLEX_AS_V12

APL_FCREATE_PROPS_C

This parameter specifies the default chksum level for newly-created component files.

APL_FCREATE_PROPS_J

This parameter specifies the default journaling level for newly-created component files.

APL_FAST_FCHK

This parameter specifies whether Dyalog APL should optimise ⎕FCHK by allowing it to reliably determine whether a component file had been properly untied and therefore does not need to be checked (this is overridable using the ⎕FCHK option 'force').

Optimising ⎕FCHK in this way has a performance impact on ⎕FUNTIE and it is recommended this optimisation is switched off if your application frequently ties and unties files.

Note: this only affects component files with journaling enabled.

The values of the parameter are:

0 | Do not optimise ⎕FCHK (optimise ⎕FUNTIE instead)
1 | Optimise ⎕FCHK

The default values of the parameter reflect the existing behaviour in Version 12.1: 0 on Windows and 1 on Linux / AIX. On Windows, setting the value 1 has no effect.

APL_EXTERN_DECF

By default, arrays of type DECF (128-bit decimal) will be passed unchanged to Auxiliary Processors, and to DLLs using A or Z argument types. However, if APL_EXTERN_DECF is set to 0, DECF arrays will be converted to DOUBLE before they are passed to AP's and DLL's. This will allow user-written Auxiliary Processors and DLLs to continue to work at least temporarily while users determine how to change their code to cater for the new data type. This parameter will not be supported beyond Version 13.0.

APL_COMPLEX_AS_V12

Support for Complex Numbers means that some functions produce different results from previous Versions of Dyalog APL. If APL_COMPLEX_AS_V12 is set to 1 the behaviour of code developed using Version 12.1 or earlier will be unchanged; in particular:

  • Power (*) and logarithm (⍟) do not produce Complex Numbers as results from non-complex arguments.
  • ⎕VFI will not honour "J" or "j" as part of a number.
  • ¯4○Y will be evaluated as (̄1+Y*2)*0.5, which is positive for negative real arguments.

If APL_COMPLEX_AS_V12 is set to any other value or is not set at all then code developed using version 12.1 or earlier may now generate Complex Numbers.

Note that this feature is provided to simplify the transition of older code to Version 13.0. It does not prevent the generation and use of Complex Numbers using features new to 13.0 (such as explicitly specifying a Complex Number literal), and it will be removed in a future release of Dyalog APL.


Deprecated 32-bit Component Files

Deprecation of 32-bit component files

Since Version 10.1, Dyalog APL has supported large span (64-bit) component files, and since Version 12.0 ⎕FCREATE has created these by default. Existing small span (32-bit) component files are still supported and 32-bit component files may still be created if suitable options are specified, but they have restrictions which 64-bit files do not, including:

  • The maximum file size is 4GB.
  • The files are not fully architecture-independent meaning that there are limitations sharing them between, for example, Windows or Linux and AIX machines.
  • Components may not contain Unicode data.

Dyalog intends to withdraw support for 32-bit component files in future releases.

If you have any existing 32-bit component files, or applications which create and/or use them, Dyalog recommends that you prepare for this in the following ways:

  • Ensure that Dyalog is not started with the command-line option -F32. This option sets the default component file type which is created to 32-bit.
  • Ensure that no ⎕FCREATE within your applications explicitly specifies that 32-bit files are to be created.
  • Make plans to convert any existing 32-bit component files to 64-bit using ⎕FCOPY. ⎕FCOPYwill create a 64-bit copy even if the file being copied is 32-bit.

Note: in order to allow the use of legacy files retrieved from backups etc., Dyalog will continue to provide a means to convert 32-bit files to supported formats for a minimum of 10 years after direct support is withdrawn.


New Tack Functions

Left Tack

Monadic ⊣ (left tack) is called Same and returns its argument.

Dyadic ⊣ is called Left and returns its left argument.

Right Tack

Monadic ⊢ (right tack) is called Identity and returns its argument.

Dyadic ⊢ is called Right and returns its right argument.

Note:

Note that monadic + is now called Conjugate and it is recommended that its use as "Identity" be replaced by monadic ⊢.


Improvements to Take, Drop and Index

You may now elide trailing items of the left argument to the primitive functions Take (↑), Drop (↓) and Index (⌷). Instead of causing a RANK ERROR or LENGTH ERROR, the missing items default to appropriate values.

      A←3 4 5 6⍴⍳360 ⍝ rank-4 array.

Take: missing trailing items of the left argument default to the length of the corresponding axis.

      2↑A ←→ 2 4 5 6↑A
      1 1↑A ←→ 1 1 5 6↑A
      ⍬↑A ←→ 3 4 5 6↑A ←→ A

Drop: missing trailing items of the left argument default to 0:

      2↓A ←→ 2 0 0 0↓A
      1 1↓A ←→ 1 1 0 0↓A
      ⍬↓A ←→ 0 0 0 0↓A ←→ A

Index: missing trailing items of the left argument default to the index vector of the corresponding axis:

      2⌷A ←→ 2(⍳4)(⍳5)(⍳6)⌷A
      1 1⌷A ←→ 1 1 (⍳5)(⍳6)⌷A
      ⍬⌷A ←→ (⍳3)(⍳4)(⍳5)(⍳6)⌷A ←→ A


Introduction

Licences for third-party components

The software product you have received may include one or more third-party software components. Licence notices for these components are provided within the Dyalog installation directory.

Note that if your Dyalog licence permits the distribution of applications built upon Dyalog APL, or the redistribution of Dyalog APL itself, these licence notices must also be redistributed. For your convenience they are supplied as a Word document for use in your own documentation. If you have any concerns about redistributing these third party software products, please contact Dyalog to discuss your options.


ActiveXControl Children

ActiveXContainer | Animation | Bitmap
BrowseBox | Button | ButtonEdit
Calendar | Circle | Clipboard
ColorButton | Combo | ComboEx
CoolBar | Cursor | DateTimePicker
Edit | Ellipse | FileBox
Font | Form | Grid
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Marker
MDIClient | Menu | MenuBar
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertySheet
Rect | RichEdit | Scroll
Spinner | Splitter | Static
StatusBar | SubForm | TabBar
TabControl | TCPSocket | Text
Timer | TipField | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


Animation Children

Bitmap | Circle | Cursor
Ellipse | Font | Marker
Poly | Rect | Text
Timer |  |


Bitmap Children

Circle | Ellipse | Font
Image | Marker | Metafile
Poly | Rect | Text
Timer |  |


BrowseBox Children

Timer


Button Children

Bitmap | Circle | Cursor
Ellipse | Font | Marker
Poly | Rect | Text
Timer |  |


ButtonEdit Children

Circle | Ellipse | Font
ImageList | Marker | Poly
Rect | Text | Timer


Calendar Children

Cursor | Font | Menu
MsgBox | TCPSocket | Timer


Circle Children

Timer


Clipboard Children

Timer


Combo Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


ComboEx Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


CoolBand Children

Bitmap | BrowseBox | Button
Clipboard | Combo | ComboEx
Cursor | Edit | FileBox
Font | Grid | Group
Icon | ImageList | Label
List | ListView | Menu
Metafile | MsgBox | OCXClass
OLEClient | Printer | ProgressBar
RichEdit | Scroll | Spinner
Static | StatusBar | SubForm
TabControl | TCPSocket | Timer
TipField | ToolBar | ToolControl
TrackBar | TreeView | UpDown


CoolBar Children

CoolBand | ImageList | Menu
Timer |  |


Cursor Children

Timer


DateTimePicker Children

Cursor | Font | Menu
MsgBox | TCPSocket | Timer


Edit Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


Ellipse Children

Timer


FileBox Children

Timer


Font Children

Timer


Form Children

ActiveXControl | Animation | Bitmap
BrowseBox | Button | ButtonEdit
Calendar | Circle | Clipboard
ColorButton | Combo | ComboEx
CoolBar | Cursor | DateTimePicker
Edit | Ellipse | FileBox
Font | Form | Grid
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Marker
MDIClient | Menu | MenuBar
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertySheet
Rect | RichEdit | Scroll
SM | Spinner | Splitter
Static | StatusBar | SubForm
SysTrayItem | TabBar | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolControl
TrackBar | TreeView | UpDown


Grid Children

Bitmap | BrowseBox | Button
Circle | ColorButton | Combo
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Icon | Image | Label
Marker | Menu | MsgBox
OCXClass | Poly | Rect
Spinner | Text | Timer
TrackBar |  |


Group Children

Animation | Bitmap | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
Cursor | DateTimePicker | Edit
Ellipse | Font | Grid
Group | Image | ImageList
Label | List | ListView
Locator | Marker | Metafile
Poly | ProgressBar | Rect
RichEdit | Scroll | SM
Spinner | Splitter | Static
SubForm | Text | Timer
TipField | TrackBar | TreeView
UpDown |  |


Icon Children

Timer


Image Children

Timer


ImageList Children

Bitmap | Cursor | Icon
Timer |  |


Label Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


List Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


ListView Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
ImageList | Marker | Poly
Rect | Text | Timer


Locator Children

Timer


Marker Children

Timer


MDIClient Children

Circle | Ellipse | Font
Marker | Poly | Rect
SubForm | Text | Timer


Menu Children

Bitmap | Menu | MenuItem
Separator | Timer |


MenuBar Children

Bitmap | Menu | MenuItem
Separator | Timer |


MenuItem Children

Bitmap Timer


Metafile Children

Circle | Ellipse | Font
Image | Marker | Poly
Rect | Text | Timer


MsgBox Children

Timer


NetClient Children

Timer


NetControl Children

NetClient OLEClient Timer


NetType Children

Bitmap | NetClient | TCPSocket
Timer |  |


OLEClient Children

Form TCPSocket Timer


OLEServer Children

Bitmap | BrowseBox | Clipboard
Cursor | FileBox | Font
Form | Icon | ImageList
Menu | Metafile | MsgBox
OCXClass | OLEClient | OLEServer
Printer | PropertySheet | TCPSocket
Timer | TipField |


Poly Children

Timer


Printer Children

Bitmap | Circle | Ellipse
Font | Icon | Image
Marker | Metafile | Poly
Rect | Text | Timer


ProgressBar Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
Marker | Poly | Rect
Text | Timer |


PropertyPage Children

Animation | Bitmap | BrowseBox
Button | ButtonEdit | Calendar
Circle | Clipboard | ColorButton
Combo | ComboEx | Cursor
DateTimePicker | Edit | Ellipse
FileBox | Font | Grid
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Marker
Metafile | MsgBox | OCXClass
Poly | Printer | ProgressBar
Rect | RichEdit | Scroll
SM | Spinner | Splitter
Static | SubForm | TCPSocket
Text | Timer | TipField
TrackBar | TreeView | UpDown


PropertySheet Children

Bitmap | BrowseBox | Circle
Clipboard | Cursor | Ellipse
FileBox | Font | Icon
Locator | Marker | Metafile
MsgBox | Poly | Printer
PropertyPage | Rect | Text
Timer | TipField |


Rect Children

Timer


RichEdit Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
Marker | Poly | Rect
Text | Timer |


Root Children

Bitmap | BrowseBox | Clipboard
Cursor | FileBox | Font
Form | Icon | ImageList
Locator | Menu | Metafile
MsgBox | NetClient | NetType
OCXClass | OLEClient | OLEServer
Printer | PropertySheet | SysTrayItem
TCPSocket | Timer | TipField


Scroll Children

Circle | Cursor | Ellipse
Font | Marker | Poly
Rect | Text | Timer


Separator Children

Timer


SM Children

Cursor Timer


Spinner Children

Circle | Ellipse | Font
Marker | Poly | Rect
Text | Timer |


Splitter Children

Timer


Static Children

Circle | Cursor | Ellipse
Font | Image | Locator
Marker | Metafile | Poly
Rect | Text | Timer


StatusBar Children

Bitmap | BrowseBox | Circle
Cursor | Ellipse | FileBox
Font | Icon | Image
Marker | Poly | ProgressBar
Rect | StatusField | Text
Timer |  |


StatusField Children

Menu Timer


SubForm Children

Animation | Bitmap | BrowseBox
Button | ButtonEdit | Calendar
Circle | ColorButton | Combo
ComboEx | Cursor | DateTimePicker
Edit | Ellipse | FileBox
Font | Form | Grid
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Marker
MDIClient | Menu | MenuBar
Metafile | MsgBox | OCXClass
Poly | ProgressBar | PropertySheet
Rect | RichEdit | Scroll
SM | Spinner | Splitter
Static | StatusBar | SubForm
TabBar | TabControl | TCPSocket
Text | Timer | TipField
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


SysTrayItem Children

Icon Menu Timer


TabBar Children

Circle | Ellipse | Font
Marker | Poly | Rect
TabBtn | Text | Timer


TabBtn Children

Timer


TabButton Children

Timer


TabControl Children

ImageList | SubForm | TabButton
Timer |  |


TCPSocket Children

Bitmap | BrowseBox | Clipboard
Cursor | FileBox | Font
Form | Icon | ImageList
Locator | Menu | Metafile
MsgBox | OCXClass | OLEClient
Printer | PropertySheet | TCPSocket
Timer | TipField |


Text Children

Timer


TipField Children

Circle | Ellipse | Font
Marker | Poly | Rect
Text | Timer |


ToolBar Children

Bitmap | BrowseBox | Button
Calendar | Circle | Combo
ComboEx | Cursor | DateTimePicker
Edit | Ellipse | FileBox
Font | Group | Icon
Image | ImageList | Label
List | ListView | Locator
Marker | Menu | Metafile
MsgBox | OCXClass | Poly
ProgressBar | Rect | RichEdit
Scroll | SM | Spinner
Static | SubForm | Text
Timer | TrackBar | TreeView
UpDown |  |


ToolButton Children

Bitmap Timer


ToolControl Children

Bitmap | BrowseBox | Button
Combo | ComboEx | Cursor
Edit | FileBox | Font
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Menu
MenuBar | Metafile | MsgBox
OCXClass | ProgressBar | RichEdit
Scroll | SM | Spinner
Static | SubForm | Timer
ToolButton | TrackBar | TreeView
UpDown |  |


TrackBar Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
Marker | Poly | Rect
Text | Timer |


TreeView Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
ImageList | Marker | Poly
Rect | Text | Timer


UpDown Children

Bitmap | Circle | Cursor
Ellipse | Font | Icon
Marker | Poly | Rect
Text | Timer |


ActiveXContainer Events

Close Create AmbientChanged


ActiveXControl Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
AmbientChanged | Select | PreCreate


Animation Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | AnimStarted | AnimStopped


Bitmap Events

Close Create Select


BrowseBox Events

Close | Create | FileBoxOK
FileBoxCancel |  |


Button Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | FontOK | FontCancel
Select | DropDown |


ButtonEdit Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select | BadValue | KeyError
Change | DropDown |


Calendar Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
SelDateChange | GetDayStates | CalendarDown
CalendarUp | CalendarDblClick | CalendarMove
Select |  |


Circle Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


Clipboard Events

Close | Create | ClipChange
Select |  |


ColorButton Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | ColorChange | DropDown


Combo Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
DropDown | Select | Change


ComboEx Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
DropDown | Select |


CoolBand Events

Close | Create | DockStart
DockMove | DockRequest | DockAccept
DockEnd | DockCancel |


CoolBar Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
DockStart | DockMove | DockRequest
DockAccept | DockEnd | DockCancel


Cursor Events

Close Create Select


DateTimePicker Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
DateTimeChange | DropDown | CloseUp
Select |  |


Edit Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select | BadValue | Change
KeyError |  |


Ellipse Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


FileBox Events

Close | Create | FileBoxOK
FileBoxCancel | Select |


Font Events

Close | Create | FontOK
FontCancel | Select |


Form Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | StateChange | DockStart
DockMove | DockRequest | DockAccept
DockEnd | DockCancel | Select
FrameContextMenu | DyalogCustomMessage1 | FontOK
FontCancel | VScroll | HScroll
VThumbDrag | HThumbDrag |


Grid Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseEnter
MouseLeave | GridKeyPress | CellChange
CellMove | AddRow | AddCol
CellError | CellOver | CellDown
CellUp | CellDblClick | CellChanged
GridSelect | Expanding | Retracting
SetRowSize | SetColSize | GridCut
GridCopy | GridPaste | GridDelete
GridPasteError | GridDropSel | GridCopyError
IndexChanged | ShowComment | HideComment
ClickComment | Select |


Group Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select |  |


Icon Events

Close Create Select


Image Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


ImageList Events

Close Create


Label Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select |  |


List Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select |  |


ListView Events

Close | Create | FontOK
FontCancel | BeginEditLabel | EndEditLabel
DragDrop | Configure | ContextMenu
DropFiles | DropObjects | Expose
Help | KeyPress | GotFocus
LostFocus | MouseDown | MouseUp
MouseMove | MouseDblClick | MouseEnter
MouseLeave | MouseWheel | ColumnClick
SetItemPosition | ItemDown | ItemUp
ItemDblClick | GetTipText | SetColSize
Select |  |


Locator Events

Close | Create | Locator
Select |  |


Marker Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


MDIClient Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | Select |


Menu Events

Close | Create | DropDown
Select |  |


MenuBar Events

Close Create


MenuItem Events

Close Create Select


Metafile Events

Close Create Select


NetType Events


OCXClass Events


OLEClient Events


OLEServer Events

Close Create


Poly Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


Printer Events

Close Create Select


ProgressBar Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | Select |


PropertyPage Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | FontOK | FontCancel
PageApply | PageCancel | PageHelp
PageBack | PageNext | PageFinish
PageChanged | PageActivate | PageDeactivate
SetWizard |  |


PropertySheet Events

Close | Create | FontOK
FontCancel |  |


Rect Events

Close | Create | DragDrop
MouseDown | MouseUp | MouseMove
MouseDblClick | Help | Select


RichEdit Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Protected | Change | Select


Root Events

FontOK | FontCancel | DDE
Idle | ExitWindows | ExitApp
WinIniChange | SysColorChange | DisplayChange
ActivateApp |  |


Scroll Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | Select | ThumbDrag
Scroll |  |


Separator Events

Close Create


SM Events

Close | Create | MouseDown
MouseUp | MouseDblClick | MouseEnter
MouseLeave | Configure | Help
DragDrop |  |


Spinner Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Spin | SetSpinnerText | Select
BadValue | KeyError | Change


Splitter Events

Close | Create | StartSplit
Splitting | EndSplit |


Static Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | FontOK | FontCancel
Select |  |


StatusBar Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
Select |  |


StatusField Events

Close | Create | DropObjects
Select | MouseDown | MouseUp
MouseMove | MouseDblClick |


SubForm Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
StateChange | MDIActivate | MDIDeactivate
DockStart | DockMove | DockRequest
DockAccept | DockEnd | DockCancel
Select | FrameContextMenu | VScroll
HScroll | VThumbDrag | HThumbDrag


SysTrayItem Events

Close | Create | MouseDown
MouseUp | MouseMove | MouseDblClick
BalloonShow | BalloonHide | BalloonTimeout
BalloonUserClick |  |


TabBar Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | Select |


TabBtn Events

Close | Create | FontOK
FontCancel | DropObjects | Select
MouseDown | MouseUp | MouseMove
MouseDblClick |  |


TabButton Events

Close Create Select


TabControl Events

Close Create


TCPSocket Events

Close | Create | TCPError
TCPAccept | TCPConnect | TCPRecv
TCPClose | TCPGotAddr | TCPGotPort
TCPReady |  |


Text Events

Close | Create | FontOK
FontCancel | DragDrop | MouseDown
MouseUp | MouseMove | MouseDblClick
Help | Select |


Timer Events

Close Create Timer


TipField Events

Close | Create | FontOK
FontCancel |  |


ToolBar Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | Select |


ToolButton Events

Close | Create | Help
MouseDown | MouseUp | MouseMove
MouseDblClick | Select |


ToolControl Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
MouseDown | MouseUp | MouseMove
MouseDblClick | MouseEnter | MouseLeave
MouseWheel | DockStart | DockMove
DockRequest | DockAccept | DockEnd
DockCancel |  |


TrackBar Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
KeyPress | GotFocus | LostFocus
MouseDown | MouseUp | MouseMove
Select | ThumbDrag | Scroll


TreeView Events

Close | Create | FontOK
FontCancel | DragDrop | Configure
ContextMenu | DropFiles | DropObjects
Expose | Help | KeyPress
GotFocus | LostFocus | MouseDown
MouseUp | MouseMove | MouseDblClick
MouseEnter | MouseLeave | MouseWheel
BeginEditLabel | EndEditLabel | Expanding
Retracting | ItemDown | ItemUp
ItemDblClick | GetTipText | Select


UpDown Events

Close | Create | DragDrop
Configure | ContextMenu | DropFiles
DropObjects | Expose | Help
MouseDown | MouseUp | MouseMove
MouseEnter | MouseLeave | Select
Spin |  |


Splitter: Example 1
'F'⎕WC'Form' 'Vertical Splitter'('Size' 25 25)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.S'⎕WC'Splitter' 'F.E1' 'F.E2'


Splitter: Example 2
'F'⎕WC'Form' 'Horizontal Splitter'('Size' 25 25)
'F.E1'⎕WC'Edit'(5 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(5 6⍴'Edit 2')('Style' 'Multi')
'F.S'⎕WC'Splitter' 'F.E1' 'F.E2'('Style' 'Horz')


Splitter: Example 3
'F'⎕WC'Form' 'Multiple Splitters: hierarchical using SubForms'('Size' 25 50)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.SF1'⎕WC'SubForm'('EdgeStyle' 'Default')
'F.S1'⎕WC'Splitter' 'F.E1' 'F.SF1'
'F.SF1.E1'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.SF1.E2'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.SF1.S1'⎕WC'Splitter' 'F.SF1.E1' 'F.SF1.E2'

After dragging the first Splitter to the left.


Splitter: Example 4
'F'⎕WC'Form' 'Multiple Splitters: non-hierarchical'('Size' 25 50)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.E3'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.S1'⎕WC'Splitter' 'F.E1'
'F.S2'⎕WC'Splitter' 'F.E2' 'F.E3'

After dragging the first Splitter to the left.


Splitter: Example 5
'F'⎕WC'Form' 'Combining Horizontal and Vertical Splitters'
'F.E1'⎕WC'Edit'(20 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.E3'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.E4'⎕WC'Edit'(5 6⍴'Edit 4')('Style' 'Multi')
'F.E5'⎕WC'Edit'(5 6⍴'Edit 5')('Style' 'Multi')

'F.S1'⎕WC'Splitter' 'F.E1'('Style' 'Vert')
'F.S2'⎕WC'Splitter' 'F.E2'('Style' 'Horz')
'F.S3'⎕WC'Splitter' 'F.E3'('Style' 'Vert')
'F.S4'⎕WC'Splitter' 'F.E4' 'F.E5'('Style' 'Horz')


TabControl: Example 1
'F'⎕WC'Form' 'TabControl: Default'('Size' 25 50)
'F.TC'⎕WC'TabControl'

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 2
'F'⎕WC'Form' 'TabControl: Buttons Style'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Style' 'Buttons')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 3
'F'⎕WC'Form' 'TabControl: FlatButtons Style'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Style' 'FlatButtons')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 3a
'F1'⎕WC'Form' 'TabControl: FlatButtons with FlatSeparators'('Size' 25 50)
'F1.TC'⎕WC'TabControl'('Style' 'FlatButtons')('FlatSeparators' 1)

'F1.TC.IL'⎕WC'ImageList'
'F1.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F1.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F1.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F1.TC'⎕WS'ImageListObj' 'F1.TC.IL'

'F1.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F1.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F1.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 4
'F'⎕WC'Form' 'TabControl: Align Bottom'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Align' 'Bottom')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 5
'F'⎕WC'Form' 'TabControl: Align Left'('Size' 40 30)
'F.TC'⎕WC'TabControl'('Align' 'Left')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 6
'F'⎕WC'Form' 'TabControl: Align Right'('Size' 40 30)
'F.TC'⎕WC'TabControl'('Align' 'Right')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 7
'F'⎕WC'Form' 'TabControl: Default Scrolling'('Size' 25 40)
'F.TC'⎕WC'TabControl'

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')
'F.TC.S4'⎕WC'SubForm'('TabObj' 'F.TC.T4')


TabControl: Example 8
'F'⎕WC'Form' 'TabControl: MultiLine Tabs'('Size' 25 40)
'F.TC'⎕WC'TabControl'('MultiLine' 1)

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 9
'F'⎕WC'Form' 'TabControl: MultiLine Buttons'('Size' 25 40)
'F.TC'⎕WC'TabControl'('Style' 'Buttons')( 'MultiLine' 1))

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 10
'F'⎕WC'Form' 'TabControl: ScrollOpposite'('Size' 25 40)
'F.TC'⎕WC'TabControl'('ScrollOpposite' 1)

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 11
'F'⎕WC'Form' 'TabControl: MultiLine Tabs, Justify None'('Size' 25 40)
'F.TC'⎕WC'TabControl'('MultiLine' 1)('Justify ' 'None')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 12
'F'⎕WC'Form' 'TabControl: MultiLine Buttons, Justify None'('Size' 25 40)
'F.TC'⎕WC'TabControl'('Style ' 'Buttons') ('MultiLine' 1)('Justify ' 'None')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 13

The TabJustify Property.


ToolControl: Example 3
'F'⎕WC'Form' 'ToolControl: Transparent 1)'('Size' 10 40)
'F.BM'⎕WC'Bitmap' 'C:\WINDOWS\WINLOGO'
'F'⎕WS'Picture' 'F.BM' 1

'F.TB'⎕WC'ToolControl'('Transparent' 1)('Style' 'FlatList')
'F.TB.IL'⎕WC'ImageList'('Masked' 0)('Size' 24 24)
'F.TB.IL.'⎕WC'Bitmap'('ComCtl32' 121)⍝ STD_LARGE
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
'F.TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
'F.TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)


ActiveXContainer Methods

Detach OLEQueryInterface


ActiveXControl Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
SetFnInfo | SetVarInfo | SetEventInfo


Animation Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | AnimOpen
AnimClose | AnimPlay | AnimStop


Bitmap Methods

Detach | FileRead | FileWrite
MakePNG | MakeGIF | GetTextSize


BrowseBox Methods

Detach Wait


Button Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


ButtonEdit Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP


Calendar Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
GetVisibleRange | GetMinSize | IDNToDate
DateToIDN |  |


Circle Methods

Detach


Clipboard Methods

Detach Wait


ColorButton Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


Combo Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


ComboEx Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP


CoolBand Methods

Detach


CoolBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


Cursor Methods

Detach FileRead FileWrite


DateTimePicker Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
IDNToDate | DateToIDN |


Edit Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


Ellipse Methods

Detach


FileBox Methods

Detach Wait


Font Methods

Detach ChooseFont


Form Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont
Wait |  |


Grid Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
DelRow | DelCol | SetCellType
RowChange | ColChange | Undo
SetCellSet | RowSetVisibleDepth | ColSorted
DuplicateRow | DuplicateColumn | CellFromPoint
GetCellRect | LockRows | LockColumns
AddComment | DelComment | GetComment


Group Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


Icon Methods

Detach FileRead FileWrite


Image Methods

Detach


ImageList Methods

Detach


Label Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


List Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


ListView Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
GetItemState | SetItemState | GetItemPosition


Locator Methods

Detach Wait


Marker Methods

Detach


MDIClient Methods

Detach | MDICascade | MDITile
MDIArrange | GetTextSize | Animate
GetFocus | ShowSIP |


Menu Methods

Detach Wait


MenuBar Methods

Detach


MenuItem Methods

Detach


Metafile Methods

Detach FileRead FileWrite


MsgBox Methods

Detach Wait


NetType Methods


OCXClass Methods

Detach | GetPropertyInfo | GetEventInfo
GetMethodInfo | GetTypeInfo | SetPropertyInfo
SetMethodInfo | ShowHelp | ShowProperties
Browse | OLEAddEventSink | OLEDeleteEventSink
OLEListEventSinks |  |


OLEClient Methods

Browse | Detach | GetEventInfo
GetMethodInfo | GetPropertyInfo | GetTypeInfo
OLEAddEventSink | OLEDeleteEventSink | OLEListEventSinks
OLEQueryInterface | SetMethodInfo | SetPropertyInfo
ShowHelp |  |


OLEServer Methods

Detach | OLERegister | OLEUnregister
SetFnInfo | SetVarInfo | SetEventInfo


Poly Methods

Detach


Printer Methods

Detach | Print | Setup
NewPage | Abort | RTFPrintSetup
GetTextSize |  |


ProgressBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ProgressStep


PropertyPage Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP


PropertySheet Methods

Detach | ChooseFont | SetFinishText
CancelToClose | GetFocus | Wait


Rect Methods

Detach


RichEdit Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP
RTFPrintSetup | RTFPrint | FileRead
FileWrite |  |


Root Methods

ChooseFont | Flush | NameFromHandle
GreetBitmap | GetCommandLine | GetCommandLineArgs
GetEnvironment | ListTypeLibs | DeleteTypeLib
GetTextSize | GetFocus | ShowSIP
IDNToDate | DateToIDN | TCPGetHostID
GetBuildID | Wait |


Scroll Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


Separator Methods

Detach


SM Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


Spinner Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP


Splitter Methods

Detach


Static Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


StatusBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP | ChooseFont


StatusField Methods

Detach


SubForm Methods

Detach | ChooseFont | GetTextSize
Animate | GetFocus | ShowSIP


SysTrayItem Methods

Detach ShowBalloonTip Wait


TabBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


TabBtn Methods

Detach ChooseFont


TabButton Methods

Detach


TabControl Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


TCPSocket Methods

Detach | TCPSend | TCPGetHostID
TCPSendPicture | Wait |


Text Methods

Detach ChooseFont


Timer Methods

Detach Wait


TipField Methods

Detach ChooseFont


ToolBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


ToolButton Methods

Detach


ToolControl Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


TrackBar Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


TreeView Methods

Detach | ChooseFont | GetItemState
SetItemState | AddItems | DeleteItems
AddChildren | DeleteChildren | GetParentItem
GetItemHandle | SetItemImage | ShowItem
GetTextSize | Animate | GetFocus
ShowSIP |  |


UpDown Methods

Detach | GetTextSize | Animate
GetFocus | ShowSIP |


Animate Method

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | TabControl | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


ChooseFont Method

ActiveXControl | Button | ButtonEdit
Calendar | Combo | ComboEx
DateTimePicker | Edit | Font
Form | Grid | Group
Label | List | ListView
PropertyPage | PropertySheet | RichEdit
Root | Spinner | Static
StatusBar | SubForm | TabBtn
Text | TipField | TreeView


Close Event

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OLEServer
Poly | Printer | ProgressBar
PropertyPage | PropertySheet | Rect
RichEdit | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Configure Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | ToolBar | ToolControl
TrackBar | TreeView | UpDown


ContextMenu Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


Create Event

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OLEServer
Poly | Printer | ProgressBar
PropertyPage | PropertySheet | Rect
RichEdit | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Detach Method

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Scroll | Separator | SM
Spinner | Splitter | Static
StatusBar | StatusField | SubForm
SysTrayItem | TabBar | TabBtn
TabButton | TabControl | TCPSocket
Text | Timer | TipField
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


DragDrop Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
CoolBar | DateTimePicker | Edit
Ellipse | Form | Grid
Group | Image | Label
List | ListView | Marker
MDIClient | Poly | ProgressBar
PropertyPage | Rect | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | Text | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


DropDown Event

Button | ButtonEdit | ColorButton
Combo | ComboEx | DateTimePicker
Menu |  |


DropFiles Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


DropObjects Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | Spinner | Static
StatusBar | StatusField | SubForm
TabBar | TabBtn | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


Expose Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


FontCancel Event

ActiveXControl | Button | ButtonEdit
Calendar | Combo | ComboEx
DateTimePicker | Edit | Font
Form | Grid | Group
Label | List | ListView
PropertyPage | PropertySheet | RichEdit
Root | Spinner | Static
StatusBar | SubForm | TabBtn
Text | TipField | TreeView


FontOK Event

ActiveXControl | Button | ButtonEdit
Calendar | Combo | ComboEx
DateTimePicker | Edit | Font
Form | Grid | Group
Label | List | ListView
PropertyPage | PropertySheet | RichEdit
Root | Spinner | Static
StatusBar | SubForm | TabBtn
Text | TipField | TreeView


GetFocus Method

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | PropertySheet
RichEdit | Root | Scroll
SM | Spinner | Static
StatusBar | SubForm | TabBar
TabControl | ToolBar | ToolControl
TrackBar | TreeView | UpDown


GetTextSize Method

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Calendar
ColorButton | Combo | ComboEx
CoolBar | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | Printer | ProgressBar
PropertyPage | RichEdit | Root
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | TabControl | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


GotFocus Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | List | ListView
MDIClient | ProgressBar | PropertyPage
RichEdit | Scroll | Spinner
SubForm | TrackBar | TreeView


Help Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
CoolBar | DateTimePicker | Edit
Ellipse | Form | Grid
Group | Image | Label
List | ListView | Marker
MDIClient | Poly | ProgressBar
PropertyPage | Rect | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | Text | ToolBar
ToolButton | ToolControl | TrackBar
TreeView | UpDown |


KeyPress Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | List | ListView
MDIClient | ProgressBar | PropertyPage
RichEdit | Scroll | Spinner
SubForm | TrackBar | TreeView


LostFocus Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | List | ListView
MDIClient | ProgressBar | PropertyPage
RichEdit | Scroll | Spinner
SubForm | TrackBar | TreeView


MouseDblClick Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Form | Group | Image
Label | List | ListView
Marker | MDIClient | Poly
ProgressBar | PropertyPage | Rect
RichEdit | Scroll | SM
Spinner | Static | StatusBar
StatusField | SubForm | SysTrayItem
TabBar | TabBtn | Text
ToolBar | ToolButton | ToolControl
TreeView |  |


MouseDown Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Form | Group | Image
Label | List | ListView
Marker | MDIClient | Poly
ProgressBar | PropertyPage | Rect
RichEdit | Scroll | SM
Spinner | Static | StatusBar
StatusField | SubForm | SysTrayItem
TabBar | TabBtn | Text
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


MouseEnter Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | Label | List
ListView | MDIClient | ProgressBar
PropertyPage | RichEdit | Scroll
SM | Spinner | Static
StatusBar | SubForm | TabBar
ToolBar | ToolControl | TreeView
UpDown |  |


MouseLeave Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | Label | List
ListView | MDIClient | ProgressBar
PropertyPage | RichEdit | Scroll
SM | Spinner | Static
StatusBar | SubForm | TabBar
ToolBar | ToolControl | TreeView
UpDown |  |


MouseMove Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Form | Group | Image
Label | List | ListView
Marker | MDIClient | Poly
ProgressBar | PropertyPage | Rect
RichEdit | Scroll | Spinner
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | Text | ToolBar
ToolButton | ToolControl | TrackBar
TreeView | UpDown |


MouseUp Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Form | Group | Image
Label | List | ListView
Marker | MDIClient | Poly
ProgressBar | PropertyPage | Rect
RichEdit | Scroll | SM
Spinner | Static | StatusBar
StatusField | SubForm | SysTrayItem
TabBar | TabBtn | Text
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


MouseWheel Event

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Group
Label | List | ListView
MDIClient | ProgressBar | PropertyPage
RichEdit | Scroll | Spinner
Static | StatusBar | SubForm
TabBar | ToolBar | ToolControl
TreeView |  |


Select Event

ActiveXControl | Bitmap | Button
ButtonEdit | Calendar | Circle
Clipboard | Combo | ComboEx
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | Label
List | ListView | Locator
Marker | MDIClient | Menu
MenuItem | Metafile | Poly
Printer | ProgressBar | Rect
RichEdit | Scroll | Spinner
Static | StatusBar | StatusField
SubForm | TabBar | TabBtn
TabButton | Text | ToolBar
ToolButton | TrackBar | TreeView
UpDown |  |


ShowSIP Method

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
ProgressBar | PropertyPage | RichEdit
Root | Scroll | SM
Spinner | Static | StatusBar
SubForm | TabBar | TabControl
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


Wait Method

BrowseBox | Clipboard | FileBox
Form | Locator | Menu
MsgBox | PropertySheet | Root
SysTrayItem | TCPSocket | Timer


WorkspaceLoaded Event

WorkspaceLoaded Event 525
Applies To:

Description

If enabled, this event is reported when a workspace is loaded or on a clear ws. You may not nullify or modify the event with a 0-returning callback, nor may you generate the event using ⎕NQ, or call it as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event | 'WorkspaceLoaded' or 525

This event is fired immediately after a workspace has been loaded and before the execution of ⎕LX.

The callback function you attach should be defined in ⎕SE.


Class Identifier (CLSID)

The CLSID is a unique identifier that, when displayed, appears as a string of hexadecimal digits wrapped in braces; for example "{3B7C8860-D78F-101B-B9B5-04021C009402}".


COM data types

The table below shows the correspondence between COM data types and APL arrays.

OLE DataType | APL array
VT_BOOL | numeric scalar
VT_I1 | numeric scalar
VT_I2 | numeric scalar
VT_I4 | numeric scalar
VT_R4 | numeric scalar
VT_R8 | numeric scalar
VT_BSTR | character vector
VT_CY | 2-element numeric vector
VT_DATE | 6 element numeric vector
VT_VARIANT | any array
VT_SAFEARRAY | any array (VT_ARRAY OF VT_VARIANT)
VT_DISPATCH | ⎕OR of a namespace
VT_COLOR | 3-element RGB

APL vectors may be described by pre-fixing the data type string with 'VT_ARRAY OF '. For example 'VT_ARRAY OF BSTR' specifies a vector of character vectors.

If the APL array is the ⎕OR of a namespace, its data type should be specified as 'VT_DISPATCH'.


Globally Unique Identifier (GUID)

A Globally Unique Identifier (GUID) is a 128-bit number that is generated by a special algorithm and is virtually guaranteed a to be unique in the world. That is to say that every GUID generated by this algorithm is different from any other.

Dyalog APL properties that represent GUIDs are read-only character vectors that represent the GUID as a string of hexadecimal digits wrapped in braces.

For example "{3B7C8860-D78F-101B-B9B5-04021C009402}".


International Day Number

The values of dates used by the properties, events and methods of the Calendar object are specified using IDNs (International Day Numbers).

An IDN is an integer that represents a date as the number of days starting at Jan 1st 1900, i.e. Jan 01 1900 is IDN 1.

Note that the value of IDNs calculated by Dyalog APL are one less than IDNs calculated by Microsoft Excel which incorrectly assumes that 1900 was a leap year.


Port Number

A port number identifies the service provided by a particular server. It is an integer number in the range 0-65536,

Port numbers in the range 0-1023 are reserved for "well-known" services (e.g., FTP and HTTP).

Port number 1024 is reserved for IANA.

Port numbers 1025-5000 are typically assigned for user-defined services.


Stream Sockets

A Stream socket is a connection-based transport that is analogous to a telephone service. A Stream socket handles error correction, guarantees delivery, and preserves data sequence. This means that if you send two messages to a recipient, the messages are sure to arrive and in the sequence that you sent them. However, individual messages may be broken up into several packets (or accumulated into one), and there is no predetermined protocol to identify message boundaries. This means that Stream-based applications must implement some kind of message protocol that both ends of a connection understand and adhere to.


Twips

There are 1,440 Twips to one inch.


User Datagram Protocol (UDP)

User Datagram Protocol (UDP) is a connection-less transport mechanism that is somewhat similar to a postal service. It permits a sending application to transmit a message or messages to a recipient. It neither guarantees delivery nor acknowledgment, nor does it preserve the sequence of messages. Messages are also limited to fit into a single packet which is typically no more than 1500 bytes in size. However, a UDP message will be delivered in its entirety.

You may wonder why anybody would use a service that does not guarantee delivery. The answer is that although UDP is technically an unreliable service, it is perfectly possible to implement reliable applications on top of it by building in acknowledgments, time-outs and re-transmissions.


Native Look and Feel

Windows Native Look and Feel is an optional feature of Windows from Windows XP onwards.

If Native Look and Feel is enabled, user-interface controls such as Buttons take on a different appearance and certain controls (such as the ListView) provide enhanced features.

Dyalog Session

During development, both the Dyalog Session and the Dyalog APL GUI will display native style buttons, combo boxes, and other GUI components if Native Look and Feel is enabled. The option is provided in the General tab of the Configuration dialog.

Applications

There are two ways to enable Native Look and Feel in end-user applications.

If you use the File/Export… menu item on the Session MenuBar to create a bound executable, an OLE Server (in-process or out-of-process), an ActiveX Control or a .Net Assembly, check the option box labelled Enable Native Look and Feel in the create bound file dialog box. See User Guide.

If not, set the XPLookandFeel parameter to 1, when you run the program. For example:

dyalogrt.exe XPLookAndFeel=1 myws.dws

Note that to have effect, Native Look and Feel must also be enabled at the Windows level.


NetControl Object
Parents Children Properties
Purpose: The NetControl object provides the means to instantiate a .Net control in the Dyalog GUI.

Description

In principle, you may use the NetControl to embed any class that derives from System.Windows.Forms.Control (from system.windows.forms.dll), including derived classes written in Dyalog APL.

To load a particular .Net control, the appropriate .Net Assembly must be specified in ⎕USING; otherwise the expression will cause a LIMIT ERROR. For example, to load one of the standard .Net controls:

⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'

The ClassName property specifies the name of the .Net control to be instantiated and to which the new object named by the left argument of ⎕WC is to be connected. ClassName may only be specified by ⎕WC.

Once you have created an instance of a particular NetControl, the properties, events and methods it supports may be obtained using ⎕NL. These are the properties, events and methods defined for the control by its author. The "Dyalog" properties listed above, are not reported by ⎕NL, but take precedence over (i.e. mask) any members of the same name that may be exposed by the class itself.

The following example illustrates the use of the Button class. In this case, the FlatStyle property of the button is set to "Popup". This gives the button a flat appearance until the mouse is hovered over it, when its appearance it changes to 3-dimensional.

       ⎕USING←'System'
       ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'
       ⎕USING,←⊂'System.Drawing,system.drawing.dll'
       an←⎕NEW FontFamily(⊂'Arial')
       myfont←⎕NEW Font(an 24 FontStyle.Bold GraphicsUnit.Point)

       'f'⎕WC'Form'('Coord' 'Pixel')('Size' 120 200)
       f.Caption←'NetControl'
       'f.l'⎕WC'Label' 'Button with FlatStyle=Popup'(2 2)

       'f.b'⎕WC'NetControl' 'Button'('Size' 60 160)

       f.b.⎕NL ¯2
AutoSizeMode DialogResult AutoEllipsis AutoSize BackColor FlatStyle FlatAppearance...

       f.b.⎕NL ¯3
BeginInvoke BringToFront Contains CreateControl CreateGraphics CreateObjRef Dispose DoDragDrop...

       f.b.⎕NL¯8
DoubleClick MouseDoubleClick AutoSizeChanged ImeModeChanged BackColorChanged...

       f.b.Text←'Popup'
       f.b.Font←myfont

       f.b.(FlatStyle←FlatStyle.Popup)

Normal appearance (Flat) | Appearance when mouse over

In most cases, you may use a NetControl in the cells of a Grid object. Unless you specify otherwise, using the InputProperties property of the Grid, the default property of the NetControl will be associated with the corresponding element of Values. The following example illustrates the use of a TextBox control. In this example, the CharacterCasing property of the TextBox is set to Upper, causing all text to be converted to upper-case.

       ⎕USING←'System'
       ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'
       ⎕USING,←⊂'System.Drawing,system.drawing.dll'
       an←⎕NEW FontFamily(⊂'Arial Narrow')
       myfont←⎕NEW Font(an 11 FontStyle.BoldGraphicsUnit.Point)
       'f'⎕WC'Form'('Coord' 'Pixel')('Size' 130 500)
       f.Caption←'Grid using .Net TextBox Control'
       'f.g'⎕WC'Grid'('Posn' 0 0)f.Size
       f.g.(ShowInput TitleWidth)←1 0
       'f.g.tb'⎕WC'NetControl' 'TextBox'
       f.g.tb.Font←myfont
       f.g.tb.(CharacterCasing←CharacterCasing.Upper)
       f.g.Input←'f.g.tb'
       wds←'All' 'TeXt' 'Is' 'Changed' 'to' 'Upper' 'casE'
       wds,←'ακομα' 'kai' 'τα' 'Ελληνικα'
       f.g.Values←5 5⍴wds

Implementation note: The instance of the .Net control is actually placed inside an instance of the .Net class System.Windows.Forms.ContainerControl.This ContainerControl is then embedded in the Dyalog parent, such as a Form. This "extra level" should have no affect on how the control is used or on how it behaves.


ActiveXContainer Parents

ActiveXControl


ActiveXControl Parents

Form


Animation Parents

ActiveXControl | Form | Group
PropertyPage | SubForm |


Bitmap Parents

ActiveXControl | Animation | Button
CoolBand | Form | Grid
Group | ImageList | ListView
Menu | MenuBar | MenuItem
NetType | OLEServer | Printer
ProgressBar | PropertyPage | PropertySheet
RichEdit | Root | StatusBar
SubForm | TCPSocket | ToolBar
ToolButton | ToolControl | TrackBar
TreeView | UpDown |


BrowseBox Parents

ActiveXControl | CoolBand | Form
Grid | OLEServer | PropertyPage
PropertySheet | Root | StatusBar
SubForm | TCPSocket | ToolBar
ToolControl |  |


Button Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


ButtonEdit Parents

ActiveXControl | Form | Group
PropertyPage | SubForm |


Calendar Parents

ActiveXControl | Form | Group
PropertyPage | SubForm | ToolBar


Circle Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


Clipboard Parents

ActiveXControl | CoolBand | Form
OLEServer | PropertyPage | PropertySheet
Root | TCPSocket |


ColorButton Parents

ActiveXControl | Form | Grid
Group | PropertyPage | SubForm


Combo Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


ComboEx Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


CoolBand Parents

CoolBar


CoolBar Parents

ActiveXControl Form


Cursor Parents

ActiveXControl | Animation | Button
Calendar | Combo | ComboEx
CoolBand | DateTimePicker | Edit
Form | Grid | Group
ImageList | Label | List
ListView | OLEServer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Root | Scroll | SM
Static | StatusBar | SubForm
TCPSocket | ToolBar | ToolControl
TrackBar | TreeView | UpDown


DateTimePicker Parents

ActiveXControl | Form | Grid
Group | PropertyPage | SubForm
ToolBar |  |


Edit Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


Ellipse Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


FileBox Parents

ActiveXControl | CoolBand | Form
Grid | OLEServer | PropertyPage
PropertySheet | Root | StatusBar
SubForm | TCPSocket | ToolBar
ToolControl |  |


Font Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Calendar
Combo | ComboEx | CoolBand
DateTimePicker | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | OLEServer | Printer
ProgressBar | PropertyPage | PropertySheet
RichEdit | Root | Scroll
Spinner | Static | StatusBar
SubForm | TabBar | TCPSocket
TipField | ToolBar | ToolControl
TrackBar | TreeView | UpDown


Form Parents

ActiveXControl | Form | OLEClient
OLEServer | Root | SubForm
TCPSocket |  |


Grid Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm


Group Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


Icon Parents

ActiveXControl | CoolBand | Form
Grid | ImageList | ListView
OLEServer | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Root | StatusBar | SubForm
SysTrayItem | TCPSocket | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


Image Parents

ActiveXControl | Bitmap | Form
Grid | Group | Metafile
Printer | PropertyPage | Static
StatusBar | SubForm | ToolBar
ToolControl |  |


ImageList Parents

ActiveXControl | ButtonEdit | CoolBand
CoolBar | Form | Group
ListView | OLEServer | PropertyPage
Root | SubForm | TabControl
TCPSocket | ToolBar | ToolControl
TreeView |  |


Label Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


List Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


ListView Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


Locator Parents

ActiveXControl | Form | Group
PropertyPage | PropertySheet | Root
Static | SubForm | TCPSocket
ToolBar | ToolControl |


Marker Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


MDIClient Parents

ActiveXControl Form SubForm


Menu Parents

ActiveXControl | Calendar | CoolBand
CoolBar | DateTimePicker | Form
Grid | Menu | MenuBar
OLEServer | Root | StatusField
SubForm | SysTrayItem | TCPSocket
ToolBar | ToolControl |


MenuBar Parents

ActiveXControl | Form | SubForm
ToolControl |  |


MenuItem Parents

Menu MenuBar


Metafile Parents

ActiveXControl | Bitmap | CoolBand
Form | Group | OLEServer
Printer | PropertyPage | PropertySheet
Root | Static | SubForm
TCPSocket | ToolBar | ToolControl


MsgBox Parents

ActiveXControl | Calendar | CoolBand
DateTimePicker | Form | Grid
OLEServer | PropertyPage | PropertySheet
Root | SubForm | TCPSocket
ToolBar | ToolControl |


NetClient Parents

NetType Root


NetControl Parents

Form | Grid | Group
PropertyPage | SubForm |


NetType Parents

Root


OCXClass Parents

ActiveXControl | CoolBand | Form
Grid | OLEServer | PropertyPage
Root | SubForm | TCPSocket
ToolBar | ToolControl |


OLEClient Parents

ActiveXControl | CoolBand | Form
OLEServer | Root | TCPSocket


OLEServer Parents

ActiveXControl | Form | OLEServer
Root |  |


Poly Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


Printer Parents

ActiveXControl | CoolBand | Form
OLEServer | PropertyPage | PropertySheet
Root | TCPSocket |


ProgressBar Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | StatusBar
SubForm | ToolBar | ToolControl


PropertyPage Parents

PropertySheet


PropertySheet Parents

ActiveXControl | Form | OLEServer
Root | SubForm | TCPSocket


Rect Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


RichEdit Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


Scroll Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


Separator Parents

Menu MenuBar


SM Parents

Form | Group | PropertyPage
SubForm | ToolBar | ToolControl


Spinner Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


Splitter Parents

ActiveXControl | Form | Group
PropertyPage | SubForm |


Static Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


StatusBar Parents

ActiveXControl | CoolBand | Form
SubForm |  |


StatusField Parents

StatusBar


SubForm Parents

ActiveXControl | CoolBand | Form
Group | MDIClient | PropertyPage
SubForm | TabControl | ToolBar
ToolControl |  |


SysTrayItem Parents

Form Root


TabBar Parents

ActiveXControl Form SubForm


TabBtn Parents

TabBar


TabButton Parents

TabControl


TabControl Parents

ActiveXControl | CoolBand | Form
SubForm |  |


TCPSocket Parents

ActiveXControl | Calendar | CoolBand
DateTimePicker | Form | NetType
OLEClient | OLEServer | PropertyPage
Root | SubForm | TCPSocket


Text Parents

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Combo
ComboEx | Edit | Form
Grid | Group | Label
List | ListView | MDIClient
Metafile | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | Spinner | Static
StatusBar | SubForm | TabBar
TipField | ToolBar | TrackBar
TreeView | UpDown |


Timer Parents

ActiveXControl | Animation | Bitmap
BrowseBox | Button | ButtonEdit
Calendar | Circle | Clipboard
Combo | ComboEx | CoolBand
CoolBar | Cursor | DateTimePicker
Edit | Ellipse | FileBox
Font | Form | Grid
Group | Icon | Image
ImageList | Label | List
ListView | Locator | Marker
MDIClient | Menu | MenuBar
MenuItem | Metafile | MsgBox
NetClient | NetType | OLEClient
OLEServer | Poly | Printer
ProgressBar | PropertyPage | PropertySheet
Rect | RichEdit | Root
Scroll | Separator | SM
Spinner | Splitter | Static
StatusBar | StatusField | SubForm
SysTrayItem | TabBar | TabBtn
TabButton | TabControl | TCPSocket
Text | Timer | TipField
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


TipField Parents

ActiveXControl | CoolBand | Form
Group | OLEServer | PropertyPage
PropertySheet | Root | SubForm
TCPSocket |  |


ToolBar Parents

ActiveXControl | CoolBand | Form
SubForm |  |


ToolButton Parents

ToolControl


ToolControl Parents

ActiveXControl | CoolBand | Form
SubForm |  |


TrackBar Parents

ActiveXControl | CoolBand | Form
Grid | Group | PropertyPage
SubForm | ToolBar | ToolControl


TreeView Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


UpDown Parents

ActiveXControl | CoolBand | Form
Group | PropertyPage | SubForm
ToolBar | ToolControl |


Accelerator Property

ActiveXControl | Bitmap | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | Cursor | DateTimePicker
Edit | Ellipse | Form
Grid | Group | Icon
Image | Label | List
ListView | Locator | Marker
MDIClient | Menu | MenuItem
Metafile | Poly | Printer
ProgressBar | Rect | RichEdit
Scroll | Spinner | Static
StatusBar | StatusField | SubForm
TabBar | TabBtn | TabButton
Text | ToolBar | ToolButton
TrackBar | TreeView | UpDown


AcceptFiles Property

ActiveXControl | Animation | Button
ButtonEdit | Combo | ComboEx
DateTimePicker | Edit | Form
Grid | Group | Image
Label | List | ListView
ProgressBar | PropertyPage | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | ToolBar | TrackBar
TreeView | UpDown |


Active Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | Label | List
ListView | Menu | MenuItem
ProgressBar | PropertyPage | PropertySheet
RichEdit | Scroll | Spinner
Splitter | Static | StatusBar
SubForm | TabBar | TabBtn
Text | Timer | ToolBar
ToolButton | TrackBar | TreeView
UpDown |  |


Align Property

Animation | Button | ButtonEdit
CoolBar | DateTimePicker | ListView
Menu | MenuItem | Scroll
Spinner | Splitter | StatusBar
StatusField | TabBar | TabBtn
TabControl | ToolBar | ToolControl


Attach Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | CoolBar | DateTimePicker
Edit | Grid | Group
Label | List | ListView
MDIClient | ProgressBar | RichEdit
Scroll | SM | Spinner
Static | StatusBar | StatusField
SubForm | TabBar | TabBtn
TabControl | ToolBar | ToolControl
TrackBar | TreeView | UpDown


AutoConf Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Form | Grid | Group
Image | Label | List
ListView | Marker | Poly
ProgressBar | Rect | RichEdit
Scroll | SM | Spinner
Static | StatusBar | StatusField
SubForm | TabBar | TabBtn
Text | ToolBar | TrackBar
TreeView | UpDown |


BCol Property

ActiveXContainer | ActiveXControl | Animation
Button | ButtonEdit | Circle
Combo | ComboEx | CoolBand
CoolBar | Edit | Ellipse
Form | Grid | Group
Label | List | ListView
MDIClient | Menu | MenuItem
Poly | ProgressBar | Rect
RichEdit | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | TabBar | TabBtn
Text | TipField | ToolBar
TrackBar | TreeView | UpDown


Border Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | RichEdit | Scroll
SM | Spinner | Static
StatusBar | StatusField | SubForm
TabBtn | ToolBar | TrackBar
TreeView | UpDown |


Caption Property

BrowseBox | Button | ColorButton
CoolBand | FileBox | Form
Group | Label | Menu
MenuItem | MsgBox | PropertyPage
PropertySheet | Root | StatusField
SubForm | TabBtn | TabButton
ToolButton |  |


ChildList Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Coord Property

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Calendar
Circle | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Ellipse | Form | Grid
Group | Image | Label
List | ListView | Locator
Marker | MDIClient | Menu
Metafile | Poly | Printer
ProgressBar | PropertyPage | PropertySheet
Rect | RichEdit | Root
Scroll | SM | Spinner
Splitter | Static | StatusBar
StatusField | SubForm | TabBar
Text | ToolBar | TrackBar
TreeView | UpDown |


CursorObj Property

ActiveXControl | Button | ButtonEdit
Calendar | Circle | ColorButton
Combo | ComboEx | CoolBar
DateTimePicker | Edit | Ellipse
Form | Grid | Group
Label | List | ListView
Locator | MDIClient | Poly
ProgressBar | Rect | RichEdit
Root | Scroll | SM
Spinner | Splitter | Static
StatusBar | SubForm | TabBar
Text | ToolBar | TrackBar
TreeView | UpDown |


Data Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Dragable Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
DateTimePicker | Edit | Ellipse
Grid | Group | Image
Label | List | ListView
Marker | Poly | ProgressBar
Rect | RichEdit | Scroll
SM | Spinner | Static
StatusField | Text | TrackBar
TreeView | UpDown |


EdgeStyle Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | DateTimePicker
Edit | FileBox | Form
Grid | Group | Image
Label | List | ListView
MDIClient | Menu | MenuBar
MenuItem | MsgBox | Printer
ProgressBar | PropertyPage | PropertySheet
Rect | RichEdit | Root
Scroll | Separator | SM
Spinner | Static | StatusBar
StatusField | SubForm | TabBtn
ToolBar | TrackBar | TreeView
UpDown |  |


Event Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Form
Grid | Group | Icon
Image | ImageList | Label
List | ListView | Locator
Marker | MDIClient | Menu
MenuBar | MenuItem | Metafile
MsgBox | OCXClass | OLEClient
OLEServer | Poly | Printer
ProgressBar | PropertyPage | PropertySheet
Rect | RichEdit | Root
Scroll | Separator | SM
Spinner | Splitter | Static
StatusBar | StatusField | SubForm
SysTrayItem | TabBar | TabBtn
TabButton | TabControl | TCPSocket
Text | Timer | TipField
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


EventList Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


FCol Property

ActiveXContainer | ActiveXControl | Button
ButtonEdit | Circle | Combo
ComboEx | CoolBand | CoolBar
Edit | Ellipse | Grid
Group | Label | List
ListView | Marker | Menu
MenuItem | Poly | Rect
RichEdit | Separator | Spinner
Static | StatusBar | StatusField
TabBtn | Text | TipField
ToolBar | TreeView | UpDown


File Property

Animation | Bitmap | Cursor
FileBox | Icon | Metafile
RichEdit |  |


FontObj Property

ActiveXContainer | ActiveXControl | Bitmap
Button | ButtonEdit | Calendar
Combo | ComboEx | DateTimePicker
Edit | Form | Grid
Group | Label | List
ListView | Menu | MenuBar
MenuItem | Printer | PropertyPage
PropertySheet | RichEdit | Root
Spinner | Static | StatusBar
StatusField | SubForm | TabBar
TabBtn | TabControl | Text
TipField | ToolBar | ToolControl
TrackBar | TreeView |


Handle Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBar
Cursor | DateTimePicker | Edit
Font | Form | Grid
Group | Icon | ImageList
Label | List | ListView
MDIClient | Menu | MenuBar
Metafile | OLEClient | OLEServer
Printer | ProgressBar | PropertySheet
RichEdit | Scroll | SM
Spinner | Static | StatusBar
SubForm | TabBar | TabControl
ToolBar | ToolControl | TrackBar
TreeView | UpDown |


Hint Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | MenuItem | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | ToolBar | ToolButton
TrackBar | TreeView | UpDown


HintObj Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | MenuItem | ProgressBar
PropertyPage | PropertySheet | RichEdit
Root | Scroll | SM
Spinner | Static | StatusBar
SubForm | TabBar | ToolBar
ToolButton | TrackBar | TreeView
UpDown |  |


HScroll Property

Combo | ComboEx | Edit
Form | Grid | ListView
RichEdit | Scroll | StatusBar
SubForm | TabBar | ToolBar
TrackBar | UpDown |


IconObj Property

Form | MDIClient | Root
SubForm | SysTrayItem | TabBar
ToolBar |  |


ImageIndex Property

ButtonEdit | ComboEx | CoolBand
ListView | Menu | MenuItem
TabButton | ToolButton | TreeView


ImageListObj Property

ButtonEdit | ComboEx | CoolBar
ListView | Menu | TabControl
ToolControl | TreeView |


Index Property

Combo | ComboEx | CoolBand
FileBox | Grid | List
TreeView |  |


KeepOnClose Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


MethodList Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


OnTop Property

Circle | Ellipse | Form
Image | Marker | Poly
PropertySheet | Rect | SubForm
TabBar | Text | ToolBar


Picture Property

ActiveXControl | Button | Clipboard
CoolBand | Form | Group
Image | MDIClient | SM
Static | StatusBar | StatusField
SubForm | TabBar | ToolBar


Points Property

Circle | Ellipse | Image
Marker | Poly | Rect
Text |  |


Posn Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | ColorButton
Combo | ComboEx | CoolBand
CoolBar | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
Locator | MDIClient | Menu
MenuItem | ProgressBar | PropertyPage
PropertySheet | RichEdit | Root
Scroll | Separator | SM
Spinner | Splitter | Static
StatusBar | StatusField | SubForm
TabBar | TabBtn | TabButton
TabControl | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


PropList Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Redraw Property

ActiveXControl | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | CoolBar | DateTimePicker
Edit | Form | Grid
Group | Label | List
ListView | MDIClient | ProgressBar
RichEdit | Scroll | SM
Spinner | Static | StatusBar
SubForm | TabBar | ToolBar
ToolControl | TrackBar | TreeView
UpDown |  |


Size Property

ActiveXControl | Animation | Bitmap
Button | ButtonEdit | Calendar
ColorButton | Combo | ComboEx
CoolBand | CoolBar | DateTimePicker
Edit | Ellipse | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Metafile | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | SM
Spinner | Splitter | Static
StatusBar | StatusField | SubForm
TabBar | TabBtn | TabButton
TabControl | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Sizeable Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
Locator | ProgressBar | RichEdit
Scroll | SM | Spinner
Static | StatusBar | StatusField
SubForm | TabBar | ToolBar
TrackBar | TreeView | UpDown


Step Property

Form | Locator | ProgressBar
Scroll | Spinner | SubForm
TrackBar | UpDown |


Style Property

Button | ButtonEdit | Calendar
Combo | ComboEx | DateTimePicker
Edit | FileBox | Icon
List | ListView | Locator
Marker | MenuItem | MsgBox
ProgressBar | PropertySheet | Separator
Splitter | Static | StatusField
TabControl | TCPSocket | ToolButton
ToolControl | TrackBar |


TabIndex Property

ActiveXControl | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | ProgressBar | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
TabBar | ToolBar | TrackBar
TreeView | UpDown |


Text Property

ButtonEdit | Clipboard | Combo
ComboEx | Edit | MsgBox
RichEdit | Spinner | StatusField
Text |  |


TextSize Property

ActiveXControl | Bitmap | Edit
Form | Grid | Printer
Root | Static | StatusBar
SubForm | TabBar | ToolBar


Thumb Property

Form | ProgressBar | Scroll
Spinner | SubForm | TrackBar
UpDown |  |


Tip Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | MenuItem | ProgressBar
PropertyPage | PropertySheet | RichEdit
Scroll | SM | Spinner
Static | StatusBar | SubForm
SysTrayItem | TabBar | TabButton
ToolBar | ToolButton | TrackBar
TreeView | UpDown |


TipObj Property

Animation | Button | ButtonEdit
Calendar | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
Label | List | ListView
MDIClient | MenuItem | ProgressBar
PropertyPage | PropertySheet | RichEdit
Root | Scroll | SM
Spinner | Static | StatusBar
SubForm | TabBar | ToolBar
TrackBar | TreeView | UpDown


Translate Property

ActiveXControl | Animation | Bitmap
BrowseBox | Button | ButtonEdit
Clipboard | ColorButton | Combo
ComboEx | DateTimePicker | Edit
Form | Grid | Group
ImageList | Label | List
ListView | MDIClient | Menu
MenuBar | MenuItem | Metafile
OCXClass | Printer | ProgressBar
PropertyPage | PropertySheet | RichEdit
Root | Scroll | Separator
Spinner | Static | StatusBar
StatusField | SubForm | SysTrayItem
TabBar | TabBtn | Text
TipField | ToolBar | TrackBar
TreeView | UpDown |


Type Property

ActiveXContainer | ActiveXControl | Animation
Bitmap | BrowseBox | Button
ButtonEdit | Calendar | Circle
Clipboard | ColorButton | Combo
ComboEx | CoolBand | CoolBar
Cursor | DateTimePicker | Edit
Ellipse | FileBox | Font
Form | Grid | Group
Icon | Image | ImageList
Label | List | ListView
Locator | Marker | MDIClient
Menu | MenuBar | MenuItem
Metafile | MsgBox | OCXClass
OLEClient | OLEServer | Poly
Printer | ProgressBar | PropertyPage
PropertySheet | Rect | RichEdit
Root | Scroll | Separator
SM | Spinner | Splitter
Static | StatusBar | StatusField
SubForm | SysTrayItem | TabBar
TabBtn | TabButton | TabControl
TCPSocket | Text | Timer
TipField | ToolBar | ToolButton
ToolControl | TrackBar | TreeView
UpDown |  |


Visible Property

ActiveXControl | Animation | Button
ButtonEdit | Calendar | Circle
ColorButton | Combo | ComboEx
CoolBand | DateTimePicker | Edit
Ellipse | Form | Grid
Group | Image | Label
List | ListView | Marker
MenuBar | Poly | ProgressBar
PropertySheet | Rect | RichEdit
Scroll | SM | Spinner
Splitter | Static | StatusBar
StatusField | SubForm | TabBar
TabBtn | TabControl | Text
ToolBar | ToolButton | ToolControl
TrackBar | TreeView | UpDown


VScroll Property

Combo | ComboEx | Edit
Form | Grid | List
ListView | RichEdit | Scroll
StatusBar | SubForm | TabBar
ToolBar | TrackBar | UpDown


XRange Property

ActiveXControl | Bitmap | Form
Grid | Group | MDIClient
Metafile | Printer | Root
Static | StatusBar | SubForm
TabBar | ToolBar |


YRange Property

ActiveXControl | Bitmap | Form
Grid | Group | MDIClient
Metafile | Printer | Root
Static | StatusBar | SubForm
TabBar | ToolBar |


ActiveXContainer Properties

Type | Event | FontObj
FCol | BCol | Data
KeepOnClose | MethodList | ChildList
EventList | PropList |


ActiveXControl Properties

Type | ClassName | Posn
Size | Coord | Border
Active | Visible | Event
Dragable | FontObj | FCol
BCol | Picture | CursorObj
AutoConf | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Translate | Accelerator
AcceptFiles | ClassID | Container
KeepOnClose | HelpFile | ToolboxBitmap
TypeLibID | TypeLibFile | LastError
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Animation Properties

Type | Posn | Size
File | Coord | Border
Active | Visible | Event
Sizeable | Dragable | BCol
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | AcceptFiles | KeepOnClose
AutoPlay | Transparent | Align
MethodList | ChildList | EventList
PropList |  |


Bitmap Properties

Type | File | Bits
CMap | KeepBits | Size
Coord | Event | FontObj
YRange | XRange | Data
TextSize | Translate | Accelerator
KeepOnClose | CBits | MaskCol
MethodList | ChildList | EventList
PropList |  |


BrowseBox Properties

Type | Caption | BrowseFor
Target | StartIn | HasEdit
Event | Data | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


Button Properties

Type | Caption | Posn
Size | Style | Coord
Align | State | Default
Cancel | Border | Justify
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
BtnPix | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | ReadOnly
Translate | Accelerator | AcceptFiles
KeepOnClose | Redraw | TabIndex
Elevated | Note | MethodList
ChildList | EventList | PropList


ButtonEdit Properties

Type | Text | Posn
Size | Style | Coord
Align | Border | Justify
Active | Visible | Event
ImageListObj | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FieldType | MaxLength
Decimals | Password | ValidIfEmpty
ReadOnly | FormatString | Changed
Value | Translate | Accelerator
AcceptFiles | KeepOnClose | Transparent
ImageIndex | Redraw | TabIndex
Cue | ShowCueWhenFocused | MethodList
ChildList | EventList | PropList


Calendar Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
FirstDay | MaxSelCount | SelDate
MinDate | MaxDate | CalendarCols
Today | HasToday | CircleToday
WeekNumbers | MonthDelta | Sizeable
Dragable | FontObj | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Accelerator | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Circle Properties

Type | Points | Radius
FCol | BCol | Start
End | ArcMode | LStyle
LWidth | FStyle | FillCol
Coord | Visible | Event
Dragable | OnTop | CursorObj
AutoConf | Data | Accelerator
KeepOnClose | DrawMode | RadiusMode
MethodList | ChildList | EventList
PropList |  |


Clipboard Properties

Type | Event | Data
Formats | Text | Bits
CMap | CBits | MetafileObj
Picture | Array | RTFText
Translate | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


ColorButton Properties

Type | Caption | Posn
Size | CurrentColor | DefaultColors
CustomColors | OtherButton | Coord
Active | Visible | Event
Sizeable | Dragable | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | KeepOnClose
ShowDropDown | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


Combo Properties

Type | Items | Text
Posn | Size | Style
Coord | Rows | Border
Active | Visible | Event
VScroll | HScroll | SelItems
SelText | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Index
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


ComboEx Properties

Type | Items | Text
Posn | Size | Style
Coord | Rows | Border
Active | Visible | Event
Indents | ImageListObj | ImageIndex
SelImageIndex | CaseSensitive | EditImage
EditImageIndent | PathWordBreak | VScroll
HScroll | SelItems | SelText
Sizeable | Dragable | FontObj
FCol | BCol | CursorObj
AutoConf | Index | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


CoolBand Properties

Type | Caption | Posn
Size | Visible | Event
ImageIndex | FCol | BCol
Picture | Index | Data
KeepOnClose | ChildEdge | NewLine
GripperMode | Dockable | UndocksToRoot
MethodList | ChildList | EventList
PropList |  |


CoolBar Properties

Type | Posn | Size
Align | Event | ImageListObj
FCol | BCol | CursorObj
Data | Attach | Handle
KeepOnClose | BandBorders | DblClickToggle
FixedOrder | VariableHeight | DockChildren
Redraw | MethodList | ChildList
EventList | PropList |


Cursor Properties

Type | File | Bits
CMap | Mask | HotSpot
KeepBits | Event | Data
Handle | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


DateTimePicker Properties

Type | Posn | Size
Style | Coord | Align
Border | Active | Visible
Event | DateTime | MinDate
MaxDate | CalendarCols | Today
HasToday | CircleToday | WeekNumbers
MonthDelta | HasCheckBox | FieldType
CustomFormat | Sizeable | Dragable
FontObj | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Edit Properties

Type | Text | Posn
Size | Style | Coord
Border | Justify | Active
Visible | Event | VScroll
HScroll | SelText | Sizeable
Dragable | FontObj | FCol
BCol | CursorObj | AutoConf
Data | Attach | TextSize
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
FieldType | MaxLength | Decimals
Password | ValidIfEmpty | ReadOnly
FormatString | Changed | Value
Translate | Accelerator | AcceptFiles
WantsReturn | KeepOnClose | Redraw
TabIndex | Cue | ShowCueWhenFocused
MethodList | ChildList | EventList
PropList |  |


Ellipse Properties

Type | Points | Size
FCol | BCol | Start
End | ArcMode | LStyle
LWidth | FStyle | FillCol
Coord | Visible | Event
Dragable | OnTop | CursorObj
AutoConf | Data | Accelerator
KeepOnClose | DrawMode | MethodList
ChildList | EventList | PropList


FileBox Properties

Type | Caption | Directory
Filters | File | FileMode
Style | Event | Index
Data | EdgeStyle | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Font Properties

Type | PName | Size
Fixed | Italic | Underline
Weight | Rotate | CharSet
Data | Handle | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Form Properties

Type | Caption | Posn
Size | Coord | State
Border | Active | Visible
Event | Thumb | Range
Step | VScroll | HScroll
Sizeable | Moveable | SysMenu
MaxButton | MinButton | HelpButton
OKButton | SIPMode | SIPResize
FontObj | BCol | Picture
OnTop | IconObj | CursorObj
AutoConf | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Dockable | Docked | DockShowCaption
DockChildren | UndocksToRoot | MaskCol
AlphaBlend | Redraw | TabIndex
PageSize | MethodList | ChildList
EventList | PropList |


Grid Properties

Type | Values | Posn
Size | FCol | BCol
Coord | Border | Active
Visible | Event | VScroll
HScroll | SelItems | Sizeable
Dragable | FontObj | CursorObj
AutoConf | Index | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FormatString | RowTitles
ColTitles | CurCell | TitleWidth
CellHeights | CellWidths | TitleHeight
CellFonts | Input | CellTypes
AutoExpand | CellSelect | ResizeRows
ResizeCols | ResizeRowTitles | ResizeColTitles
ClipCells | InputModeKey | InputMode
GridFCol | GridBCol | ShowInput
CellSet | RowTitleFCol | ColTitleFCol
RowTitleDepth | ColTitleDepth | RowTitleAlign
ColTitleAlign | OverflowChar | AlignChar
GridLineFCol | GridLineWidth | RowLineTypes
ColLineTypes | EnterReadOnlyCells | RowTitleBCol
ColTitleBCol | RowTreeDepth | RowTreeStyle
RowTreeImages | ColSortImages | SelectionColor
SelectionColorAlpha | SelectionBorderWidth | HighlightHeaders
Translate | Accelerator | AcceptFiles
KeepOnClose | Redraw | InputProperties
TabIndex | AlwaysShowSelection | AlwaysShowBorder
RowHiddenDepth | MethodList | ChildList
EventList | PropList |


Group Properties

Type | Caption | Posn
Size | Coord | Border
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
CursorObj | AutoConf | YRange
XRange | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | AcceptFiles
KeepOnClose | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


Icon Properties

Type | File | Bits
CMap | Mask | Style
KeepBits | Size | Event
Data | Handle | Accelerator
KeepOnClose | CBits | MethodList
ChildList | EventList | PropList


Image Properties

Type | Points | Coord
Visible | Event | Dragable
Picture | OnTop | AutoConf
Data | EdgeStyle | Size
Accelerator | AcceptFiles | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


ImageList Properties

Type | Size | Event
Data | Handle | Translate
ImageCount | Masked | MapCols
KeepOnClose | MethodList | ChildList
EventList | PropList |


Label Properties

Type | Caption | Posn
Size | Coord | Border
Justify | Active | Visible
Event | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FieldType | Decimals
FormatString | Value | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


List Properties

Type | Items | Posn
Size | Style | Coord
Border | Active | Visible
Event | VScroll | SelItems
Sizeable | Dragable | FontObj
FCol | BCol | CursorObj
AutoConf | Index | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | MultiColumn | ColumnWidth
KeepOnClose | Redraw | SortItems
TabIndex | MethodList | ChildList
EventList | PropList |


ListView Properties

Type | Items | Posn
Size | Style | Coord
Align | Border | Active
Visible | Event | DragItems
View | AutoArrange | Header
Wrap | EditLabels | ImageListObj
ReportInfo | ColTitles | ImageIndex
ReportImageIndex | ReportBCol | HeaderImageList
HeaderImageIndex | VScroll | HScroll
SelItems | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | ColTitleAlign | ColTitle3D
Translate | Accelerator | AcceptFiles
KeepOnClose | CheckBoxes | FullRowSelect
GridLines | Redraw | TabIndex
AlwaysShowSelection | ItemGroups | ItemGroupMetrics
MethodList | ChildList | EventList
PropList |  |


Locator Properties

Type | Posn | Size
LStyle | Style | Coord
Event | Step | Sizeable
CursorObj | Data | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


Marker Properties

Type | Points | Style
Size | FCol | Coord
Visible | Event | Dragable
OnTop | AutoConf | Data
Accelerator | KeepOnClose | DrawMode
MethodList | ChildList | EventList
PropList |  |


MDIClient Properties

Type | Posn | Size
Coord | Border | Event
BCol | Picture | IconObj
CursorObj | YRange | XRange
Data | Attach | EdgeStyle
Handle | MDIActive | MDIActiveObject
Hint | HintObj | Tip
TipObj | Translate | Accelerator
KeepOnClose | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


Menu Properties

Type | Caption | Posn
Coord | Align | Active
Event | FontObj | FCol
BCol | BtnPix | Data
EdgeStyle | Handle | Translate
Accelerator | KeepOnClose | ImageListObj
ImageIndex | MethodList | ChildList
EventList | PropList |


MenuBar Properties

Type | Visible | Event
FontObj | Data | EdgeStyle
MDIMenu | Handle | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


MenuItem Properties

Type | Caption | Posn
Style | Align | Active
Event | Checked | FontObj
FCol | BCol | BtnPix
Data | EdgeStyle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | KeepOnClose
ImageIndex | MethodList | ChildList
EventList | PropList |


Metafile Properties

Type | File | Size
Coord | RealSize | Event
YRange | XRange | Data
Handle | Translate | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


MsgBox Properties

Type | Caption | Text
Style | Btns | Default
Event | Data | EdgeStyle
KeepOnClose | MethodList | ChildList
EventList | PropList |


NetControl Properties

Type | Posn | Size
Coord | ClassName | Attach
MethodList | ChildList | EventList
PropList |  |


NetType Properties

BaseClass


OCXClass Properties

Type | ClassName | Event
Data | Translate | ClassID
KeepOnClose | TypeList | HelpFile
ToolboxBitmap | LicenseKey | QueueEvents
MethodList | ChildList | EventList
PropList |  |


OLEClient Properties

Type | ClassName | Event
Data | Handle | ClassID
KeepOnClose | TypeList | HelpFile
LastError | Locale | AutoBrowse
QueueEvents | InstanceMode | MethodList
ChildList | EventList | PropList


OLEServer Properties

Type | ClassName | Event
Data | Handle | ExportedFns
ExportedVars | ClassID | KeepOnClose
TypeLibID | TypeLibFile | ServerVersion
LastError | RunMode | ShowSession
MethodList | ChildList | EventList
PropList |  |


Poly Properties

Type | Points | FCol
BCol | LStyle | LWidth
FStyle | FillCol | Coord
Visible | Event | Dragable
OnTop | CursorObj | AutoConf
Data | Accelerator | KeepOnClose
DrawMode | MethodList | ChildList
EventList | PropList |


Printer Properties

Type | PName | DevCaps
Coord | Event | FontObj
FontList | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Orientation | Copies
PrintRange | Collate | PaperSize
PaperSizes | PaperSource | PaperSources
ColorMode | Resolution | Resolutions
Duplex | Translate | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


ProgressBar Properties

Type | Posn | Size
Style | Coord | Active
Visible | Event | Thumb
Step | Wrap | Limits
Sizeable | Dragable | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | ProgressStyle
Redraw | TabIndex | Interval
MethodList | ChildList | EventList
PropList |  |


PropertyPage Properties

Type | Caption | Posn
Size | Coord | Active
Event | HasHelp | FontObj
Data | EdgeStyle | Hint
HintObj | Tip | TipObj
Changed | Translate | AcceptFiles
KeepOnClose | MethodList | ChildList
EventList | PropList |


PropertySheet Properties

Type | Caption | Posn
Size | Style | Coord
Active | Visible | Event
HasApply | HasHelp | PageActive
PageActiveObject | HelpButton | FontObj
OnTop | Data | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


Rect Properties

Type | Points | Size
Radius | FCol | BCol
LStyle | LWidth | FStyle
FillCol | Coord | Visible
Event | Dragable | OnTop
CursorObj | AutoConf | Data
EdgeStyle | Accelerator | KeepOnClose
DrawMode | MethodList | ChildList
EventList | PropList |


RichEdit Properties

Type | Text | Posn
Size | File | Coord
Border | Active | Visible
Event | VScroll | HScroll
SelText | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Changed | RTFText
Translate | Accelerator | CharFormat
WordFormat | ParaFormat | PageWidth
AcceptFiles | WantsReturn | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Root Properties

Type | Caption | Posn
Size | DevCaps | Coord
Event | FontObj | FontList
PrintList | IconObj | CursorObj
YRange | XRange | Data
TextSize | Yield | EdgeStyle
HintObj | TipObj | Translate
UpperCase | APLVersion | EvaluationDays
KeepOnClose | OLEControls | OLEServers
LastError | RadiusMode | MethodList
ChildList | EventList | PropList


Scroll Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
Thumb | Range | Step
VScroll | HScroll | Limits
Sizeable | Dragable | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | PageSize | MethodList
ChildList | EventList | PropList


Separator Properties

Type | Posn | Style
Event | FCol | BCol
Data | EdgeStyle | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


SM Properties

Type | Posn | Size
Coord | Border | Visible
Event | Sizeable | Dragable
BCol | Picture | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Spinner Properties

Type | Items | Text
Posn | Size | Coord
Align | Border | Justify
Active | Visible | Event
Thumb | Step | Wrap
Limits | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FieldType | MaxLength
Decimals | Password | ValidIfEmpty
ReadOnly | FormatString | Changed
Value | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Splitter Properties

Type | SplitObj1 | SplitObj2
Posn | Size | Style
Coord | Align | Active
Visible | Event | BCol
CursorObj | Data | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Static Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
CursorObj | AutoConf | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


StatusBar Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
VScroll | HScroll | Sizeable
FontObj | FCol | BCol
Picture | CursorObj | AutoConf
YRange | XRange | Data
Attach | TextSize | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


StatusField Properties

Type | Caption | Text
Posn | Size | Style
Coord | Align | Border
Visible | Event | Sizeable
Dragable | FontObj | FCol
BCol | Picture | AutoConf
Data | Attach | EdgeStyle
Translate | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


SubForm Properties

Type | Caption | Posn
Size | Coord | State
Border | Active | Visible
Event | Thumb | Range
Step | VScroll | HScroll
Sizeable | Moveable | SysMenu
MaxButton | MinButton | HelpButton
FontObj | BCol | Picture
OnTop | IconObj | CursorObj
AutoConf | YRange | XRange
Data | Attach | TextSize
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
TabObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Dockable
Docked | DockShowCaption | DockChildren
UndocksToRoot | Redraw | TabIndex
PageSize | MethodList | ChildList
EventList | PropList |


SysTrayItem Properties

Type | Event | IconObj
Data | Tip | Translate
Popup | KeepOnClose | MethodList
ChildList | EventList | PropList


TabBar Properties

Type | Posn | Size
Coord | Align | Active
Visible | Event | VScroll
HScroll | Sizeable | FontObj
BCol | Picture | OnTop
IconObj | CursorObj | AutoConf
YRange | XRange | Data
Attach | TextSize | Handle
Hint | HintObj | Tip
TipObj | TabObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


TabBtn Properties

Type | Caption | Posn
Size | Align | Border
Active | Visible | Event
FontObj | FCol | BCol
AutoConf | Data | Attach
EdgeStyle | TabObj | Translate
Accelerator | KeepOnClose | MethodList
ChildList | EventList | PropList


TabButton Properties

Type | Caption | Posn
Size | State | Event
ImageIndex | Data | Tip
TabObj | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


TabControl Properties

Type | Posn | Size
Style | Visible | Event
ImageListObj | FontObj | Data
Attach | Handle | TabObj
KeepOnClose | MultiLine | TabSize
Justify | TabJustify | Align
MultiSelect | TabFocus | HotTrack
ScrollOpposite | FlatSeparators | MethodList
ChildList | EventList | PropList


TCPSocket Properties

Type | LocalAddr | LocalPort
RemoteAddr | RemotePort | Style
Event | LocalAddrName | LocalPortName
RemoteAddrName | RemotePortName | Data
SocketType | SocketNumber | CurrentState
TargetState | KeepOnClose | Encoding
MethodList | ChildList | EventList
PropList |  |


Text Properties

Type | Text | Points
FCol | BCol | VAlign
HAlign | Coord | Active
Visible | Event | Dragable
FontObj | OnTop | CursorObj
AutoConf | Data | Translate
Accelerator | KeepOnClose | DrawMode
MethodList | ChildList | EventList
PropList |  |


Timer Properties

Type | Interval | Active
Event | Data | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


TipField Properties

Type | Event | FontObj
FCol | BCol | Data
Translate | KeepOnClose | MethodList
ChildList | EventList | PropList


ToolBar Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
VScroll | HScroll | Sizeable
FontObj | FCol | BCol
Picture | OnTop | IconObj
CursorObj | AutoConf | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


ToolButton Properties

Type | Caption | Posn
Size | Style | State
Active | Visible | Event
ImageIndex | Data | Hint
HintObj | Tip | Accelerator
Popup | KeepOnClose | MethodList
ChildList | EventList | PropList


ToolControl Properties

Type | Posn | Size
Style | Align | Visible
Event | ImageListObj | FontObj
Data | Attach | Handle
KeepOnClose | MultiLine | Transparent
Divider | ShowCaptions | ShowDropDown
Dockable | UndocksToRoot | Redraw
ButtonsAcceptFocus | MethodList | ChildList
EventList | PropList |


TrackBar Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
Thumb | Step | VScroll
HScroll | Limits | SelRange
Sizeable | Dragable | FontObj
BCol | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | TickAlign | TickSpacing
HasTicks | ShowThumb | TrackRect
ThumbRect | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


TreeView Properties

Type | Items | Posn
Size | Coord | Border
Active | Visible | Event
Depth | HasLines | HasButtons
EditLabels | ImageListObj | ImageIndex
SelImageIndex | SelItems | Sizeable
Dragable | FontObj | FCol
BCol | CursorObj | AutoConf
Index | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | AcceptFiles
KeepOnClose | CheckBoxes | FullRowSelect
SingleClickExpand | Redraw | TabIndex
AlwaysShowSelection | MethodList | ChildList
EventList | PropList |


UpDown Properties

Type | Posn | Size
Coord | Border | Active
Visible | Event | Thumb
Step | VScroll | HScroll
Wrap | Limits | Sizeable
Dragable | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Object Management Functions
⎕DQ | Dequeue | processes user actions, invoking callbacks
⎕NQ | Enqueue | generates an event under program control
⎕WC | Create Object | creates new object with specified properties
⎕WG | Get Properties | gets values of properties from an object
⎕WN | Object Names | reports names of all children of an object
⎕WS | Set Properties | sets values of properties for an object


:For Statement

       |
       :For var :In[Each] aexp
       |
       code
       |
       :End[For]
       |


:Hold Statement

      |
      :Hold token(s)
      |
      code
      |
      |-------.
      |       |
      |       :Else
      |       |
      |       code
      |       |
      |<------.
      |
      :End[Hold]
      |


:Repeat Statement

       |
       :Repeat
       |
       code
       |
       .---------------.
       |               |
       :End[Repeat]    :Until bexp
       |               |
       |               .-------.
       |               |       |
       |               |       andor
       |               |       |
       |               |<------'
       |               |
       |<--------------'
       |


:Trap Statement

       |
       :Trap <ecode>
       |
       code
       |
       |<------------------------------------.
       |                                     |
       .-------.-------.                     |
       |       |       |                     |
       |       :Else   :Case[List] <ecode>   |
       |       |       |                     |
       |       |       |                     |
       |       |       |                     |
       |       code    code                  |
       |       |       |                     |
       |<------'       `---------------------'
       |
       :End[Trap]
       |

Where ecode is a scalar or vector of ⎕TRAP event codes (see Trappable Event Codes ).

Note that within the :Trap control structure, :Case is used for a single event code and :CaseList for a vector of event codes.


:While Statement

       |
       :While bexp
       |
       .-------.
       |       |
       |       andor
       |       |
       |<------'
       |
       code
       |
       .---------------.
       |               |
       :End[While]     :Until bexp
       |               |
       |               .-------.
       |               |       |
       |               |       andor
       |               |       |
       |               |<------'
       |               |
       |<--------------'
       |


:With Statement

       |
       :With namespace (ref or name)
       |
       code
       |
       :End[With]
       |


C H A P T E R 2 Defined Functions Operators

Defined Functions & Operators

A defined function is a program that takes 0, 1, or 2 arrays as arguments and may produce an array as a result. A defined operator is a program that takes 1 or 2 functions or arrays (known as operands) and produces a derived function as a result. To simplify the text, the term operation is used within this chapter to mean function or operator.


Model Syntax

The model for the defined operation identifies the name of the operation, its valence, and whether or not an explicit result may be returned. Valence is the number of explicit arguments or operands, either 0, 1 or 2; whence the operation is termed NILADIC, MONADIC or DYADIC respectively. Only a defined function may be niladic. There is no relationship between the valence of a defined operator, and the valence of the derived function which it produces. Defined functions and derived functions produced by defined operators may be ambivalent, i.e. may be executed monadically with one argument, or dyadically with two. An ambivalent operation is identified in its model by enclosing the left argument in braces.

The value of a result-returning function or derived function may be suppressed in execution if not explicitly used or assigned by enclosing the result in its model within braces. Such a suppressed result is termed SHY.

The tables below show all possible models for defined functions and operators respectively.

Defined Functions

Result | Niladic | Monadic | Dyadic | Ambivalent
None | f | f Y | X f Y | {X} f Y
Explicit | R←f | R←f Y | R←X f Y | R←{X} f Y
Suppressed | {R}←f | {R}←f Y | {R}←X f Y | {R}←{X} f Y

Note:The right argument Y and/or the result R may be represented by a single name, or as a blank-delimited list of names surrounded by parentheses. For further details, see Namelists.

Derived Functions produced by Monadic Operator

Result | Monadic | Dyadic | Ambivalent
None | (A op)Y | X(A op)Y | {X}(A op)Y
Explicit | R←(A op)Y | R←X(A op)Y | R←{X}(A op)Y
Suppressed | {R}←(A op)Y | {R}←X(A op)Y | {R}←{X}(A op)Y

Derived Functions produced by Dyadic Operator

Result | Monadic | Dyadic | Ambivalent
None | (A op B)Y | X(A op B)Y | {X}(A op B)Y
Explicit | R←(A op B)Y | R←X(A op B)Y | R←{X}(A op B)Y
Suppressed | {R}←(A op B)Y | {R}←X(A op B)Y | {R}←{X}(A op B)Y


The State Indicator

The state of execution is dynamically recorded in the STATE INDICATOR. The state indicator identifies the chain of execution for operators, functions and the evaluated or character input/output system variables (⎕ and ⍞). At the top of the state indicator is the most recently activated operation.

Execution may be suspended by an interrupt, induced by the user, the system, or by a signal induced by the system function ⎕SIGNAL or by a stop control set by the system function ⎕STOP. If the interrupt (or event which caused the interrupt) is not defined as a trappable event by the system variable ⎕TRAP, the state indicator is cut back to the first of either a defined operation or the evaluated input prompt (⎕) such that there is no locked defined operation in the state indicator. The topmost operation left in the state indicator is said to be SUSPENDED. Other operations in the chain of execution are said to be PENDENT.

The state indicator may be examined when execution is suspended by the system commands )SI and )SINL. The names of the defined operations in the state indicator are given by the system functions ⎕SI and ⎕XSI while the line numbers at which they are suspended or pendent is given by the system variable ⎕LC.

Suspended execution may be resumed by use of the Branch function (see Branch:). Whilst execution is suspended, it is permitted to enter any APL expression for evaluation, thereby adding to the existing state indicator. Therefore, there may be more than one LEVEL OF SUSPENSION in the state indicator. If the state indicator is cut back when execution is suspended, it is cut back no further than the prior level of suspension (if any).

Examples

     ∇ F
[1]    G
     ∇

     ∇ G
[1]    'FUNCTION G'+
     ∇

      ⍎'F'
SYNTAX ERROR
G[1] 'FUNCTION G'+
     ^

      )SI
#.G[1]*
#.F[1]
⍎

⎕LOCK'G'

      ⍎'F'
SYNTAX ERROR
F[1] G
     ^

      )SI
#.F[1]*
⍎
#.G[1]*
#.F[1]
⍎

A suspended or pendent operation may be edited by the system editor or redefined using ⎕FX provided that it is visible and unlocked. However, pendent operations retain their original definition until they complete, or are cleared from the State Indicator. When a new definition is applied, the state indicator is repaired if necessary to reflect changes to the operations, model syntax, local names, or labels.


APL Error Messages

There follows an alphabetical list of error messages reported from within Dyalog APL.


Clover Class Example

:Class Clover ⍝ Constructor Overload Example
    :Field Public Con
    ∇ Make0
      :Access Public
      :Implements Constructor
      make 0
    ∇
    ∇ Make1(arg)
      :Access Public
      :Implements Constructor
      make arg
    ∇
    ∇ Make2(arg1 arg2)
      :Access Public
      :Implements Constructor
      make arg1 arg2
    ∇
    ∇ Make3(arg1 arg2 arg3)
      :Access Public
      :Implements Constructor
      make arg1 arg2 arg3
    ∇
    ∇ MakeAny args
      :Access Public
      :Implements Constructor
      make args
    ∇
    ∇ make args
      Con←(⍴args)(2⊃⎕SI)args
    ∇
:EndClass ⍝ Clover


BirdBehaviour Interface

:Interface BirdBehaviour
∇ R←Fly ⍝ Returns description of flying capability
∇
∇ R←Lay ⍝ Returns description of egg-laying behaviour
∇
∇ R←Sing ⍝ Returns description of bird-song
∇
:EndInterface ⍝ BirdBehaviour


FishBehaviour Interface

:Interface FishBehaviour
∇ R←Swim ⍝ Returns description of swimming capability
∇
:EndInterface ⍝ FishBehaviour


Penguin Class

:Class Penguin: Animal,BirdBehaviour,FishBehaviour
    ∇ R←NoCanFly
      :Implements Method BirdBehaviour.Fly
      R←'Although I am a bird, I cannot fly'
    ∇
    ∇ R←LayOneEgg
      :Implements Method BirdBehaviour.Lay
      R←'I lay one egg every year'
    ∇
    ∇ R←Croak
      :Implements Method BirdBehaviour.Sing
      R←'Croak, Croak!'
    ∇
    ∇ R←Dive
      :Implements Method FishBehaviour.Swim
      R←'I can dive and swim like a fish'
    ∇
:EndClass ⍝ Penguin


DiaryStuff Example Namespace

:Namespace DiaryStuff
:Using System

    :Class DiaryEntry
        :Field Public When
        :Field Public What
        ∇ Make(ymdhm wot)
          :Access Public
          :Implements Constructor
          When What←(⎕NEW DateTime(6↑5↑ymdhm))wot
          ⎕DF⍕When What
        ∇
        ∇ Make0
          :Access Public
          :Implements Constructor
          When What←⎕NULL''
        ∇
    :EndClass ⍝ DiaryEntry

    :Class Diary
        :Field Private entries←0⍴⎕NEW DiaryEntry
        ∇ R←Add(ymdhm wot)
          :Access Public
          R←⎕NEW DiaryEntry(ymdhm wot)
          entries,←R
        ∇
        ∇ R←DoingOn ymd;X
          :Access Public
          X←,(↑entries.When.(Year Month Day))^.=3 1⍴3↑ymd
          R←X/entries
        ∇
        ∇ R←Remove ymdhm;X
          :Access Public
          :If R←∨/X←entries.When=⎕NEW DateTime(6↑5↑ymdhm)
              entries←(~X)/entries
          :EndIf
        ∇
        :Property Numbered Default Entry
            ∇ R←Shape
              R←⍴entries
            ∇
            ∇ R←Get arg
              R←arg.Indexers⊃entries
            ∇
            ∇ Set arg
              entries[arg.Indexers]←arg.NewValue
            ∇
        :EndProperty
    :EndClass ⍝ Diary

:EndNamespace


Booking Class

    :Class Booking
        :Field Public OK
        :Field Public Course
        :Field Public TeeTime
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course TeeTime Message←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕Course TeeTime(⊃OK⌽Message'OK')
        ∇
    :EndClass


GetCourses Method

    ∇ R←GetCourses;COURSECODES;COURSES;INDEX
      :Access Public
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      R←{⎕NEW GolfCourse ⍵}¨↓⍉↑COURSECODES COURSES
    ∇


GetStartingheet Method

    ∇ R←GetStartingSheet ARGS;CODE;COURSE;DATE;COURSECODES
                             ;COURSES;INDEX;COURSEI;IDN
                             ;DATES;COMPS;IDATE;TEETIMES
                             ;GOLFERS;I;T
      :Access Public
      CODE DATE←ARGS
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      COURSEI←COURSECODES⍳CODE
      COURSE←⎕NEW GolfCourse(CODE(COURSEI⊃COURSES,⊂''))
      R←⎕NEW StartingSheet(0 COURSE DATE)
      :If COURSEI>⍴COURSECODES
          R.Message←'Invalid course code'
          :Return
      :EndIf
      IDN←2 ⎕NQ'.' 'DateToIDN',DATE.(Year Month Day)
      DATES COMPS←⎕FREAD GOLFID,COURSEI⊃INDEX
      IDATE←DATES⍳IDN
      :If IDATE>⍴DATES
          R.Message←'No Starting Sheet available'
          :Return
      :EndIf
      TEETIMES GOLFERS←⎕FREAD GOLFID,IDATE⊃COMPS
      T←DateTime.New¨(⊂DATE.(Year Month Day)),¨↓[1]
                                   24 60 1⊤TEETIMES
      R.Slots←{⎕NEW Slot ⍵}¨T,∘⊂¨↓GOLFERS
      R.OK←1
    ∇


GolfCourse Class

    :Class GolfCourse
        :Field Public Code←¯1
        :Field Public Name←''

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          Code Name←args
          ⎕DF Name,'(',(⍕Code),')'
        ∇

    :EndClass


Slot Class

    :Class Slot
        :Field Public Time
        :Field Public Players

        ∇ ctor1 t
          :Implements Constructor
          :Access Public Instance
          Time←t
          Players←0⍴⊂''
        ∇
        ∇ ctor2 (t pl)
          :Implements Constructor
          :Access Public Instance
          Time Players←t pl
        ∇
        ∇ format
          :Implements Trigger Players
          ⎕DF⍕Time Players
        ∇
    :EndClass


StartingSheet Class

    :Class StartingSheet
        :Field Public OK
        :Field Public Course
        :Field Public Date
        :Field Public Slots←⎕NULL
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course Date←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕2 1⍴(⍕Course Date)(↑⍕¨Slots)
        ∇
    :EndClass


Dual Example Class

Dual Class Example

:Class Dual: 'SubForm'
    :Include GUITools
    :Field Private _Caption1←''
    :Field Private _Caption2←''
    :Field Private _Value1←0
    :Field Private _Value2←0
    :Field Private _Range←0
    :Field Private _Intercept←0
    :Field Private _Gradient←1
    :Field Private _Height←40

    ∇ Create args;H;W;POS;SH;CH;Y1;Y2;BaseArgs;MyArgs;Defaults
      :Access Public
      MyArgs BaseArgs←SplitNV args
      :Implements Constructor :Base BaseArgs,⊂'EdgeStyle' 'Dialog'
      ExecNV_ MyArgs ⍝ Set Fields named _PropertyName in MyArgs
      Coord←'Pixel'
      H W←Size
      POS←2↑⌊0.5×0⌈(H-_Height)
      CH←⊃GetTextSize'W'
      'Slider'⎕WC'TrackBar'POS('Size'_Height W)
      Slider.(Limits AutoConf)←_Range 0
      Slider.(TickSpacing TickAlign)←10 'Top'
      Slider.onThumbDrag←'ChangeValue'
      Slider.onScroll←'ChangeValue'
      Y1←POS[1]-CH+1
      Y2←POS[1]+_Height+1
      'Caption1_'⎕WC'Text'_Caption1(Y1,0)('AutoConf' 0)
      'Caption2_'⎕WC'Text'_Caption2(Y2,0)('AutoConf' 0)
      'Value1_'⎕WC'Text'(⍕_Value1)(Y1,W)('HAlign' 2)('AutoConf' 0)
      CalcValue2
      'Value2_'⎕WC'Text'(⍕_Value2)(Y2,W)('HAlign' 2)('AutoConf' 0)
      onConfigure←'Configure'
    ∇
    :Property Caption1, Caption2
    :Access Public
        ∇ R←Get arg
          R←(arg.Name,'_')⎕WG'Text'
        ∇
        ∇ Set arg
          (arg.Name,'_')⎕WS'Text'arg.NewValue
        ∇
    :EndProperty

    :Property Value1
    :Access Public
        ∇ R←Get
          R←_Value1
        ∇
        ∇ Set arg
          ⎕NQ'Slider' 'Scroll' 0 arg.NewValue
        ∇
    :EndProperty

    :Property Intercept, Gradient, Range, Height, Value2
    :Access Public
        ∇ R←Get arg
          R←⍎'_',arg.Name
        ∇
    :EndProperty

    ∇ CalcValue2
      _Value2←_Intercept+_Gradient×_Value1
    ∇

    ∇ ChangeValue MSG
      ⍝ Callback for ThumbDrag and Scroll
      _Value1←⊃¯1↑MSG
      CalcValue2
      Value1_.Text←⍕_Value1
      Value2_.Text←⍕_Value2
    ∇

    ∇ Configure MSG;H;W;POS;CH;Y1;Y2
      2 ⎕NQ MSG
      H W←Size
      POS←2↑⌊0.5×(H-_Height)
      CH←⊃GetTextSize'W'
      Slider.(Posn Size)←POS(_Height W)
      Y1←POS[1]-CH+1
      Y2←POS[1]+_Height+1
      Caption1_.Points←1 2⍴Y1,0
      Caption2_.Points←1 2⍴Y2,0
      Value1_.Points←1 2⍴Y1,W
      Value1_.Points←1 2⍴Y2,W
    ∇

    :EndClass ⍝ Dual


Temperature Converter Example Class

Temperature Converter Example

 class="APLCode">:Class Temp: 'Form'
    ∇ Make pv;TITLE
      :Access Public
      TITLE←'Temperature Converter'
      :Implements Constructor :Base (⊂'Caption' TITLE),pv,⊂('Size' (30 40))
      MB←⎕NEW⊂'MenuBar'
      MB.(M←⎕NEW'Menu'(,⊂'Caption' '&Scale'))
      MB.M.(C←⎕NEW'MenuItem'(('Caption' '&Centigrade')('Checked' 1)))
      MB.M.(F←⎕NEW'MenuItem'(,⊂('Caption' '&Fahrenheit')))
      LF←⎕NEW'Label'(('Caption' 'Fahrenheit')('Posn'(10 10)))
      F←⎕NEW'Edit'(('Posn'(10 40))('Size'(⍬ 20))('FieldType' 'Numeric'))
      LC←⎕NEW'Label'(('Caption' 'Centigrade')('Posn'(40 10)))
      C←⎕NEW'Edit'(('Posn'(40 40))('Size'(⍬ 20))('FieldType' 'Numeric'))
      F2C←⎕NEW'Button'(('Caption' 'F->C')('Posn'(10 70))('Default' 1))
      C2F←⎕NEW'Button'(('Caption' 'C->F')('Posn'(40 70)))
      Q←⎕NEW'Button'(('Caption' '&Quit')('Posn'(70 30))('Size'(⍬ 40))('Cancel' 1))
      S←⎕NEW'Scroll'(⊂('Range' 101))
      MB.M.C.onSelect←'SET_C'
      MB.M.F.onSelect←'SET_F'
      F2C.onSelect←'f2c'
      F.onGotFocus←'SET_DEF'
      C2F.onSelect←'c2f'
      C.onGotFocus←'SET_DEF'
      onClose←'QUIT'
      Q.onSelect←'QUIT'
      S.onScroll←'c2f_scroll'
    ∇

    ∇ f2c
      C.Value←(F.Value-32)×5÷9
    ∇
    ∇ c2f
      F.Value←32+C.Value×9÷5
    ∇
    ∇ c2f_scroll MSG
      ⍝ Callback for Centigrade input via scrollbar
      C.Value←101-4⊃MSG
      c2f
    ∇
    ∇ f2c_scroll Msg
      ⍝ Callback for Fahrenheit input via scrollbar
      F.Value←213-4⊃Msg
      f2c
    ∇
    ∇ Quit
      Close
    ∇
    ∇ SET_DEF MSG
      (⊃MSG).Default←1
    ∇
    ∇ SET_C
      ⍝ Sets the scrollbar to work in Centigrade
      S.Range←101
      S.onScroll←'c2f_scroll'
      MB.M.C.Checked←1
      MB.M.F.Checked←0
    ∇
    ∇ SET_F
      ⍝ Sets the scrollbar to work in Fahrenheit
      S.Range←213
      S.onScroll←'f2c_scroll'
      MB.M.F.Checked←1
      MB.M.C.Checked←0
    ∇
:EndClass ⍝ Temp


Primitive Functions

Scalar Monadic Functions | + - × ÷ | ⌈ ⌊ * ⍟ ○ ! ~ ? ∊
Scalar Dyadic Arithmetic Functions | + - × ÷ | ⌈ ⌊ * ⍟ !
Scalar Dyadic Logical Functions | ∧ ∨ ⍲ ⍱ < > ≤ ≥ = ≠
Scalar Dyadic Circular Functions | ○
Non-Scalar Monadic Structural Fns | ⍴ , ⍪ ⌽ ⊖ ⍉ ↑ ↓ ⊂ ⍕ ≡ ∊
Non-Scalar Dyadic Structural Fns | ⍴ , ⍪ ⌽ ⊖ ⍉ ⊂ ⍕
Non-Scalar Selection Functions | ⊃ ↑ ↓ / ⌿ \ ⍀ ~ ∩ ∪
Non-Scalar Selector Functions | ⍳ ∊ ⍷ ⍋ ⍒ ? ≡ ≢
Non-Scalar Computational Fns | → ⍬ ⍎ ⊥ ⊤ ⌹


Replicate First

Replicate First: R←X⌿[K]Y

The form R←X⌿Y implies replication along the first axis of Y. See Replicate:.


Primitive Operators

Each | f¨⍵ | apply monadic f to elements of ⍵
Dyadic Each | ⍺f¨⍵ | apply dyadic f to corresponding elements of ⍺ and ⍵
Power | ⍺(f⍣g)⍵ | apply monadic or dyadic f repeatedly to ⍵
Reduce | f/⍵ | dyadic f placed between each sub-array along (last) axis
Reduce First | f⌿⍵ | dyadic f placed between each sub-array along (first) axis
N-Wise Reduce | ⍺f/⍵ | dyadic f placed between items of sub-vectors of length ⍺
Scan | f\⍵ | successive reductions along (last) axis
Scan First | f⍀⍵ | successive reductions along (first) axis
Commute | ⍺f⍨⍵ | commute arguments of dyadic f
Compose (Form I) | f∘g⍵ | gives result f g ⍵
Compose (Form II) | I∘g⍵ | gives result I g ⍵
Compose (Form III) | f∘k⍵ | gives result ⍵ f k
Compose (Form IV) | ⍺f∘g⍵ | gives result ⍺ f g ⍵
Inner Product | ⍺f.g⍵ | apply f and g like + and × in matrix multiplication
Outer Product | ⍺∘.g⍵ | apply dyadic g to all combinations of elements from ⍺ and ⍵
Spawn | ⍺f&⍵ | start a new thread with f applied to its argument(s)
I-Beam | {f}(⍺⌶)⍵ | provides a range of system-related services


Ampersand &

Ampersand is a Monadic operator with an ambivalent operand

Operator Ampersand means

Spawn

      ⍎& '⌹4 4⍴1 2 3 4 5'
¯0.17   0.21   0.014  0.014
 0.029 ¯0.19   0.21   0.014
 0.029  0.014 ¯0.19   0.21
 0.26   0.029  0.029 ¯0.17

      3 2 1 4 ⌹& 4 4⍴1 2 3 4 5
¯0.014 ¯0.014 0.79 0.17

Language Elements


Circle ○

Monadic Circle means

Pi Times

      ○ 0 1 2
0 3.141592654 6.283185307

Dyadic Circle means

Circular Function

      1 ○ 0 1.5707963 3.1415927
0 1 ¯4.6410207E¯8

Language Elements


Circle Bar ×

Monadic Circle Bar means

Reverse First

      ⊖ 3 2⍴1 2 3 4 5 6
5 6
3 4
1 2

Dyadic Circle Bar means

Rotate First

      1 2 ⊖ 3 2⍴1 2 3 4 5 6
3 6
5 2
1 4

Language Elements


Circle Stile ⌽

Monadic Circle Stile means

Reverse

      ⌽ 8 2 5 6.6 ¯2
¯2 6.6 5 2 8

Dyadic Circle Stile means

Rotate

      1 2 ¯1 ⌽ 3 3⍴⍳9
2 3 1
6 4 5
9 7 8

Language Elements


Comma ,

Monadic Comma means

Ravel

      , 2 2 2 2⍴3
3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

Dyadic Comma means

Catenate/Laminate

      (2 3⍴9) , 2 4⍴8
9 9 9 8 8 8 8
9 9 9 8 8 8 8

Language Elements


Comma Bar ⍪

Monadic Comma Bar means

Table

       ⍪  2 3 4
2
3
4

Dyadic Comma Bar means

Catenate First

      (3 2⍴9) ⍪ 4 2⍴8
9 9
9 9
9 9
8 8
8 8
8 8
8 8

Language Elements


Decode Symbol

Decode;Up Tack ⊥

Monadic Decode is not defined

Dyadic Decode means

Decode;Base Value

      2 ⊥ 2 3⍴0 1 1 1 0 1
1 2 3

Language Elements


Dieresis ¨

Dieresis is a Monadic operator with an ambivalent operand

Operator Dieresis means

Each (Monadic)

      ⊃¨ 1 2 3 'ABC' (9 8 7)
1 2 3 A 9

Each (Dyadic)

      3 ↑¨ 1 2 3 (2 3) 'A'
 1 0 0  2 0 0  3 0 0  2 3 0  A

Language Elements


Dieresis Tilde ⍨

Dieresis Tilde is a Monadic operator with a Dyadic operand

Operator Dieresis Tilde means

Commute

      3.1243 -⍨ 4.1234 1 0
0.9991 ¯2.124 ¯3.124

Language Elements


DieresisStar ⍣

DieresisStar is a Dyadic operator with an ambivalent left operand and an integer or dyadic right operand

Operator DieresisStar means

Power Operator

     (↓⍣1)  2 2 2 2⍴⎕a                      ⍝ split once.
 AB  CD
 EF  GH

 IJ  KL
 MN  OP

      (↓⍣2)  2 2 2 2⍴⎕a                     ⍝ split twice.
  AB  CD    EF  GH
  IJ  KL    MN  OP

      (↓⍣3)  2 2 2 2⍴⎕a                     ⍝ split thrice
   AB  CD    EF  GH      IJ  KL    MN  OP

      1+∘÷⍣=1                               ⍝ Golden Mean
1.618033989

      f←(32∘+)∘(×∘1.8)                      ⍝ Fahrenheit from Celsius

      f ¯273 ¯40 0 100
¯459.4 ¯40 32 212

      c←f⍣¯1                                ⍝ inverse: Celsius from Fahrenheit

      c ¯459.4 ¯40 32 212
¯273 ¯40 0 100

Language Elements


Divide Sign ÷

Monadic Divide Sign means

Reciprocal

      ÷ 1 2 3 1
0.5 0.33333333

Dyadic Divide Sign means

Divided By

      1 2 3 4 ÷ 5 6 7 8
0.2 0.33333333 0.42857142 0.5

Language Elements


Domino

Domino;Quad Divide ⌹

Monadic Domino means

Matrix Inverse Of

      ⌹ (2 2⍴1 2 3 4)
¯2    1
 1.5 ¯0.5

Dyadic Domino means

Matrix Division By

      5 6 ⌹ 2 2⍴1 2 3 4
¯4 4.5

Language Elements


Dot

Dot;Full Stop;Decimal Point .

Dot can be used as a Dyadic operator with Dyadic operands

Operator Dot means

Inner Product;Dot

      (4 3⍴1 2) +.× 3 5⍴3 4 5
17 15 16 17 15
19 21 20 19 21
17 15 16 17 15
19 21 20 19 21

Used with Jot in place of the left operand Jot Dot means

Outer Product;Jot Dot

      1 2 3 ∘.× 1 2 3 4
1 2 3  4
2 4 6  8
3 6 9 12

NB Dot is also used as a decimal point and as a name separator in namespace reference syntax.

Language Elements


Down Arrow

Down Arrow ↓

Monadic Down Arrow means

Split

      ↓ 3 3⍴1 2 3 4
 1 2 3  4 1 2  3 4 1

Dyadic Down Arrow means

Drop

      1 1 ↓ 3 3⍴1 2 3 4 5 6
5 6
2 3

Language Elements


Downstile ⌊

Monadic Downstile means

Floor

      ⌊ 3.4 ¯2.1 8.1 3 0
3 ¯3 8 3 0

Dyadic Downstile means

Minimum

      3 1.1 ¯2 ⌊ 3.4 8.1 ¯3.44
3 1.1 ¯3.44

Language Elements


Encode Symbol

Encode;Down Tack ⊤

Monadic Encode is not defined

Dyadic Encode means

Encode;Representation

      2 2 2 2 2 2 ⊤ 8 16 32
0 0 1
0 1 0
1 0 0
0 0 0
0 0 0
0 0 0

Language Elements


Epsilon ∊

Monadic Epsilon means

If ⎕ML=0 Type Of

      ∊ 3 3⍴1 'abc'
   0         0
        0
   0         0

If ⎕ML≥1 Enlist

      ∊ 3 3⍴1 'abc'
1 abc 1 abc 1 abc 1 abc 1

Dyadic Epsilon means

Member Of

      'abc' 1.1 ∊ 1.1 'ab' 'abcd'
0 1

Language Elements


Epsilon Underbar ⍷

Monadic Epsilon Underbar is not defined

Dyadic Epsilon Underbar means

Find

      0 0 ⍷ 4 4⍴0 1 0
0 0 1 0
0 1 0 0
1 0 0 0
0 0 1 0

Language Elements


Equal Sign =

Monadic Equal Sign is not defined

Dyadic Equal Sign means

Equals

      2 = (2 2 2⍴1 2 3)
0 1
0 0

1 0
0 1

Language Elements


Equal Underbar

Equal Underbar;Equivalent ≡

Monadic Equal Underbar means

Depth Of

      ≡ 1 (1 2)('ab' 'def')
¯3

NB Result is always positive if ⎕ML is greater than or equal to 2

Dyadic Equal Underbar means

Match

      'b' 'e' 'x'≡ 'bex'
1

Language Elements


Equal Underbar Slash

Not Equal Underbar;Inequivalent ≢

Monadic Not Equal Underbar is not defined

Dyadic Not Equal Underbar means

Does Not Match;Natch

      'bex' ≢ 'b','e','x'
0

Language Elements


Exclamation Mark

Exclamation Mark;Quote Dot !

Monadic Exclamation Mark means

Factorial

      ! 3 10 ¯0.11
6 3628800 1.076830683

Dyadic Exclamation Mark means

Binomial

      2 1 3 ! 3 10 ¯0.11
3 10 ¯0.0429385

Language Elements


Execute Symbol

Execute;Hydrant;Up Tack Jot ⍎

Monadic Execute means

Execute

      ⍎ '1+1⋄2+2'
2
4

Dyadic Execute means

Namespace Execute

      '#' ⍎ '⎕PP ⎕CT ⎕RL'
10 1E¯14 1131570933

Language Elements


Grade Down

Grade Down;Del Stile ⍒

Monadic Grade Down means

Grade Down

      ⍒ 3 1 4 6 2
4 3 1 5 2

Dyadic Grade Down means

Collated Grade Down

      'ABCDEFG' ⍒ 'CDEDEDE'
3 5 7 2 4 6 1

Language Elements


Grade Up

Grade Up;Delta Stile ⍋

Monadic Grade Up means

Grade Up

      ⍋ 3 1 4 6 2
2 5 1 3 4

Dyadic Grade Up means

Collated Grade Up

      'ABCDEFG'⍋'CDEDEDE'
1 2 4 6 3 5 7

Language Elements


Greater Than Or Equal To Sign ≥

Monadic Greater Than or Equal To Sign is not defined

Dyadic Greater Than or Equal To Sign means

Is Greater Or Equal To

      (1 2⍴2 ¯8) ≥ (1 2⍴2 2)
1
0

Language Elements


Greater Than Sign

Monadic Greater Than Sign is not defined

Dyadic Greater Than Sign means

Is Greater Than

      2 ¯8 2 5 4 > 2 2 ¯2 0 8
0 0 1 1 0

Language Elements


I-Beam ⌶

I-Beam is a monadic operator that provides a range of system related services.

Examples

      {}1111⌶ ncpu←1111⌶1 ⍝ Number of threads

      2000⌶ 0 1 2 3 4     ⍝ Memory manager statistics
65374272 184256 2 1 0

Language Elements


Index Symbol

Index ⌷

Index means

Index

      2 3⌷4 3⍴⍳12

6

Index with Axes means

Index with Axes

      2⌷[1]⍳2 3 4
 2 1 1  2 1 2  2 1 3  2 1 4
 2 2 1  2 2 2  2 2 3  2 2 4
 2 3 1  2 3 2  2 3 3  2 3 4

Language Elements


Iota ⍳

Monadic Iota means

Index Generator

      ⍳10
1 2 3 4 5 6 7 8 9 10

Dyadic Iota means

Index Of

      'ABCDABCDEF' ⍳ 'ACF'
1 3 10

Language Elements


Jot

Jot;Null ∘

Jot is a Dyadic operator with a Dyadic operand

Operator Jot means

Composed With

Form I

      *∘⍳ 3 2
 2.718 2.718  2.718 7.389
 7.389 2.718  7.389 7.389
 20.09 2.718  20.09 7.389

Form II

      3 0∘⍕ 1.2 3.4 5.678 22
  1  3  6 22

Form III

      (*∘0.5) 1 2 3 4 5 6
1 1.414 1.732 2 2.236 2.449

Form IV

      5 ×∘⍳ 3 4
 5 5   5 10   5 15   5 20
 10 5  10 10  10 15  10 20
 15 5  15 10  15 15  15 20

NB Jot is also used in conjunction with Dot to mean Outer Product .

Language Elements


Left Shoe ⊂

Monadic Left Shoe means

Enclose

      ⊂ 1 (2 2) (2 2⍴3)
 1  2 2  3 3
         3 3

Dyadic Left Shoe means

If ⎕ML<3 Partitioned Enclose

      0 1 0 1 ⊂ 1 2 3 4
 2 3  4

If ⎕ML≥3 Partition

      0 1 0 1 ⊂ 1 2 3 4
 2  4

Language Elements


Left Tack ⊣

Monadic Left Tack means

Same

     ⊣'abc' 1 2 3
 abc  1 2 3

Dyadic Left Tack means

Left

      42⊣'abc' 1 2 3
42

Language Elements


Less Than Or Equal To Sign ≤

Monadic Less Than Or Equal To Sign is not defined

Dyadic Less Than or Equal To Sign means

Is Less Or Equal To

      (2 1⍴2 ¯8 ) ≤ (2 1⍴2 2)
1
1

Language Elements


Less Than Sign

Monadic Less Than Sign is not defined

Dyadic Less Than Sign means

Is Less Than

      2 ¯8 2 5 4 < 2 2 ¯2 0 8
0 1 0 0 1

Language Elements


Log

Log;Circle Star ⍟

Monadic Log means

Natural Logarithm

      ⍟ 1 2 3 2.7182818285
0 0.6931471806 1.098612289 1

Dyadic Log means

Logarithm

      10 ⍟ 1 10 100 1000
0 1 2 3

Language Elements


Logical And

Logical And;Up Caret ∧

Monadic Logical And is not defined.

Dyadic Logical And means

And, Lowest Common Multiple

      0 1 0 1 ∧ 0 0 1 1
0 0 0 1

      15 1 2 7 ∧ 35 1 4 0
105 1 4 0

Language Elements


Logical Or

Logical Or;Down Caret ∨

Monadic Logical Or is not defined.

Dyadic Logical Or means

Or, Greatest Common Divisor

      0 1 0 1 ∨ 0 0 1 1
0 1 1 1

      15 1 2 7 ∨ 35 1 4 0
5 1 2 7

Language Elements


Minus Sign

Minus Sign;Bar -

Monadic Minus Sign means

Negate

      - 3 2 5.5 ¯7 0
¯3 ¯2 ¯5.5 7 0

Dyadic Minus Sign means

Minus;Subtract

      3 7 9 - 5
¯2 2 4

Language Elements


Nand Symbol

Nand;Up Caret Tilde ⍲

Monadic Nand is not defined

Dyadic Nand means

Nand;Not And

0 1 0 1 ⍲ 0 0 1 1 1 1 1 0

Language Elements


Nor Symbol

Nor;Down Caret Tilde ⍱

Monadic Nor is not defined

Dyadic Nor means

Nor;Not Or

      0 1 0 1 ⍱ 0 0 1 1
1 0 0 0

Language Elements


Not Equal To

Not Equal ≠

Monadic Not Equal is not defined

Dyadic Not Equal means

Is Not Equal To

      (2 2 2⍴1 2 3) ≠ 3
1 1
0 1
1 0
1 1

Language Elements


Plus Sign +

Monadic Plus Sign means

Conjugate

      + 3.2 ¯12.666
3.2 ¯12.666

Dyadic Plus Sign means

Plus;Added To

      1 2 3 4 + 5 6 7 8
6 8 10 12

Language Elements


Question Mark

Question Mark;Query ?

Monadic Question Mark means

Roll

      ? 1000 1000 1000 9000
756 459 533 1971

Dyadic Question Mark means

Deal

      7 ? 1000
67 418 687 589 931 847 527

Language Elements


Rho ⍴

Monadic Rho means

Shape Of

      ⍴ 15 3 7 8 75.53
5

Dyadic Rho means

Reshape

      2 3 4 ⍴ 15 3 7 8 75.53
15     3     7     8
75.53 15     3     7
 8    75.53 15     3

 7     8    75.53 15
 3     7     8    75.53
15     3     7     8

Language Elements


Right Arrow

Niladic Right Arrow means

Abort

      →

Monadic Right Arrow means

Branch To

      → 10

Language Elements


Right Shoe ⊃

Monadic Right Shoe means

If ⎕ML<2 Disclose;First

      ⊃ (2 2)(3 3 3)
2 2

If ⎕ML≥2 Mix

      ⊃ (2 2)(3 3 3)
2 2 0
3 3 3

Dyadic Right Shoe means

Pick

      2 ⊃ (2 2)(3 3⍴3)
3 3 3
3 3 3
3 3 3

Language Elements


Right Tack ⊢

Monadic Right Tack means

Identity

      ⊢'abc' 1 2 3
 abc  1 2 3

Dyadic Right Tack means

Right

      42⊢'abc' 1 2 3
 abc  1 2 3

Language Elements


Set Intersection

Set Intersection;Up Shoe ∩

Monadic Set Intersection is not defined

Dyadic Set Intersection means

Intersection

      22 'ab' 'fg' ∩ 'a' 'ab' 22
22  ab

Language Elements


Set Union

Set Union;Down Shoe ∪

Monadic Set Union means

Unique

       ∪ 'ab' 'ba' 'ab' 1 1 2
 ab  ba  1 2

Dyadic Set Union means

Union

      'ab' 'cde' 'fg' ∪ 'a' 'ab'
 ab  cde  fg a

Language Elements


Slash

Used as a Function

Monadic Slash is not defined

Dyadic Slash means

Replicate

     2 1 3 3 / 3.1 4 1 3.2
3.1 3.1 4 1 1 1 3.2 3.2 3.2

Used as an Operator

Slash is a Monadic operator with a Dyadic operand

Operator Slash with a Monadic derived function means

Reduce

      ∧/ 2 3 4⍴1 1 1 1 0
1 0 0
0 0 1

Operator Slash with a Dyadic derived function means

N-wise Reduce

      ¯2 -/ 1 3 4 1
2 1 ¯3

Language Elements


Slash Bar ⌿

Used as a Function

Monadic Slash Bar is not defined

Dyadic Slash Bar means

Replicate along First Axis

      2 3 ⌿ 2 29⍴'NETHOTSONDS1'
NETHOTSONDS1NETHOTSONDS1NETHO
NETHOTSONDS1NETHOTSONDS1NETHO
TSONDS1NETHOTSONDS1NETHOTSOND
TSONDS1NETHOTSONDS1NETHOTSOND
TSONDS1NETHOTSONDS1NETHOTSOND

Used as an Operator

Slash Bar is a Monadic operator with a Dyadic operand

Operator Slash Bar means

Reduce along First Axis

      +⌿ 10 3⍴5
50 50 50

Language Elements


Slope

Used as a Function

Monadic Slope is not defined

Dyadic Slope means

Expand

      3 ¯2 4 \ 3 2⍴1.1 2.2 3.3
1.1 1.1 1.1 0 0 2.2 2.2 2.2 2.2
3.3 3.3 3.3 0 0 1.1 1.1 1.1 1.1
2.2 2.2 2.2 0 0 3.3 3.3 3.3 3.3

Used as an Operator

Slope is a Monadic operator with a Dyadic operand

Operator Slope means

Scan

      +\ 1 2 3 4 5 6 7 8 9 10
1 3 6 10 15 21 28 36 45 55

Language Elements


Slope Bar

Slope Bar;Back Slash Bar ⍀

Used as a Function

Monadic Slope Bar is not defined

Dyadic Slope Bar means

Expand along First Axis

      0 1 1 2 ⍀ 3 6⍴'ABCDE'

ABCDEA
BCDEAB
CDEABC
CDEABC

Used as an Operator

Slope Bar is a Monadic operator with a Dyadic operand

Operator Slope Bar means

Scan along First Axis

      =⍀ 5 6⍴0 1 0
0 1 0 0 1 0
1 1 1 1 1 1
0 1 0 0 1 0
1 1 1 1 1 1
0 1 0 0 1 0

Language Elements


Star *

Monadic Star means

Exponential

      * 2 2⍴1 2 3 4
2.718281828 7.389056099 20.08553692 54.59815003

Dyadic Star means

Power

      (2 2⍴1 2 3 4) * 2 2⍴1 2 3 4
 1   4
27 256

Language Elements


Stile

Monadic Stile means

Magnitude

      | 2.3 4 ¯2 0
2.3 4 2 0

Dyadic Stile means

Residue;Modulus

      2 | 2.3 4 ¯2 0 ¯2.3
0.3 0 0 0 1.7

Language Elements


Thorn Symbol

Format;Thorn;Down Tack Jot ⍕

Monadic Format means

Format

      ⍕ 0.0000003  3.87687857858
3E¯7 3.876878579

NB depends on ⎕PP

Dyadic Format means

Format By Specification

      8 3 ⍕ 0.00003 3.87687
   0.000   3.877

Language Elements


Tilde ~

Monadic Tilde means

Not

      ~ 3 3⍴0 1
1 0 1
0 1 0
1 0 1

Dyadic Tilde means

Without;Excluding

      'ab' 'ce' 'fg' ~ 'ce' 'ab'
 fg

Language Elements


Times Sign ×

Monadic Times Sign means

Direction

      × 3 2 ¯2 0 8
1 1 ¯1 0 1

Dyadic Times Sign means

Times;Multiplied By

      2 ¯8 2 5 4 × 3 2 ¯2 0 8
6 ¯16 ¯4 0 32

Language Elements


Transpose

Transpose;Circle Slope ⍉

Monadic Transpose means

Transpose

      ⍉ 3 3⍴1 2 3 4 5 6 7 8 9
1 4 7
2 5 8
3 6 9

Dyadic Transpose means

General Transpose

      2 1 3 ⍉ 2 3 4⍴⍳24
 1  2  3  4
13 14 15 16

 5  6  7  8
17 18 19 20

 9 10 11 12
21 22 23 24

Language Elements


Up Arrow

Monadic Up Arrow means

If ⎕ML<2 Mix

      ↑ (6 4) 5 3
6 4
5 0
3 0

If ⎕ML≥2 Disclose;First

      ↑ (6 4) 5 3
6 4

Dyadic Up Arrow means

Take

      3 3↑7
7 0 0
0 0 0
0 0 0

Language Elements


Upstile ⌈

Monadic Upstile means

Ceiling

      ⌈ 3.4 2 8.1 ¯3.44 0
4 2 9 ¯3 0

Dyadic Upstile means

Maximum

      3 1.1 ¯2 ⌈ 3.4 8.1 ¯3.44
3.4 8.1 ¯2

Language Elements


Variant ⍠

The Variant operator specifies the value of an option to be used by its left operand function.

Examples

The following derived function returns the location of the word 'variant' within its right argument using default values for all the options.

      f1 ← 'variant' ⎕S 0
      f1 'The variant Variant operator'
4

It may be modified to perform a case-insensitive search:

      (f1 ⍠ 1) 'The variant Variant operator'
4 12

This modified function may be named:

      f2 ← f1 ⍠ 1
      f2 'The variant Variant operator'
4 12

The modified function may itself be modified, in this case to revert to a case sensitive search:

      f3 ← f2 ⍠ 0
      f3 'The variant Variant operator'
4

This is equivalent to:

      (f1 ⍠ 1 ⍠ 0) 'The variant Variant operator'
4

Language Elements


Zilde Symbol

Zilde;Zero Tilde ⍬

Niladic Zilde is

Zilde;Zero Length Numeric

      ⍬≡⍳0
1

      ⍬≢''
1

      ⍬≡0⍴0
1

Language Elements


Erase Object

Erase Object: )ERASE nms

This command erases named global defined objects (functions, operators, variables, namespaces and GUI objects) from the active workspace or current namespace.

If a named object is a function or operator in the state indicator, or the object is an operand of an operator in the state indicator, or the object is a function whose left argument is being executed, the object remains defined until its execution is completed or it is no longer referenced by an operator in the state indicator. However, the name is available immediately for other uses.

If a named object is a GUI object, the object and all its children are deleted and removed from the screen.

If an object is not erased for any reason, the system reports not found followed by the name of the object.

Erasing objects such as external functions may have other implications: see Expunge Object: for details.

Example

      )ERASE FOO A ⎕IO
not found ⎕IO


Catenate To
Catenate To A,←A

This idiom optimises the catenation of one array to another array. The performance gain is most significant when A is small.

Note that the idiom is not applied if the value of the left array is shared with another symbol in the workspace.

      V1←⍳10
      V1,←11
 The idiom is used to perform the catenation to V1.
      V1←⍳10
      V2←V1
      V1,←11
 The idiom is not used to perform the catenation to V1, because its value is at that point sharedwith V2.
     ∇ V←V Join A
[1]    V,←A
     ∇
      (⍳10) Join 11
1 2 3 4 5 6 7 8 9 10 11
 The idiom is not used to perform the catenation to V in Join[1] because its value is at that point shared with the array used to call the function


Catenate To First
Catenate To First A⍪←A

This idiom optimises the catenation of one array to another array along the first axis.

Note that the idiom is not applied if the value of the left array is shared with another symbol in the workspace. See Catenate To.


Euler's Idiom

Euler's idiom *○N

Euler's idiom *○N produces accurate results for right argument values that are a multiple of 0J0.5. This is so that Euler's famous identity 0=1+*○0J1 holds, even though the machine cannot represent multiples of pi, including ○0J1, accurately.


New UNIX I-Beams

Four new I-beam functions are provided to perform certain system operations under UNIX. These are:

4000⌶ | Fork New Task
4001⌶ | Change User
4002⌶ | Reap Forked Tasks
4007⌶ | Signal Counts


Speedy DataTable Interface

The ADO.NET DataTable object may only be accessed using an explicit row-wise loop, which is slow at the APL level.

2010⌶ (Update DataTable) and 2011⌶ (Read DataTable) implement an internal row-wise loop which is much faster on large arrays. Furthermore, these function handles NULL values and the conversion of internal APL data to and from the appropriate .Net datatype in a more efficient manner than can be otherwise achieved.

These factors together mean that these functions provides a significant improvement in performance compared to calling the row-wise programming interface directly at the APL level.


Subarray Selection Idioms

Sub-array selection idioms ⊢⌿A, ⊢/A, ⊣⌿A, and ⊣/A return the first (resp. last) rank (0⌈¯1+⍴⍴A) sub-array along the first (resp. last) axis of A. For example, if V is a vector, then:

⊣/A | First item vector
⊢/V | Last item of vector

Similarly, if M is a matrix, then:

⊣⌿M | First row of matrix
⊣/M | First column of matrix
⊢⌿M | Last row of matrix
⊢/M | Last column of matrix

The idiom generalises uniformly to higher-rank arrays.