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

di_GET()
Replacement for @..GET Function to output to multiple device types
------------------------------------------------------------------------------
Syntax

    di_GET(<nTop>, <nLeft>, <cVarName>, [<cPict>], [<cColor>],
             [<cCaption>], [<cMessage>], [<cWhen>], [<cRange>],
             [<cValid>], [<cSend>], [<cGUISend>]) --> nSuccessList

Arguments

    <nTop> and <nLeft> specify the row and column coordinates for
    the operation.  <nTop> must be between 0 and MAXROW(), and <nLeft>
    between 0 and MAXROW() for screen output.  For HTML output, values must
    simply be zero or greater.  Output fails for those devices for which
    values are out of range (devices with sucssessful output are listed in
    the return value).

    <cVarName> contains the literal name of the variable associated
    with the GET.  As of di_Library version 0.1, &cVarName must be a PUBLIC
    or PRIVATE variable.  Usually, <cVarName> will be a character
    expression in quotes.  If a character variable is used as an argument,
    the GET will be on the NAME contained in the variable, not for the
    variable itself.  The named variable may be of any storage class
    (if the storage class is ambiguous, FIELD is assumed).  If the named
    variable is an array value, you must supply one or more subscripts.
    The current value of the named variable is displayed at the GET
    coordinates.  The value must be character, date, numeric, or logical
    type.  Array, NIL, code block, and null string values are not
    permitted.

    <cPict> contains the display format and editing rules for the GET.

    <cColor> contains the color settings for the current Get object.
    <cColor> is a character expression containing one or more color
    settings.  You must specify literal color settings enclosed in quote
    marks.

    If you specify two color settings, the first determines the unselected
    color (the display color for the Get object) and the second determines
    the selected color (the color when the Get object has focus).  If you
    only specify one color, it determines both the unselected and selected
    colors for the Get object.

    <cCaption> is currently only specified for compatibility reasons.
    di_Libarary version 0.1 does not implement the CAPTION option.

    <cMessage> contains a character string that is displayed on the Get
    system's status bar line when the GET has input focus.  Typically, it
    describes the anticipated contents or user response of the GET.  Refer
    to the SET MESSAGE command for details pertaining to the Get system's
    status bar.

    <cWhen> contains an expression that must be satisfied before the
    cursor can enter the GET during a READ.

    <cRange> contains a character expression specifying a range of
    allowable values for input to the GET.  During a READ command, if you
    enter a new GET value that does not fall within the specified range,
    the cursor cannot leave the GET.  Specifying <cRange> as "n,m" is
    identical to specifying <cValid> as "cVarName<=m .AND. cVarName>=n"

    <cValid> contains an expression that must be satisfied before the
    cursor can leave the GET during a READ.

    <cSend> is currently only specified for compatibility reasons.
    di_Libarary version 0.1 does not implement the CAPTION option.

    <cGUISend> is currently only specified for compatibility reasons.
    di_Libarary version 0.1 does not implement the CAPTION option.

Returns

    nSuccessList is the sum of the devices handles successfully written
    to.  Only devices currently set to output are addressed; therefore,
    nSuccessList is always less than or equal to the current return value
    from di_setOutput().

Description

    Attemps to create a GET on all devices whose output is currently
    enabled.  The validation capabilities of a GET object depend upon the
    device(s) receiving output.  HTML devices do not implement PICTURE,
    COLOR, MESSAGE, WHEN, RANGE, VALID.  CAPTION, SEND and GUISEND are not
    currently supported for any device.  Returns a value indicating the
    list of devices which successfully receive output.

Examples

    // First di_GET()
    di_GET(1,1, "myVar", "@!", "W/N", , , , , "myVar % 2 = 0", , )

    // Second di_GET()
    cName  := "myVar"
    cPict  := "@!"
    cColor := "W/N"
    cValid := "myVar % 2 = 0"
    di_GET(1,1, cName, cPict, cColor, , , , , cValid, , )

    Note: each argument, except <nTop> and <nLeft>, is passed as a
    character expression!  Even if <myVar> is not of a character type, a
    character expression resolving to the string "myVar" must by used to
    implement a GET to <myVar>.  The first and second di_GET() examples
    perform identical actions

    See the examples listed under the Examples menu heading