TABLE.OPENMAP Function
Syntax
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.
The TABLE.OPEN() method automatically finds and opens an associated index file (.cdx) matching the table name and its related data dictionary.
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