Field Functions

Field functions change fields, read their metadata and get their values.

In every function below, the field argument is the field name in double quotes, for example "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 ancestor above it.

Syntax

GetParent( field, transaction )

Arguments

• field
  • The name of the field to return.
• 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

Returns the value of a field of the current record. If the field has no value, GetValue returns the default value for the field's type.

Remarks

GetValue is most useful when you need to get a value dynamically, in place of the %field syntax.

Syntax

GetValue( field )

Arguments

• field
  • The name of the field to return.

Example

GetValue("fieldName")

IsFieldNull

Description

Returns True when a field has no value, and False when it has one.

Remarks

A field with no value gives the default for its type when you read it: %Qty is 0 and %Name is an empty string. IsFieldNull is the only way to tell a field with no value from one that holds 0, False or the zero date. IMan does not store an empty value. IsFieldNull therefore also returns True for a field whose source value was blank.

Syntax

IsFieldNull( field )

Arguments

• field
  • The name of the field to test, in quotes. IsFieldNull(%Qty) passes the field's value as the name and fails.

Example

' Use the list price when the line has no price, but
' keep a price of zero.
Dim Price
If IsFieldNull("UnitPrice") Then Price = %ListPrice Else Price = %UnitPrice
Price

IsFirst

Description

Returns True if the current record is the first, and False if not.

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 if the current record is the last, and False if not.

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 on the next record. If the current record is the last, NextRecord returns Empty, not Null. Empty equals both "" and 0, and IsNull is False for it. Test the position with IsLast instead.

Syntax

NextRecord( field )

Arguments

• field
  • The name of the field to return.

Example

' A field's value on the NEXT sibling transaction.
' Returns Empty on the last one, so test IsLast() first.
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 on the previous record. If the current record is the first, PreviousRecord returns Empty, not Null. Empty equals both "" and 0, and IsNull is False for it. Test the position with IsFirst instead.

Syntax

PreviousRecord( field )

Arguments

• field
  • The name of the field to return.

Example

' A field's value on the PREVIOUS sibling transaction.
' Returns Empty on the first one, so test IsFirst() first.
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, that is, to no value.

Syntax

SetFieldNull( field )

Arguments

• field
  • The name of the field to set to null.

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 name of the field to set in the sibling transaction.
• transaction
  • The transaction id of the field being referenced.
• value
  • The value to set the field to.

Example

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