(RPG) LRNG_Using vs. LRNG_UsingEX and...

[JohnJoiner]

I'm currently evaluating LongRange and have been pouring through all the example programs and documentation I can find.

Many of the example programs call procedure LRNG_UsingEx, but I don't see any documentation on this procedure.

How does LRNG_UsingEx differ from LRNG_Using? Is this documented anywhere?

There are other things that I am coming across in the example programs that don't appear to be documented, such as:
'/SharedStates' - how does this differ from using the 'SavedSTATE' parameter?
'/System' - as in '/System.menus', '/System.GEO.updateFrequency', etc. - I understand from the context the use of '/System' in these instances, but what other properties of '/System' are available?

I've got both the 'Programming LongRange With RPG' and 'LongRange RPG Tutorials' guides. Is there any other documentation I'm lacking?

TIA

JJ

[tsupartono]

Hi John,
Yes you are right, these items are missing from the documentation.
I will get them updated ASAP - will post an announcement here when it's done.

Just to quickly answer your question about the LRNG_UsingEx.
The LRNG_UsingEx procedure has 2 parameters:
1. EmptyStackIfFullyQualified (Boolean)
2. Context (String)

The LRNG_UsingEx (and LRNG_Using) works by pushing contexts to a stack. The topmost in the stack is the current context to use when you are referring to properties using (say) LRNG_AssignStrToProp. The context will be popped out when you call LRNG_EndUsing. This implies that every call to LRNG_Using must have a matching LRNG_EndUsing, otherwise you will just keep adding context to the stack - and at one point your program will crash as LongRange limits the number of contexts you can push using LRNG_Using.

For convenience, the first parameter (EmptyStackIfFullyQualified) indicates whether the context stack should automatically be emptied when you push a 'fully-qualified context'.
A fully-qualified context is one that starts with the forward-slash character ('/'). An example of fully-qualified context is '/Form.Fields.NAMEINPUTBOX'.
If EmptyStackIfFullyQualified is set to *ON, the stack will automatically be emptied when you push a fully-qualified context such as '/Form.Fields.NAMEINPUTBOX''. This allows you to forgo the use of LRNG_EndUsing, and you don't have to have a matching LRNG_EndUsing for every LRNG_Using.
Since this is generally desirable under most situations (ie to have default value of *ON for EmptyStackIfFullyQualified parameter), we have a shortcut for this, which is
just the plain LRNG_Using. So LRNG_Using is just a shortcut to LRNG_UsingEx(*ON : properties).

There are times when you absolutely need to maintain the stack, even you you are pushing a fully-qualified context onto the stack.
This is generally when you are creating a utility procedure that can be called from anywhere. It's important to set EmptyStackIfFullyQualified to *OFF in these situations so you don't mess up the context stack, as you can't make an assumption as to whether the caller of your function still needs to the contexts in the stack.
For example, if you have a procedure called 'DisplayErrorPopover' that you can call from any of your programs. Inside this function, you want to set the context to '/Form'.
So you would need to do:

Code: Select all

// EmptyStackIfFullyQualified must be set to *OFF, so that we don't empty the context stack, 
// as we don't know if the caller of this function will depend on the stack or not.
LRNG_UsingEx(*OFF : '/Form');
...
LRNG_EndUsing();

[JohnJoiner]

Thanks for the reply, and I now understand the difference between LRNG_Using and LRNG_UsingEx. Important distinction.