2e Development Standards - (Composite Functions)

Todays topic is composite functions.

I have said before that there are many ways to skin a cat and with development regardless of tools and languages used, it is no different.

To date I have concentrated on the generic principles of development and also on the CA 2E tool from Computer Associates. I have put quite a few posts in place around 2E with many many more to go. To be honest I am less than 20% through what I intend to post from the technical perspective and I have barely touched the Plex product. Still good things come to those who wait.

http://www.dictionary.com/ has the definition of 'composite' as "made up of disparate or separate parts or elements". In 2E terms it means the linking of two or more functions to serve a business purpose. For example to clear a file using 2e function types you may either call a EXCUSRPGM and use the operating system or you may chose to use a RTVOBJ with no restrictor/positioner keys and then call a DLTOBJ for each record in the file. You could also call a SQL routine, embed the OS400 command in a message etc etc etc. You get my point. The composite in this example is the RTVOBJ/DLTOBJ combination.

There are other composite types that are more often encountered. Especially around creating or changing records in a database file (table for the SQLites amongst you).

I have created functions named CRT/CHG or CHG/CRT to solve a common problem of what do do if the record does or does not already exist in the database.

This lead me to consider is there is a preferred default method and are there any variations. Once again a big thanks to Ray for his contributions here.

CHG/CRT v CRT/CHG

There are times when if a CRTOBJ fails due to the record already being in existence or a CHGOBJ fails because the record does not exist. To solve these issues we generally create combination functions named either CRT/CHG or CHG/CRT. Or if you follow my recommended standards and if these are default functions then they would be named *CRT/CHG or *CHG/CRT.

In general you should select the one that is most likely to succeed, so depending on your knowledge of the environment and the data being processed, if the record is likely to not be there then you need to use the CRT/CHG combo.

There are some performance considerations over and above the availability or otherwise of the underlying record.

A CHGOBJ that contains a CRTOBJ if a record does not exist is inefficient as it generates the following code. This is particularly true for SQL generation.

Pseudo SQL Code

DECLARE CURSOR FOR UPDATE
FETCH
UPDATE if record found
INSERT if no record found
CLOSE CURSOR

Pseudo RPG Code

CHAIN
UPDATE if record found
SETLL & INSERT if no record found

An alternative coding style with a CRTOBJ calling a CHGOBJ if record already exists will generate the following code. The CHGOBJ must be an 'update style' that does not use a cursor.

Pseudo SQL Code

SELECT by key
INSERT if record not found
UPDATE if record exists

Pseudo RPG Code

SETLL
WRITE if record not found
CHAIN & UPDATE if record exists

A CHGOBJ with a little bit of grunt.

To create an 'Update style' CHGOBJ:-

For performance reasons we need to omit the prior SELECT generated for SQL CHGOBJs. This is mainly for CHGOBJs called repeatedly in batch type processing. But it can only be done if there is no requirement to read existing DB1 context fields. To do an immediate update we need to create a special version of a CHGOBJ called an UPDATE function. This will have following characteristics:-

1 - Ensure that there is no coding inside the CHGOBJ. Commonly we must transfer the timestamp coding from inside the CHGOBJ to input parameters and setting the timestamp fields directly on the CHGOBJ call.

2 - Ensure that the CHGOBJ parameters are defined in the default way using the UPD ACP structure. Fields that do not need to be changed should be made NEITHER parameters.

3 - The CHGOBJ function option for Null Update Suppression should be = No. This ensures that there is no attempt to perform an image check.

4 - UPD style CHGOBJs should ideally only have the attributes that are being changed. This is particularly important when calling a CHGOBJ from inside a RTVOBJ over the same file. Passing in DB1 context for those filed not being changed is not conducive to performance since the optimiser cannot differentiate between changed & non changed attributes.

Thoughts, opinions, concerns or fanmail gratefully accepted. Cash donations to charity please.

Thanks for reading.
Lee.

2e Development Standards - (Hints and Tips CRTOBJ)

Here we go again. Another in the series around 2e development standards. Today I thought I'd cover the CRTOBJ function type and share what I have gathered on the road over the years.

Cutting straight to the point.

Keep numbers to a minimum. In general there should only be one CRTOBJ, i.e. The default (*CRT), per file. This will have all or most parameters open and will not contain any complex processing. This makes the function reusable. The exception being surrogates that are generated inside the function and control fields like audit stamps.

These will generally be set to NEITHER and primed inside the function.

The exception to one per file would be for files that are archived or image copied. But this would not in general usage be the default *CRT. I.e. CRT Archive Image.

Shielding developers from the parameters. For simple files where records are only created under standard application control then time stamp fields may be set as NEITHER parameters and the DB1 context primed inside the CRTOBJ. Similarly, where an internal surrogate number is generated as part of the primary key then an appropriate function call over another file may be inserted. The surrogate number will normally be NEITHER, but it may be OUTPUT or BOTH if required for lower level files.

Wrappering the CRTOBJ with an internal. In some cases there may be a hierarchy of EXCINTFUN calls. Each call then performing some specific function at one level before calling the next level. This may be necessary, for example, because associated files have to be updated when a new record is created. Each main line request to create a new record will call the EXCINTFUN appropriate to the level of complexity required. If requiring just an image copy then it will call the CRTOBJ direct.

An EXCINTFUN designed to participate in the create process should have its parameters defined using the UPD ACP RCD, similar to a CRTOBJ.

Be aware of the probability of a records existence. Where it is not clear whether a record exists for a given primary key then it may be necessary to define a special CRTOBJ i.e. CRT/CHG, which suppresses the error condition and optionally changes the record. I will post a CHG/CRT v CRT/CHG vs RTV/CHG or RTV/CRT debate once I have covered off the intricacies of each of the four main internal function types.

Gotchas

To suppress the error message & error condition if a record already exists then a CRTOBJ may be created where the PGM.*Return Code is set to *Normal in USER:Record Already Exists.

Alternatively if a record already exists and it is appropriate to change attributes then a call to a CHGOBJ may be inserted in USER:Record Already Exists. In this case it is important to ensure that the parameters passed to the CHGOBJ are PAR and not DB1 context.

It is very important in any CRTOBJ to ensure that the DB1 context for any fields not directly input by parameters are initialised or primed with data inside the CRTOBJ. (They will not be input if they are set to NEITHER or if the parameter definition is changed to KEY). There is no automatic move from PAR to DB1 for NEITHER parameters and the DB1 context may contain old data from previous database functions.

By default a SQL CRTOBJ will not check for duplicate records if there is no coding in any action diagram user point other than ‘Processing Before Data Update’. However, there are times when you must or it would be better if you did check. This is accomplished by inserting code, such as comments, in ‘Processing if Record Exists’. This also suppresses the error message if the row already exists.

Next up. The CHGOBJ.

Thanks for reading.
Lee.