SET RELATION

SET RELATION

Relate two work areas by a key value or record number

Syntax

      SET RELATION TO [<expKey> | <nRecord> INTO <xcAlias>]
            [, [TO] <expKey2> | <nRecord2> INTO <xcAlias2>...]
            [ADDITIVE]

Arguments

TO <expKey> is an expression that performs a SEEK in the child work area each time the record pointer moves in the parent work area. For this to work, the child work area must have an index in USE.

TO <nRecord> is an expression that performs a GOTO to the matching record number in the child work area each time the record pointer moves in the parent work area. If <nRecord> evaluates to RECNO(), the relation uses the parent record number to perform a GOTO to the same record number in the child work area. For a numeric expression type of relation to execute correctly, the child work area must not have an index in USE.

INTO <xcAlias> identifies the child work area and can be specified either as the literal alias name or as a character expression enclosed in parentheses.

ADDITIVE adds the specified child relations to existing relations already set in the current work area. If this clause is not specified, existing relations in the current work area are released before the new child relations are set.

SET RELATION TO with no arguments releases all relations defined in the current work area.

Description

SET RELATION is a database command that links a parent work area to one or more child work areas using a key expression, record number, or numeric expression. Each parent work area can be linked to as many as eight child work areas. A relation causes the record pointer to move in the child work area in accordance with the movement of the record pointer in the parent work area. If no match is found in the child work area, the child record pointer is positioned to LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

The method of linking the parent and child work areas depends on the type of <expKey> and presence of an active index in the child work area. If the child work area has an active index, the lookup is a standard SEEK. If the child work area does not have an active index and the type of <expKey> is numeric, a GOTO is performed in the child work area instead.

Notes

. Cyclical relations: Do not relate a parent work area to itself either directly or indirectly.

. Soft seeking: SET RELATION does not support SOFTSEEK and always behaves as if SOFTSEEK is OFF even if SOFTSEEK is ON. This means that if a match is not found in the child work area, the child record pointer is always positioned to LASTREC() + 1.

. Record number relations: To relate two work areas based on matching record numbers, use RECNO() for the SET RELATION TO expression and make sure the child work area has no active indexes.

Examples

      .  This example relates three work areas in a multiple parent-
         child configuration with Customer related to both Invoices and Zip:

         USE Invoices INDEX Invoices NEW
         USE Zip INDEX Zipcode NEW
         USE Customer NEW
         SET RELATION TO CustNum INTO Invoices, Zipcode INTO Zip
         LIST Customer, Zip->City, Invoices->Number, ;
                  Invoices->Amount

      .  Sometime later, you can add a new child relation using the
         ADDITIVE clause, like this:

         USE BackOrder INDEX BackOrder NEW
         SELECT Customer

         SET RELATION TO CustNum INTO BackOrder ADDITIVE

Seealso

DBRELATION(), DBRSELECT(), FOUND(), RECNO(), SET INDEX

dbFilter()

DBFILTER()

Return the filter expression in a work area

Syntax

      DBFILTER() --> cFilter

Returns

DBFILTER() returns the filter expression.

Description

This function return the expression of the SET FILTER TO command for the current or designated work area. If no filter condition is present, a NULL string will be returned.

Examples

      USE test INDEX test NEW
      SET FILTER TO Name == "Harbour"
      USE testid INDEX testid NEW
      SET FILTER TO Id == 1
      SELECT Test
      //
      ? DBFILTER()
      ? testid->( DBFILTER() )

Compliance

Clipper

Files

Library is rdd

Seealso

DBRELATION(), DBRSELECT()

C5_DBRELATION

 DBRELATION()
 Return the linking expression of a specified relation
------------------------------------------------------------------------------
 Syntax

     DBRELATION(<nRelation>) --> cLinkExp

 Arguments

     <nRelation> is the position of the desired relation in the list of
     current work area relations.  The relations are numbered according to
     the order in which they were defined with SET RELATION.

 Returns

     DBRELATION() returns a character string containing the linking
     expression of the relation specified by <nRelation>.  If there is no
     RELATION SET for <nRelation>, DBRELATION() returns a null string ("").

 Description

     DBRELATION() is a database function used with DBRSELECT() to determine
     the linking expression and work area of an existing relation created
     with the SET RELATION command.

     DBRELATION() returns the linking expression defined by the TO clause.
     DBRSELECT() returns the work area linked as defined by the INTO clause.

     By default, DBRELATION() operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression (see example below).

 Notes

     .  Declared variables: A character string returned by
        DBRELATION() may not operate correctly when recompiled and executed
        using the macro operator (&) if the original expression contained
        references to local or static variables, or otherwise depends on
        compile-time declarations.

 Examples

     .  This example opens three database files, sets two child
        relations from the parent work area, and then displays the linking
        expression to the second child work area:

        USE Invoices INDEX Invoices NEW
        USE BackOrder INDEX BackOrder NEW
        USE Customer INDEX Customer NEW
        SET RELATION TO CustNum INTO Invoices, OrderNum ;
              INTO BackOrder
        //
        ? DBRELATION(2)                  // Result: OrderNum

     .  Later you can query the same linking expression from an
        unselected work area by using an aliased expression like this:

        USE Archive NEW
        ? Customer->(DBRELATION(2))   // Result: OrderNum

     .  This example is a user-defined function, Relation(), that
        returns the results of both DBRELATION() and DBRSELECT() as an array:

        FUNCTION Relation( nRelation )
           RETURN { DBRELATION(nRelation), ;
                 ALIAS(DBRSELECT(nRelation)) }

 Files   Library is CLIPPER.LIB.

