Parent | Child | Previous | Next
 

table.ENTER_BEGIN function

IN THIS PAGE

Syntax

<TBL>.ENTER_BEGIN( [ Field_Rules_Flag as L ] )

Arguments

Field_Rules_Flag

Optional. Default = .F.

.T. (TRUE) = Enforce UI Level field rules when the record is entered.
.F. (FALSE) = Ignore UI Level field rules when the record is entered.

Description

Initiates an Enter operation to add a new record.

Discussion

The ENTER_BEGIN() method initiates an Enter operation to add a new record to the table referenced by <TBL>. You complete the Enter operation by using the <TBL>.ENTER_END() method. Field_Rules_Flag is an optional parameter. If Field_Rules_Flag is .T., or is set to HONOR_FIELD_RULES, then UI Level field rules are enforced when the record is entered (only under special circumstances - see Note below). If the Field_Rules_Flag is .F., then Alpha Anywhere does not enforce these UI Level field rules. UI Level field rules are rules such as:

trigger events
capitalization
minimum and maximum values
masks/templates
lookup fill-ins
required fields

Engine Level

rules, such as auto-increment values are always enforced. Note : The Field_Rules_Flag parameter is only honored if the <TBL> pointer is the same pointer that a layout is using. For example, assume you have a button on a form with the following code: 

dim tbl as P
tbl = table.current()
tbl.enter_begin(.T.)
    tbl.LASTNAME = "Simpson"
    tbl.FIRSTNAME = "Bart"
tbl.enter_end(.T.)

In the above example, Alpha Anywhere will honor the Field_Rules_Flag variable because <TBL> references the primary instance of the table on which the Form is based. However, the following code will NOT honor the Field_Rules_Flag variable because <TBL> references a new instance of the "customer" table.

dim tbl as P
tbl = table.open("customer")
tbl.enter_begin(.T.)
    tbl.LASTNAME = "Simpson"
    tbl.FIRSTNAME = "Bart"
tbl.enter_end(.T.)
tbl.close()

One or more Enter operations can occur simultaneously, each on a different open table. The number of active Enter operations cannot exceed the number of open tables. Once a table is in Enter mode, you can assign values to the table fields in the record buffer. For example, the following operation creates a new record and assigns values to the LAST_NAME and FIRST_NAME fields: 

dim tbl as P
tbl = table.open("d:\a5\a_sports\customer")
tbl.enter_begin()
    tbl.LASTNAME = "Simpson"
    tbl.FIRSTNAME = "Bart"
tbl.enter_end(.T.)
tbl.close()

You cannot use the <TBL>.ENTER_BEGIN() method or <TBL>.CHANGE_BEGIN() methods on a table that is already in either Change or Enter mode. To determine the current mode, use the <TBL>.MODE_GET() method. You cannot move the record pointer (using any of the fetch methods) in a table that is already in either Change or Enter mode. The <TBL>.ENTER_BEGIN() method is for working with tables "behind the scenes". Contrast this method with the form methods. Note : The value of the current record number, as returned by <TBL>.RECNO() and the values of auto-increment fields read between the <TBL>.ENTER_BEGIN()and <TBL>.ENTER_END() methods may change in a multi-user environment. The actual values of these numbers can only be determined after the record is written. 

dim tbl as P
tbl = table.open("d:\a5\a_sports\customer")
tbl.enter_begin()
    i = tbl.recno()' do not use this approach in a multi-user environment
    i2 = tbl.invoice_number ' do not use this approach in a multi-user environment
tbl.enter_end(.T.)
k = tbl.recno()' use this approach instead
k2 = tbl.invoice_number ' use this approach instead (i.e. read the value after the record is saved)
tbl.close()

Note : The example below uses the a_current_db system variable. This variable contains the name of the current primary table.

Example

This script adds 10 new records.

dim tbl as P
tbl = table.current()
for i = 0 TO 9
    tbl.enter_begin()
    tbl.prod_id = "P00" + LTRIM(STR(i))
    tbl.enter_end(.T.)
next i

This script prompts the user for a record number, and then add a new a new record to the table that is a duplicate of the specified record. The script is attached to a button on a form.

rec = ui_get_number("Duplicate record","Enter record number:")
if rec = "" then
    end
else
    tbl_1 = table.current()
    'Open a second instance of the session primary table
    tbl_2 = table.open(a_current_db)
    'Set its index to record order
    indx_2 = tbl_2.index_primary_put()
    'Find the specified record
    tbl_2.fetch_findrec?
    'Put first instance of table into enter mode and clone record
    'from second instance
    tbl_1.enter_begin()
    tbl_1.record_clone(tbl_2)
    tbl_1.enter_end(.T.)
    'Synch up the form to display the new record
    parent.resynch()
    tbl_2.close()
end if

This script, attached to a button on a form, uses form methods instead of the <TBL>.ENTER_BEGIN() method to enter a new record.

topparent.new_record()
customer.value = "Alpha Software Corporation"
customer.address = "168 Middlesex Turnpike"
customer.city = "Burlington"
customer.state_prov = "MA"
customer.postal_code = "01803"
parent.commit()

See Also