# Directives

PROPERTY | Declare Object Properties

## Formats

1. Declare Property: | PROPERTY [HIDE] prop1 [OBJECT], prop2 [OBJECT], ...
2. Specify Read/Write Procedure: | PROPERTY [HIDE] prop1 [getOptions] [setOptions], prop2 ...

Where:

prop1 prop2 | Property names – treated like any other variable in the system. (In Object Oriented Programming, data is referred to as properties.)
getOptions | Defined as { =expr | [ OBJECT ] [ GET label ] } (See Example) Where:
expr | Defines an expression that will be evaluated to return the property value when referenced externally or via the object handle. By default, if an expression is used to define a property, the system will not allow the property to be SET externally unless a specific SET procedure is defined.
GET | Keyword indicating that logic is to be called when properties are read.
label | Can be a statement label within the program or ERR to restrict read access.
setOptions | Defined as SET label (See Example) Where:
SET | Keyword indicating that logic is to be called when properties are written.
label | Can be a statement label within the program or ERR to restrict updating.
ERR | Keyword blocking reads or writes to a property following a GET/SET declaration.
HIDE | Keyword indicating that method is not to be displayed in the list of methods returned by '*.
OBJECT | Optional keyword identifies that the property contains an object identifier to another object.

(The HIDE option was added in PxPlus v8.11.)

## Description

The PROPERTY directive is used in Object Oriented Programming to declare the properties that can be accessed by the application program. These properties can be treated like any other variable in the system and are accessible using the Apostrophe Operator.

A property name can be followed by a GET label to define the location of the logic to call whenever the property is read in the application. With GET in place, the specified logic issues a RETURN value that returns the actual value of the property to the application.

Example:

> property ExtendedAmount get Extension
> …
> Extension:
> return Quantity*Price

If the logic resides outside of the defining program, then the name of the program and entry point can be provided in quotes instead.

#### Note:
If the logic required to do a read is simply a formula, then it can be inserted directly into the PROPERTY definition clause using an = (equals sign) instead of using a subroutine and a GET declaration.
Example:
property ExtendedAmount=Quantity*Price

Specify the SET label to intercept all of the property updates. With SET in place, the system calls the logic whenever the property is being updated and passes it the value being set.

Example:

> property Quantity set ChgQty

Like the GET option, an external program/entry point can be provided:

> property Quantity set "Invline;ChgQty"

Where:

Invline contains:

> ChgQty:
> enter NewQty
> if NewQty=Quantity \
> then return
> ! .. Update inventory then return

Use the keyword ERR to prevent the user from being able to GET or SET a property following the GET or SET declaration:

> property ExtendedAmount set err

If the property contains an object identifier to another object, specify the keyword OBJECT after the property name. When the object is deleted, PxPlus will use the REF( ) function against the object identifier to remove it (as long as it has no other references):

> def class "Customer"
> property File object

> When you delete an object whose class is "Customer", then the system reduces the reference count of the object whose identifier is in "File", and if it is no longer being referenced, deletes it as well.

For defining properties for an object class that are not exposed to external applications, see LOCAL directive.

## See Also

DEF CLASS Define Object Class
DROP CLASS Delete Class Definition
DROP OBJECT Delete Object
FUNCTION Declare Object Method
LIKE Inherit Properties
LOAD CLASS Pre-Load Class Definition
LOCAL Designation of Local Data
PROGRAM Create/Assign Program File
RENAME CLASS Change Name of Class
STATIC Add Local Properties at Runtime
NEW( ) Create New Object
REF( ) Control Reference Count

## Example

These examples illustrate the use of the PROPERTY directive:

> property session$ set err ! Allows user to read value but not set

> property errmsg_valid$="Invalid input data:\n\n"

> property objChild object set err