4 15 3 Steps to Editing RDML Commands

LANSA for i

4.15.3 Steps to Editing RDML Commands

The steps involved in editing the RDML commands associated with a function are as follows:

 

                                          __________

 1. Select the option to "Review or      |          |

    Change a function's RDML commands"   | PROCESS  |

    from the process definition menu     |DEFINITION|

                                         |  MENU    |

                                         |__________|

                                              |

                                              |

                                          ____|_____

 2. Select the desired function.         |          |

                                         |  SELECT  |

                                         | FUNCTION |

                                         |          |

                                         |__________|

                                              |

                                          ____|_____

 3. Review or Change the RDML commands.  |          |

                                         |   EDIT   |

                                         |   RDML   |

                                         | COMMANDS |

                                         |__________|

                                          ____|_____

 4. Run the function checker             |          |

    (if desired).                        |   RUN    |

                                         | FUNCTION |

                                         | CHECKER  |

                                         |__________|

                                              |

                                          ____|__________

                                     ____|_____      ____|_____

 5. Use the screen design facility  |          |    |          |

    and/or the report design        |USE SCREEN|    |USE REPORT|

    facility (if desired).          |  DESIGN  |    |  DESIGN  |

                                    | FACILITY |    | FACILITY |

                                    |__________|    |__________|

 

