C5_RTRIM

 RTRIM()
 Remove trailing spaces from a character string
------------------------------------------------------------------------------
 Syntax

     RTRIM(<cString>) --> cTrimString

 Arguments

     <cString> is the character string to be copied without trailing
     spaces.

 Returns

     RTRIM() returns a copy of <cString> with the trailing spaces removed.
     If <cString> is a null string ("") or all spaces, RTRIM() returns a null
     string ("").

 Description

     RTRIM() is a character function that formats character strings.  It is
     useful when you want to delete trailing spaces while concatenating
     strings.  This is typically the case with database fields which are
     stored in fixed-width format.  For example, you can use RTRIM() to
     concatenate first and last name fields to form a name string.

     RTRIM() is related to LTRIM() which removes leading spaces, and
     ALLTRIM() which removes both leading and trailing spaces.  The inverse
     of ALLTRIM(), LTRIM(), and RTRIM() are the PADC(), PADR(), and PADL()
     functions which center, right-justify, or left-justify character strings
     by padding them with fill characters.  RTRIM() is exactly the same as
     TRIM() in function.

 Notes

     .  Space characters: The RTRIM() function treats carriage
        returns, line feeds, and tabs as space characters and removes these
        as well.

 Examples

     .  This is a user-defined function in which RTRIM() formats city,
        state, and zip code fields for labels or form letters:

        FUNCTION CityState(cCity, cState, cZip)
           RETURN RTRIM(cCity) + ", " ;
            + RTRIM(cState) + "  " + cZip

     .  In this example the user-defined function, CityState(),
        displays a record from Customer.dbf:

        USE Customer INDEX CustName NEW
        SEEK "Kate"
        ? CityState(City, State, ZipCode)
        // Result: Athens, GA 10066

 Files   Library is CLIPPER.LIB.

See Also: PAD() SUBSTR() TRIM()

 

Advertisements

C5_ROW

 ROW()
 Return the screen row position of the cursor
------------------------------------------------------------------------------
 Syntax

     ROW() --> nRow

 Returns

     ROW() returns the cursor row position as an integer numeric value.  The
     range of the return value is zero to MAXROW().

 Description

     ROW() is a screen function that returns the current row or line position
     of the screen cursor.  The value of ROW() is updated by both console and
     full-screen commands and functions.  @...SAY only updates ROW() when the
     current DEVICE is the SCREEN.

     ROW() is used with COL() and all variations of the @ command to position
     the cursor to a new line relative to the current line.  In particular,
     you can use ROW() and COL() to create screen position-independent
     procedures or functions where you pass the upper-left row and column as
     parameters.

     ROW() is related to PROW() and PCOL(), which track the current printhead
     position instead of the screen cursor position.

 Examples

     .  In this example, ROW() simulates the LIST command, displaying
        text on the same line but in different columns:

        LOCAL nRow
        USE Customer INDEX CustName NEW
        DO WHILE .NOT. EOF()
           CLS
           @ 1, 1 SAY PADR("Name", LEN(CustName))
           @ ROW(), COL() + 2 SAY PADR("Address", ;
                 LEN(Address))
           @ ROW(), COL() + 2 SAY PADR("Phone", LEN(Phone))
           nRow = 0
           DO WHILE nRow++ <= 15 .AND. (!EOF())
              @ ROW() + 1, 1 SAY CustName
              @ ROW(), COL() + 2 SAY Address
              @ ROW(), COL() + 2 SAY Phone
              SKIP
           ENDDO
           WAIT
        ENDDO
        CLOSE Customer

 Files   Library is CLIPPER.LIB.

See Also: ?|?? @…GET @…SAY PCOL() PROW()

 

C5_ROUND

 ROUND()
 Return a numeric value rounded to a specified number of digits
