Create RPG Template (CRTRPGTPL)

The CRTRPGTPL command is used to generate a compiled source member template used by the RPG API Express 3 XML composition engine. Unlike with RXS 2, newer versions of RPG API Express do not reference template files in the IFS at runtime. Intead, the template source member generated with CRTRPGTPL is included in your programs using the /COPY compiler directive and is compiled directly into your program. By using these compiled templates, we remove this additional external runtime dependency, reducing the risk of errors caused by file changes and allowing your programs to be more self-contained. For more information, see our guide for creating an RXS template.

The CRTRPGTPL command is designed to be run against either your existing .tpl template files in the IFS, or new template files that are first created with BLDTPL and have been modified to add sections as needed. To generated a compiled template member, your .tpl template file requires at least one section.

As with all of your program source code members, the generated template source members should not be stored in the RXS library.

Note: It is imperative that you never edit or modify the source member generated by the CRTRPGTPL command in any way, unless directed to do so by a member of our support staff. If you need to make changes to your template, first update the corresponding .tpl file in the IFS, then run CRTRPGTPL on that updated .tpl file to regenerate the compiled template member.

New in RXS 3.5.0:

New Parameter

INCCRTCMD: used to specify whether or not to include the creation command in the generated template output.

Enhancements

The template generation process now supports whitespace in front of section delimiters - sections added to .tpl files before calling CRTRPGTPL no longer need to be fully left-aligned.
Better support for wrapping escaped single quotation marks in generated output.
Corrected an issue where the creation command could be generated with a truncated filepath.
Corrected an issue where the command was sometimes retaining a lock on a source member that was provided as input.

Parameters

Input Stream File Template (STMF)

This is a required parameter.

Specify the path name of the template stream file that will be processed to generate the RPG template. This template stream file would have been previously created using the BLDTPL command.

Possible Values:

character-value: Qualified filepath of IFS stream file.

Output Source File (FILE)

This is a required parameter.

Specify the source physical file where the template source member will be created. The specified source physical file must exist, and the user profile must have authority to the object.

Possible Values:

character-value: Name of the source physical file in which the template member will be generated.

Qualifier Values:

*LIBL: The library list for the job will be used to located the file. This is the default value.
character-value: Specify the library name where the file is located.

Output Member Name (MBR)

This is a required parameter.

Specify the name of the source member where the RPG template will be generated. If this source member does not exist, it will be created. If this source member does exist, the generated RPG template will overwrite any existing content.

Note that the default value of this parameter - *FIRST - is a placeholder and must be overwritten.

Possible Values:

character-value: Name of the source member.

Sections DS Name (SECTIONSDS)

This is a required parameter.

Specify the name of the data structure within the RPG template that containsthe template section names.

It is strongly advised to set this value to improve the readability of your program code and allow for sections and variables that may share a name.

Possible Values:

*NONE: No name is given to the Sections data structure.
character-value: This name will be assigned to the Sections data structure.

Variables DS Name (VARSDS)

This is a required parameter.

Specify the name of the data structure within the RPG template that contains the template variable names.

It is strongly advised to set this value to improve the readability of your program code and allow for sections and variables that may share a name.

Possible Values:

*NONE: No name is given to the Variables data structure.
character-value: This name will be assigned to the Variables data structure.

Coded Character Set ID (CCSID)

Specify the CCSID for which the RPG template will be generated. This will additionally control the output of the template source member to support multi-byte character sets when *STMF is selected.

Possible Values:

*JOB: The CCSID of the current job is used.
*STMF: The CCSID of the IFS stream file is used. This setting must be selected with multi-byte character sets (eg. CCSID 1208).

Trim Template Lines (TRIMLINES)

Specify whether leading and trailing whitespace should be trimmed from the template. Line control characters - carriage returns and line feeds - will always be preserved.

Possible Values:

*NO: All whitespace will be preserved.
*YES: Leading and trailing whitespace will be trimmed.

Include Creation Command (INCCRTCMD)

Specifies whether the command used to create this template member will be included in generated template output. Including the creation command may make updating and maintaining the template easier in the future.

Including the creation command will not impact the XML composed by the template - it is only included for reference.

Possible Values:

*YES: The template creation command will be included within the created template member. This is the default value.
*NO: The template creation command will not be included.