FWD » Core Development » User Interface

This comment is reserved for the emerging documentation describing the logic behind OE focus management.

It will be edited later.

Question to gurus:

A Progress trigger can return a value. If the NO-APPLY is returned, the further event processing is aborted.

The question: are values other than the NO-APPLY ever used by Progress?

First, I want to record some of our older documentation:

https://proj.goldencode.com/artifacts/javadoc/latest/api/com/goldencode/p2j/ui/chui/package-summary.html#Focus_Management
https://proj.goldencode.com/artifacts/javadoc/latest/api/com/goldencode/p2j/convert/package-summary.html#Transaction_Processing_and_Block

The first reference is not 100% complete. It especially was only looked at in ChUI and the influence of mouse processing, drag and drop, multiple windows and child frames are not considered.

The second reference is based on 9.x and thus is not up to date with the additional block processing of OO, structured error handling or the more recent transaction processing related changes in 10.x and 11.x. It also doesn't consider anything related to appserver/REST/SOAP agent session processing, nor anything about persistent/super procedures.

Even with these caveats, these are useful resources.

The question: are values other than the NO-APPLY ever used by Progress?

Limiting this question to triggers, the answer is yes and no.

This may help (it is the javadoc from BlockManager.returnWorker()):

Return from the nearest enclosing top-level block. This will process differently based on the type of the top-level block (internal/external procedures, triggers or user-defined functions), the type of return processing that is requested (see BlockManager.ReturnType) and the presence or absence of a value to return.

The following behavior is provided:

 Codes   Meaning                
 ------  -----------------------------------------------------
 C       Invoke LogicalTerminal.consume()
 E       Invoke TransactionManager.triggerErrorInCaller()
 V       Invoke ControlFlowOps.setReturnValue(val)
 N       Invoke ControlFlowOps.setReturnValue("")
 F       Invoke setFuncReturn(val)
 U       Invoke setFuncReturn(null) (set return value as unknown)
 I       Invalid (compile error in Progress)

  Return    Return    Internal  External  Trigger  Function
  Value      Type       Proc      Proc
 --------  ---------  --------  --------  -------  --------
 null      NORMAL     N         N         N        U
 non-null  NORMAL     V         V         V        F
 null      CONSUME    N         N         NC       U
 non-null  CONSUME    V         V         VC       F
 null      ERROR      NE        NE        I        U
 non-null  ERROR      VE        VE        I        U

In all cases, a ReturnUnwindException will be thrown and this will cause the stack to unwind to the nearest enclosing top-level block. That block will then handle the return in a block specific manner. For example, in a user-defined function, the given value or by default the unknown value will be returned to the caller. Procedures and triggers have void return values.

The part about the ReturnUnwindException is no longer 100% correct but otherwise the details are quite accurate and match the 4GL behavior. The way to interpret (for triggers) is as follows:

• A RETURN. ("NORMAL" return without a value) in a trigger sets the RETURN-VALUE to "" and then returns, allowing default processing to occur.
• A RETURN <expression>. ("NORMAL" return with a value) in a trigger sets the RETURN-VALUE to the evaluated value of the <expression> and then returns, allowing default processing to occur.
• A RETURN NO-APPLY. ("CONSUME" return without a value) in a trigger sets the RETURN-VALUE to "" and then returns, suppressing the default processing.
• A RETURN NO-APPLY <expression>. ("CONSUME" return with a value) in a trigger sets the RETURN-VALUE to the evaluated value of the <expression> and then returns, suppressing the default processing.
• A RETURN ERROR. ("ERROR" return without a value) in a trigger causes a compilation error.
• A RETURN ERROR <expression>. ("ERROR" return with a value) in a trigger causes a compilation error.

So these other constructions can affect the behavior but in no case does the value actually get returned as in a function call. In the "NORMAL" return with a value and "CONSUME" return with a value, the value can only be found in RETURN-VALUE. Relying upon this is tricky at best, because of the very idea of a trigger. It is happening in response to an event occurring, so how do you check the RETURN-VALUE just after a trigger executes BUT BEFORE any other procedure or trigger processing overwrites the RETURN-VALUE. Since there is just one global RETURN-VALUE, it is a pretty poor idea to use it from a trigger, in my opinion.

I hope this helps.

Marian: If I've gotten anything wrong here, please do let us know.

Thanks, Greg.

One question:

The following two RETURN <expression>. statements look the same:

• A RETURN <expression>. ("NORMAL" return with a value) in a trigger sets the RETURN-VALUE to the evaluated value of the <expression> and then returns, allowing default processing to occur.
• A RETURN <expression>. ("CONSUME" return with a value) in a trigger sets the RETURN-VALUE to the evaluated value of the <expression> and then returns, suppressing the default processing.

How can the "CONSUME" return with a value be expressed in 4gl?

I edited it. It should have been RETURN NO-APPLY <expression>..