2E - Development Standards (AD & Contexts)

Continuing the series of development standards for 2E (Synon). Today's topic is Action diagramming and contexts.

Once again in no particular order.

Beware of a negative list. Do not use a 'negative' LST on a STS field. E.g. If STS field has Val's A,B,C,D then do not create a LST 'Not B' which contains A,C,D. If a new VAL is added to the STS field then the negative LST immediately becomes out of date and also needs amending.

Note: As with Access Paths and File changes, status conditions should be considered a DBA level change and appropriate care and attention taken.

When not to call the *RTVCND. Do not use *RTVCND to get a condition name if the STS field is blank. This is not required as the result should be blank on the screen. Can use a derived field, although these should be discouraged if you are considering thin screen clients and business services for easy migration.

Do not use a *RTVCND in programs that may be converted to other platforms. Feature not supported on other platforms. Not sure on the impact the ADCMS though.

Know how to quit. Never use *QUIT unless you understand explicitly where you are jumping to. Only a few recognised action diagram user points should ever contain a *QUIT. Note, you can quit out of a user defined subroutine. This is a useful technique if you wish to cut down on conditional code.

Pro's
Allows you to strategically exit a subroutine for efficiency i.e. RTVOBJ.
Allows you to suppress PRTOBJ.
Allows you to exit a user defined subroutine. Especially useful for functions with lots of validation logic.

Con's
If used in wrong subroutine can seriously impact the flow of a function.
Care should be taken if code is being copied into other subroutine as the desired affect of the *QUIT may not be the same.
Not directly supported in CA Plex if you are considering a migration.

Do not use *Exit Program in internal functions.

When trying to determine the success or otherwise of a called function you should always check PGM.*Return Code.

Be extra wary of arithmatic operations that might overflow. In particular DO NOT use any tricks to truncate numeric data such as multiplying a 7-digit date by 1 into a 2 byte result field in order to extract the day number. This causes a numeric overflow and may give rise to invalid data. This is especially true (Pre 8.1) for RPGIV generate programs that will also abend with a runtime error that is not a good look to the end user.

Keeping it all in Context.

The following section is about the usage of contexts in 2e.

NLL Context.

NLL context can be used to discard any unwanted output parameters on both internal and external functions.

It will be used predominately on GETs to avoid having to define numerous RTVOBJ functions, each with different parameters. But be aware that a NLL context parameter still creates a usage for that field within the model. Thus you may create lots of spurious field usages. In earlier versions of 2e pre 8.1 the NLL also created NLL fields in the source. This has been resolved and NLL fields are no longer generated.

Pro’s
Cleaner looking action diagram.
In 8.1+ the NLL fields are no longer generated so program are smaller
Easier and quick to default whilst action diagramming.

Con’s
Dumper fields are easier to determine usage for impact analysis as NLL fields are still shown as used.

WRK/LCL context.

Try to use LCL context in preference to WRK context. Unlike WRK context the LCL context is only scoped to the function it's used in. WRK context being scoped to the whole external that the function is generated into.

WRK context should never be used to pass data between function calls, bypassing any parameter declaration.

Be careful about introducing LCL context into existing functions that use WRK context. Mixing the two contexts could be dangerous.

Be EXTRA careful about replacing WRK context. You need to follow through all usages of internal functions that use it to ensure its integrity.

Be aware that LCL context fields are not the same as NEITHER parameters. NEITHER parameters are automatically initialised upon each entry to the function. LCL context fields are only initialised upon program entry and can be used to carry over data between call invocations of the internal function. That is, LCL context can be used to cache function level data.

When reading/writing or processing lots of fields from a given record or model file then PAR context arising from NEITHER parameter access path definitions are preferable to LCL context. PAR context requires a specific parameter declaration that can be queried, and can participate in action diagramming logical parameter defaulting mechanism.

Do not use WRK or LCL context as target of a *MOVE ALL. It doesn't work. You can enter these in the action diagram and 2E will generate a comment but no code will be created.

JOB Context

Care should be taken with the use of the JOB *System Timestamp field. It is only refreshed if moved into a field. Therefore a subsequent query of the JOB context of the field will only be of the last set value. This can equate to Zero.

CON/CND Context

Best Practice - Always use conditions (CND) rather than constants (CON) for non-trivial values. That is, values other than blank or zero. This allows the exact usage of special values to be obtained from the model, and allows translation of condition names. Exceptions are simple values – see below.

CON *BLANK and CON *ZERO are fine for input parameters.

CON is also acceptable for trivial arithmetic operations such as incrementing by 1, sign reversal by multiplying by -1, percentages by dividing by 100, special characters used in *CONCAT such as periods or commas, character position numbers used in *SUBST. National language impact should be considered. i.e. When to use a comma or not. This is especially true for German as they use a comma as the decimal character.

CON.xxxxxxxxxx can also be used to initialise descriptions and text fields in one off initialisation programs.

Note the CON context is not supported in CA Plex and must be converted before any migration can occur.

CON values do no appear in impact analysis.

CON values cannot be exposed for use via the NLS product.

If you have any questions or enquiries about anything published on this blog, please do not hesitate to contact me. I welcome all comments and opinions.

Thanks for reading.
Lee.