If the option to review or change the RDML commands associated with a function is chosen from the process or function definition menus, a screen similar to this example will result:

 

 DC@P309901                   Display RDML Commands                    

                                                                       

 XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXX  Editor . . LANSA 

 Find . . . ________________________________________  Roll . . .    13 

 Invoke function checker . . . ______ YES, LIST, DESIGN, COMP, NO      

 No Act Lbl Command     Parameters                                     

           *********  Beginning of RDML commands ***************      

   1       BEGIN_LOOP                                                 

   2       REQUEST    FIELDS (#ORDNO #PRODNO #QUANTITY)                

   3       INSERT    FIELDS (#ORDNO #PRODNO #QUANTITY) TO_FILE(ORDERS)

   4       END_LOOP                                                    

           *********** End of RDML commands ***********                

                                                                       

 Fnn=Help F5=W/C/P F6=Start F7=End F8=Jump F9=Audit F11=Tag Fnn=Cancel 

 F13=Top Fnn=Messages F16=F/Fwd F17=F/Bkwd F20=Indent F21=Change 

 

 

 

 

Working from the Display RDML Commands screen it is possible to:

Review the RDML program associated with a function

Use the ROLL keys to roll backwards and forwards through the RDML program.

Change the RDML program using the LANSA editor

If the name of the editor shown at the top right of the screen is not LANSA change it and press enter. Then use the CHANGE function key to indicate that you wish change (edit) the RDML program. Using the LANSA editor is described in more detail in the following sections.

Change the RDML program using the IBM SEU editor

If the name of the editor shown at the top right of the screen is not SEU, change it and press enter. Then use the CHANGE function key to indicate that you wish to change (edit) the RDML program. Use of the SEU editor is described in more detail in the following sections.

Run the function checker

Enter YES, LIST or DESIGN into the field at the top of the screen. Enter NO to avoid running the function checker. If YES or LIST are entered a full check of all commands in the function will be performed. Additionally, if LIST is entered, an indented listing of the function and any screen layouts will be printed. If DESIGN is entered only commands that relate to the layout of screen formats and/or report formats will be checked.

Run the screen design facility

If the function checker has been run and no errors were found it is possible to run the screen design facility. Enter SCREEN into the field which will appear at the top of the screen to run the screen design facility.

Run the report design facility

If the function checker has been run and no errors were found it is possible to run the report design facility. Enter REPORT into the field which will appear at the top of the screen to run the report design facility.

Find some text string within the function

Use function key 16 to scan forwards. Use function key 17 to scan backwards.

In both cases, the scan starts from the position directly adjacent to the current location of the screen cursor.

The scan facility also supports word wrapping over two lines, the use of "?" as a "wild card" in the scan string, and ignores upper and lowercase differences.

Position a line to the top of the display

To position any line to the top of the display, move the screen cursor onto the line and use function key 13. "Zoomed" lines cannot be positioned to the top of the display.

Display the RDML program in color coded format

Use function key 19 to turn color coding off or on. You must be on a properly configured color device for function key 19 to be enabled. This facility is best used in conjunction with the indent function key.

Display the RDML function in an indented format

Use function key 20 to turn indenting mode off or on. The indented format displayed is similar to that produced in hardcopy reports that list RDML functions.

Ask "What is xxxx?" or use the "Cut and Paste" facility

To do this, position the screen cursor anywhere in the parameter area on a full (or partial) field or file name and use function key 5.

W/C/P stands for "What is xxxx? / Cut / Paste" and it is a very specialized function key that is designed to be used in two different ways:

To answer the question "What is XXXXX?" when browsing:

While browsing an RDML function you will often come across field and file names that you need further information about.

To get additional information about a field or file simply position the screen cursor on the field or file name and use the F5=W/C/P function key. The resulting pop-up window will show summary details of the object and then allow you to use function key 8 to display more detailed information.

To allow "Cut and Paste" operations when defining RDML logic:

While specifying RDML commands you may need to "remember" the name of a field or file. The F5=W/C/P function key may be used to aid in doing this on an ad-hoc" basis (to build lists of fields it is easier to use the normal "F" prompt facility).

As an example of using the W/C/P facility, imagine you have specified this much of the following command:

SELECT FIELDS(#SURNAME #FIRSTNAME #EM_

and then need to "remember" whether "Employee Number" is EMPNO or EMPNUM. To do this, use F5, position the cursor onto the correct name (EMPNUM, say) and then use F5 again. The selected value will be "pasted" back into your command:

SELECT FIELDS(#SURNAME #FIRSTNAME #EMPNUM

Similarly you may not know which view of a file called PSLMST is to be used on a FETCH command:

FETCH FIELDS(.......) FROM_FILE(PSL_

Using F5=W/C/P with a full or partial name you can build a list of the physical and logical files, examine their attributes and key details, and finally "cut and paste" a selected name back into the RDML editor:

FETCH FIELDS(.......) FROM_FILE(PSLMST06

You can also "cut and paste" field names from within file details. For example you may wish to select "Employee Number" but have no idea of its name. However you do know that it comes from the PSLMST file, so you could type the following and then use the F5 function key:

SELECT FIELDS(#SURNAME #FIRSTNAME #PSLMST_

and then use F8 to show a list of all the fields in the PSLMST file. You may then position the screen cursor over "Employee Number" and use F5 to "paste" the name. This would alter your RDML command to:

SELECT FIELDS(#SURNAME #FIRSTNAME #EMPNUM

Some important points about the F5=W/C/P function key:

  • The W/C/P facility determines the "search name" by searching backwards from the current screen cursor location for a non-blank character and then by attempting to "pick out" a name at the cursor position. The name location facility will handle a name that wraps around onto a following line (provided the line is on the current display page) but it will not handle wrap around onto a preceding line.
  • When the W/C/P window first appears a summary of all objects generically matching the search criteria is shown. To view more details of an object place the screen cursor on it and use function key 8.
  • When any W/C/P window is shown you can "cut and paste" the name of an object back into the RDML editor by placing the screen cursor on it and using function key 5.
  • The "cut and paste" facility is very simple. It maps the name of the selected object back into the RDML function editor. It does not compress or expand commands. Only the original search string and any blanks to the right of it will be overlaid by the "cut and paste" string.
  • The displayed pop-up window will be located as close as possible to the position of the cursor at the time that F5=W/C/P function key was used.
  • The W/C/P window is deliberately made to be very small. It is a simple development aid and not designed to be a substitute for other major online inquiries or reports.
  • All searches are terminated after 100 items have been selected. If the required object cannot be found, exit from the W/C/P window and then re-invoke it with a more precise search name.
  • The W/C/P window will include details of function defined fields and data dictionary overridden fields. However the details shown for such fields are as they were at the time of the last full or partial function check or compile.

Jump to the start of the RDML function

Use function key 6 to jump to the start of the RDML function.

Jump to the end of the RDML function

Use function key 7 to jump to the end of the RDML function.

Jump to a pre-determined point within the function

Use function key 8 to invoke the jump screen panel. When it appears use the screen cursor to select to jump directly to:

  • The start of the function.
  • The end of the function.
  • To any subroutine defined within the function. .
  • To any line within the function that has been "tagged". (See the next point for details of how lines are tagged).

Tag a line to allow direct jumping to it

Use function key 11 when the screen cursor is positioned on an RDML line. The line will be "tagged" so that the next time that the "Jump" function key (see previous point) is used you may elect to jump directly to it.

Up to 50 lines may be tagged. To "un-tag" lines that have been previously tagged, use F8 (Jump) and then repeatedly use F11 (and the screen cursor) to select lines that are to be dropped from the list of tagged lines (i.e. to be "untagged").

Using F11 is a way of "temporary" tagging. The tagging is temporary because the tag is only remembered until you exit from the editor. Details of individual temporary tags are also dropped if you delete the tagged line, prompt it by using F4, or cause the entire function to be (re)loaded by performing some action such as editing via the SEU editor, screen painting or report painting.

However, there is a way to apply "permanent" tags to lines within the RDML function. Whenever an RDML comment line is processed by the editor the first 3 characters of the line are examined. If they contain "TAG", "Tag" or "tag" then the line is automatically considered to be a tagged line and loaded into the tagged list.

This means that a permanent tagging method may be established to allowing direct jumping to important sections of functions.

For example:

 **********  Tag : Group and List Definitions

 **********  Tag : Print Line Definitions

 **********  Tag : Function Mainline

 

 

Zoom Back and In on the details of the function

To use the "zoom" keys, you must first use the "Indent" function key to place the display in an indented mode.

Repeatedly use function key 23 to "Zoom Back" and show less and less of the "details" of the current function.

Repeatedly use function key 24 to "Zoom In" and show more and more of the "details" of the current function.

By showing less of the "details" on the display, you can examine the overall structure of the function, or parts of the function.

This allows you to check the structure more easily, and also to move more quickly through the structure until the part that you are interested in is visible.

Once it has been found, repeatedly use the "Zoom In" function key to show more and more details of the program structure.

When scrolling through the function, look for the "zoom light" in the upper left of the screen panel. It indicates that something on the current display is in "zoom mode", and therefore not shown in full detail.

Display the RDML Audit Information

Use function key 9 to toggle the display of the audit date, user and, if used, the task identifier of RDML commands, overlaying the right hand portion of the RDML parameters. The audit date is displayed in installation date format.

 

 DC@P309901                   Display RDML Commands     

 

 XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXX  Editor . LANSA  

 Find . . . ________________________________________  Roll . . .   13  

 Invoke function checker . . . ______ YES, LIST, DESIGN, COMP, NO      

 No Act Lbl Command    Parameters             Date     User     Task Id

          ********* Beginning of RDML commands ***************         

 1        BEGIN_LOOP                                                   

 2        REQUEST  FIELDS (#ORDNO #PRODNO yyyy/mm/dd USERXXXXX XXXXXXXX

 3        INSERT   FIELDS (#ORDNO #PRODNO yyyy/mm/dd USERXXXXX XXXXXXXX

 4        END_LOOP                                                     

          *********** End of RDML commands ***********                 

 

  Fnn=Help  F6=Start  F7=End  F9=Audit off  Fnn=Cancel  F13=Top        

  Fnn=Messages  F21=Change                                             

 

 

 

Change Text String within the Function

This operation is possible only when in change mode. When function key 21 is pressed on the Display RDML Commands screen, the Change RDML Commands screen is displayed.

 

 DC@P309902              Change RDML Commands       

 

 XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXX  Editor . LANSA    

 Find . . . ______________________________________    Roll . . .   13  

 Change N   ______________________________________    Syntax . . ON     

 No Act Lbl Command     Parameters                                     

           *********  Beginning of RDML commands ***************      

 1 __ ___ BEGIN LOOP                                                   

 2 __ ___ REQUEST     FIELDS(#ORDNO #PRODNO #QUANTITY)                 

 3 __ ___ INSERT      FIELDS(#ORDNO #PRODNO #QUANTITY) TO FILE(ORDERS) 

 4 __ ___ END LOOP                                                     

            ********   End of RDML commands *********************     

 

 Fnn=Help  F4=Prompt  F5=W/C/P  F6=Start  F7=End  F8=Jump  F11=Tag     

 Fnn=Cancel  F13=Top  Fnn=Messages  F16=F/Fwd  F17=F/Bkwd              

 

 

 

If the find text strings and change text strings are entered along with the single character change flag and function key 16 is pressed, the find and change operation will be activated. The single character change flag could be either N or A.

If N is entered for the single character change flag, it will find the next occurrence of the string starting at the position of the cursor and replace it. The scan wraps to the beginning of the function when the end of the function is reached.

If A is entered for the single character change flag, it will find all occurrences of the string from the beginning of the function to the end of the function and replace them all.

The Find/Change facility supports word wrapping around over two lines and ignores upper and lowercase differences. It will not support the use "?" as a wild card in the scan string and find/change backwards using function key 17. Also if change text string is not entered and function key 16 is pressed, it will act as a scan forward operation.

For Best Performance in the LANSA Editor

To optimise response time when using the LANSA editor to enter new function control commands, do the following:

  • Turn the online syntax checker OFF.
  • Turn indenting off.
  • Turn color coding off.
  • Turn all zooming off.
  • Turn audit information off.

Input Options

The following input options apply to the panel that allows the review or change of the RDML program associated with a function:

Editor

Indicates the RDML program editor that will be used if the CHANGE function key is used. Allowable values are:

LANSA

Use the LANSA editor to edit the RDML program.

SEU

Use the IBM i editor SEU to edit the RDML program.

 

The use of these program editors is described in more detail in the following sections of this guide.

The "default" editor that appears on the screen when you first begin to edit an RDML program is determined from the LANSA system definition data area. For more details, refer to System Definition Data Area Overview and how to change it.

Roll

Specifies how many lines are to be "rolled" when either the ROLL up or ROLL down keys are used. The roll up and roll down keys are used when reviewing or changing the RDML program to roll back- wards and forwards through the program.

The default roll value is one less then the number of lines on the display. When the roll up key is used the last line on the current display will become the first line on the next display. Likewise, when the roll down key is used the first line on the current display will become the last line on the next display.

Entering a roll value of 999 then using the roll up key is a quick way of locating the end of an RDML program.

Invoke Function Checker

Specifies whether or not the function checker should be invoked. Allowable values are:

YES

Invoke a full check of the function.

LIST

Invoke a full check of the function. An indented listing of the RDML program and associated screen layouts is to be printed. The resulting output is similar to that produced when the "produce source listings" option is used when compiling the functions in a process.

DESIGN

Invoke a partial check of the function. Only commands that affect the design of screen and/or report layouts are to be checked. This option is mainly used as a quicker means of accessing the screen and/or report design facilities.

NO

Do not invoke the function checker. Using this option will cause the function definition menu to be re-displayed.

COMP

Invoke a full check of the function. If the full check completes with no errors then a screen will be displayed allowing the user the option of submitting a compile of the function. If the function is submitted for compilation then information from the full check is passed from the RDML program editor to the compiler, reducing the time needed to compile.

This option does not produce Documentor details, because it has been designed to be quick. If Documentor details are required, use normal compile.

 

Note: The function checker must be run BEFORE the screen design facility can be used. The function checker is described in more detail in 4.15.10 Function Checker.

Invoke the Design Facility

Specifies whether or not the screen or report design facility should be invoked. This option is only presented after the function checker has been invoked AND no errors were found in the RDML program. Allowable values are:

SCREEN

invoke the screen design facility.

REPORT

invoke the report design facility.

<blank>

Do not invoke either design facility, return to the function definition menu.

 

The screen and report design facilities are described in more detail in the following sections.

Syntax

Specifies whether or not the online syntax checker should be used. Allowable values are:

ON

Turn the syntax checker on and syntax check each function control command that is entered or changed.

OFF

Turn the syntax checker off. Do not syntax check commands that are entered or changed.

 

Note that the syntax checker only checks command SYNTAX. For instance if the command GOTO LABEL(L10) was entered and the syntax checker was on it would detect the unbalanced parenthesis and highlight the error.

However, if label L10 did not exist in the RDML program it would not detect this problem. This type of problem is diagnosed by the full function checker that validates syntax AND logic.

The syntax checker can be turned OFF when entering large RDML programs to improve response time.

No

Indicates the line number or sequence number associated with the RDML command line. This field is analogous to the source statement numbers used in conventional programming languages on the IBM i such as RPG or COBOL.

The field is not input capable and is automatically generated by LANSA for every line in the RDML program. Since one RDML command can continue over many input lines it can have many line or sequence numbers associated with it.

The line or sequence number is used on the RDML program listings produced by LANSA and when using the LANSA debug facility to uniquely identify one RDML command.

Note: The maximum allowed number of lines of RDML code is 4096.

Act (Action)

Allows the input of line editing or prompting actions that are used to make the input or amendment of RDML programs easier. These are described in much more detail in the following sections.

Lbl (Label)

Specifies a label that is to be associated with a command. The following points apply to command labels:

  • The specification of a label is optional. Only use a label on a command when you wish to transfer control to the command via a GOTO command or a similar transfer control parameter.
  • When a command spans multiple input lines specify the label on the first input line only.
  • Labels must conform to IBM i conventions. The first character must be in the range A->Z and subsequent characters must be in the range A->Z or 0->9. Imbedded blanks are not allowed in a label.
  • Each label used in an RDML program must be unique. No 2 commands can have the same label within one RDML program.

Command

Specifies the command that is to executed. The command entered must be one of the LANSA RDML commands or a comment which is indicated by a first character of "*" (asterisk). For more information about RDML commands and RDML programming, refer to the Technical Reference Guide.

Parameters

Specifies any parameter(s) that are to be associated with the command.

Command parameters may be mandatory or optional.

If a mandatory parameter is omitted from a command the error will be highlighted by the syntax checker and/or function checker.

If an optional parameter is omitted from a command the default value of the parameter is used.

Parameters may be specified in keyword format or positional format. This type of parameter formatting is identical to that used by the IBM i for CL (control language) programs.

For full details about the RDML commands available and their associated parameters refer to the Technical Reference Guide.

Where the parameters associated with a command cannot be fitted onto the same line as the command continue on the next input line.

No "+" or "-" continuation character is required when continuing RDML commands onto another line under the LANSA program editor