See Also: DBFILTER() DBRSELECT() SET RELATION



C5 Database Functions

AFIELDS() :

Fill arrays with the structure of the current database file

AFIELDS([<aFieldNames>],
    [<aTypes>],
    [<aWidths>],
    [<aDecimals>]) --> nFields

ALIAS() : 

Return a specified work area alias

ALIAS([<nWorkArea>]) --> cAlias

BOF() : 

Determine when beginning of file is encountered

BOF() --> lBoundary

DBAPPEND() : 

Add a new record

DBAPPEND() --> NIL

DBCLEARFILTER() : 

Clear a filter condition

    DBCLEARFILTER() –> NIL

DBCLEARIND() :  Close all indexes for the current work area

    DBCLEARINDEX() --> NIL

DBCLEARREL() : 

Clear active relations

DBCLEARRELATION() --> NIL

DBCLOSEALL() : 

Close all occupied workareas

DBCLOSEALL() --> NIL

DBCLOSEAREA() : 

Close a workarea

DBCLOSEAREA() --> NIL

DBCOMMIT() : 

Flush pending updates

DBCOMMIT() --> NIL

DBCOMMITALL() : 

Flush pending updates in all workareas

DBCOMMITALL() --> NIL

DBCREATE() : 

Create a database file from a database structure array

DBCREATE(<cDatabase>, <aStruct> [, <cDriver> ] ) --> NIL

DBCREATEIND() : 

Create an Index

   DBCREATEINDEX(<cIndexName>, <cKeyExpr>,
        [<bKeyExpr>], [<lUnique>]) --> NIL

DBDELETE() : 

Mark a record for deletion

DBDELETE() --> NIL

DBEDIT() : 

        Browse records in a table layout

    DBEDIT([<nTop>], [<nLeft>],
        [<nBottom>], <nRight>],
        [<acColumns>],
        [<cUserFunction>],
        [<acColumnSayPictures> | <cColumnSayPicture>],
        [<acColumnHeaders> | <cColumnHeader>],
        [<acHeadingSeparators> | <cHeadingSeparator>],
        [<acColumnSeparators> | <cColumnSeparator>],
        [<acFootingSeparators> | <cFootingSeparator>],
        [<acColumnFootings> | <cColumnFooting>]) --> NIL

DBEVAL() : 

Evaluate a code block for each record

DBEVAL(<bBlock>,
    [<bForCondition>],
    [<bWhileCondition>],
    [<nNextRecords>],
    [<nRecord>],
    [<lRest>]) --> NIL

DBF()* : 

Return current alias name

DBF() --> cAlias

DBFIELDINFO() : 

Return and optionally change information about a field

   DBFIELDINFO(<nInfoType>,

        <nFieldPos>,
        [<expNewSetting>]) --> uCurrentSetting

DBFILEGET() : 

Insert the contents of a field into a file

     DBFILEGET(<nFieldPos>, <cTargetFile>, <nMode>)
        --> lSuccess

DBFILEPUT() : 

Insert the contents of a file into a field

     DBFILEPUT(<nFieldPos>, <cSourceFile>)
        --> lSuccess

 DBFILTER() : 

Return the current filter expression as a character string

DBFILTER() --> cFilter

DBGOBOTTOM() : 

Move to the last logical record

DBGOBOTTOM() --> NIL

DBGOTO() : 

Move to a particular record

DBGOTO(<nRecordNumber>) --> NIL

DBGOTOP() : 

Move to the first logical record

DBGOTOP() --> NIL

DBINFO() : 

         Return and optionally change database file information

    DBINFO(<nInfoType>, [<expNewSetting>])
        --> uCurrentSetting

DBORDERINFO() :          Return and optionally change information about orders and index files

    DBORDERINFO(<nInfoType>,   [<cIndexFile>],
        [<cOrder> | <nPosition>],
        [<expNewSetting>]) --> uCurrentSetting

DBRECALL() : 

Reinstate a record marked for deletion

DBRECALL() --> NIL

