CDS041

Retrieve Template

 Last Revised: 11/26/21

This routine retrieves and validates templates stored internally within MKV files, from temporary BBj global namespace and global variables, template (.tpl) files, and the Dynamo Data Dictionary.  It is not typically needed for accessing data files, since CDS095 calls CDS041, but is often used to retrieve templates associated with data structures passed to programs such as CDS038 and CDS084.

A template can be used to describe the record format of a disc file, a string variable on a call/enter list, or any internal data structure.

Template Files

A template file is a string file with a .tpl suffix that is defined and updated by CDS034 based on file definitions contained within the Dynamo Data Dictionary. A template file can contain one template. Template files are only used for data files, not programs or other data structures.

Template files must be located in a tpl directory immediately below the data file.  For example, the data file DS/DSCM01 would have a template file named DS/tpl/DSCM01.tpl.  The same is true for files located across a data server.  If the data server file name is /<server>/u/CDI/DS/DSCM01, the template file should be /<server>/u/CDI/DS/tpl/DSCM01.tpl.  If you place data files in a DAT subdirectory such as PY/DAT/PYUD10, then the template file would be PY/DAT/tpl/PYUD10.tpl.

For non-MKV data files, a template file is required, and will contain the current data structure of the file.  To add fields or change field sizes, make the changes using the data dictionary, and not by editing the template file.  Call CDS034 to convert the data file based on the changes made in the data dictionary which will also replace the template file.

For programs, a template file should not be defined. CDS041 will build the program template from the data dictionary and store the result in global namespace or global variables for fast subsequent access.

For temporary work files, a template file is not used, but a global variable is assigned so that CDS041 can retrieve and return the template to the calling program.

Calling Format:

CALL "CDS041", ERR=NOTPL, FILENAME$, DIMTPL$, { PAR$, SOURCE$ }

CDS041
NOTPL Branch to location if unable to locate the template, the template is invalid, or the user does not have permission to access the template or data dictionary files.
FILENAME$ the file or data structure name such as XXCM01, GL012, CDSM08, PY/DAT/PYUD10, DS/DSCM01, etc.
DIMTPL$ is set by CDS041 as a variable dimensioned to the template, i.e., DIM DIMTPL$:TEMPLATE$.  The template string itself can be retrieved using FATTR(DIMTPL$).  You can re-initialize the templated string variable using DIM DIMTPL$:FATTR(DIMTPL$).
PAR$ Can be passed as null, blanks, or not passed at all for default values.
PAR$(1,1)display operator error message
Ydisplay message if unable to locate template, or if template file is empty or does not contain a valid template, or if the operator does not have read permission on the template file
Ndo not display any operator messages (default)
PAR$(2,1)template search process
Nsearch internal (MKV, FTS), namespace (bbj), global variable, then tpl file. This option is appropriate for use with data files where a .tpl file is expected.
Psearch internal (MKV, FTS), namespace (bbj), global variable, then Data Dictionary. Always use this option when calling CDS041 to obtain a template for programs where there is no .tpl file. It improves the performance by excluding searching for .tpl files.
Ysearch internal (MKV, FTS), namespace (bbj), global variable, tpl file, Data Dictionary.
blank or not passedsearch internal (MKV, FTS), namespace (bbj), global variable, search tpl file if FILENAME$ is not a program, then Data Dictionary. Avoid passing PAR$(2,1) as blank, or not passing PAR$ at all, as it requires a file OPEN to determine if FILENAME$ is a data file well as additional logic which reduce performance.
The following options should not be used by most application programs, as it takes much longer to build the template from the Data Dictionary, each time CDS041 is called, as opposed to the very quick access to a global variable.
Dsearch Data Dictionary only.
Tsearch internal (MKV, FTS) and tpl file only
Fsearch internal (MKV, FTS), tpl file and Data Dictionary, but not global variable
PAR$(3,1)pass as Y to convert fixed length U, I, and N field types to C in order to optimize using SELECT.  Assumed N.
SOURCE$ optional parameter which will return the source of the template information.  The source will return as either the global TPL_XXXXXX, the template file name used tpl/GL012.tpl, or the data dictionary file used DY/DYDD11.  To improve performance, and bypass the logic that looks up the SOURCE$, exclude SOURCE$ when calling CDS041.

Searches to the Data Dictionary include all company codes in the current prefix.

In order to improve performance, CDS041 saves all retrieved templates in global namespace (bbj) or global variables (bbx) named "TPL_"+FILENAME$. Subsequent calls to CDS041 will retrieve the template from the global memory space, eliminating the disc activity.  This means that if you manually change the template file after CDS041 has been called, CDS041 will return the original and not the revised template.  Log off or clear the global variable to insure retrieving the revised template.  You can call CDS277 to display and clear global variables. See the Clear Namespace section below for clearing global namespace variables.

Clear Namespace

For optimum performance in bbj, templates are stored in Global namespace and shared among all bbj user sessions. You can clear these templates, forcing rebuilding upon the next call, using the format:

CALL "CDS041::CLEARNS" {, MASK$)

If MASK$ is not provided, then all templates will be cleared.

If MASK$ is provided then all templates where POS(MASK$ = FILENAME$) will be cleared.

Examples

Example using CDS041 to pass arguments to another Dynamo Tool
CALL "CDS041",ERR=ERROR,"CDS084",S084$
S084.NAME$="P12"
S084.MODE$="f"
CALL "CDS084",ERR=F4,Y$,Y5$,U0,S084$,Y6,Y6$
Example using CDS041 to pass arguments to an application routine
CALL "CDS041",ERR=ERROR,"GL012",GL012$,"YY"
GL012.GLCODE$="SLS"
GL012.GLDATA$="105"
CALL "GL012",Y$,G012$
Example using the SOURCE$ option
CALL "CDS041",ERR=ERROR,"XXAP12",AP12$,"YY",SOURCE$
?SOURCE$
EX/tpl/EXAP12.tpl
CALL "CDS041",ERR=ERROR,"XXAP12",AP12$,"YY",SOURCE$
?SOURCE$
TPL_EX/EXAP12

