Get

See Also: Function, Property, Set, WebGet, WebSet

Purpose

To get the value of a function or object property.

Note: For web applications, you will most likely use WebGet and WebSet instead of Get and Set. Please see those commands for more information.

Syntax

Get {method-name} [of {object-ID}] [{param1 … paramN}] To {receiving-variable}

Argument Explanation

The order of the parameters must match the list of parameters in the method's declaration. The parameters you pass can be either constants, variables or expressions, so long as they are of comparable type to the matching parameters in the method declaration.

What It Does

The Get command is used to get the value of an object's property or call a function method of an object. An object function may be invoked for a given object; however, commonly the destination object is omitted, and the object function operates on the current object, Self.

If the data type of the variable that receives the value variable does not match the return type of the function, the data is converted to the data type of variable. In DataFlex, arguments to functions are passed by value. Type conversion is also performed on the arguments, so that the function parameter requirements are satisfied. For example, if the second parameter of a function is an integer, and the function requires that it is a string, DataFlex will perform type conversion, so the function receives a string parameter.

Properties in DataFlex define two messages: one function Get_propname and one procedure Set_propname. Here is an example of the Get command accessing a property and invoking a function:

Class cTestClass is a cObject

    Procedure Construct_Object Integer Image

        Forward Send Construct_Object

        Property Integer piProperty 1

    End_Procedure  // Construct_Object

    Function Func1 String sParam1 Returns Integer

        Showln "In Func1 - String Param is: " sParam1

        Function_Return 2

    End_Function  // Func1

    Procedure Test

        Integer iValue

        Get Func1 "Hello World" To iValue

        Showln "Function Func1 returned: " iValue

        Get piProperty to iValue

        Showln "Property piProperty is: " iValue

    End_Procedure  // Test

End_Class

Struct Properties

Special consideration needs to be given for accessing data that is stored in class properties that are of struct type. The Get and Set commands that are used for accessing a property's data can only be used to get and set the entire struct. This works just like a struct variable assignment.

To read or write individual members of a struct property, it is necessary to get the property to a local struct variable of the same type. You would then manipulate the data of this local struct and write back the changes by setting the struct property once again.

Example…

Struct tNameAndAddress

    String sName

    String sAddress

End_Struct

Class cMyButton is a Button

    Procedure Construct_Object

        Forward Send Construct_Object

        // Declare a struct property

        Property tNameAndAddress pContact

    End_Procedure

    Procedure StoreName String sName

        tNameAndAddress contact    // create a local struct variable

        // get the struct property to the variable.

        Get pContact to contact

        // show the current name.

        Send Info_Box ("The current name is: " + contact.sName)

        // change the name.

        Move sName to contact.sName

        // Save the change back to the struct property.

        Set pContact to contact

    End_Procedure

 End_Class

Array Properties

Special consideration needs to be given for accessing data that is stored in array properties. The Get and Set commands that are used for accessing a property's data can only be used to get and set the entire array. This works just like an array variable assignment.

To read or write individual array property elements, it is necessary to get the property to a local array variable of the same type. You would then manipulate the data of this local array and write back the changes by setting the array property once again.

Example…

Class cMyButton is a Button

    Procedure Construct_Object

        Forward Send Construct_Object

        // Declare an array property

        Property string[] psNames

    End_Procedure

    Procedure StoreName String sNewName

        string[] sNames     // create a local array variable

        integer  iElementCount

        // get the array property to the variable.

        Get psNames to sNames

        // Add the new name.

        Move (SizeOfArray(sNames)) to iElementCount

        Move sNewName to sNames[iElementCount]

        // Save the change back to the array property.

        Set psNames to sNames

    End_Procedure

 End_Class

Item-Based Properties

The compiler must explicitly recognize that a message requires an index parameter. Special compiler commands are created to identify these messages. The indexed messages identified as current-item based, which means that current_item is used if the index parameter is omitted, are:

The indexed messages identified as Form based, which means that zero is used if the index parameter is omitted, are:

The difference between current-item based and form based messages are historical. Since we only recommend that you omit the index parameter on single item objects the current-item should always be zero. This means that both types of messages should be treated the same.

We advise that you always omit the item index parameters for objects that are single item objects (in which case current_item should be zero anyway). Examples of single item objects are dbForms, Forms, and ComboForms. For example, when in a dbForm the Value property should be accessed as follows:

Set Value of oMyDbForm to "form test value"

We advise that you always include the item index parameter in multi-item objects. Examples of multi item objects are Arrays, Grids, dbGrids and dbLists. For example, when in an array the Value property should be accessed as follows:

For iCount from 1 to 10

    Set Value iCount to "Array test value"

Loop

Every property has a known data type. If value is a variable of other than the type specified in the property, its value will be converted automatically to the required type.

Notes

• In older programs you will see the keyword item before the index value (e.g., set Value item 0 to "x"). The item keyword is optional. Its usage is no longer recommended.

• Some properties, such as Location and Size, return folded integer values, where two short integers (16 bits) are packed into a single 32-bit value. Use the Hi and Low functions to extract from the return value.

• If the data type of the variable that receives the value variable does not match the return type of the function, the data is converted to the data type of variable.

• The Get command can also be used to call global functions, however the preferred method for doing this is to use an expression. For more information see Calling Function Methods.