CRTRPGBEAN Command Documentation

The Command

The CRTRPGBEAN (Create RPG Bean) Command will analyze a database file and generate appropriate encapsulating source code. This source code is essentially based on my ITJungle article Encapsulating File Access in a Service Program.

Below is a sample of the command screen:

(click on image to view full size)

CRTRPGBEAN Command Parameters

Parameter Name	Description
Database File	The file name to encapsulate.
Database Library	The library location of the file. LIBL and CURLIB are acceptable special values.
Source File	This is the source file to which you wish to add the encapsulating member (ex. QRPGLESRC, QSOURCE, etc.)
Source Library	The library in which the source file is located.
Source Member	This is the source member you are creating in the previously listed File/Library. This will provide the source code for the eventual *MODULE object.
Prototype File	This is the file name to reference in the source member for the prototype /copy statement. (ex. QRPGLESRC, QSOURCE, etc.) The prototype fields are also used to indicate what prototype /copy member to create if the "CRTPROTO" option value is "*YES".
Prototype Library	The library of the Prototype File.
Prototype Member	The source member name of the /copy member.
Key Field Name	The key field used in the resulting encapsulation object for all individual record access. At present, the tool only supports single field keys.
Template File	The file name where the desired template resides. (ex. QRPGLESRC, QSOURCE, etc.) QSOURCE is the default value because it is the location for the default template.
Template File	The library name of the template file. RPGBEANLIB is the default value because it is the location for the default template.
Template Member	The source member to be used as a template for the resulting source member. TEMP_MAIN is the default value because it is the location for the default template.
Create Prototypes	Indicates whether or not the actual prototypes should be created. If this value is "YES", then the command will also issue a call to the CRTPTYPMBR command based on the Prototype values listed above. If the value is "NO", the prototypes are not created and the next parameter is ignored.
Append To Prototype Member	If "CRTPROTO"'s value is "YES", then this parameter will indicate whether or not the prototype /copy member is a new member or if it should append the prototypes to an existing /copy member. A value of "NO" (the default) will create a new member for the prototypes, and if "*YES" the prototypes will be added to the /copy member referenced in the Prototype parameters above.

Working with Templates

The CRTRPGBEAN command is template based. The library ships with a default template located in the QSOURCE file of the RPGBEANLIB library. You may develop custom templates in any source file of your choosing and then apply them when you run the CRTRPGBEAN command. I would recommend that you NOT modify the default template because subsequent upgrades may replace the current template.

The templates work based on a series of replacement strings:

%PROTO_LIB%	Replaced with the Prototype Library parameter value.
%PROTO_FILE%	Replaced with the Prototype File parameter value.
%PROTO_MBR%	Replaced with the Prototype Member parameter value.
%FILE_NAME%	Replaced with the File Name parameter value.
%KEY_FIELD%	Replaced with the Key Field parameter value.
%FIELD_NAME%	A special placeholder used only by the command.

You'll notice if you look at the template that there are no getter and setter records. The program processes the template first, replacing all necessary strings as it goes, then loops through the file description to create the getter() and setter() procedures. The best approach for using a custom template is to copy the default template from QSOURCE in RPGBEANLIB: alter the existing procedures as necessary (for instance, internally my template includes user and timestamp automation), and add new procedures to the template.

The default template includes the following procedures:

%FILE_NAME%_getRecord()	Used to retrieve a record based on the key value. The incoming parameter has a specified type and length in the template, but that is replaced at Command run-time by the actual type and length in the database file.
%FILE_NAME%_clear()	Clears and resets the Service Program's file-based datastructure.
%FILE_NAME%_update()	Updates the current database record with the current datastructure values.
%FILE_NAME%_write()	Writes a record with the current datastructure values.
%FILE_NAME%_delete()	Deletes the current database record.
%FILE_NAME%_isOnFile()	Checks for the existence of a record with this Key Field value.

An Example

There is an example of the resulting Source code and Prototypes posted at RPGNext Codesamples. This example is based on the following database file:

   -------------------------------------------------
      RECNO         1    7  S    7  7, 0
      MAP           8   37  A   30
      MAPNO        38   40  A    3
      INSERT       41   42  A    2
      DCIR         43   44  A    2
      BLOCK        45   46  A    2
      LOTS         47   67  A   21
      MAPFIRST     68   76  A    9
      WORK1        77   96  A   20
      WORK2        97  116  A   20
      WORK3       117  136  A   20
      WORK4       137  156  A   20
      STATUS      157  157  A    1