Entry_name_item Command

Obsolete

This command is obsolete. This command is valid only in character-mode DataFlex. There is no Windows equivalent for this option.

See Also

Purpose

To allow the assignment of names to entry items.

Syntax

entry_name_item
item_name file.field [[entry_options]]

What It Does

Entry_name_item is a replacement for the entry_item command that permits the assignment of names to object items for easier recognition in source code. Item_name is the name by which you choose to refer to the item, and the remainder of the syntax (file.field and entry_options) is the original syntax of the entry_item command.

Referring to items in objects by their item numbers straightforwardly can result in code that is very difficult to read, as the following example demonstrates. The item list establishes items for price, quantity, and total, and the succeeding procedure calculates the extension to the total.

Object My_Form is an entry_form My_Form Using a_data_dictionary
    item_list
        entry_item Tran.Id
        entry_item Part.Id
        entry_item Part.Description
        entry_item Part.Amount
        entry_item Tran.Qty
        entry_item Tran.Total
    end_item_list

    Procedure Calc_Total Integer Item#
        Number A1 A2
        Get value item 3 to A1        // this doesn't tell
        Get value item 4 to A2        // you a whole lot.
        Set value item 5 to (A1 * A2)
    end_procedure
end_object

We have to keep track of the item numbers (they are zero-based). This can be difficult. What if we counted wrong? What if we moved the items around (e.g., moved Description to the end)?

The following example shows how the same would be done using entry_name_item:

Object My_Form is an entry_form My_Form Using a_data_dictionary
    item_list
        entry_item Tran.Id
        entry_item Part.Id
        entry_item Part.Description
        entry_name_item Amount## Part.Amount
        entry_name_item Quantity## Tran.Qty
        entry_name_item Total## Tran.Total
    end_item_list

    Procedure Calc_Total Integer Item#
        Number A1 A2
        Get value item Quantity## to A1      // much nicer!
        Get value item Amount## to A2        // Suddenly I can see!!
        Set value item Total## to (A1 * A2)
    end_procedure
end_object

In the following discussion, we will talk about the entry_name_item command. Everything discussed applies equally to the on_name_item command.

Note that you do not need to use entry_name_item everywhere you would have used entry_item. In fact, it is best to only name the items that you actually need (we will see why later on).

Limitations

1. Global Names

The item_names are global names and must therefore be unique. Ideally, these names would be local to the object containing the items. Therefore, you should use unique names for the items and only name the items that you really need (the entry_name_item and entry_item commands may be intermixed freely). In the above example, we ended each item name with a double pound-sign (##). This makes it less likely that they will be used for other symbols (images, local variables, etc.) and makes it easy to recognize as an item name.

1. Forward Referencing

You can't use the item names until you've named them. Therefore, you could not do the following:

Procedure Calc_Total Integer Item#
    Number A1 A2
    Get value item Quantity## to A1     // Hey, who is this Quantity##?
    Get value item Amount## to A2       // Amount##, what's that?
    Set value item Total## to (A1 * A2) // Huh?
end_procedure

item_list
    entry_item Tran.Id
    entry_item Part.Id
    entry_item Part.Description
    entry_name_item Amount## Part.Amount
    entry_name_item Quantity## Tran.Qty
    entry_name_item Total## Tran.Total
end_item_list

This suggests that you should place your item_lists towards the top of your objects. Also, you can't reference these names in an earlier object (bad OOP practice to begin with).

If you can't live with this restriction, then you should do the following:

Look at your program. Odds are you are having problems because your code is not OOP-proper. Are you trying to directly access item information for one object from within another object? See if you can correct the problem.

If you can't (or you won't), then use the alternate command, name_items (see below). This command is similar to the name command of DataFlex and can be placed at the top of your program.

Naming Items in Grid Objects

When referencing items in Grid-class objects, you need to reference the item number relative to the item number of the current row. This can usually be accomplished by using the base_item property as your item number offset. For example, the above sample could be turned into a grid:

Object My_Table is a grid My_Form ;
    main_file Tran by Index.1 ;
    Using a_data_dictionary
    begin_row
        entry_item Tran.Id
        entry_item Part.Id
        entry_item Part.Description
        entry_name_item Amount## Part.Amount
        entry_name_item Quantity## Tran.Qty
        entry_name_item Total## Tran.Total
    end_row

    Procedure Calc_Total Integer Item#
        Number A1 A2
        Integer BI
        Get base_item to BI // should be item number of column 0 of current row
        Get value item (Quantity## + BI) to A1    // use BI as our offset into
        Get value item (Amount## + BI) to A2      // the table.
        Set value item (Total## + BI) to (A1 * A2)
    end_procedure
end_object