Notice how SOURCE$ used the template file for the first access, and the global variable for subsequent accesses.

Search Hierarchy

  1. Global memory, both namespace and STBL(), file name as passed: If PAR$(2,1)="Y" or "N", then the global memory is searched first.  The global for a regular template is TPL_<Relative Path to File>.  For example, the file DS/DSCM01 would have its template stored in TPL_DS/DSCM01, and PY/DAT/PYUD10 would have its template stored in TPL_PY/DAT/PYUD10.  This is the first and fastest way to retrieve a template.  If PAR$(3,1) is Y, then the global is named with a lower case "tpl_".
  2. Global memory using relative path name:  If PAR$(2,1)="Y" or "N" and there is no slash included in FILENAME$, then CDS041 will open the file, and use the relative pathname to the file.  For example, if you have added to your prefix list a job prefix entered at the menu as JMB/MMM/ and the program MSI263 is contained within your project directory, CDS041 will check for a global variable named TPL_JMB/MMM/MSI263 even though MSI263 was passed to CDS041.
  3. Global memory: If PAR$(2,1)="Y" or "N" and PAR$(3,1)="Y", meaning that you are looking for the special modified template used for SELECT optimizations, and the lower case tpl_ template was not found in steps 1 or 2 above, then a global variable with the upper case TPL_ and relative path name will be used.  Then any fixed length U and N type fields are converted to C type, and the revised template stored with a lower case tpl_ for use with subsequent calls to CDS041.
  4. Template file in tpl directory below file: Using the relative path to the file. This is the preferred location for template files.  If the relative path to the file is DS/DSCM01, then the template file searched first is named DS/tpl/DSCM01.tpl.  If the relative file name is PY/DAT/PYUD10, then the template file searched first is named PY/DAY/tpl/PYUD10.tpl.
  5. Template file based on first two characters of path name:  If the relative file name is DS/J1234/IC030 and the template was not found in an earlier step, then DS/tpl/IC030.tpl is searched at this step.  Another example would be JMB/MMM/MSI423 would look next for JM/tpl/MSI423.tpl.
  6. Template file based on first two characters of file name:  Relative file name of DS/J1234/IC030 would look for template file IC/tpl/IC030.tpl and JMB/MMM/MSI423 would look in MS/tpl/MSI423.tpl.
  7. Template file based on current prefix using only base file name: DS/J1234/IC030 would look for template file tpl/IC030.tpl in each directory specified in the PFX.  If your PREFIX is JMB/MMM/ PY/ PY/DAT/ and the base file name is MSI423, then template files named JMB/MMM/tpl/MSI423.tpl, PY/tpl/MSI423.tpl, and PY/DAT/tpl/MSI423.tpl will be checked.
  8. Template file based on package code specified in Company Information Maintenance (SMC): If the package code is specified, and this package code was not in the prefix, then CDS041 will look in the package code directory: PK/tpl/MSI423.tpl.  This option is rarely required, since the package code is typically included in the prefix used in step 7.
  9. Data Dictionary: Parent Company: If PAR$(2,1)="Y" or "D" (or blank and FILENAME$ is a program) then the data dictionary in the company code before base name will be checked.  CD/CDS084 will look in data dictionary file CDDD11, DY/IC030 will look in DYDD11, MM/DY/IC030 will also look in DYDD11 first, since that is the company code closest to the base file name of IC030.
  10. Data Dictionary: first two characters of relative path name.  MM/DY/IC030 will look in MMDD11.  DS/J1234/IC030 will look in DSDD11.  JMB/MMM/MSI423 will look for a data dictionary named JMDD11.
  11. Data Dictionary: first two characters of base file name.  LEK/CDS187 will look in CDDD11.  JRG/BC/PYD310 will look in PYDD11.  This option is useful when using programmer specific development directories.
  12. Data Dictionary: First two characters after data server prefix.  /<server>/SP/SPAR12 and /<server>SP/SPAR12 would look in data dictionary SPDD11.
  13. Data Dictionary: Current Company Y.COMPCODE$.
  14. If no template is found, and the base file name contains a period, as in EXAP00.030215, then the template search process is repeated excluding the suffix.  This enables archived file names or names with other suffixes to share the template associated with the original file.

If the data dictionary file can be opened, then the first two characters of the base file name are excluded when the same as the company code.  For example, if the base file name is CDS084 and the relative file name is CD/CDS084, then the data dictionary CDDD11 will be accessed using data dictionary name S084.  In other cases, the complete base name is used.  With a relative file name of DY/IC030, the DYDD11 data dictionary file will be checked for data dictionary name IC030.

When a template is found using a template file or by data dictionary, a global variable is assigned to improve performance and will be used for subsequent template searches.  In some cases, the application program can place a template in a global variable, so that other Dynamo Tools including CDS037, CDS038, and CDW038 can locate the template.

Debug Mode

It is sometimes difficult to determine why CDS041 does not locate the template desired, so there is a debug mode where CDS041 will pause and display the FILENAME$ and PAR$ passed to it, as well as the template files and data dictionaries checked.  You enable this debug mode by assigning the global variable "SMS_CDS041_DEBUG" to any value.  Clear the gobal or log off to return to normal mode.

TMP$=STBL("SMS_CDS041_DEBUG","")
This statement will enable debug mode.

TMP$=STBL("!CLEAR","SMS_CDS041_DEBUG")
This statement will disable debug mode.