TABLE.OPENMAP Function

Syntax

tbl as P = TABLE.OpenMap(C tableName ,C fieldList [,N mode [, C alias [,C password ]]])

Arguments

tableNameCharacter

The table file's path and name. The .DBF file extension is automatically added to the filename if you do not specify a file extension. To open a set, you must supply the .SET extension.

fieldListCharacter

A comma delimited list of fields to open. There should not be any space characters between field names. The list should be formatted: field1,field2,field3.

modeNumeric

Determines the access privileges that apply to the open table file. You can use one of the following system variables:

Variable
Function
FILE_RO_EXCLUSIVE

Read Only (Exclusive)

FILE_RW_EXCLUSIVE

Read or Write (Exclusive)

FILE_RO_SHARED

Read Only (Shared)

FILE_RW_SHARED

Read or Write (Shared)

FILE_REUSE_EXISTING

Intended for internal use only. Allows you to create another pointer to an open file.

aliasCharacter

Default = "". Specifies the alias for the table. A table alias is automatically generated if the alias parameter is blank or null alias.

By default, the table alias is automatically derived from the table name. For example, if the table name is "customer", the first instance of the table that is opened will have an alias of "customer", the second instance will have an alias of "customer0" and so on.

Specifying an alias when opening a table is rarely required.

passwordCharacter

Required if the table has been encrypted, and the default encryption key has not been set (using the DEFAULT_ENCRYPTION_KEY_SET() function), or if the table was encrypted using a different encryption key than the default encryption key.

Returns

tblPointer

Returns a pointer that references the table, or in the case of a set, the parent table of the set.

Description

Creates a pointer to an open table and only contains the fields specified in the fieldList.

Discussion

The TABLE.OPENMAP() method opens an existing table or set, and creates an object pointer that references the table, or in the case of a set, the parent table of the set. The function is similar to the TABLE.OPEN() method, but limits the fields that are visible to those in a specified field list. This command is especially useful in conjunction with the <ARRAY>.INITIALIZE_FROM_TABLE() method to load an array with data from a table.

If you have set a Master Password for your database, and have encrypted tables using the Tools > Security menu on the Control Panel, then the default encryption key is automatically set when the database is opened, and you do not need to specify the password parameter when opening tables.

The TABLE.OPEN() method automatically finds and opens an associated index file (.cdx) matching the table name and its related data dictionary.

In addition to the above modes, another mode flag can be used in conjunction with the above modes. The flag, FILE_REUSE_EXISTING indicates to Alpha Anywhere that rather than opening a new instance of the table, it should attempt to find an already open instance of the table (if possible) and use that instead. For example, specify an Open Mode of FILE_REUSE_EXISTING + FILE_RW_SHARED, indicates that you want to get a pointer to an existing instance of a table in read/write/shared mode.

The table opened by the TABLE.OPEN() method does not become the primary table of the session. For example, if a session is started by opening a form, the table for that form is the primary table in the session. The user interface menus and buttons on the form apply to the session's primary table. The table opened by the TABLE.OPEN() method can only be manipulated by Xbasic methods, not by the user interface. You can change the primary table of a session with the TABLE.RESET() method, however this method should only be used in the Interactive session.

If you use the <TBL>.ENTER_BEGIN() or <TBL>.CHANGE_BEGIN() methods to do data entry into a table opened with the TABLE.OPEN() method, not all field rules are in effect. Engine level field rules, such as auto-increment, and validation expressions are enforced. However, user interface level field rules, such as Lookups and case conversion are not enforced. If you want all field rules to be enforced, you should open a form based on the table (you can use the FORM.LOAD() method to open the form invisibly) and then use form methods to enter data.

The TABLE.CURRENT() method automatically assigns a unique alias to the table. To determine the alias for a particular pointer, use the <TBL>.NAME_GET() method. The alias is the table name, modified with a trailing "1", "2", "3", etc. if necessary, to ensure that the alias is unique.

The .OPEN() method will fail if you try to open a set, and any of the tables in the set are already open. This is because Alpha Anywhere assumes that the aliases for all of the tables in the set will be the same as the table names. If, however, one of the tables in the set is already open in the session, the table name will have already been assigned as the alias name to the open table.

Refer to Contrasting TABLE.OPEN with TABLE.CURRENT and TABLE.GET.

Use the <TBL>.FETCH_FIRST(), <TBL>.FETCH_LAST(), <TBL>.FETCH_FIND(), or <TBL>.FETCH_GOTO() methods to position the record pointer in the table after you first open it.

Example 

The following example shows how you can open a view on the customer table in AlphaSports.

dim fieldList as C
dim tbl as P
dim cn as sql::connection

fieldList = <<%txt%
fname = firstname
lastname
fullname = alltrim(lastname) + ", " + alltrim(firstname)
date = date()
number = 123.45
%txt%

tbl = table.OpenMap("customer",fieldList)
ui_msg_box("Fullname",tbl.fullname)

'Get a resultset from the open table
rs = cn.ResultSetFromDBF(tbl)

'Display a window showing the rows in the resultset
sql_resultset_preview(rs)

'Now export the results to a text file
export.type = 0
export.names = .T.
export.file = "c:\customer.txt"
export.options = ""
export.field_sep = ","
export.record_sep = ""
export.fields = 5
export.field1 = "fname"
export.field2 = "lastname"
export.field3 = "fullname"
export.field4 = "date"
export.field5 = "number"
tbl.export()
sys_open(export.file)

tbl.close()

This script opens the same table but with only two fields.

dim tt as P
tt = table.openmap("customer","firstname,lastname")
? tt.fields_get()
= 2
? tt.field_name_get()
= firstname
lastname
dim a100 as P
a.initialize_from_table(tt)
? a1
= FIRSTNAME = "Fred"
LASTNAME = "Harrison"

See Also