7/13/2011

1

New RPG features to improve your applicationsNew RPG features to improve your applications

Original Presentation by Barbara MorrisOriginal Presentation by Barbara MorrisIBMIBMIBMIBM

Brian MayBrian MayIBM IBM ii Modernization SpecialistModernization Specialist

Profound Logic SoftwareProfound Logic Software

Webmaster  and Coordinator Webmaster  and Coordinator Young Young ii ProfessionalsProfessionals

ILE RPG Enhancements New and updated built‐in functions %LEN, %SCANRPL, %PARMNUM Implicit unicode conversion for parameters Sort and search data structures Performance when returning large values Optional prototypes Support for ALIAS names in externally‐described data structures New options for XML‐INTO (also available with a PTF for 6.1) Support for Open Access RPG Edition (also available with a PTF for 6.1) A few system‐related enhancements

7/13/2011

2

%LEN(varying : *MAX) Get the maximum number of characters for a varying field.

Problem solved by %LEN(*MAX): Starting in V6R1, calculations involving the size of the varying‐length 

prefix became error‐prone because the size might be either 2 or 4.p p g In V6R1, %ADDR was enhanced with %ADDR(*DATA) to simplify 

getting the address of the data part. Previously, programmers added 2 to %ADDR.

%LEN(*MAX) simplifies getting the maximum length of the data part. Previously, programmers subtracted 2 from %SIZE, and then divided by 2 for UCS‐2 and DBCS.

New built‐in function %SCANRPL The %SCANRPL built‐in function replaces all The %SCANRPL built in function replaces all occurrences a string with another string.

Problem solved by %SCANRPL:Problem solved by %SCANRPL:

Hand‐written versions of scan‐and‐replace tend to be large, error prone, and difficult to maintain.

7/13/2011

3

New built‐in function %PARMNUM The %PARMNUM built‐in function returns a The %PARMNUM built in function returns a parameter’s position in the parameter list.

Problem solved by %PARMNUM:

Parameter‐information APIs such as CEEDOD or CEETSTA require a parameter’s number.

Soft‐coding the parameter’s number makes the code easier to read and maintain.

Implicit CCSID conversion ‐ parms Implicit CCSID conversion is now supported for prototyped 

  d b  VALUE  d b   d l   f  parameters passed by VALUE and by read‐only reference (CONST)

This reduces the number of code changes that have to be made when a database field is changed from alphanumeric or DBCS to Unicode (UCS‐2 or UTF‐16).

Prior to this change, if the type (A, C or G) of a passed parameter was not the same as the prototype, the compiler would issue a diagnostic. With this change, the compiler will implicitly convert the passed parameter to the type of the prototype.

7/13/2011

4

Implicit CCSID conversion ‐ parms Parameter conversion also provides a way to have a single string‐

h dli   d   h    h dl   l h i  UCS    handling procedure that can handle alphanumeric, UCS‐2 or DBCS.

In the example below, there is only one “makeTitle” procedure with a UCS‐2 parameter and return value. If the passed parameter is alpha or DBCS, it will be converted to UCS‐2 on the call. The procedure will work with the UCS‐2 parameter and return a UCS‐2 value. This returned value can then be converted   i t t   l h    DBCS  if on assignment to alpha or DBCS, if necessary.

Sort and search data structure arrays Sort a data structure array using one subfield as a keyy g y

Search a data structure array using one subfield as a keySearch a data structure array using one subfield as a key

7/13/2011

5

Sort and search data structure arrays The (*) index identifies the array to be sorted. Any other ( ) y yarrays in the expression must have a numeric index.

The subfields preceding the (*) index indicate the array to be sorted. The subfields following the (*) array represent the key to be searched or sorted.

Sort ascending or descending Non‐sequenced arrays can be sorted either ascending Non sequenced arrays can be sorted either ascending or descending.

(D) extender indicates a descending sort.

(A) Extender indicates ascending (default).

7/13/2011

6

Performance returning large values RTNPARM keyword greatly improves performance RTNPARM keyword greatly improves performance when a procedure returns a large value