------------------------------------------------------------------------------
 Syntax

     ROUND(<nNumber>, <nDecimals>) --> nRounded

 Arguments

     <nNumber> is the numeric value to be rounded.

     <nDecimals> defines the number of decimal places to retain.
     Specifying a negative <nDecimals> value rounds whole number digits.

 Returns

     ROUND() returns a numeric value.

 Description

     ROUND() is a numeric function that rounds <nNumber> to the number of
     places specified by <nDecimals>.  Specifying a zero or negative value
     for <nDecimals> allows rounding of whole numbers.  A negative
     <nDecimals> indicates the number of digits to the left of the decimal
     point to round.  Digits between five to nine (inclusive) are rounded up.
     Digits below five are rounded down.

     The display of the return value does not obey the DECIMALS setting
     unless SET FIXED is ON.  With SET FIXED OFF, the display of the return
     value contains as many decimal digits as you specify for <nDecimals>, or
     zero, if <nDecimals> is less than one.

 Examples

     .  These examples round values with decimal digits:

        SET DECIMALS TO 2
        SET FIXED ON
        //
        ? ROUND(10.4, 0)                     // Result: 10.00
        ? ROUND(10.5, 0)                     // Result: 11.00
        ? ROUND(10.51, 0)                    // Result: 11.00
        ? ROUND(10.49999999999999, 2)        // Result: 10.50

     .  These examples use a negative <nDecimals> argument to round
        numeric values to whole number values:

        ? ROUND(101.99, -1)                  // Result: 100.00
        ? ROUND(109.99, -1)                  // Result: 110.00
        ? ROUND(109.99, -2)                  // Result: 100.00

 Files   Library is CLIPPER.LIB.

See Also: SET DECIMALS SET FIXED STR() VAL()

 

C5_RLOCK

 RLOCK()
 Lock the current record in the active work area
------------------------------------------------------------------------------
 Syntax

     RLOCK() --> lSuccess

 Returns

     RLOCK() returns true (.T.) if the record lock is obtained; otherwise, it
     returns false (.F.).

 Description

     RLOCK() is a network function that locks the current record, preventing
     other users from updating the record until the lock is released.
     RLOCK() provides a shared lock, allowing other users read-only access to
     the locked record while allowing only the current user to modify it.  A
     record lock remains until another record is locked, an UNLOCK is
     executed, the current database file is closed, or an FLOCK() is obtained
     on the current database file.

     For each invocation of RLOCK(), there is one attempt to lock the current
     record, and the result is returned as a logical value.  An attempt to
     obtain a record lock fails if another user currently has a file or
     record lock on that particular record, or EXCLUSIVE USE of the database
     file.  An attempt to RLOCK() in an empty database returns true (.T.).

     By default, RLOCK() 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).  This feature is useful since
     RLOCK() does not automatically attempt a record lock for related files.

     As a general rule, RLOCK() operates solely on the current record.  This
     includes the following commands:

     .  @...GET

     .  DELETE (single record)

     .  RECALL (single record)

     .  REPLACE (single record)

     Refer to the "Network Programming" chapter in the Programming and
     Utilities Guide for more information.

 Notes

     .  SET RELATION: Clipper does not automatically lock all
        records in the relation chain when you lock the current work area
        record.  Also, an UNLOCK has no effect on related work areas.

 Examples

     .  This example deletes a record in a network environment, using
        RLOCK():

        USE Customer INDEX CustName SHARED NEW
        SEEK "Smith"
        IF FOUND()
           IF RLOCK()
              DELETE
              ? "Smith deleted"
           ELSE
              ? "Record in use by another"
           ENDIF
        ELSE
           ? "Smith not in Customer file"
        ENDIF
        CLOSE

     .  This example specifies RLOCK() as an aliased expression to
        lock a record in an unselected work area:

        USE Sales SHARED NEW
        USE Customer SHARED NEW
        //
        IF !Sales->(RLOCK())
           ? "The current Sales record is in use by another"
        ENDIF

 Files   Library is CLIPPER.LIB.

See Also: APPEND BLANK SET EXCLUSIVE* UNLOCK USE

 

C5_RIGHT

 RIGHT()
 Return a substring beginning with the rightmost character
------------------------------------------------------------------------------
 Syntax

     RIGHT(<cString>, <nCount>) --> cSubString

 Arguments

     <cString> is the character string from which to extract characters.

     <nCount> is the number of characters to extract.

 Returns

     RIGHT() returns the rightmost <nCount> characters of <cString>.  If
     <nCount> is zero, RIGHT() returns a null string ("").  If <nCount> is
     negative or larger than the length of the character string, RIGHT()
     returns <cString>.  The maximum string size is 65,535 (64K) bytes.

 Description

     RIGHT() is a character function that extracts a substring beginning with
     the rightmost character in <cString>.  It is the same as the character
     expression, SUBSTR(<cString>, <nCount>).  For example, RIGHT("ABC", 1)
     is the same as SUBSTR("ABC", -1).  RIGHT() is related to LEFT(), which
     extracts a substring beginning with the leftmost character in <cString>.

     The RIGHT(), LEFT(), and SUBSTR() functions are often used with both the
     AT() and RAT() functions to locate either the first and/or the last
     position of a substring before extracting it.

 Examples

     .  This example shows the relationship between RIGHT() and
        SUBSTR():

        ? RIGHT("ABCDEF", 3)              // Result: DEF
        ? SUBSTR("ABCDEF", -3)            // Result: DEF

     .  This example extracts a substring from the end of another
        string up to the last occurrence of a comma:

        LOCAL cName := "James,William"
        ? RIGHT(cName,;
        LEN(cName) - RAT(",", cName) - 1)      // Result: William

 Files   Library is EXTEND.LIB.

