$relation

Return the related key field.

$relation { (Field) }

Parameters

Parameters
Parameter Data Type Description
Field String Field name; optional; can optionally contain a qualified field name, for example, MYFLD.MYENT. If omitted, the current field is used.

Return Values

  • Name of the related primary or foreign key field. The value returned depends on where the entities occur in the component data structure.
  • Empty string (""), if the specified field is not part of a related primary or foreign key.

Use

Allowed in all component types.

Description

The function $relation can be used to find the name of the key field that is related to the specified field when a one-to-many relationship exists between two component entities.

The use of $relation depends upon where the entities occur in the data structure:

  • If the specified field is part of the foreign key of an inner, many entity, $relation returns the name of the primary key field corresponding to that foreign key field.
  • If the specified field is part of the foreign key of an outer, many entity, $relation returns the name of the primary key field corresponding to that foreign key field.

    If two or more component entities are related to the outer entity via the same foreign key, the first one entity is the one considered by $relation.

  • If the specified field is part of the primary key of an inner, one entity, $relation returns the name of the foreign key field corresponding to that primary key field.
  • In all other cases, $relation returns an empty string ("").

Using $relation

The figure below illustrates an up relationship between the one entity OWNER and many entity HORSE:

Up Relationship

UP relationship painted between the one entity OWNER and many entity HORSE

$relation can be used to obtain one of the following:

  • The name of the primary key field (in entity OWNER) that is related to the foreign key field HORSE_OWNER (in entity HORSE).
  • The name of the foreign key field (in entity HORSE) that is related to the primary key field OWNER_NAME in entity (OWNER).

This is illustrated in the following example:

$1 = $relation(HORSE_OWNER.HORSE)
; $1 is "OWNER_NAME.OWNER.TRACKER"
$2 = $relation(OWNER_NAME.OWNER)
; $2 is "HORSE_OWNER_NAME.HORSE.TRACKER"
$3 = $relation(HORSE_AGE.HORSE)
; $3 is ""

Related Topics