Using return values

You can use return values of functions and events.

Functions

All built-in PowerScript functions return a value. You can use the return value or ignore it. User-defined functions and external functions might or might not return a value.

To use a return value, assign it to a variable of the appropriate datatype or call the function wherever you can use a value of that datatype.

Posting a function

If you post a function, you cannot use its return value.

Examples

The built-in Asc function takes a string as an argument and returns the Unicode code point value of the string's first character:

string S1 = "Carton"
long Test
Test=32+Asc(S1)   // Test now contains the value 99
                 // (the code point value of "C" is 67).

The SelectRow function expects a row number as the first argument. The return value of the GetRow function supplies the row number:

dw_1.SelectRow(dw_1.GetRow(), true)

To ignore a return value, call the function as a single statement:

Beep(4)       // This returns a value, but it is 
               // rarely needed.

Events

Most system events return a value. The return value is a long numeric codes have specific meanings for each event. You specify the event's return code with a RETURN statement in the event script.

When the event is triggered by user actions or system messages, the value is returned to the system, not to a script you write.

When you trigger a system or user-defined event, the return value is returned to your script and you can use the value as appropriate. If you post an event, you cannot use its return value.

Using cascaded calling and return values

PowerBuilder dot notation allows you to chain together several object function or event calls. The return value of the function or event becomes the object for the following call.

This syntax shows the relationship between the return values of three cascaded function calls:

func1returnsobject( ).func2returnsobject( ).func3returnsanything( )

Disadvantage of cascaded calls

When you call several functions in a cascade, you cannot check their return values and make sure they succeeded. If you want to check return values (and checking is always a good idea), call each function separately and assign the return values to variables. Then you can use the verified variables in dot notation before the final function name.

Dynamic calls

If you use the DYNAMIC keyword in a chain of cascaded calls, it carries over to all function calls that follow.

In this example, both func1 and func2 are called dynamically:

object1.DYNAMIC func1().func2()

The compiler reports an error if you use DYNAMIC more than once in a cascaded call. This example would cause an error:

object1.DYNAMIC func1().DYNAMIC func2() // error

Posted functions and events

Posted functions and events do not return a value to the calling scripts. Therefore, you can only use POST for the last function or event in a cascaded call. Calls before the last must return a valid object that can be used by the following call.

System events

System events can only be last in a cascaded list of calls, because their return value is a long (or they have no return value). They do not return an object that can be used by the next call.

An event you have defined can have a return value whose datatype is an object. You can include such events in a cascaded call.