Apollo API Listing > sx

VB Declaration

Declare Function sx_Use Lib "Apollo9.dll"

(ByVal cpFileName As String,

ByVal cpAlias As String,

ByVal iOpenMode As Integer,

ByVal iRdeType As Integer)

As Integer

C Declaration

SHORT FAR PASCAL sx_Use

(BYTEP cpFileName,

BYTEP cpAlias,

SHORT iOpenMode,

SHORT iRdeType);

Description

Opens an existing table. No indexes are attached when the file is opened if using NTX or IDX indexes. If a CDX index is present with the same name as the DBF (except for the extension of course), it is opened automatically. The record pointer is positioned to the first physical record in the file.

If a structural compound index exists for the DBF, it is automatically opened. A structural index is one that has the same name as the DBF with an extension that matches the RDE in use (i.e., .CDX for SDEFOX and .NSX for SDENSX). When a structural index is opened, there is no controlling order presumed. You must explicitly select an order with sx_SetOrder.

Parameters

cpFileName: The name of the file containing the database including full path and extension.

cpAlias: An alias name for the file to be used when referencing field names from this database when it is not the active work area.

Alias Names

Alias names may be used to indicate the table owning a particular field. When a table is opened with sx_Use, that database is the default owner of all field references and operations until it is changed with sx_Select or another file is opened. sx_Use assigns an alias name to be used to reference the database when it is not the current work area. This becomes particularly useful when relational chains are built. Using an alias name enables you to access data from child files without having to constantly change the current work area via sx_Select.

Alias names may be used within an xBase expression as well as within other API functions. Alias names are separated from field references by the alias operator "->" within an xBase expression string. When alias names are used within other API functions that refer to field names, either the alias operator or a period delimiter (via C structure element or Visual Basic control property reference) may be used to separate the alias name from the field name.

iOpenMode: Indicates how the file is to be opened. Use one of the following defined constants:

READWRITE 0

READONLY 1

EXCLUSIVE 2

iRdeType: The replaceable database engine (RDE) to be used on the database and indexes. Apollo supports a number of different RDEs which make data and index management transparent to both the User and the programmer. Use one of the following defined constants:

SDENTX 1

SDEFOX 2

SDENSX 3

SDENSX_DBT 4 (Clipper DBT using NSX indexes)

Return Value

The order identifying number of the database work area. This value should be retained in a global variable for future sx_Select calls.

Note: If an error occurs when opening the file (e.g., exclusive use not granted), the value returned is zero.

Search Path

If no path is supplied for cpFileName, the following is the search order:

1. The current directory.

2. The Windows directory.

3. The Windows System directory.

4. The directory containing the executable file for the current task.

5. The directories listed in the PATH environment variable.

6. Network mapped directories.

VB Example

If Dir$("c:\vb\test\cust.dbf") = "" Then

MsgBox "No File"

End

End If

CustArea = sx_Use("\vb\test\cust.dbf", "cust", READWRITE, SDENTX)

sx_SetFilter "upper(trim(place))='CHINA' .and. left(last, 1)>' '"

C Example

void CNamesForm::OnButtonAppendBatch()

{

// save master before append

sx_CopyFile("c:\\back\\sqmback.dbf");

if (!sx_AppendFrom("c:\\vb\\sxqueue.dbf", SDENTX, NULL))

{

// on failure, restore master

AfxMessageBox((LPCSTR) "Batch append failed.");

sx_Close();

sx_Use("c:\\back\\sqmback.dbf", "qback", READONLY, SDENTX);

sx_CopyFile("c:\\vb\\sqmast.dbf");

sx_Use("c:\\vb\\sqmast.dbf", "qmaster", READWRITE, SDENTX);

}

else

sx_GoTop();

}

sx_Use