C5_ARRAY

Posted on July 13, 2013 by vivaclipper

 ARRAY()
 Create an uninitialized array of specified length
------------------------------------------------------------------------------
 Syntax

     ARRAY(<nElements> [, <nElements>...]) aArray

 Arguments

     <nElements> is the number of elements in the specified dimension.
     The maximum number of elements in a dimension is 4096.  Arrays in
     Clipper can have an unlimited number of dimensions.

 Returns

     ARRAY() returns an array of specified dimensions.

 Description

     ARRAY() is an array function that returns an uninitialized array with
     the specified number of elements and dimensions.  If more than one
     <nElements> argument is specified, a multidimensional array is created
     with the number of dimensions equal to the number of <nElements>
     arguments specified.  Any <nElements> that is itself an array creates a
     nested array.

     In Clipper, there are several ways to create an array.  You can
     declare an array using a declaration statement such as LOCAL or STATIC;
     you can create an array using a PRIVATE or PUBLIC statement; you can
     assign a literal array to an existing variable; or you can use the
     ARRAY() function.  ARRAY() has the advantage that it can create arrays
     within expressions or code blocks.

 Examples

     .  This example creates a one-dimensional array of five elements
        using the ARRAY() function, and then shows the equivalent action by
        assigning a literal array of NIL values:

        aArray := ARRAY(5)
        aArray := { NIL, NIL, NIL, NIL, NIL }

     .  This example shows three different statements which create the
        same multidimensional array:

        aArray := ARRAY(3, 2)
        aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} }
        aArray := { ARRAY(2), ARRAY(2), ARRAY(2) }

     .  This example creates a nested, multidimensional array:

        aArray := ARRAY(3, {NIL,NIL})

 Files   Library is CLIPPER.LIB.

See Also: AADD() ACLONE() ACOPY() ADEL() AEVAL() AFILL()

C5_ALTD

Posted on July 13, 2013 by vivaclipper

 ALTD()
 Invoke the Clipper debugger
------------------------------------------------------------------------------
 Syntax

     ALTD([<nAction>]) --> NIL

 Arguments

     <nAction> defines what action ALTD() performs when invoked.  The
     following is a complete list of <nAction> values and their actions:

     ALTD() Actions
     ------------------------------------------------------------------------
     Argument     Action
     ------------------------------------------------------------------------
     None         Invokes the debugger if it is enabled
     0            Disables Alt+D
     1            Enables Alt+D
     Other        No action
     ------------------------------------------------------------------------

 Returns

     ALTD() always returns NIL.

 Description

     ALTD() performs differently depending on its argument as shown in the
     table above.  For more information on using the debugger, refer to
     "Clipper Debugger-CLD.LIB" chapter in the Programming and Utilities
     Guide.  Also refer to the "Debugging Your Applications" chapter in the
     Workbench User Guide.

 Examples

     .  This example demonstrates a series of manifest constants that
        can be used as arguments for ALTD() before invoking the debugger
        programmatically:

        #define ALTD_DISABLE      0
        #define ALTD_ENABLE      1
        //
        ALTD(ALTD_ENABLE)

 Files   Library is CLIPPER.LIB.

See Also: SET ESCAPE SETCANCEL()

C5_ALLTRIM

Posted on July 13, 2013 by vivaclipper

 ALLTRIM()
 Remove leading and trailing spaces from a character string
------------------------------------------------------------------------------
 Syntax

     ALLTRIM(<cString>) --> cTrimString

 Arguments

     <cString> is the character expression to be trimmed.

 Returns

     ALLTRIM() returns a character string with leading and trailing spaces
     removed.

 Description

     ALLTRIM() is a character function that removes both leading and trailing
     spaces from a string.  It is related to LTRIM() and RTRIM() which remove
     leading and trailing spaces, respectively.  The inverse of ALLTRIM(),
     LTRIM(), and RTRIM() are the PADC(), PADL(), and PADR() functions which
     center, left-justify, or right-justify character strings by padding them
     with fill characters.

 Notes

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

 Examples

     .  This example creates a string with both leading and trailing
        spaces, and then trims them with ALLTRIM():

        cString := SPACE(10) + "string" + SPACE(10)
        ? LEN(cString)                     // Result: 26
        ? LEN(ALLTRIM(cString))            // Result: 6

 Files   Library is EXTEND.LIB.

