PODGE V1.0
Dynamic Subfile Display
written in RPG
for use with
iSeries DB2 SQL
using 5250 Display
iSeries OS Level V5R4 (or higher) required
SQL Command
SQL
Processor
Podge
Processor
Podge Command
Podge was designed to aid developers by generating subfile output using only SQL and a few basic
parameters, without having to spend hours of monotonous coding, writing or chopping a display
file and the associated driver program. A subfile driven by Podge can be written in as little as 10
seconds.
Its intended use is for simple menu screens and selection windows.
Podge is best suited to Green on Black screens but will work on Webfacing screen scrapes without
colours.
Podge uses two basic parameters when called
1: An SQL statement
2: A Window description
Podge supports the following DB2 data types
● Numeric : Packed, Signed, Integer, Binary ( 2 & 4 Byte )
● Character : Fixed and Vary length
● Stamps : Dates Numeric 6, 7 and 8 . and all Time Stamp formats
● Null Capable fields
● Multiple file sources using SQLs Join etc
Podge display features
● CLP Subfile capability. CL programs can generate subfile displays using Podge command.
Podge works well with operating system *OUTFILE listed output.
● Multiple panel design allowing full screen / window and various sizes and positions on
screen. New panel formats easily made and added to Podge.
● Date conversion e.g. CYYMMDD displays as DD/MM/CCYY
● Window title and border colour
● Column titles and automatic positioning
● Data column colour , text justification, casing and truncation
● Defined Function Keys
● Single / Multiple subfile selection
● Subfile selection validation
Podge returns details to calling program
● A Key Value. The key value can be one or more values extracted from SQL. The key value
is passed back to the requesting program signalling the subfile line(s) selected. The return
key could be a file RRN and/or a field value(s).
● Multiple returns supported ( up to 9999 selections )
● Function Key. A two digit number representing the Function key pressed.
● Subfile selection value. A one character code which is the option entered on the subfile line.
Ways to Run Podge.
The program can be run using commands PODGE or PODGEGET or by using the script testing
program SCRIPT.
Command PODGE is for use at command line, PODGEGET is for use in CL programs and
program SCRIPT is for script testing Podge syntax.
Starting Podge.
Call SCRIPT.
SQL Command entry ( initial display )
Enter any SQL string as you would in STRSQL . If you don't know any SQL then typing “Select *
from myfile” is sufficient to start Podge.
Press F5 at any time to run Podge and view your file.
Describe the Window ( F8 ).
Enter a Podge command string. This will tell Podge how you want the data to be presented on
screen and the information you want returning.
Podge command syntax.
Each command must begin with a “:” . There are two types of command. Window level commands
which are prefixed with a “@” and column commands which are prefixed with a “*”.
Window level commands describe the type of window subfile to display and how Podge captures
and returns data. Column commands describe if and how the data is presented on screen, its position
and colour etc.
Example
:@Panelform F01:Col001 *Title A Description:@Title My Subfile Window
Validation.
Podge will check the command string and warn of any illegal command syntax.
Command values themselves ( with few exceptions ) aren't validated. If the command value is not
recognised then it will be ignored by Podge.
Commands are not case sensitive, a mixture of upper and lower case is acceptable.
Command syntax.
Window commands are expressed as @COMMAND param x y z.
Column commands are expressed as COLnnn *COMMAND param x y z.
Column names.
Columns can be referred to as COLnnn ( where nnn is a number between 001 and 999 ).
The column number will be the sequence that SQL delivers the fields.
Columns can also be referred to by their SQL/DDS field name ( long name limitation found here ).
Command ordering.
@Panelform , *Size and *Column ( if used ) ideally should be the first commands in the string.
The screen positioning routine is very primitive and Podge may calculate positions incorrectly
because the field size or available screen space has been changed at a later point in the command
sequence. Correct and incorrect usage can be found here.
All other commands can specified in any sequence.
Podge will resequence the command string before applying the instructions.
Eg. “:@Funkey 05( F5=Refresh):@Funkey 01( F1=Help)” will appear on screen as
“ F1=Help F5=Refresh”.
Column commands are sequenced and applied in column order.
@WINDOW Commands 1 of 2
Possible
Command
Values
Default Value
@COLOUR
*See Colour
List
GRN
Set the default colour for column fields.
@COLOURT
*See Colour
List
WHT
Set the default colour for column titles.
@COLTITLEH
[1 – 2 ]
2
Use one or two lines for column titles.
@DATE
*See Date List *EUR
Set the output format of date fields.
@EDITC
DDS Edit
Code
Z
DDS Edit Code to be applied to numeric fields.
@FUNESC
[01– 24]
03
Set Escape Function Key. When an escape key
is pressed, Podge ends without validating the
subfile.
@FUNKEY
[01 – 24](Text) 03(F3=Exit)
Enables a function key. Any text between the
12(F12=Previous) parenthesis is displayed on screen. If any
function key(s) are specified in the command
string then the defaults for function keys F3
and F12 are removed.
@MINMAX
[0 - 9999]
[0 - 9999]
@PANELFORM
F01/F02/Other F01
Screen format to display. F01 = Fullscreen.
F02 = Window. These formats can be changed
or new Formats added using DDS,
@READ
nnn
Number of records SQL to fetch each time. If
not specified then this value is set to the
number of lines on the subfile page.
@RETURN
COLnnn
@SFLADV
YES/NO
0000 9999
Subfile lines per
page.
Minimum and Maximum options that can be
selected from the subfile.
This column is to be returned to the requesting
program. If multiple columns have been
selected then the return value is assembled in
column sequence i.e. Return Value = COL001
+ COL003 + COL014.
Parameter
dependant. If
Using less than 6
parameters i.e.
user space not
used then YES
else NO
If set to YES then Automatic Record Advance
is turned on. Each subfile selection keyed is
immediately validated. This is best suited for
subfiles that require a single selection.
@SFLADV can be used in conjunction with
@MINMAX.
@WINDOW Commands 2 of 2
Possible
Command
Values
Default Value
@SFLCASE
UP/LO
@SFLOPT
x(text)
Any key allowed
X represents any keyboard character the user
can use to select a subfile line. Any text
between the parenthesis is displayed on screen.
@SFLPRELOD
YES/NO
NO
If set to YES then the entire subfile is built
before the screen is displayed.
@TITLE
[%L/%R/%C]
Text
@WINDCLR
*See Colour
List
Any subfile typed selections is upper or lower
cased. This is intended for returning data to the
requesting program in case type the program
expects.
% Justification is optional. Text can be Left,
Right or Centre justified. The remainder of the
text is displayed to screen.
GRN
The colour of the window border.
*COLUMN Commands
Command
Possible
Values
*CASE
*See Case List
*COLOUR
*See Colour
List
*COLUMN 20
[01 - 80]
Data for this column will begin at column n.
*CONCAT
:COLnnn
where
n= 000 to 999
Whenever possible, use SQLs concatenate
command. :COL004 *CONCAT COL002.is
the equivalent of COL004 = TRIM(COL004) +
TRIM(COL002). Concatenate can be used for
assembling a return key value where spaces in
the data aren't required.
*CONCHR
A single
character
This character is inserted between the two
concatenated fields.
*DATE
*See Date List
The data in this column is a date field and its
format is ...
*DISPLAY
YES/NO
*EDITC
F01/F02/Other @EDITC Value
Screen format to display. F01 = Fullscreen.
F02 = Window. Other formats available.
*JUSTIFY
LEFT/RIGHT/ LEFT for Alpha
CENTRE/
RIGHT for
L/R/C
numeric
If the data size is smaller than the space
allocated on screen then the data will be
justified.
*SIZE
[01 - 80]
How many characters wide this field will
appear on screen
*TITLE
[%L/%R/%C]
Left, Right or Centre justified. The remainder
of the text is displayed as the column title.
Default Value
Convert the displayed data into a certain case.
Note this does not effect the returned value.
Returned value case remains unchanged.
@COLOUR Value
YES
Data in this column will be of this colour.
Data from this column will not appear on
screen. Certain data returned from SQL e.g.
RRN or a key value etc. should be stored by
Podge. The column retains its column number
and SQL field name and can be referenced by
other Podge commands.
List of values recognised by some commands.
Date Formats
Date format
Code ( RPG Style )
ddmmyy
DMY
mmddyy
MDY
yymmdd
YMD
cyymmdd
CYMD
ddmmccyy
EUR
ccyymmdd
ISO
mmddccyy
USA
Colour Formats
Colour
Code ( DDS Style )
Green
GRN
Pink
PNK
Red
RED
Turquoise
TRQ
White
WHT
Yellow
YLW
Colour Attributes
Attribute
Code ( DDS Style )
Blink
BL
Reverse Image
RI
Underline
UL
Underline and Reverse
UR
Text Case
Attribute
Example
Code ( 3 Formats available )
Upper Case
XXXX X XXX. XX XXX
U / UP / UPPER
Lower Case
xxxx x xxx. xx xxx
L / LO / LOWER
Proper Case
Xxxx X Xxx. Xx Xxx
P / PR / PROPER
Sentence
Xxxx x xxx. Xx xxx
S / SE / SENTENCE
Suggested approach to writing a program using Podge.
Call program SCRIPT to begin designing your display.
Type the SQL command to retrieve the data you want to view. If Podge reports errors then simply
copy the SQL command, STRSQL and paste the contents into the STRSQL command screen.
STRSQL will give detailed error reporting unlike Podge which will only display a generic message.
Once the SQL command is running OK, begin describing the window using Podge commands.
Press F1 Help for a list of commands.
After the Display is showing correctly, view returned data. Here you can test that Podge is
responding correctly to user keyed options.
Now the SQL command and the Window describe commands can be copied and pasted into your
program.
Considerations.
Writing in CL.
Use @MINMAX value of 0 1 or 1 1 when writing programs in CL. This is because multiple returns
do not use the parameter list. No documentation is provided here for accessing user spaces from CL.
Integrating Podge into many programs.
If Podge is to be used on regular basis, it maybe worthwhile having a “Style Sheet” file where
certain features of a Podge display that are commonly required can be stored. The commonly used
commands could be stored as a string, then additional commands are added to the base command
string I.e.
Style Name Podge command string
NORMAL01 :@PANEL F02:@MINMAX 1 9999:@FUNKEY 07(F07–Next)
WARN01
:@WINDCLR PNK:@MINMAX 1 1:@FUNKEY 08(F08–Confirm ):@FUNESC 08
STOP01
:@WINDCLR RED:@TITLE Big Problem !:@FUNKEY 24(F24-Shutdown)
Key Lengths.
Podge supports a total key length of 30.
If your database uses key identifier fields that are larger eg PART_NUM 50Alpha then either the
source code will need modifying or use RRN as return key.
Using RRN does restrict SQL usage such as summing functions etc.
A couple of changes to the D specs in the RPG and modifying the hidden value KEYV in the DDS
display file will do the trick.
Function Key Escapes.
If a function key is described as escape, no validation of user entries is performed when the function
key is used. The entries are however still returned.
Program Ending.
Podge always does LR not RETURN. User spaces are left upon program ending.
There is code that's commented out to do these things, it could be reinstated.
They were commented out to allow flexibility in the use of Podge as Open Source.
Known Quirks.
Column command is intended for spacing out fields on screen. It can also be used to force one field
to overlay another. If used to reorder column sequence, problems displaying data may occur.
Podge calculates the screen position of each field in the order SQL delivers them. Working from left
to right, Podge calculates which position on screen a column of data should appear. Podge looks at
the ending position of the previous field when calculating the position of the current field. If
*Column was used on the previous field then Podge will attempt to position to the right of it.
Example Data
Field1 (50 Alpha ) , Field2 (20 Alpha), Field3 (10 Alpha)
Default output when *Column command not used
SQL = Select Field1, Field2, Field3 from File.
Podge = No column command used
Podge Output
1
2
3
4
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxx xxxxxxxx
Field 1
Field 2
Field 3
Field 3 Truncated.
Wrong usage of *Column command.
SQL = Select Field1, Field2, Field3 from File.
Podge = :col001 *COLUMN 50
Podge Output
1
2
3
4
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Field 1
Field 1 Truncated. Field 2 Not Displayed. Field 3 Not Displayed.
Correct usage of *Column command ( by stating the field positions of the columns to the
right ) .
SQL = Select Field1, Field2, Field3 from File.
Podge = :col001 *COLUMN 50:col002 *COLUMN 05:col003 *COLUMN 30
Podge Output
1
2
3
4
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
xxxxxxxxxxxxxxxxxxxx
xxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Field 2
Field 3
Field 1
Field 1 Truncated.
Alternate solution to *Column command ( by reordering the sequence SQL delivers the
fields ) .
SQL = Select Field2, Field3, Field1 from File.
Podge = No column command used
Podge Output
1
2
3
4
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
xxxxxxxxxxxxxxxxxxxx xxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Field 2
Field 3
Field 1
Field 1 Truncated.
SQL Field Names.
Long field names aren't recognised by Podge command line.
Podge does store a 30 long name in the program but only the first 10 characters can be referenced
from the command line. If the first 10 characters are not unique then the field can only be
referenced using the internal column identifier COLnnn .
Modifying the Podge Display File.
It is expected that the Podge display file will be modified to match the same style of other programs
on any particular system.
Edit source file QDDSSRC.PODGE#
Podge is shipped with only 2 record formats, F01 and F02.
F01 is the default record format when @PANELFORM” is not specified. The RPG copy routines
have “F01” hard coded as a default, so care should be taken if deleting this record format.
Typically 4 to 30 differently positioned sized windows exist on an iSeries system and various styles
of using hot spots or push buttons etc. Any amount of record formats can be added to Podge using
any record format name.
Copy one of the existing record formats to a new format. RPG limitations require all field names to
be unique.
DDS Fields not required should be hidden. Fields can be deleted but its not recommended.
After compiling the Display file, modify source members QRPGLESRC.PODGE1@F and
QRPGLESRC.PODGE2@C adding the new fields and their size definition. Recompile Podge.
Future Development.
Podge is two programs in one, the SQL extraction and the Screen parser. They should be separate
but the proper interfaces haven't been completed. If developed, the plan is to modify the screen
parser to allow field testing logic and action events. The SQL extraction to pipe data to the screen
parser or alternate ILE programs for output methods such as HTML/XML/CSV File/Printer etc.
This will improve performance and allow a backward version compatibility whilst adding more
functionality.
Document created using open office http://www.openoffice.org/
End of Document.
Aug 2008