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.