Activating Operations Using Handles

After obtaining the handle of an object, you can activate the object's exposed operations using the handle operator (->). The return value of an operation that has been activated using a handle is returned inline.

Use the following syntax:

Handle->Operation({Parameter 1{, ... ,Parameter n}})

For more information, see Access Operators.

Activating Operations

Some examples of invoking an operation on a handle:

  • vDetailForm->exec($collhandle("myEntityCollection"))

    The operation exec($collhandle("myEntityCollection")) is invoked on the handle vDetailForm

  • $vCollection$->getCurrent($vOccurrence$)

    The operation getCurrent($vOccurrence$) is invoked on the handle $vCollection$

  • $vOccurrence$->setName(accname.accdt)

    The operation setName(accname.accdt) is invoked on the handle $vOccurrence$

  • $collhandle("MyEntity")->clear()

    The clear() operation is invoked on the entity collection using the handle value returned by $collhandle("MyEntity").

Capturing Operation Return Values

When an operation is activated using a handle, the return value is returned inline, making it possible to capture an operation's return value. For example, in the following instruction the variable vReturn is used to capture the value returned by myOperation:

vReturn = myHandle->myOperation(vParam)

If the operation was successful, vReturn contains the return value, and $status contains whatever value it may have received during module execution. If it has not been explicitly set or changed by ProcScript in the same operation, $status will be 0.

If an error occurred in calling the operation (the operation could not be found or an incorrect parameter was supplied), vReturn contains the error code, but $status is not changed.

If you don't redirect the handle's return value, it is placed in $status.

Caution: Although you can explicitly assign the operation’s result to $status, this is not recommended because it resets the value of $procerror to 0.

Return Values

The following code examples demonstrate how return values and $status values are treated when activating operations using handles. In these examples, the value of $status is explicitly set to -99 prior to each activation:

  1. The operation oper1 returns a value of 1.
    operation oper1
   return(1)
end
    • Activate oper1, but do not capture the return value:
      $status = -99
$instancehandle->oper1()

; Result: $status = 1
; The return value is placed in $status
    • Activate oper1 and assign return value to vReturn:
      $status = -99
vReturn = $instancehandle->oper1()

; Result: vReturn = 1, $status = 0
; The return value is placed in vReturn and $status is reset to indicate success
  2. The operation oper2 does not exist.
    • Activate oper2, but do not capture the return value:
      $status = -99
$instancehandle->oper2()

; Result: $status = -1
; An error is returned, which is placed in $status, overriding the value -99
    • Activate oper2, and assign the return value to vReturn:
      $status = -99
vReturn = $instancehandle->oper2()

; Result: vReturn = -1, $status = -99
; The error is captured in vReturn and the value of $status remains unchanged

Value of $status

When $status is set by a ProcScript command in the operation, or is explicitly set to a value in the operation, it's value is not changed when the operation returns.

  1. $status explicitly set in the operation.

    The operation oper3 returns a value of 1, but also sets $status to 3:

    operation oper3
   $status = 3
   return(1)
end
    • Activate oper3, and assign the return value to vReturn:
      $status = -99
vReturn = $instancehandle->oper3()

; Result: vReturn = 1, $status = 3
; The operation explicitly set $status, so the value of $status remains unchanged
  2. $status set by ProcScript command.

    The operation oper4 tries to retrieve data that does not exist:

    operation oper4
   retrieve/e "DoesNotExist"
   return(1)
end
    • Activate oper4, and assign the return value to vReturn:
      $status = -99
vReturn = $instancehandle->oper4()

; Result: vReturn = 1, $status = -1
; The operation retrieve/e command failed, setting $status to -1. This value is not reset by the operation.

Related Topics