The speed of using a parameter with the convenience of using a return value

Especially noticeable when the prototyped return value is a large varying length value

Performance returning large values With RTNPARM the return value is handled as a With RTNPARM the return value is handled as a parameter, under the covers

The hidden parameter is the first parameter, so be sure to use %PARMNUM(parmname) when checking for unpassed parameters or calling CEEDOD.

7/13/2011

7

RTNPARM gives another way to prototype CL RTNPARM is not supported by other languages such as RTNPARM is not supported by other languages such as CL, C and COBOL.

Those languages must code the "return value" as the first parameter.

The first parameter of a CL procedure can be prototyped in RPG as a return value, using RTNPARM.

RTNPARM gives another way to prototype CL CL procedure has two parms:CL procedure has two parms:

RTNPARM prototype has a return value and 1 parm:

7/13/2011

8

Optional prototypes If a program or procedure is not called by another RPG If a program or procedure is not called by another RPG module, it is optional to specify the prototype.

These are some of the programs and procedures that do not require an RPG prototype

An exit program, or the command‐processing program for a command

A program or procedure that is never intended to be called from RPG

A procedure that is not exported from the module

Optional prototypes Here is an RPG module with a main procedure and a psubprocedure. No prototypes are necessary.

7/13/2011

9

Support for ALIAS names BackgroundBackground

Fields in externally described files can have a standard name up to 10 characters and an alternate (ALIAS) name up to 128 characters.

RPG III only allowed 6 characters, so many customers have files with cryptic names like CUSNAM, CUSADR. The files often have alternate names such as The files often have alternate names such as CUSTOMER_NAME and CUSTOMER_ADDRESS, that can be used in SQL queries.

RPG programmers would like to use the alternate names in their RPG programs.

Support for ALIAS names New ALIAS keyword for RPGy

When ALIAS is specified, RPG will use the alternate name instead of the 10‐character standard name.

Supported on F specs for any file that will not have Input or Output specs generated. Used for LIKEREC data structures.

Supported on D specs for any externally‐described data structure.

The subfields of the LIKEREC or externally‐described data structure will have the alternate names instead of the standard name.

7/13/2011

10

Support for ALIAS names

XML‐INTO: new option datasubf The new datasubf option enables XML‐INTO to support XML elements in this 

formform<emp type=“regular” id=“13573”>John Smith</emp>

Problem solved by datasubf: When an XML element has attributes or child elements, the XML element 

(emp) itself matches an RPG data structure and the attributes (type, id) match the subfields. (Child elements would also match subfields.) If there is text data for the data structure (“John Smith”), there is no XML name available for subfield matching.

Without the datasubf option, two XML‐INTO operations would be needed to get the data from that XML element.

One XML‐INTO would get the type and id values One XML‐INTO would get the value “John Smith” The allowextra=yes option would be needed for both XML‐INTOs

7/13/2011

11

XML‐INTO: datasubf The datasubf option gives the name for any subfields that are p g y

intended to receive text data associated with a data structure.

<emp type=“regular” id=“13573”>John Smith</emp>

For this XML element, the data structure would be called “emp”, and it would have subfields “type” and “id”. Another subfield, say “value”, would be added to receive the “John Smith” text data.

XML‐INTO: datasubf example

7/13/2011

12

XML‐INTO: new option countprefix The new countprefix option enables RPG programmers to 

   i f i   b    XML d   i  XMLget more information about an XML document using XML‐INTO.

Problem solved by countprefix: When an XML element has a variable number repeating elements, it matches an RPG array. The RPG programmer has to code the maximum elements for the RPG array, but the XML document will usually have fewer elementsXML document will usually have fewer elements.

Without the countprefix option, The allowmissing=yes option would be required, also allowing other 

necessary data to be missing The RPG programmer would have to figure out how many XML 

elements there were by looking for some default value.

XML‐INTO: countprefix The countprefix option gives the prefix for the subfields to 

i   h     f  h   b   f XML  l   d   fill  h  receive the count of the number of XML elements used to fill the RPG array.

