How to use

REPL allows you to enter short snippets of RPG code into an interactive session and immediately evaluate the results. It achieves this by creating a temporary RPG program based on your snippet and dynamically inserting statements to record the values of variables as they change. After execution, the original snippet and stored results are displayed side-by-side.

This immediate feedback is extremely useful in helping developers become comfortable with unfamiliar concepts.

Declaring variables

REPL supports both free and fixed format RPG, determining the type based on the first character of each line. Any line with a capital letter corresponding to a fixed format specification (HFDICOP) in the first column is treated as fixed format, otherwise free format is assumed.

Fixed format code is only partially supported, and will not be able to return the same level of feedback as free format code, as shown in the following example.

Evaluation

After building a snippet, evaluation is triggered by taking F11. This will create, compile, and execute the evaluating program. If this is successful, the message Program ran successfully is shown on screen.

Evaluation types

REPL will evaluate a variable whenever it is changed by a free format RPG statement. Values changed as part of a fixed format statement, or as part of an embedded SQL statement will not be evaluated.

In addition, REPL records how many times a loop was executed, and the SQL state and code after any SQL statement. In the case that a variable has been executed multiple times within a loop, each individual evaluation is shown.

Finally, REPL includes the ability to print and make assertions about local variables, using replPrint and replEquals. These also support certain built in functions to make it easy to check out any values within your code!

Investigating problems

If REPL is unable to compile the evaluating program, the message Module not created. F7 to check spool files, F17 to view generated source is shown. A similar message is shown if the module compiles normally, but the program cannot be created.

In this case, you will be directed to take F7 to view the spool files to identify any problems. The spool files for compilation are named REPL_SRC and REPL_MOD.

Alternatively, taking F17 will display the temporary source generated for the evaluating program. This help to identify if the problem is within the snippet, or if REPL has introduced a coding defect while creating the evaluating program.

Setting Control statements

REPL provides a single default control statement of ctl-opt;, with no options specified. In order to keep the code sequence compliant around the framework code injected by REPL, this can only be changed via a pop-up available under F16.

Users may edit the control statement for this snippet only, or may also overwrite their personal default control statement. This may be useful in organisations where separate developers or teams regularly use different control statements (perhaps to specify certain binding directories).

The available options on screen are:

• F7=System default - restore the control statement on screen to the system default, ctl-opt;
• F8=My default - restore the control statement on screen to the user's default. If the user does not have a default, the system default is used instead
• F10=Save - save the on-screen control statement to the current snippet
• F11=Save as default - save the on-screen control statement to the current snippet, and also set this control statement to be this user's default
• F12=Cancel - do not change the current snippet control statement

Control statements are saved with the snippet, and so are loaded back into the session with the snippet. The order of hierarchy for using snippets is:

1. The control statement associated with this snippet
2. The control statement associated with this user
3. The system default control statement

Changing the system default

A maximum of a three-line system default control statement can be set using the following SQL statement - simply replace the lines as required:

INSERT INTO REPLSRC (LINE_NUMBER, CODE, SOURCE_TYPE)
VALUES
  (1, 'ctl-opt', 'control'),
  (2, 'datedit(*ymd)', 'control'),
  (3, 'bnddir(''MYDIR'');', 'control')

Binding service programs

REPL can be used to bind in a service program as an easy way to access exported procedures. To help with this, reference source can be included using /copy <library>/<file>,<member> or /include <library>/<file>,<member>.

If reference source is included, REPL will assume that a service program should be bound, and will attempt to find a service program in the libary list with the same name as the member. If no such service program is found, the CRTPGM command will be shown, prompting the user to replace or remove the service program.

Alternatively, F23 can be used to access the CRTSQLRPGI and CRTPGM commands to allow amendments before submitting them.

Debug mode

Sometimes it is useful to add a breakpoint to be able to debug the evaluating program. This may be especially true for stepping through calls to exported procedures in bound service programs. To do this, the create, compile and execute function provided by F11 can be broken down:

