Click above to get retro games delivered to your door ever month!

Function:    OPENED()

Purpose:     Open one or more databases with network error checking.

Syntax:      OPENED( [ errorFlag ] database [ ...  database10 ] )

Arguments:   errorFlag   - Optional LOGICAL value which if true will cause
                           automatic error messages to be displayed.  The
                           default value is True.

             database    - Character string similar in form to that
                           supplied to the USE command.  This string may
                           contain one or more INDEX files, and ALIAS name
                           specifier and an EXCLUSIVE or SHAREABLE keyword
                           qualifier.  Up to 10 database parameter strings
                           may be passed allowing up to 10 files to be
                           opened at once.

Returns:     True if all files were opened successfully, false otherwise.
             If a false is returned an errorlevel is also passed via the
             RlibError() function.  See below for specific error values.

Description: OPENED() is a database function which lets you open several
             database files and indexes with one call!  It also checks to
             make sure everything opened ok before returning.  If any one
             of the file opens fails, all files opened thus far in the
             call to OPENED() are closed, and a false (and RlibError())
             are returned.  This is primarily intended to aid the
             developer in dealing with opening multiple databases in a
             network environment where error trapping is critical.
             OPENED() eliminates the messy and cumbersome nested IF
             statements necessary to ensure proper error trapping.
             OPENED() can also benefit the single user developer by
             greatly reducing the amount of code needed to open files and
             indexes.  See the example below for sample syntax and the
             amount of coding it can save!

Notes:       OPENED() works by parsing each of up to ten parameters, one
             at a time.  Each parameter is first verified to be character
             then left and right trimmed and converted to upper case.
             Next, each parameter is checked for the following keyword
             strings:

             " ALIAS "     -- An alias name was specified.
             " INDEX "     -- Index file(s) are to be opened.
             " EXCLUSIVE"  -- File is to be opened in exclusive mode.
             " SHAREABLE"  -- File is to be opened in shareable mode.

             The exclusive and shareable keywords are EXPLICIT
             instructions.  This means that OPENED() will use the current
             default state of SET EXCLUSIVE unless either of these flags
             is specified.  Since there is no way in native Summer '87
             Clipper to query the status of SET EXCLUSIVE, OPENED() cannot
             change the setting and return it to its incoming state.  This
             is one area where OPENED() is not black boxed.  (For
             compatibility reasons, the Clipper 5.0 version of OPENED()
             will NOT save and restore the setting of SET EXCLUSIVE.  Some
             applications may come to expect the state of SET EXCLUSIVE to
             be as the last call to OPENED() left it).

             Work area selection:

             Upon successful completion, OPENED() leaves the last database
             specified as the currently selected work area.  If OPENED()
             fails, the work area selected upon entry is re-selected, and
             all files OPENED() may have successfully opened are closed.

             Important points:

             1.  Index file names MUST be separated by commas, not spaces.
             2.  Four letter abbreviations such as INDE are NOT allowed.

             Parameter sequence:

             The order in which the keyword string ALIAS, INDEX,
             EXCLUSIVE, and SHAREABLE is arbitrary.  The only requirement
             is that, naturally, the name of the database file to open is
             the first part of the string.

             Any of the parameters may be a logical value.  If a logical
             parameter is encountered, its value is used to set the flag
             whether or not automatic error messages are displayed.  The
             default state is true which means that if a file is not
             found, or and index file is not present, or a file open
             fails, then an error message will be displayed before
             OPENED() stops and returns .F.  (plus setting RLIBERROR()).
             If this flag is set to false, then error messages will not be
             generated, only a return value will signal your application
             which may then generate its own error messages.

             These logical values may be listed multiple times, the status
             takes effect on all files opened after the logical value is
             encountered.

             One interesting side effect of turning automatic error
             messages off is that the user will not have the option of
             re-trying to open a file in a network environment, if the
             open failed due to an exclusive use conflict; OPENED() will
             simply fail and return .F.  plus RlibError() = 1101.

             RLIBERROR() return values:

             The possible RlibError() return values from OPENED() are:

                0  =  Success
             1101  =  File sharing violation
             1102  =  Database .DBF file not found
             1103  =  Associated .NTX file not found
             1104  =  Associated .DBT file not found (future)
             1105  =  Invalid alias name syntax or other syntax error

             These error values are established to be in an increasing
             order of severity.  Normally an error level of 1101 means
             that the file was not available in a network environment.
             Error levels of 1102, 1103, or 1104 indicate that a run-time
             file is not present.  This is usually recoverable by
             correcting the situation outside of the program.  An
             errorlevel of 1105 or above is intended to indicate a calling
             program syntax problem.

Example:     *-- Open three dbf's and indexes in various modes with error
             *-- reports in a network environment.  See how simple it is!

             d1= "cust ALIAS Customers INDEX custName, custNumb SHAREABLE"
             d2= "invt ALIAS Inventory INDEX invtNumb, invtDesc SHAREABLE"
             d3= "tempdbf.001 INDEX tempntx.001 ALIAS Tempfile EXCLUSIVE"
             IF .NOT.  OPENED( d1, d2, d3 )
                RETURN
             ENDIF
             *-- ALL DONE!!!!!!!!!!!!!


             *-- =============  T H E   O L D   W A Y  =============
             *-- Look at all this monstrous code!  Yecch!  Use OPENED()!
             SET EXCLUSIVE OFF
             IF ! (FILE("cust.dbf")     .AND. FILE("invt.dbf")     .AND.;
                   FILE("tempdbf.001")  .AND. FILE("custname.ntx") .AND.;
                   FILE("custnumb.ntx") .AND. FILE("invtnumb.ntx") .AND.;
                   FILE("invtdesc.ntx") .AND. FILE("tempntx.001"))
                *-- You think this is overkill?  What happens if one file
                *-- gets deleted from under your nose on a network?
                BUZZ(2)
                BOXASK( "W+/R", "Required file(s) are missing" )
                RETURN
             ENDIF

             *-- we've only just begun, lots of code still must follow!
             SET EXCLUSIVE OFF
             SELECT 0
             DO WHILE .T.
                USE cust ALIAS Customers
                IF .NOT.  NETERR()
                   EXIT
                ENDIF
                IF BOXASK( "File in use by another.  Re-try?", 30 ) = "N"
                   RETURN
                ENDIF
             ENDDO
             SET INDEX TO custname, custnumb

             SELECT 0
             DO WHILE .T.
                USE invt ALIAS Inventory
                IF .NOT.  NETERR()
                   EXIT
                ENDIF
                IF BOXASK( "File in use by another.  Re-try?", 30 ) = "N"
                   CLOSEAREA("Customers")
                   RETURN
                ENDIF
             ENDDO
             SET INDEX TO invtNumb, invtDesc

             SELECT 0
             SET EXCLUSIVE ON
             DO WHILE .T.
                USE tempdbf.001 ALIAS Tempfile
                IF .NOT.  NETERR()
                   EXIT
                ENDIF
                IF BOXASK( "File in use by another.  Re-try?", 30 ) = "N"
                   CLOSEAREA("Customers", "Inventory")
                   RETURN
                ENDIF
             ENDDO
             SET INDEX TO tempntx.001
             *-- FINALLY, we're done!  Yech, what a pile of code!

Source:      RL_OPENE.PRG

See also:    BOXASK(), CLOSEAREA(), RLIBERROR()