Field Functions

Field functions provide functionality to manipulate, get metadata and obtain the value of fields.

For each of the functions listed below the field argument is the field name and should be supplied in inverted commas e.g. “fieldname”.

• GetParent
• GetValue
• IsFieldNull
• IsFirst
• IsLast
• NextRecord
• PreviousRecord
• SetFieldNull
• SubPushDown

GetParent

Description

Returns the value of a field from a parent record. The parent can be the immediate parent or any parent thereafter.

Syntax

GetParent( field, transaction )

Arguments

• field
  • The field name to return the value of.
• transaction
  • The transaction id of the field being referenced.

Example

' Read a field from an ancestor transaction. The FIELD
' comes first and the transaction second, and the named
' transaction must actually be an ancestor of the
' current one -- it errors rather than returning empty
' if it is not.
GetParent("OrderNo", "Order")   ' On any OrderLine, returns "SO-10432"

' Carrying a header value down onto every line is the
' usual use:
GetParent("CustomerCode", "Order") & "-" & %ItemCode
' Returns "ACME001-ACME-4471-BLU"

GetValue

Description

Obtains the value of a field of the current record. If the field has no value it will return the field’s default value (link) based on its type.

Remarks

The GetValue function is most useful in scenarios where a value needs to be obtained dynamically, and not with the %field type syntax.

Syntax

GetValue( field )

Arguments

• field
  • The field name to return the value of.

Example

GetValue(“fieldName”)

IsFieldNull

Description

Tests whether a field is null or has a value set to it.

Syntax

IsFieldNull( field )

Arguments

• field
  • The field name to test for null/no value.

Example

' True when the field is not set. This is NOT the same
' as an empty string: a field can be present and blank,
' which returns False.
If IsFieldNull("WarehouseCode") Then
  "MAIN"
Else
  %WarehouseCode
End If   ' Defaults the warehouse only when the field is genuinely absent

IsFirst

Description

Returns true or false to indicate if the current record is the first.

Syntax

IsFirst

Example

' Takes NO arguments. True when the current transaction
' has no previous sibling -- so on the first of the
' three order lines.
IsFirst()   ' On "ACME-4471-BLU" returns True, on the other two False

' Number the lines as they are written:
If IsFirst() Then
  RegisterValue("LineNo", 1)
Else
  RegisterValue("LineNo", GetRegisteredValue("LineNo") + 1)
End If
GetRegisteredValue("LineNo")

IsLast

Description

Returns true or false to indicate if the current record is the last.

Syntax

IsLast

Example

' Takes NO arguments. True when the current transaction
' has no next sibling -- so on the last of the three
' order lines.
'
' Useful for writing a trailer record, or for putting a
' rounding difference on the final line only.
IsLast()   ' On "WIDGET-88" returns True, on the other two False

NextRecord

Description

Returns the value of the field of the next record. If the current record is the last record, null is returned.

Syntax

NextRecord( field )

Arguments

• field
  • The field name to return the value of.

Example

' A field's value on the NEXT sibling transaction.
' Returns Null on the last one, so test IsLast() first
' or guard the result.
NextRecord("ItemCode")   ' On "ACME-4471-BLU" returns "ACME-4471-RED"

' Detect a change of warehouse, to group lines onto
' separate despatches:
IIf(IsLast(), True, NextRecord("WarehouseCode") <> %WarehouseCode)
' True on "ACME-4471-RED" (MAIN, next is NORTH) and on
' the last line

PreviousRecord

Description

Returns the value of the field of the previous record. If the current record is the first record, null is returned.

Syntax

PreviousRecord( field )

Arguments

• field
  • The field name to return the value of.

Example

' A field's value on the PREVIOUS sibling transaction.
' Returns Null on the first one, so test IsFirst() first
' or guard the result.
PreviousRecord("ItemCode")   ' On "WIDGET-88" returns "ACME-4471-RED"

' Suppress a repeated warehouse code on all but the
' first line of a run:
IIf(IsFirst(), %WarehouseCode, IIf(PreviousRecord("WarehouseCode") = %WarehouseCode, "", %WarehouseCode))

SetFieldNull

Description

Sets a field to null or no value.

Syntax

SetFieldNull( field )

Arguments

• field
  • The field name to set to null/no value.

Example

' Clears a field, so the writer omits it rather than
' sending a blank. The distinction matters to an ERP
' that treats an empty string as "overwrite with
' nothing" and an absent field as "leave alone".
'
' It returns an empty string, so on the last line of an
' expression it would be the result. Call it, then
' return the value you want.
If %WarehouseCode = "" Then
  SetFieldNull("WarehouseCode")
End If
%ItemCode

SubPushDown

Description

Copies or sets a field’s value from a parent record to its sibling records.

Syntax

SubPushDown( field, transaction, value )

Arguments

• field
  • The field name in the sibling transaction to be set.
• transaction
  • The transaction id of the field being referenced.
• value
  • The value to set the field to.

Example

SubPushDown(“field”, “transaction”, %FieldInCurrentTran)