1. Take F10 to create and compile the evaluating program
2. Take F2 to start a debug session over the evaluating program
3. Place all required breakpoints, and return to REPL with F12
4. Execute the current evaluating program by taking F12

Bash Script

A bash script replwrpr.sh is made available to be able to run snippets in REPL remotely. This can be launched in one of two ways:

1. Running a saved snippet
2. Running standalone source

This can be useful for running assertions, as provided by replEquals. This will return a 0 if the program compiles and all tests pass, or a 0 otherwise. Assistance with details of a failure can be toggled with the various log levels.

Installation & Pre-requisites

The latest REPLWRPR.SH script may require copying to the IBMi separately in order to be able to use it.

The library containing REPL (specifically, the commands REPLWRPR and REPLPRTR) must be in the library list when running this script.

Help

Help can be accessed at any time by running replwrpr.sh --help.

Running a saved snippet

Note that this will run any saved snippet with this name - but a snippet name only guarantees uniqueness under a single username. This can be addressed if it is required.

The simplest way of running this test set is by saving it as a snippet. I have saved the above as "repl tom". This can be ran with various log levels as follows:

> rpgle-repl/replwrpr.sh -s 'repl tom'
0

> rpgle-repl/replwrpr.sh -s 'repl tom' -v
** submitting build task for repl tom                  
** build and run complete for snippet, fetching results
Success, 1 tests passed, 0 tests failed              
0                                                      

> rpgle-repl/replwrpr.sh -s 'repl tom' -w
** submitting build task for repl tom                  
** build and run complete for snippet, fetching results
Line 4 TEST-SUCCESS Success, lower(Tom) = tom          
Success, 1 tests passed, 0 tests failed\n              
0                                                      

> rpgle-repl/replwrpr.sh -s 'repl tom' -x
[as above, but also includes the compiler listing]

Failing tests are representing in the following way:

> rpgle-repl/replwrpr.sh -s 'repl tom'
-1

> rpgle-repl/replwrpr.sh -s 'repl tom' -v
** submitting build task for repl tom                  
** build and run complete for snippet, fetching results
Failure, 0 tests passed, 1 tests failed                
-1                                                                                                         

> rpgle-repl/replwrpr.sh -s 'repl tom' -w
** submitting build task for repl tom                      
** build and run complete for snippet, fetching results    
Line 4 TEST-FAILURE Failure, lower(Tom) = TOM, expected tom
Failure, 0 tests passed, 1 tests failed                    
-1                                                                                                             

> rpgle-repl/replwrpr.sh -s 'repl tom' -x
[as above, but also includes the compiler listing]

Running a non-REPL snippet

Snippets can be saved elsewhere on the system as required, and will be loaded into the system as though they were native REPL snippets. The snippets elsewhere must follow a few basic rules:

• Control specifications are not required
• Program return statements are not required
• **FREE programs are not supported.

For example, this faux-snippet has been created:

This can be tested using the library, file, and member parameters on REPLWRPR.SH

> rpgle-repl/replwrpr.sh -l wtom -f qrpglesrc -m repltest
0

> rpgle-repl/replwrpr.sh -l wtom -f qrpglesrc -m repltest -v
** submitting build task for wtom/qrpglesrc/repltest   
** build and run complete for snippet, fetching results
Success, 1 tests passed, 0 tests failed\n              
0                                                                                                                                                             

> rpgle-repl/replwrpr.sh -l wtom -f qrpglesrc -m repltest -w
** submitting build task for wtom/qrpglesrc/repltest      
** build and run complete for snippet, fetching results   
Line 400 TEST-SUCCESS Success, lower(Tom) = tom           
Success, 1 tests passed, 0 tests failed\n                 
0                                                                                                                                                                   

> rpgle-repl/replwrpr.sh -l wtom -f qrpglesrc -m repltest -x
[as above, but also includes the compiler listing]

Failure messages work in the same way as the REPL snippets.