See Also: LTRIM() PAD() RTRIM() TRIM()

C5_ALIAS

Posted on July 13, 2013 by vivaclipper

 ALIAS()
 Return a specified work area alias
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <nWorkArea> is any work area number.

 Returns

     ALIAS() returns the alias of the specified work area as a character
     string in uppercase.  If <nWorkArea> is not specified, the alias of the
     current work area is returned.  If there is no database file in USE for
     the specified work area, ALIAS() returns a null string ("").

 Description

     ALIAS() is a database function that determines the alias of a specified
     work area.  An alias is the name assigned to a work area when a database
     file is USEd.  The actual name assigned is either the name of the
     database file, or a name explicitly assigned with the ALIAS clause of
     the USE command.

     ALIAS() is the inverse of the SELECT() function.  ALIAS() returns the
     alias name given the work area number, and SELECT() returns the work
     area number given the alias name.

     .  This example returns the name of the previously selected work
        area:

        USE File1 NEW ALIAS Test1
        nOldArea := SELECT()
        USE File2 NEW ALIAS Test2
        ? ALIAS( nOldArea )            // Returns Test1

 Files   Library is CLIPPER.LIB.

See Also: SELECT SELECT() USE

C5_ALERT

Posted on July 13, 2013 by vivaclipper

 ALERT()
 Display a simple modal dialog box
------------------------------------------------------------------------------
 Syntax

     ALERT( <cMessage>, [<aOptions>] ) --> nChoice

 Arguments

     <cMessage> is the message text displayed and centered in the alert
     box.  If the message contains one or more semicolons, the text after the
     semicolons is centered on succeeding lines in the dialog box.

     <aOptions> defines a list of up to 4 possible responses to the
     dialog box.

 Returns

     ALERT() returns a numeric value indicating which option was chosen.  If
     the Esc key is pressed, the value returned is zero.

 Description

     The ALERT() function creates a simple modal dialog.  It is useful in
     error handlers and other "pause" functions.  The user can respond by
     moving a highlight bar and pressing the Return or SpaceBar keys, or by
     pressing the key corresponding to the first letter of the option.  If
     <aOptions> is not supplied, a single "Ok" option is presented.

     ALERT() is sensitive to the presence or absence of the Clipper
     full-screen I/O system.  If the full-screen system is not present,
     ALERT() uses standard I/O to display the message and options tty-style
     (i.e., 80-column, without word wrap, each line ended with carriage
     return/linefeed).

 Examples

     .  This example demonstrates use of an alert dialog box.  First,
        the array of options is defined, the ALERT() function gets the user's
        selection, and finally, the user's choice is handled with a DO
        CASE...ENDCASE control structure:

        #define AL_SAVE         1
        #define AL_CANCEL      2
        #define AL_CONT         3

        // Define an array of options
        aOptions := {"Save", "Don't Save", "Continue"}

        // Display the dialog box and get the user's selection
        nChoice  := ALERT("File has changed...", aOptions)

        // Handle the user's request
        DO CASE
        CASE nChoice == AL_SAVE
           ? "Save"
        CASE nChoice == AL_CANCEL
           ? "Don't Save"
        CASE nChoice == AL_CONT
           ? "Continue"
        OTHERWISE
           ? "Escape"
        ENDCASE
        //
        RETURN

 Files   Library is LLIBG.LIB.

See Also: @…PROMPT MENU TO

C5_AINS

Posted on July 13, 2013 by vivaclipper

 AINS()
 Insert a NIL element into an array