See Also: RTRIM() STUFF() SUBSTR()

 

C5_RESTSCREEN

 RESTSCREEN()
 Display a saved screen region to a specified location
------------------------------------------------------------------------------
 Syntax

     RESTSCREEN([<nTop>], [<nLeft>],
        [<nBottom>], [<nRight>], <cScreen>) --> NIL

 Arguments

     <nTop>, <nLeft>, <nBottom>, and <nRight> define the
     coordinates of the screen information contained in <cScreen>.  If
     <cScreen> was saved without coordinates to preserve the entire screen,
     no screen coordinates are necessary with RESTSCREEN().

     <cScreen> is a character string containing the saved screen region.

 Returns

     RESTSCREEN() always returns NIL.

 Description

     RESTSCREEN() is a screen function that redisplays a screen region saved
     with SAVESCREEN().  The target screen location may be the same as or
     different from the original location when the screen region was saved.
     If you specify a new screen location, the new screen region must be the
     same size or you will get ambiguous results.  To use RESTSCREEN() to
     restore screen regions saved with SAVE SCREEN, specify the region
     coordinates as 0, 0, MAXROW(), MAXCOL().

     Warning!  SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), and
     RESTSCREEN() are supported when using the default (IBM PC memory mapped)
     screen driver.  Other screen drivers may not support saving and
     restoring screens.

 Examples

     .  This example demonstrates RESTSCREEN() as part of a general
        purpose pop-up menu function, PopMenu():

        ? PopMenu({1, 1, 3, 10, {"ItemOne", "ItemTwo"}, ;
              "BG+/B"})

        FUNCTION PopMenu( aList )
           LOCAL cScreen, nChoice, cOldColor := ;
                    SETCOLOR(aList[6])
           cScreen := SAVESCREEN(aList[1], aList[2],;
               aList[3], aList[4])
           @ aList[1], aList[2], TO aList[3], aList[4] DOUBLE
           nChoice := ACHOICE(++aList[1], ++aList[2],;
              --aList[3], --aList[4], aList[5])
           SETCOLOR(cOldColor)
           RESTSCREEN(--aList[1], --aList[2], ++aList[3],;
               ++aList[4], cScreen)
           RETURN nChoice

 Files   Library is EXTEND.LIB.

See Also: RESTORE RESTORE SCREEN* SAVE SAVESCREEN()

 

C5_REPLICATE

 REPLICATE()
 Return a string repeated a specified number of times
------------------------------------------------------------------------------
 Syntax

     REPLICATE(<cString>, <nCount>) --> cRepeatedString

 Arguments

     <cString> is the character string to be repeated.

     <nCount> is the number of times to repeat <cString>.

 Returns

     REPLICATE() returns a character string up to a maximum of 65,535 (64K)
     bytes in length.  Specifying a zero as the <nCount> argument returns a
     null string ("").

 Description

     REPLICATE() is a character function that repeatedly displays, prints, or
     stuffs the keyboard with one or more characters.  REPLICATE() is like
     the SPACE() function, which returns a specified number of space
     characters.

 Examples

     .  These examples demonstrate REPLICATE() repeating strings:

        ? REPLICATE("*", 5)           // Result: *****
        ? REPLICATE("Hi ", 2)         // Result: Hi Hi
        ? REPLICATE(CHR(42), 5)       // Result: *****

     .  This example uses REPLICATE() to stuff the keyboard with
        several Down arrow keys:

        #include "Inkey.ch"
        KEYBOARD REPLICATE(CHR(K_DOWN), 25)

 Files   Library is CLIPPER.LIB.

See Also: SPACE()