So here we go. Another part in the CA 2E development standards series. Here I discuss/publish some naming conventions I have found useful with common functions in a 2E model.
I have worked at a few sites over the years that have varying levels of standards applied to the model and different approaches aiming to solve the same problem.
I have worked at sites that like to use an incremental prefix i.e. RTV56 etc, some that leave the defaults and others that follow naming convention prefixes. As with any standard it is not the actual standard that it is important. The area of concern for any development shop is the continued adherence of the standards.
What I have found works best for me is to use a common set of naming standards for the core functions in a model. Today we will discuss core functions and their naming conventions.
I will finish with a couple of examples of why I settled on my approach for 2E naming standards and as always I expect these to cause some debate in the community.
Default Create Object
I prefer that the default create object (CRTOBJ) on a file is named as '*CRT'. This function will have all the relevant processing that is appropriate to the most common use of the function. Some shops will have auditing and others use surrogate systems. The default will be named as above but other variations may be named 'CRT with Audit' or 'CRT (No Audit)'. However, if most of the time you only need to perform your sites default processing when creating a record, the '*CRT' is much easier for everyone to remember.
The important fact here in the *CRT means the default behaviour. The others are variations and are therefore not classed as default functions and will be named slightly differently. i.e. without the *. The CRT prefix should remain.
As only one function of any name can appear on any file, for *Arrays the standard is extended slightly to be '*CRT Array name' as all arrays share the same file. They simply use different definitions for the access path (sorry, array structure).
Default Change Object
Follows the same rules as the create object but will use *CHG and CHG prefixes as appropriate.
Default Delete Object
Follows the same rules as the create object but will use the *DLT and DLT prefixes as appropriate.
Also a *DLT (Cascade) can also be created. This will actually be based on a RTVOBJ and will delete all child records before deleting the parent key. Thus reducing orphaned records.
Default Retrieve Objects
As a retrieve object (RTVOBJ) can be used in many ways. I will refer to the two most common usages. The fetch of a record and the checking for a record's existence. Also remember that a RTVOBJ is also used for processing files. The next two default functions are based on a fully restricted key.
I have used the *GET naming convention for a full record being fetched. This function will be based on the default retrieval access path. Variations that bring back fewer fields or use an alternative access path will begin with GET. If using another access path use the standard of 'GET By Access Path Name'. If getting a subset of fields use the 'GET subset' - replace subset with a meaningful description. Once again I am highlighting the default usage of this function type.
I have worked at one site that prefers to bring back a Record Found Y/N flag rather than use the return code. This is site specific and I'll leave you to decide on the correct usage of the flag versus the *Return Code. See my other blog which provides further details.
Another usage of the RTVOBJ is for checking for the existence of a record. I have seen this implemented as either a *CHK or and *XST. Either are fine as long as you are consistent.
Again, note that for both of these functions types the array version will need to supply the array name as a qualifier.
There are a further two usages of the *GET and *CHK/*XST function type. This is only related to files that use the 'Qualified By' file relation to describe the key. You will know that the 'Qualified By' is used for file structures that may have a term or a date to identify a value in the key. i.e. A product price file might be qualfied by a field like 'Product Effect Date'. This saves you having to have a record for each day that a price is valid.
You will also know that this relation will automatically read backwards or forwards to find the correct record. Note this only works for the default retrieval access path. Therefore a *GET or the *CHK/*XST will generally find a record but your business logic is trying to determine if a record exists for the actual date. There are several ways to do this. You can either create an alternate RTV access path and write a 'GET By RTV 2' type function. This is perfectly reasonable.
However, and there always is one, I would suggest that a function named '*GET (Exact)' which is only used for files with a 'Qualified By' relationship will do additional processing to determine if the KEY is equal to DB1. This will help to identify to a developer when they are programming, that the file has a 'Qualified By' key but also negates the need for an unnecessary access path to be created.
This pretty much summarises my recommended standards for internal default functions. There are a couple of regularly used external function types that might also be useful and form part of my DBA recommendations of functions that should be created for every file.
The rule of thumb for creating default functions should be.
All Files - *GET, *CRT, *CHG, *DLT, *CHK/*XST and *GETEXT.
Files with a qualified By - *GET (Exact) and *CHK (Exact)/*XST (Exact)
Reference Files - '*SLT filename'
Parent/Child - *DLT (Cascade)
Default External Functions
The *SLT function is named this way as it will be used by the generator when building implicit field prompting code. The routine is also used to validate a record existence in relation checking. As such a default select must be first on the file and also never have its parameter interface changed unless the keys to the file changes.
The *GETEXT (An EXTEXFFUN with a parameter interfaces the same as the *GET) is often used for several reasons.
RPG Limits. Used to limit the number of subroutines or files in a compiled program, not a fully recommended reason. There are other specialist reasons why you would want to use this routine.
Cursor awareness. Wanting to re-read an access path whilst reading the same access path. , therefore not corrupting the cursor.
Externalisation or Program API. Externalising a RTVOBJ function for use within a non Synon environment i.e. CL Program.
If externalising based on another access path call the function 'GETEXT By access path'.
Best Practice
If creating these functions ask yourself this simple question. Am I creating this because of a file limit and if so, is this really the best section of code to externalise? Remember reducing a program from 51 files to 50 (so it compiles) only leaves a maintenance issue for the next developer, and it might be you. Afterall, there is nothing worse than seeing a string of externalised RTVOBJ functions.
Summary
I have generally preferred a prefix and/or suffix when naming functions. The prefix has been used to identify format of the function and the suffix as a sub group. This will become clearer as you see the examples build up on this blog.
You will notice that some are prefixed with an asterisk (*). This is usually reserved to indicate internal Synon objects in a model. I have chosen to indicate my core functions using this method because the * for default function types means that are all grouped them nicely on pick lists. This is done to ensure that they appear at the top of the list of functions. I am aware of other sites using numeric or other acceptable characters to attain the same result.
Note: If you choose to use this approach a known issue is that searching for a *CRT in the open functions screen doesn’t work. This is the only known limitation of this approach from a technical perspective. Other may well say that this encroaches on 2E objects. I fully agree that files should not start with * but the odd function that is core to your development model, no worries.
I have worked at a few sites over the years that have varying levels of standards applied to the model and different approaches aiming to solve the same problem.
I have worked at sites that like to use an incremental prefix i.e. RTV56 etc, some that leave the defaults and others that follow naming convention prefixes. As with any standard it is not the actual standard that it is important. The area of concern for any development shop is the continued adherence of the standards.
What I have found works best for me is to use a common set of naming standards for the core functions in a model. Today we will discuss core functions and their naming conventions.
I will finish with a couple of examples of why I settled on my approach for 2E naming standards and as always I expect these to cause some debate in the community.
Default Create Object
I prefer that the default create object (CRTOBJ) on a file is named as '*CRT'. This function will have all the relevant processing that is appropriate to the most common use of the function. Some shops will have auditing and others use surrogate systems. The default will be named as above but other variations may be named 'CRT with Audit' or 'CRT (No Audit)'. However, if most of the time you only need to perform your sites default processing when creating a record, the '*CRT' is much easier for everyone to remember.
The important fact here in the *CRT means the default behaviour. The others are variations and are therefore not classed as default functions and will be named slightly differently. i.e. without the *. The CRT prefix should remain.
As only one function of any name can appear on any file, for *Arrays the standard is extended slightly to be '*CRT Array name' as all arrays share the same file. They simply use different definitions for the access path (sorry, array structure).
Default Change Object
Follows the same rules as the create object but will use *CHG and CHG prefixes as appropriate.
Default Delete Object
Follows the same rules as the create object but will use the *DLT and DLT prefixes as appropriate.
Also a *DLT (Cascade) can also be created. This will actually be based on a RTVOBJ and will delete all child records before deleting the parent key. Thus reducing orphaned records.
Default Retrieve Objects
As a retrieve object (RTVOBJ) can be used in many ways. I will refer to the two most common usages. The fetch of a record and the checking for a record's existence. Also remember that a RTVOBJ is also used for processing files. The next two default functions are based on a fully restricted key.
I have used the *GET naming convention for a full record being fetched. This function will be based on the default retrieval access path. Variations that bring back fewer fields or use an alternative access path will begin with GET. If using another access path use the standard of 'GET By Access Path Name'. If getting a subset of fields use the 'GET subset' - replace subset with a meaningful description. Once again I am highlighting the default usage of this function type.
I have worked at one site that prefers to bring back a Record Found Y/N flag rather than use the return code. This is site specific and I'll leave you to decide on the correct usage of the flag versus the *Return Code. See my other blog which provides further details.
Another usage of the RTVOBJ is for checking for the existence of a record. I have seen this implemented as either a *CHK or and *XST. Either are fine as long as you are consistent.
Again, note that for both of these functions types the array version will need to supply the array name as a qualifier.
There are a further two usages of the *GET and *CHK/*XST function type. This is only related to files that use the 'Qualified By' file relation to describe the key. You will know that the 'Qualified By' is used for file structures that may have a term or a date to identify a value in the key. i.e. A product price file might be qualfied by a field like 'Product Effect Date'. This saves you having to have a record for each day that a price is valid.
You will also know that this relation will automatically read backwards or forwards to find the correct record. Note this only works for the default retrieval access path. Therefore a *GET or the *CHK/*XST will generally find a record but your business logic is trying to determine if a record exists for the actual date. There are several ways to do this. You can either create an alternate RTV access path and write a 'GET By RTV 2' type function. This is perfectly reasonable.
However, and there always is one, I would suggest that a function named '*GET (Exact)' which is only used for files with a 'Qualified By' relationship will do additional processing to determine if the KEY is equal to DB1. This will help to identify to a developer when they are programming, that the file has a 'Qualified By' key but also negates the need for an unnecessary access path to be created.
This pretty much summarises my recommended standards for internal default functions. There are a couple of regularly used external function types that might also be useful and form part of my DBA recommendations of functions that should be created for every file.
The rule of thumb for creating default functions should be.
All Files - *GET, *CRT, *CHG, *DLT, *CHK/*XST and *GETEXT.
Files with a qualified By - *GET (Exact) and *CHK (Exact)/*XST (Exact)
Reference Files - '*SLT filename'
Parent/Child - *DLT (Cascade)
Default External Functions
The *SLT function is named this way as it will be used by the generator when building implicit field prompting code. The routine is also used to validate a record existence in relation checking. As such a default select must be first on the file and also never have its parameter interface changed unless the keys to the file changes.
The *GETEXT (An EXTEXFFUN with a parameter interfaces the same as the *GET) is often used for several reasons.
RPG Limits. Used to limit the number of subroutines or files in a compiled program, not a fully recommended reason. There are other specialist reasons why you would want to use this routine.
Cursor awareness. Wanting to re-read an access path whilst reading the same access path. , therefore not corrupting the cursor.
Externalisation or Program API. Externalising a RTVOBJ function for use within a non Synon environment i.e. CL Program.
If externalising based on another access path call the function 'GETEXT By access path'.
Best Practice
If creating these functions ask yourself this simple question. Am I creating this because of a file limit and if so, is this really the best section of code to externalise? Remember reducing a program from 51 files to 50 (so it compiles) only leaves a maintenance issue for the next developer, and it might be you. Afterall, there is nothing worse than seeing a string of externalised RTVOBJ functions.
Summary
I have generally preferred a prefix and/or suffix when naming functions. The prefix has been used to identify format of the function and the suffix as a sub group. This will become clearer as you see the examples build up on this blog.
You will notice that some are prefixed with an asterisk (*). This is usually reserved to indicate internal Synon objects in a model. I have chosen to indicate my core functions using this method because the * for default function types means that are all grouped them nicely on pick lists. This is done to ensure that they appear at the top of the list of functions. I am aware of other sites using numeric or other acceptable characters to attain the same result.
Note: If you choose to use this approach a known issue is that searching for a *CRT in the open functions screen doesn’t work. This is the only known limitation of this approach from a technical perspective. Other may well say that this encroaches on 2E objects. I fully agree that files should not start with * but the odd function that is core to your development model, no worries.
My next 2e naming conventions post will focus on ideas for other non-default functions.
Thanks for reading.
Lee.
No comments:
Post a Comment
Thanks for considering leaving some comments about my random rants for everything software development and more.