RowId

See Also: RowId Helper Functions, Declaring Variables, Variable Declaration Commands, Struct

Purpose

Declares one or more RowId variables.

Syntax

To declare RowId variables

RowId {identifier} [{identifier}]

Where:

• {identifier} is the name of a new RowId variable.
• {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

To declare array variables of type RowId

RowId {dimension-list} {identifier} […{identifier}]

Where:

• {dimension-list} is a list of one or more array dimensions for the array. A dimension list is declared using square brackets []. One pair of brackets is used to declare each dimension. If the array is static, then you must specify the static size of each dimension between each pair of brackets, e.g., [{size}]. For more information about declaring arrays, refer to Array Variable Assignments.
• {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

What It Does

RowId defines variables in memory to contain data about a table's RowId. A RowId contains the information needed to uniquely identify a row (aka record) within a table.

Multiple variables may be declared on one command line, with their names separated from each other by spaces.

A RowId variable is assigned by either moving the RowId data from one RowId typed variable to another, or by using one of the RowId helper functions provided to work with RowId. Typically, RowId variables are used to store a table's row identifier so that it can be used later to refind that row.

Examples

It is important to note that RowId variables are strictly typed. You cannot cast RowId variables into or out of other variable types.

Procedure RunTest RowId riOrder
    // create some local RowId variables
    RowId riCustomer riSalesPerson riOrder riOldOrder
    RowId[] riDetails
    :
    Move riOrder to riOldOrder
    :
End_Procedure  // RunTest

In the above example, local RowId variables riCustomer, riSalesPerson, riOldOrder, and riDetails are created inside Procedure RunTest. The riDetails variable is defined as an array of RowIDs. The procedure is passed a RowId parameter named riOrder. This value is later assigned to riOldOrder using the move command. Because the source and destination data type of the move is RowId, this is allowed.

Procedure LoadOrder RowId riOrder
    // create some local RowId variables
    RowId riCustomer riSalesPerson
    RowId[] riDetails
    Integer iDetail
    Boolean bFound
    Move (FindByRowID(OrderHea.File_number, riOrder)) to bFound
    If bFound Begin
        // find parents Customer and Salesperson
        Relate OrderHea
        Move (GetRowID(Customer.File_Number)) to riCustomer
        Move (GetRowID(SalesP.File_Number)) to riSalesPerson
        // find all detail records
        Clear OrderDtl
        Attach OrderDtl
        Find Gt OrderDtl by 1
        While ((found) and OrderDtl.Order_number = OrderHea.Order_number)
            Move (GetRowID(OrderDtl.File_number)) to riDetails[iDetail]
            Increment iDetail
        Loop
    End
    Else Begin
        Move (NullRowID()) to riOrder
    End
    Set priOrder to riOrder
    Set priCustomer to riCustomer
    Set priSalesPerson to riSalesPerson
    Set priDetails to riDetails
End_Procedure  // LoadOrder

In the above example, the procedure is passed a RowId for an order. The order is found using the RowId. If an order is found, Customer and Salesperson records are found and stored in the appropriate RowId variables. All detail records are found and each record's RowId is stored in a RowId array. Finally, all of this data is stored in this object's properties.

RowId[] riCustomers

This example declares one dynamic array variable, named riCustomers, containing an undefined number of elements of type RowId.

RowId[5] riCustomers

This example declares one static array variable, named riCustomers, containing 5 elements of type RowId.

RowId[][3] riCustomers

This example creates a two-dimensional dynamic array variable named riCustomers, containing an undefined number of elements of type RowId. Conceptually, this represents a rectangular array with an undefined number of rows, each of 3 columns.

You can declare dynamic multi-dimensional arrays where all dimensions are dynamic; these are called jagged arrays.

Notes

• If you need to define a global RowId variable, you should use the global_variable command to do so.
• The RowId style of programming can be used with all types of tables. Even if your underlying table uses Recnum (e.g., the embedded database), you may still use the RowId programming style. The use of RowId and the RowId functions completely replaces the need to use Recnum programming techniques. Using the RowId programming style will create a more portable application.