Sunday, August 31, 2008

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.

Thursday, August 28, 2008

2E - Development Standards (Parameters)

This is Part 4 in a series of articles.

Once again I have decided to focus on development standards and best practices for 2E (Synon) development. You can search this blog for the other posts around performance, defensive programming and general coding considerations.

Today's topic is parameters and how they are used and defined in 2E.

In no particular order my tips and techniques in this are as follows:-

Use Files, Accessss Paths or *Arrays as pick lists. In general try to use ACP (Access Path) RCD (Record) structures as picking lists for parameter definition rather than individual *FIELD entries. This makes it easier to identify the impact arising from future database changes.

Never use the last parameter line. If you find yourself using the last parameter line it is time that you consider re-architecting the functions parameter interface using an array structure or access path picking lists. It is quite selfish to use that last line for when another developer needs to maintain the function. Also if creating a function from scratch and you are using 6 or 7 parameter lines then it would be prudent to consider a parameter array.

Choosing the correct passing method. In general RCD is always preferable to Field (FLD) for normal parameter definition since this has a performance benefit. Only one actual parameter address is passed rather than many. This is the preferred method for program to program calls.

However, if an external function is likely to be called from a CL program, menu, message, command line then it is easier to use FLD. This is because passing values i.e. numeric fields via a command line or CL can get complicated. This is especially true for numeric and date fields.

Pro’s
RCD uses less PAG’s and therefore system memory.
Easier to determine impact of file changes using in-built analysis tools.

Con's
Harder to call programs directly when required.
Complicated CL programming for parameter passing.
Incorrectly declares NEITHERs as parameters and can cause confusion.

Understand the impact of a neither parameter and the generated code. If an ACP definition only contains NEITHER parameters then always use FLD rather than RCD. This ensures that the parameter definitions are not implemented as actual parameters and calling functions do not need to be generated as the definition changes.

This is because Neither Parameters passed as RCD will generate a parameter entry in the RPG. Therefore it is strongly recommended that neither parameters are always passed as FLD.

No harm in using *Arrays to define your parameters. If a suitable ACP is not available, or if more than 9 parameter block lines are needed, than an array may be used for parameter definition. Typically an array is a good choice for bringing together various NEITHER MAP fields on a device design.

Never use *NONE as the ACP definition. It is not possible to track the usage of *NONE for any model file. This has been resolved and now shows *FUNPAR usages in 8.1 and above but I have included it as you may be on an earlier version of the tool.

Tip - MAP = Device Design Only. Only use MAP where it is being used specifically to map a field to a screen design. In all other cases turn the default MAP off. This helps make it clearer to understand where MAP is actually being used. It serves no purpose to have MAP on most other functions other than to confuse a beginner.

Trick - Getting at the CTL context for a SLTRCD. Use neither MAP parameters for placing values on the CTL format of a Select Record function. It is not possible to influence these CTL control fields via the action diagram as there is no Control User point. Instead set to Neither MAP and populate during the initialisation.

You can also use MAP when changing a primary key via a CHGOBJ.

Be explicit with a parameters type and role and also ensure that the parameter field name is meaningful.

Best Practice - Never use BOTH parameters for convenience i.e. Totalling inside a RTVOBJ. I have witnessed far too many functions which have a BOTH parameter for a total which then gets initialised to Zero in the initialise user point. Any developer choosing to use this function will immediately believe that they need to supply a valid value.

This is bad practice. The parameter interface is more important than a developers extra effort inside the function.

Best Practice - Parms not WRK Context. Parameters should always be passed if they are going to be used between functions. DO NOT rely on the fact that WRK fields are global.

Using sequencing to indicate parameter importance. Neither parameters can be sequenced as 999 on the EDIT FUNCTION PARAMETERS screen. This helps identify the actual parameters. If you require Neither and normal parameters i.e. Input, Output or Both then declare the file/access path twice and placing the neither parameters on the second declaration and remembering still to sequence it 999.

The only exception here is you are using duplicate parameters. There is a 2E limitation that these must be sequenced 1 to 9 only.

Thanks for reading.
Lee.

Monday, August 25, 2008

2E - Development Standards (General Coding Considerations)

My regular readers will be aware that I have begun adding articles related to 2E (Synon) development. See links on Defensive programming and Programming for performance.

Future chapters planned for the coming weeks include:-