The RPG data structure.

No "numemp" tag in the XML for subfield "numemp".

7/13/2011

13

XML‐INTO: countprefix The RPG data structure has a “numemp” subfield that The RPG data structure has a  numemp  subfield that does not appear in the XML document.

By specifying countprefix=num, when the XML‐INTO operation finds the “emp” array, if it finds a subfield called “numemp”, it will set numemp to the number of “emp” XML elements.

Open Access: RPG Edition overview Open Access RPG Edition is a means for RPG programmers to 

extend RPG's simple and well‐known I/O interface (F specs and I/O opcodes) to interact with more protocols and devices than IBM i currently supports.

When an RPG file is defined to use Open Access, the RPG compiler will generate calls to a user‐written procedure (handler), rather than calls to the system's data‐management f i  Th  h dl     id      f i   i  functions. The handler can provide any necessary function, using the type of RPG file definition that best fits the function.

Licensed program 5733‐OAR is required at runtime to use an Open Access file.

7/13/2011

14

Open Access: RPG Edition example Here is an example of an RPG program using a keyed disk file defined 

as an Open Access file with the HANDLER keyword. For the CHAIN operation, the handler contacts the web service using the key and retrieving the values for the input buffer.

Open Access: RPG Edition example In the example, the RPG program is coded as though the fil  i     di  k d d b  fil  Th   l     di  file is an ordinary keyed database file. The only new coding is the HANDLER keyword.

The handler itself can be a program or an ILE procedure. It can be written in any language.

Some other examples:p An IFS stream file could be mapped to a sequential DISK file A rich user interface could be mapped to an RPG WORKSTN file

The creation of an Excel document could be mapped to an RPG PRINTER file

7/13/2011

15

Some system‐related enhancements

Freeze SEU syntax checking at the V6R1 level

Encrypt the listing debug view

Teraspace storage model Teraspace storage model

Freeze SEU (applies to both RPG and COBOL)

The ILE RPG and ILE COBOL syntax checkers for SEU are frozen at the V6R1 level.

For customers using SEU to edit ILE RPG and ILE COBOL source, the syntax checkers will not recognize y gany features added after V6R1.

7/13/2011

16

Encrypt the debug listing view (all ILE compilers) The problem:

You want to ship a debuggable version of your application to your customers, but you don’t want them to be able to read your source code through the debug view

The solution: Encrypt the debug view so that the debug view is only visible if the person knows the encryption key.

CRTBNDRPG MYPGM DBGENCKEY(‘m  secret code’) CRTBNDRPG MYPGM DBGENCKEY(my secret code’)

Then eitherSTRDBG MYPGM DBGENCKEY(‘my secret code’)

ORSTRDBG MYPGM and wait to be prompted for the encryption key

Teraspace storage model (both RPG and COBOL) The problems:

16MB automatic storage limits with the single‐level storage model, for a single procedure, and for all the procedures on the call stack

RPG’s %ALLOC and %REALLOC have a 16MB limit

The solution: use the teraspace storage model Much higher limits for automatic storage. Can compile *CALLER programs with STGMDL(*INHERIT) so they can be called from either single‐level or teraspace programsg p p g

RPG’s %ALLOC and %REALLOC can allocate teraspace with a much higher limit

Teraspace allocations are the default in the teraspace storage model Specify H‐spec ALLOC(*TERASPACE) to have teraspace allocations in any storage model

7/13/2011

17

About the PresenterAbout the PresenterBrian May is an IBM Brian May is an IBM ii Modernization Specialist for Profound Modernization Specialist for Profound Logic Software.  He is also webmaster and coordinator for the Logic Software.  He is also webmaster and coordinator for the Young Young ii Professionals (Professionals (http://www.youngiprofessionals.comhttp://www.youngiprofessionals.com).  ).  He is a husband and father of two beautiful girls.  Brian can be He is a husband and father of two beautiful girls.  Brian can be ggreached reached at bmay@profoundlogic.comat bmay@profoundlogic.com