C5_GETREADER

 GETREADER()
 Execute standard READ behavior for a Get object
------------------------------------------------------------------------------
 Syntax

     GETREADER(<oGet>, <GetList>, <oMenu>, <nMsgRow>,
        <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> NIL

 Arguments

     <oGet> is a reference to a Get object.

     <GetList> is an array of all the Get objects in the current Get
     list.

     <oMenu> is a reference to a TopBarMenu object.

     <nMsgRow> is a numeric value representing the row number on the
     screen where the message bar is located.

     <nMsgLeft> is a numeric value representing the left border of the
     row bar.

     <nMsgRight> is a numeric value representing the right border of the
     row bar.

     <cMsgColor> is a character string representing the color string to
     be used for the message bar.

 Returns

     GETREADER() always returns NIL.

 Description

     GETREADER() is a GET function that implements the standard READ behavior
     for GETs.  By default, READMODAL() uses the GETREADER() function to read
     Get objects.  GETREADER() in turn uses other functions in Getsys.prg to
     do the work of reading the Get object.

 Notes

     .  If a Get object's Get:reader instance variable contains a code
        block, READMODAL() will evaluate that block in lieu of the call to
        GETREADER().  For more information refer to the Get:reader reference.

 Examples

     .  This example sets the current Get object to the first GET in
        the Get list.  Then, a READ is performed on this GET which has no
        menu object, but includes a message bar at row 25 from column 0 to
        column 80.  The color of the text on the message bar is white with a
        red background.

        oGet := GetList [1]
        GETREADER (oGet, Getlist, NIL,25,;
                       0,80,"W+/R")

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: GETAPPLYKEY() GETDOSETKEY() GETPOSTVALID()



C5_GETPREVALIDATE

 GETPREVALIDATE()
 Prevalidate a Get object
------------------------------------------------------------------------------
 Syntax

     GETPREVALIDATE(<oGet>) --> lSuccess

 Arguments

     <oGet> is a reference to the current Get object.

 Returns

     GETPREVALIDATE() returns a logical value indicating whether the Get
     object has been prevalidated successfully.

 Description

     GETPREVALIDATE() is a function that validates the Get object for
     editing, including evaluating Get:preBlock (the WHEN clause) if it is
     present.  The logical return value indicates whether the GET has been
     prevalidated successfully.

     Get:exitState is also set to reflect the outcome of the prevalidation:

     Get:exitState Values
     ------------------------------------------------------------------------
     Getexit.ch   Meaning
     ------------------------------------------------------------------------
     GE_NOEXIT    Indicates prevalidation success, okay to edit
     GE_WHEN      Indicates prevalidation failure
     GE_ESCAPE    Indicates that a CLEAR GETS was issued
     ------------------------------------------------------------------------

     Note that in the default system, a Get:exitState of GE_ESCAPE cancels
     the current GET and terminates READMODAL().

 Examples

     .  This example demonstrates the GETPREVALIDATE() function.

        IF GETPREVALIDATE (oGet)
           // process the get
        ELSE
           // WHEN clause not satisfied
           // give a warning to the user
        ENDIF

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: GETAPPLYKEY() GETDOSETKEY() GETPOSTVALID()



C5_GETPOSTVALIDATE

 GETPOSTVALIDATE()
 Postvalidate the current Get object
------------------------------------------------------------------------------
 Syntax

     GETPOSTVALIDATE(<oGet>) --> lSuccess

 Arguments

     <oGet> is a reference to the current Get object.

 Returns

     GETPOSTVALIDATE() returns a logical value indicating whether the Get
     object has been postvalidated successfully.

 Description

     GETPOSTVALIDATE() is a Get system function that validates a Get object
     after editing, including evaluating Get:postBlock (the VALID clause) if
     present.

     The return value indicates whether the GET has been postvalidated
     successfully.  If a CLEAR GETS is issued during postvalidation,
     Get:exitState is set to GE_ESCAPE and GETPOSTVALIDATE() returns true
     (.T.).

 Notes

     .  In the default system, a Get:exitState of GE_ESCAPE cancels
        the current GET and terminates READMODAL().

 Examples

     .  This example calls GETPOSTVALIDATE to determine whether or not
        the VALID clause of oGet is satisfied.  If not, then the user is not
        allowed to exit from the Get object.

        IF (! GETPOSVALIDATE (oGet))
           oGet : exitState := GE_NOEXIT
        ENDIF

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: GETAPPLYKEY() GETDOSETKEY() GETPREVALID()



C5_GETENV

 GETENV()
 Retrieve the contents of a DOS environment variable
------------------------------------------------------------------------------
 Syntax

     GETENV(<cEnvironmentVariable>) --> cString

 Arguments

     <cEnvironmentVariable> is the name of the DOS environment variable.
     When specifying this argument, you can use any combination of uppercase
     and lowercase letters; GETENV() is not case-sensitive.

 Returns

     GETENV() returns the contents of the specified DOS environment variable
     as a character string.  If the variable cannot be found, GETENV()
     returns a null string ("").

 Description

     GETENV() is an environment function that lets you retrieve information
     from the DOS environment into an application program.  Typically, this
     is configuration information, including path names, that gives the
     location of files (database, index, label, or reports).  This function
     is particularly useful for network environments.

 Notes

     .  Empty return value: If you are certain that an environment
        variable exists and yet GETENV() always returns a null string (""),
        be sure there are no spaces between the environment variable name and
        the first character of the string assigned to it in the DOS SET
        command.

     .  Compatibility: In previous releases of Clipper, the
        function was called GETE().  This abbreviated form of GETENV() is
        still operational.

 Examples

     .  This example retrieves the current DOS PATH setting, making it
        the current Clipper PATH:

        cPath := GETENV("PATH")
        SET PATH TO (cPath)

     .  This example uses environment variables to configure the
        specific locations of files.  When you set up a system, define
        environment variables that contain the location of various file types
        as well as the CLIPPER environment variable (see "The Runtime
        Environment" chapter in the Programming and Utilities Guide), like
        this:

        C>SET LOC_DBF=<database file path>
        C>SET LOC_NTX=<index file path>
        C>SET LOC_RPT=<report file path>

        In the configuration section of your application program, assign the
        contents of the environment variables to variables.  Then when you
        access a file, preface the reference with the path variable as
        follows:

        cDdfDirectory := GETENV("LOC_DBF")
        USE (cDdfDirectory + "Invoices")

 Files   Library is CLIPPER.LIB.

 

C5_GETDOSETKEY

 GETDOSETKEY()
 Process SET KEY during GET editing
------------------------------------------------------------------------------
 Syntax

     GETDOSETKEY(<bKeyBlock>, <oGet>) --> NIL

 Arguments

     <oGet> is a reference to the current Get object.

     <bKeyBlock> is the code block to execute.

 Returns

     GETDOSETKEY() always returns NIL.

 Description

     GETDOSETKEY() is a function that executes a SET KEY code block,
     preserving the context of the passed Get object.

     Note that the procedure name and line number passed to the SET KEY block
     are based on the most recent call to READMODAL().

 Notes

     .  If a CLEAR GETS occurs in the SET KEY code, Get:exitState is
        set to GE_ESCAPE.  In the standard system this cancels the current
        Get object processing and terminates READMODAL().

 Examples

     .  The following example determines if the last key pressed,
        nKey, has a SET KEY associated with it.  If it does, then GETDOSETKEY
        is called to execute that block on the current GET.

        IF ((bKeyBlock := SETKEY (nKey)) == NIL)
           GETDOSETKEY (bKeyBlock, oGet)
        ENDIF

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: GETAPPLYKEY() GETPOSTVALID() GETPREVALID()

 

C5_GETAPPLYKEY

 GETAPPLYKEY()
 Apply a key to a Get object from within a  reader
------------------------------------------------------------------------------
 Syntax

     GETAPPLYKEY(<oGet>, <nKey>, <GetList>, <oMenu>,
        <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>)
        --> NIL

 Arguments

     <oGet> is a reference to a Get object.

     <nKey> is the INKEY() value to apply to <oGet>.

     <GetList> is a reference to the current list of Get objects.

     <oMenu> is a reference to any top bar menu.

     <nMsgRow> is a numeric value representing the row of the message
     bar.

     <nMsgLeft> is a numeric value representing the left column of the
     message bar.

     <nMsgRight> is a numeric value representing the right column of the
     message bar.

     <cMsgColor> is a character string representing the colors to be used
     for the message bar text.

 Returns

     GETAPPLYKEY() always returns NIL.

 Description

     GETAPPLYKEY() is a Get system function that applies an INKEY() value to
     a Get object.  Keys are applied in the default way.  That is, cursor
     movement keys change the cursor position within the GET, data keys are
     entered into the GET, etc.

     If the key supplied to GETAPPLYKEY() is a SET KEY, GETAPPLYKEY() will
     execute the set key and return; the key is not applied to the Get
     object.

 Notes

     .  Focus:  The Get object must be in focus before keys are
        applied. Refer to Get:setFocus and Get:killFocus for more
        information.

     .  CLEAR GETS:  The Get object must be in focus before keys are
        applied.  Refer to Get:setFocus and Get:killFocus for more
        information.

 Examples

     This example will apply keystrokes until Exit:

        WHILE (oGet:exitState == GE_NOEXIT)
           GETAPPLYKEY (oGet, INKEY(0), GetList, oMenu, nMsgRow,;
        nMsgLeft, nMsgRight, nMsgColor)
        ENDDO

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: GETDOSETKEY() GETPOSTVALID() GETPREVALID()



C5_GETACTIVE

GETACTIVE()
 Return the currently active Get object
------------------------------------------------------------------------------
 Syntax

     GETACTIVE([<oGet>]) --> objGet

 Arguments

     <oGet> is a reference to a Get object.

 Returns

     GETACTIVE() returns the Get object referenced by <oGet>.  If <oGet> is
     not specified, then the current active Get object within the current
     READ is used.  If there is no READ active when GETACTIVE() is called, it
     returns NIL.

 Description

     GETACTIVE() is an environment function that provides access to the
     active Get object during a READ.  The current active Get object is the
     one with input focus at the time GETACTIVE() is called.

 Examples

     .  This code uses a WHEN clause to force control to branch to a
        special reader function.  Within this function, GETACTIVE() retrieves
        the active Get object:

        @ 10, 10 GET x
        @ 11, 10 GET y WHEN MyReader()
        @ 12, 10 GET z
        READ

        // Called just before second get (above)
        // becomes current
        FUNCTION MyReader
           LOCAL objGet               // Active Get holder
           objGet := GETACTIVE()      // Retrieve current

                                      // active Get
           BarCodeRead( objGet )
           RETURN (.F.)               // Causes Get to be
                                      // skipped in READ

 Files   Library is CLIPPER.LIB, source file is Getsys.prg.

See Also: @…GET READ READMODAL()