Parameters
Action Diagramming & Action Diagram Contexts
Messages and Message Handling
Subroutines
Wrapping, Relations and Function Options
DBA Best Practices
Function Type Best Practices
Gotcha's Guide
Suggested Naming Conventions
+ Much more.

When I have finally worked out how to use the Wiki. I will consolidated all my 2e postings and update.

I welcome all comments regarding these standards and guides and will endeavour to update the blog postings with your additional feedback and comments. At this stage I would also like to publicly thank Darryl Millington, Ray Weekes, Kim Motteram, Rene Belien, Rudy Moser and Mark Schroder for providing materials for review. As well as my now ex colleagues Kay, Kate, Nilesh and Sumit for their input and validation.

Today's theme is general programming considerations.

Functions should be as readable as possible. Try to fit the whole action diagram onto a single page by hiding case blocks and/or using sequences. Give these constructs meaningful names. Code should be easy to follow, where it is not intuitive add sufficient comments.

Always group and tidy up your code. Add comments where functionality is not obvious and always add comments for actions, *COMPUTE built in function, iterations, case blocks and sequence blocks.

Be careful of adding sequence blocks for tidying code. Ensure that there are no usages of the *QUIT built in function that can be negated by nesting into a sequence block. Remember the *QUIT only exists the sequence it is in.

Remove commented out code. Commented out code should only be used to temporarily change code and for assisting with debugging. Once changes are considered permanent all commented out code should be removed. This helps with both action diagram readability and impact analysis.

Keep ‘parameter passing’ to a minimum. Functions are more reusable if they do any required retrieving of database values internally. However, consider performance issues of this for large applications or performance critical programs where the opposite will be more practical.

Define all User Programs to the model. (CL, COBOL, RPG or RPG ILE). These should be declared in the model. If there is no obvious file to associate them with, add them to a generic scoping file. There must be a special case to write in native COBOL, RPG or RPGLE and this should be given careful consideration and were practical discuss with your peers.

Modularise. When copying large chunks of code from one function to another, put the code into an EXCINTFUN or EXCEXTFUN function. This avoids ending up with the same code in lots of programs.

Centralise common business calculations. Common calculations such as GST, Interest, withholding tax (finance examples) should be defined in one function and reused.

Ensure correct setting of critical function options.

Close Down Program Flag. Set to 'N' if program is called repeatedly in a loop or a processing function like a RTVOBJ. This means that any files that are open will remain open, thus improving the performance of the function dramatically. Set to 'Y' otherwise if the program is typicially a top level programs.

Reclaim Resource flag. Set to 'Y' on W/W functions, e.g. W/W Clients or other top level, W/W Funding Account. Otherwise lots of files stay open all day and will eventually consume more system resources than the system requires.

Best Practice - Updating balances or other value fields. Never use a RTVOBJ to get values from a record on the file, calculate the new values and then do a CHGOBJ with new values. You must pass the values to be added as separate fields into the CHGOBJ and then add them on to the DB1.fields inside the CHGOBJ before update. This is to take care of the automatic AS400 locking functionality on the update index as well as ensuring that you are incrementing the latest value available.

Use appropriately named fields. When using a field as a work field or screen/report field (i.e. A user field), create one with a meaningful name if one does not exist already. Using a field just because it has the correct domain attributes can be very confusing for people maintaining the function after you. Avoid generic named fields like Count 1 or Text (25).

Consider correct use of action diagram contructs. The use of *OTHERWISE blocks for grouping code is slightly misleading. Always create a sequence block. Note with RPG4 the limits for the number of subroutines is unlikely to be reached. The action diagram colouring of Pink, Green, White and Blue has inherent meaning and this fundamental principle in your action diagramming should remain. Put simply, Pink equates to a Decision, Green an Action, White as a collection of statements and Blue as an iteration.

The *OTHERWISE is still valid if deliberately trying to force a compilation error.

Avoid use of Derive Fields in screen designs. Not all of the CALC function points work correctly and this also hinders your ability to externalise code for thin client development.

Thanks for reading.
Lee.

Sunday, August 17, 2008

Version 1.0

I thought that today I would blog a little about the concept of version 1.0.

There is a saying in IT that you never buy version 1.0 of a product. Obviously this can't be true as no new products would sell or make market penetration. Also, there must be those out there who enjoy the concept of working with an early version of a new tool or perhaps even a alpha or beta.