------------------------------------------------------------------------------
 Syntax

     AINS(<aTarget>, <nPosition>) --> aTarget

 Arguments

     <aTarget> is the array into which a new element will be inserted.

     <nPosition> is the position at which the new element will be
     inserted.

 Returns

     AINS() returns a reference to the target array, <aTarget>.

 Description

     AINS() is an array function that inserts a new element into a specified
     array.  The newly inserted element is NIL data type until a new value is
     assigned to it.  After the insertion, the last element in the array is
     discarded, and all elements after the new element are shifted down one
     position.

     Warning!  AINS() must be used carefully with multidimensional
     arrays.  Multidimensional arrays in Clipper are implemented by
     nesting arrays within other arrays.  Using AINS() in a multidimensional
     array discards the last element in the specified target array which, if
     it is an array element, will cause one or more dimensions to be lost.
     To insert a new dimension into an array, first add a new element to the
     end of the array using AADD() or ASIZE() before using AINS().

 Examples

     .  This example demonstrates the effect of using AINS() on an
        array:

        LOCAL aArray
        aArray := { 1, 2, 3 }      // Result: aArray is
                                   // now { 1, 2, 3 }
        AINS(aArray, 2)            // Result: aArray is
                                   // now { 1, NIL, 2 }

 Files   Library is CLIPPER.LIB.

See Also: AADD() ACOPY() ADEL() AEVAL() AFILL() ASIZE()

C5_AFILL

Posted on July 13, 2013 by vivaclipper

 AFILL()
 Fill an array with a specified value
------------------------------------------------------------------------------
 Syntax

     AFILL(<aTarget>, <expValue>,
        [<nStart>], [<nCount>]) --> aTarget

 Arguments

     <aTarget> is the array to be filled.

     <expValue> is the value to be placed in each array element.  It can
     be an expression of any valid data type.

     <nStart> is the position of the first element to be filled.  If this
     argument is omitted, the default value is one.

     <nCount> is the number of elements to be filled starting with
     element <nStart>.  If this argument is omitted, elements are filled from
     the starting element position to the end of the array.

 Returns

     AFILL() returns a reference to <aTarget>.

 Description

     AFILL() is an array function that fills the specified array with a
     single value of any data type (including an array, code block, or NIL)
     by assigning <expValue> to each array element in the specified range.

     Warning!  AFILL() cannot be used to fill multidimensional arrays.
     Clipper implements multidimensional arrays by nesting arrays within
     other arrays.  Using AFILL() with a multidimensional array will
     overwrite subarrays used for the other dimensions of the array.

 Examples

     .  This example, creates a three-element array.  The array is
        then filled with the logical value, (.F.).  Finally, elements in
        positions two and three are assigned the new value of true (.T.):

        LOCAL aLogic[3]
        // Result: aLogic is { NIL, NIL, NIL }

        AFILL(aLogic, .F.)
        // Result: aLogic is { .F., .F., .F. }

        AFILL(aLogic, .T., 2, 2)
        // Result: aLogic is { .F., .T., .T. }

 Files   Library is CLIPPER.LIB.

See Also: AADD() AEVAL() DBSTRUCT() DIRECTORY()

C5_AFIELDS