DBRECORDINFO() :

         Return and optionally change information about a record

    DBRECORDINFO(<nInfoType>,
        [<nRecord>],
        [<expNewSetting>]) --> uCurrentSetting

DBREINDEX() :

         Recreate all active indexes for the current work area

    DBREINDEX() --> NIL

DBRELATION() :

Return the linking expression of a specified relation

DBRELATION( <nRelation> ) --> cLinkExp

DBRLOCK() :      

         Lock the record at the current or specified identity

    DBRLOCK([<xIdentity>]) --> lSuccess

DBRLOCKLIST()          Return an array of the current lock list

   DBRLOCKLIST() --> aRecordLocks

DBRSELECT() :

Return the target workarea number of a relation

DBRSELECT( <nRelation> ) --> nWorkArea

DBRUNLOCK()    

          Release all or specified record locks

    DBRUNLOCK([<xIdentity>]) --> NIL

DBSEEK() : 

Search for a key value

DBSEEK(<expKey>, [<lSoftSeek>]) --> lFound

DBSELECTAR() : 

Change the current workarea

DBSELECTAREA(<nArea> | <cAlias>) --> NIL

DBSETDRIVER() : 

Set the default database driver

DBSETDRIVER([<cDriver>]) --> cCurrentDriver

DBSETFILTER() : 

Set a filter condition

DBSETFILTER(<bCondition>, [<cCondition>]) --> NIL

DBSETINDEX()    

         Empty orders from an order bag into the order list

    DBSETINDEX(<cOrderBagName>) --> NIL

DBSETORDER()

Set the controlling order

    DBSETORDER(<nOrderNum>) --> NIL

DBSETRELAT() :

Relate two workareas

DBSETRELATION( <nArea> | <cAlias>, <bExpr>, [<cExpr>]) --> NIL

DBSKIP() : 

Move relative to the current record

DBSKIP([<nRecords>]) --> NIL

DBSTRUCT() : 

Create an array containing the structure of a database file

DBSTRUCT() --> aStruct

DBUNLOCK()

Release all locks for the current work area

    DBUNLOCK() --> NIL

DBUNLOCKALL()

Release all locks for all work areas

    DBUNLOCKALL() --> NIL

DBUSEAREA() : 

Use a database file in a workarea

DBUSEAREA( [<lNewArea>],
    [<cDriver>],
    <cName>,
    [<xcAlias>],
    [<lShared>],
    [<lReadonly>]) --> NIL

DELETED() : 

Return the deleted status of the current record

DELETED() --> lDeleted

EOF() : 

Determine when end of file is encountered

EOF() --> lBoundary

FCOUNT() : 

Return the number of fields in the current (.dbf) file

FCOUNT() --> nFields

FIELD() : 

Return a field name from the current (.dbf) file

    FIELD/FIELD(<nPosition>) --> cFieldName

FIELDBLOCK() :

Return a set-get code block for a field variable

FIELDBLOCK(<cFieldName>) --> bFieldBlock

FIELDGET() : 

Retrieve the value of a field using the ordinal position of the field in the database structure

FIELDGET(<nField>) --> ValueField

FIELDNAME() : 

Return a field name from the current (.dbf) file

FIELDNAME/FIELD(<nPosition>) --> cFieldName

FIELDPOS() : 

Return the position of a field in a workarea

FIELDPOS(<cFieldName>) --> nFieldPos

FIELDPUT() : 

Set the value of a field variable using the ordinal position of the field in the database structure

FIELDPUT(<nField>, <expAssign>) --> ValueAssigned

FIELDWBLOCK() : 

Return a set-get block for a field in a given workarea

FIELDWBLOCK(<cFieldName>, <nWorkArea>) --> bFieldWBlock

FLOCK() : 

Lock an open and shared database file

    FLOCK() –> lSuccess

FOUND() : 

Determine if the previous search operation succeeded

FOUND() --> lSuccess

HEADER() : 

Return the current database file header length

HEADER() --> nBytes

LASTREC() : 

Determine the number of records in the current (.dbf) file

LASTREC() | RECCOUNT()* --> nRecords

LUPDATE() : 

Return the last modification date of a (.dbf) file

LUPDATE() --> dModification

RECCOUNT()* : 

Determine the number of records in the current (.dbf) file

RECCOUNT()* | LASTREC() --> nRecords

RECNO() : 

Return the current record number of a work area

RECNO() --> nRecord

RECSIZE() : 

Determine the record length of a database (.dbf) file

RECSIZE() --> nBytes

RLOCK()

Lock the current record in the active work area

    RLOCK() --> lSuccess

SELECT() : 

Determine the work area number of a specified alias

SELECT([<cAlias>]) --> nWorkArea

USED() : 

Determine if a database file is in USE

USED() --> lDbfOpen