I guess these people can be summarised as conservative at one end of the scale or riding on the crest of a technology wave (rogue developer?, entrepreneur?) and the opposite end. They are clearly hoping to find the next super skill or application that they can become expert in, become recognised as an early adopter and advocate of the technology. Along with the kudos and recognition also comes the higher rates available.......Money, Money, Money..... "Its a rich man's world......". Guess who saw Mamma Mia the movie recently.

It was brought to my attention recently that an editor for a new game called spore is available on the Internet. The editor allows you the player to create your game characters.

Nothing too special at this stage I hear you say.

You are quite right but considering that the actual game is not currently available. At the time of writing it is 'gold' which means it is nearing release. I understand that millions of characters have now been created which is a pretty realistic barometer of the potential success of the game when it is finally released.

It is this model of releasing something early and benchmarking the idea that has probably allowed the developers to consider adding budget as required. How many people spend years building a product or website for that matter and then struggle to get sales or number of breakeven users to make the project viable.

Have we just witnessed version 0.0 as the new baseline and also a shift in mindset to a internet full of early adopters. Has the balance changed?

I will certainly think differently about the version 1.0 debates in future. After all, how do you get the balance between enough information to generate interest in your product or service but not too much so as to give away your plans and secrets to your competitors.

I will watch this unfold with a great deal of personal interest as I begin to build my online businesses and portals that I have been promising the world for so long.

Thanks for reading.
Lee.

Thursday, August 7, 2008

Is honesty always the best policy?

At various times in my life I have had this dilemma and I am sure many of you reading this have too.

I have always believed that honesty is the best policy.

Why?

This was drummed into me as a child. You would all remember being younger and hearing one of your parents or elders in your family/whanau say, “Just tell the truth, you won’t get into trouble as long as you tell me what happened.”, “Nobody likes liars.”, “You must be honest otherwise the truth will come out one day and come back and bite you on the bottom.”.

In various articles in this blog I have made reference to my experiences in general and I have been 100% honest in delivering balanced articles. IMHO.

Just recently I found myself in a situation where I was beginning to doubt my values/beliefs in this area. This was quite upsetting and worrying after 38 years of preaching and living by the aforementioned ideals.

So here are a few examples of where we all probably choose to ignore this policy.

Consider your answers to these questions.

“Honey, does my bum look big in this dress?”
“Who farted?”
“Do you love me?”


After looking at a baby picture “Isn’t he/she a stunner?”

Or, have you ever heard yourself saying that “The cheque is in the post” knowing full well that the cheque hasn’t even been written, let alone cashable.
Actually I have thought of a few extra ones but I will leave those to your imagination…………

So back to that dilemma. I truthfully explained why I was resigning from the company that I worked for at the time. I explained the major reason quite clearly and to be fair there were a few more including my desire for a fresh challenge so I could rediscover that "Woo factor!".

But.
The truth however, backfired I guess. Why.....
I was ignored for the remainder of my notice period and I struggled to provide the business with a true handover that it deserved. I guess as with all leavers my name will be mentioned for the things that go wrong. That is until the next person leaves. Actually i found out today that it was mud for some implementation tha I was working on. Despite my willingness to ensure it was completed.........

In summary, I believe that on this occasion it was because the truth hurts and sometimes you find yourself trying to be open and honest but if the listener doesn’t like it, they don't hear it.
I guess this has taught me that there is no judging reactions.

So I guess it all depends on the context that the honesty was received.

In my case, I believe on reflection that the combination of honesty (on my part), truth hurts (receivers reaction), arrogance and politics (receivers modus operandi and expertise), I may have chosen the wrong option, or did I?
I doubt this situation will happen again, but if I find myself in this situation in the next 25 years of my working life. I will then have a real dilemma.

Do I stick to the values that I was brought up with?
or,
  • stoop to the lowest common denominator and play dead like so many others do and stagnate in their jobs.
  • Add/have no opinion or worth to an organisation.
  • Destroy that drive and energy within me.


I don’t know the answer to this question at this stage but it will either be:-

I’ll just say nothing, stay patient and look forward to the time when karma resolves my issue for me.

Or.

Tell it as it is and hope for a more professional response and keep one of my core personal life values in place.

What would you choose? I'm leaning to the later.

Thanks for reading.
Lee.