Posted on July 13, 2013 by vivaclipper

 AFIELDS()*
 Fill arrays with the structure of the current database file
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <aFieldNames> is the array to fill with field names.  Each element
     is a character string.

     <aTypes> is the array to fill with the type of fields in
     <aFieldNames>.  Each element is a character string.

     <aWidths> is the array to fill with the widths of fields in
     <aFieldNames>.  Each element is numeric data type.

     <aDecimals> is the array to fill with the number of decimals defined
     for fields in <aFieldNames>.  Each element is numeric data type.  If the
     field type is not numeric, the <aDecimals> element is zero.

 Returns

     AFIELDS() returns the number of fields or the length of the shortest
     array argument, whichever is less.  If no arguments are specified, or if
     there is no file in USE in the current work area, AFIELDS() returns
     zero.

 Description

     AFIELDS() is an array function that fills a series of arrays (structure
     attribute arrays) with the structure of the database file currently
     open, one element in each array per field.  AFIELDS() works like ADIR(),
     filling a series of existing arrays with information.  To use AFIELDS(),
     you must first create the arrays to hold the database structure
     information, each with the same number of elements as the number of
     fields (i.e. FCOUNT()).  Once the structure attribute arrays are
     created, you can then invoke AFIELDS() to fill the structure arrays with
     information about each field.

     By default, AFIELDS() operates on the currently selected work area.  It
     can  operate on an unselected work area if you specify it within an
     aliased expression (see example below).

     AFIELDS() is a compatibility function and therefore is not recommended.
     It is superseded by DBSTRUCT(), which does not require the existence of
     any arrays prior to invocation and returns a multidimensional array
     containing the current database file structure.

 Examples

     .  This example demonstrates how AFIELDS() and ACHOICE() can be
        used together to create a fields picklist:

        USE Sales NEW
        PRIVATE aFieldNames[FCOUNT()]
        AFIELDS(aFieldNames)
        @ 1, 0 TO 10, 10 DOUBLE
        nChoice := ACHOICE(2, 1, 9, 9, aFieldNames)
        @ 12, 0 SAY IF(nChoice != 0, aFieldNames[nChoice],;
                        "None selected")
        RETURN

     .  This example uses AFIELDS() with an aliased expression to fill
        arrays with the structure of Sales.dbf, open in an unselected work
        area:

        LOCAL aFieldNames, aTypes, aWidths, aDecimals
        USE Sales NEW
        USE Customer NEW
        //
        aFieldNames := Sales->(ARRAY(FCOUNT()))
        aTypes := Sales->(ARRAY(FCOUNT()))
        aWidths := Sales->(ARRAY(FCOUNT()))
        aDecimals := Sales->(ARRAY(FCOUNT()))
        //
        Sales->(AFIELDS(aFieldNames, aTypes, ;
                 aWidths, aDecimals))

 Files   Library is EXTEND.LIB.

See Also: ACHOICE() ADIR()* AEVAL() ASCAN() DBCREATE()

C5_AEVAL

Posted on July 13, 2013 by vivaclipper

 AEVAL()
 Execute a code block for each element in an array
------------------------------------------------------------------------------
 Syntax

     AEVAL(<aArray>, <bBlock>,
        [<nStart>], [<nCount>]) --> aArray

 Arguments

     <aArray> is the array to traverse.

     <bBlock> is a code block to execute for each element encountered.

     <nStart> is the starting element.  If not specified, the default is
     element one.

     <nCount> is the number of elements to process from <nStart>.  If not
     specified, the default is all elements to the end of the array.

 Returns

     AEVAL() returns a reference to <aArray>.

 Description

     AEVAL() is an array function that evaluates a code block once for each
     element of an array, passing the element value and the element index as
     block parameters.  The return value of the block is ignored.  All
     elements in <aArray> are processed unless either the <nStart> or the
     <nCount> argument is specified.

     AEVAL() makes no assumptions about the contents of the array elements it
     is passing to the block.  It is assumed that the supplied block knows
     what type of data will be in each element.

     AEVAL() is similar to DBEVAL() which applies a block to each record of a
     database file.  Like DBEVAL(), AEVAL() can be used as a primitive for
     the construction of iteration commands for both simple and complex array
     structures.

     Refer to the Code Blocks section in the "Basic Concepts" chapter of the
     Programming and Utilities Guide for more information on the theory and
     syntax of code blocks.

 Examples

     .  This example uses AEVAL() to display an array of file names
        and file sizes returned from the DIRECTORY() function:

        #include "Directry.ch"
        //
        LOCAL aFiles := DIRECTORY("*.dbf"), nTotal := 0
        AEVAL(aFiles,;
           { | aDbfFile |;
              QOUT(PADR(aDbfFile[F_NAME], 10), aDbfFile[F_SIZE]),;
              nTotal += aDbfFile[F_SIZE]);
           } )
        //
        ?
        ? "Total Bytes:", nTotal

     .  This example uses AEVAL() to build a list consisting of
        selected items from a multidimensional array:

        #include "Directry.ch"
        //
        LOCAL aFiles := DIRECTORY("*.dbf"), aNames := {}
        AEVAL(aFiles,;
           { | file | AADD(aNames, file[F_NAME]) };
           )

     .  This example changes the contents of the array element
        depending on a condition.  Notice the use of the codeblock
        parameters:

        LOCAL aArray[6]
        AFILL(aArray,"old")
        AEVAL(aArray,;
        {|cValue,nIndex| IF(cValue == "old",;
                          aArray[nIndex] := "new",)})

 Files   Library is CLIPPER.LIB.

