A reference is something that refers to (points to) a particular/specific instance of some object/thing such as a variable or record. It is a way of identifying a specific instance of some object/thing and also locating it.

A reference is similar in concept to a street address (for example, "81 Acland Street"). If a house is an object, then the street address is the reference.

It is possible to have multiple references to the one same object instance, in much the same way as you can write the same street address on multiple envelopes or letters.

The thing that the reference refers to (points to) is known as the target of the reference. The target of a reference can be any one of these:

• A record instance.
• A tuple instance.
• An attribute (member/component) of a record instance.
• An attribute (member/component) of a tuple instance.
• A command local variable in the Activation Record (record instance) of a Command Implementation.
• A constant value that was used in the program (numeric, text, or other type).
• An item in an array in a record instance.
• Another reference in a record instance (meaning a reference to a reference).
• A Command Implementation (invokable via the reference).
• A Function Implementation (invokable via the reference).

A type expression is used to specify the type of a variable, parameter, etc. In a type expression, the "Ref" operator is used to make a reference to a type. The "Ref" operator has 1 operand indicating what type of data the reference will be refering to (the type of the target). The actual target instance is not specified in the type expression, only the type of the target is specified.

The following example type expression specifies a reference to an unsigned 32-bit integer:

Ref[TUInt32]

The following example specifies a reference to a read-only (unmodifiable) unsigned 32-bit integer. This example is written twice, the second time using shortcuts.

Ref[ReadOnly[TUInt32]]
Ref ReadOnly uint32

It is possible to define a reference that refers to another reference. The following type expression is a reference to a reference to a TUInt32.

Ref[Ref[TUInt32]]

When supplying a reference as an operand to the intrinsic functions "Add", "Sub", "Mul", "Div", "BitOr", "Equal", "Less", "Minimum", and other related functions, the function uses the target of the reference.

In the following example, the variable "x" is set to the result of the addition of the target of "inA" and the target of "inB". The references themselves are not added (that would not make sense), rather the targets of the references are added.

Command TestRefs;
    Parameter inA, Ref[TUInt32];
    Parameter inB, Ref[TUInt32];
    Variable x, TUInt32;
    Set x, Add[inA,inB];
EndCommand;

The following functions can be used with variables that are of a reference type.

Function	Description
MakeRef[v]	Makes and returns a reference to the specified variable, parameter, or attribute. The return type is Ref[GetType[v]]. If the operand is a reference, then this function returns a reference to that reference.
TargetOf[p]	The operand must be a reference (or a pointer). This function returns the target of the reference (directly, not a copy of the target). Means that the target of the reference should be used/read/modified, not the reference itself. If the operand is a reference to a reference, the result is the first target not the ultimate target.
TargetOf2[p]	Shortcut for TargetOf[TargetOf[p]]. The operand must be a reference to a reference, or a reference to a reference to a reference, etc.
GetTarget[p]	The operand must be a reference (or a pointer). This function returns either a copy of the target of the reference, or a read-only version of the target.
GetTargetSize[p]	The operand must be a reference or pointer. Returns the size (in bytes) of the target of the operand. Same as GetSize[TargetOf[p]].
Same[a, b, ...]	Any of the operands can be references, pointers, or variables. Returns true if all the operands refer to, point to, or are the same object. Compares the identity of the objects, not whether they contain equal data values. If all the operands are references, the behavior is the same as the "EqualRef" function.
NotSame[a, b]	Shortcut for Not[Same[a, b]].
EqualTarget[a, b, ...]	Each operand must be a reference or a pointer. Returns true if all the target values are equal (regardless of whether the references/pointers are equal). If an operand is a reference to a reference, the first target is used, not the ultimate target.
NotEqualTarget[a, b]	Shortcut for Not[EqualTarget[a,b]].
EqualRef[a, b, ...]	All the operands must be references. Returns true if all the references are equal. Compares the references themselves not the values of the targets. No dereferencing is performed. If references are equal, they point to the same target. If references are not equal, they point to different targets that possibly have equal values. If all the references are null, returns true. If any but not all of the references are null, returns false.
NotEqualRef[a, b]	Shortcut for Not[EqualRef[a,b]].
IsNullRef[r]	The operand must be a reference. Returns true if the reference is null. Returns false if the reference is unnullable or is not null.
NotNullRef[r]	Shortcut for Not[IsNullRef[r]].
AnyNullRefs[r1, r2, ...]	All the operands must be references. Returns true if any or all of the references are null. Same as Or[IsNullRef[r1], IsNullRef[r2], ...]
NoNullRefs[r1, r2, ...]	All the operands must be references. Returns true if all of the references are not null (or false if any or all of the reference are null). Same as And[NotNullRef[r1], NotNullRef[r2], ...]
EqualNull[v]	Shortcut for Equal[v, Null]. Returns true if the operand is null. Returns false if the operand is unnullable or is not null. If the operand is a reference, returns whether the target is null (not whether the reference is null).
NotEqualNull[v]	Shortcut for Not[EqualNull[v]] or Not[Equal[v, Null]]

The following functions have symbols for use with the symbol infix shortcut:

Name	Symbol
Same	==#
NotSame	!=#