See Also: DBEVAL() EVAL() QOUT()

C5_ADIR

Posted on July 13, 2013 by vivaclipper

 ADIR()*
 Fill a series of arrays with directory information
------------------------------------------------------------------------------
 Syntax

     ADIR([<cFilespec>],
        [<aFilenames>],
        [<aSizes>],
        [<aDates>],
        [<aTimes>],
        [<aAttributes>]) --> nFiles

 Arguments

     <cFilespec> is the path specification of files to include in the
     scan of the DEFAULT directory.  It is a standard file specification that
     can include the wildcard characters * and ?, as well as a drive and path
     reference.  If omitted, the default specification is *.*.

     <aFilenames> is the array to fill with the file names matching
     <cFilespec>.  Each element contains the file name and extension as a
     character string in all uppercase letters.

     <aSizes> is the array to fill with the sizes of the corresponding
     files in the <aFilenames> array.  Each element is a numeric data type.

     <aDates> is the array to fill with the dates of the corresponding
     files in the <aFilenames> array.  Each element is a date data type.

     <aTimes> is the array to fill with the times of the corresponding
     files in the <aFilenames> array.  Each element filled contains a
     character string of the form: hh:mm:ss.

     <aAttributes> is the array to fill with attributes of the
     corresponding files in the <aFilenames> array.  Each element is a
     character string.  If <aAttributes> is specified, hidden, system, and
     directory files are included as well as normal files.  If <aAttributes>
     is not specified, only normal files are included.

 Returns

     ADIR() returns the number of files matching the directory skeleton
     described in <cFilespec>.

 Description

     ADIR() is an array function that performs two basic operations.  First,
     it returns the number of files matching the file specification.  Second,
     it fills a series of arrays with file names, sizes, dates, times, and
     attributes.

     ADIR() is a compatibility function and therefore not recommended.  It is
     superseded by the DIRECTORY() function which returns all file
     information in a multidimensional array.

 Notes

     .  Directories:  If you specify the <aAttributes> argument and
        <cFilespec> is *.*, directories will be included in <aFilenames>.  In
        the <aAttributes> array, directories are indicated with an attribute
        value of "D".  If ADIR() is executed within a subdirectory, the first
        two entries of the <aFilenames> array are "." and "..", the parent
        and current directory aliases.  The date and time of last update are
        reported for directories, but the size of a directory is always zero.

 Examples

     .  This example creates an array to hold the names of all .txt
        files in the current DEFAULT directory, then uses AEVAL() to list
        them to the console:

        LOCAL aFiles[ADIR("*.TXT")]
        ADIR("*.TXT", aFiles)
        AEVAL(aFiles, { |element| QOUT(element) })

 Files   Library is EXTEND.LIB.

See Also: ACHOICE() AEVAL() ASCAN() ASORT() DIRECTORY()

M	T	W	T	F	S	S
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	31

Viva Clipper !

Notes of a Clipper Language Student

Daily Archives: July 13, 2013

C5_ARRAY

C5_ALTD

C5_ALLTRIM

C5_ALIAS

C5_ALERT

C5_AINS

C5_AFILL

C5_AFIELDS

C5_AEVAL

C5_ADIR

Rate this:

Rate this:

Rate this:

Rate this:

Rate this:

Rate this:

Rate this:

Rate this:

Rate this:

Rate this: