did you know [pdf library]

8/6/2019 Did You Know [PDF Library]

1/23

Susan M. GantnerPartner400susan.gantner @ partner400.comwww.partner400.com Your partner in AS/400 and iSeries Education

RPG IV - Did You Know ....... ?

OCEAN Technical ConferenceCatch the Wave

(Prototypes, Compiler Directives and other features and functions you may have missed) As I travel around the

world talking to RPGers, I often find that even experienced RPG IV programmers have "missed" a few gems alongthe way. This session is designed to fill those gaps. Examples? How about Prototypes? Most people know that youneed prototypes when defining and using Subprocedures, but many fail to appreciate their other uses. Forexample, did you know that you can use prototypes to call PGM objects? or that a prototype will defend againstpassing incorrect parameters? Or that in some cases they can take care of the differences for you? Did you knowthat you can conditionally include source lines based on a parameter for the RPG compiler? A great way toinclude/exclude additional code needed for testing without having to delete or comment it all out. There are manyother uses for this great feature too. How about mail-merge function? Did you know that through the combinationof two of the latest features of RPG IV that you now have an easy way of blending customer names and otherdetails into text templates? Additional tidbits include new performance optimization options and effective use ofpointers in RPG trigger programs. Even if you have been programming in RPG IV for some time, you will likelylearn something new in this session!

The author, Susan Gantner, is co-founder of Partner400, a firm specializing in customized education andmentoring services for AS/400 and iSeries developers. After a 15 year career with IBM, including several years atthe Rochester and Toronto laboratories, Susan is now devoted to educating developers on techniques andtechnologies to extend and modernize their applications and development environments. This is done via on-site

custom classes as well as conferences and user group events.

Together with her partner, Jon Paris, Susan authors regular technical articles for the IBM publication, eServerMagazine, iSeries edition, and the companion electronic newsletter, iSeries Extra. You may view articles in currentand past issues and/or subscribe to the free newsletter or the magazine at: http://eservercomputing.com/iseries/.

Feel free to contact the author at: susan.gantner @ partner400.com and visit the Partner400 web site atwww.partner400.com.

Copyright Partner400, 2002. Did You Know ...... Page 1-


2/23

You can embed compiler options in your RPG IV source?

Your can match statement numbers to SEU line numbers?

And you don't have to keep pressing F10 when debugging I/Ooperations

RPG IV has many new string handling options?

Including BIFs for Mail-Merge type operations

Programs can be optimized based on actual usage

Prototypes can help you defend against parameter errors?

And allow RPG IV programs to directly use C functions?

Pointers are the way to handle trigger buffers

And the same techniques apply to many APIs

The compiler can selectively include/exclude source lines?

Did you know that ......

We will be covering a lot of ground in this session, from prototyping C functions to Triggers to.... wella whole bunch of stuff. Some of it will (hopefully) be new to you and some may be familiar territory.

If you have questions or comments about this presentation, please feel free to contact the authors atthe e-mail address on the front cover.

This presentation may contain small code examples that are furnished as simple examples toprovide an illustration. These examples have not been thoroughly tested under all conditions. Wetherefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

All code examples contained herein are provided to you "as is". THE IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLYDISCLAIMED.

All of which is the boring legal way of saying that any outbreak of plague, pestilence, flood or otherdisasters apparently resulting from the use of these techniques is completely coincidental !!



3/23

Compiler Options on H-spec

Embedded Compiler OptionsMany options for CRTBNDRPG and CRTRPGMOD can now be specifiedon the H spec as keywords.

The compile options specified will override the ones specified on theCRTxxxxxx command.

The Compiler will search for the H spec in the following order:An H spec included in your source

A data area named RPGLEHSPEC in *LIBL

A data area named DFTLEHSPEC in QRPGLE

The search stops when the first of these is found.Use a /COPY source for any standard H-specs not a Data Area

Unsupported keywords:DBGVIEW, OUTPUT, REPLACE, DEFINE, PGM, SRCFILE, SRCMBR,TGTRLS

H DATFMT(*USA) TIMFMT(*USA) DFTACTGRP(*NO)

H COPYRIGHT('Release 5, Fix Level 27, Last Update 06/22/2001')

The Compiler will search for H specs in the following order:

An H spec included in your source

A data area named RPGLEHSPEC in *LIBL

A data area named DFTLEHSPEC in QRPGLE

The search stops when the first of these is found. Therefore, if you have specified H specs in thedata areas AND in your program, the specifications in the data area will NOT be used.

If you currently use one of the data areas to supply default H spec parameters, we strongly suggestthat you code them instead in a /COPY member and include this at the beginning of every sourcemember. Any additional parameters over and above the normal set can then be simply coded on Hspecs following the /COPY directive.



4/23

Debug Enhancements

Match program statement numbers with SEU !!

Use H spec keyword or command parameter OPTION(*SRCSTMT)

Easier for debugging and end user support

Faster step through I/O statements in debug sessions

User H spec keyword or command parameterOPTION(*NODEBUGIO)

Skip the individual field steps for Input and Output specsFaster step function during debugging

Specified on CRTRPGMOD & CRTBNDRPG commands

Or on the H specThis last method is also available for releases prior to V4R4

Implemented via PTF

On the H spec, if you specify multiple options, you should separate the options with a colon (:).

For example: OPTIONS( *SRCSTMT : *NODEBUGIO)

With *SRCSTMT specified, the statement number reported when an error occurs during run time willcorrespond directly to the SEU sequence number. Without this support, the statement numberreported did not correlate directly to the source statement numbers. Therefore, support of end userproblems was much more difficult. Many support desks kept compiler listings of all programs just tobe able to match the program statement numbers to SEU statement numbers.

*NOSRCSTMT indicates that line numbers are assigned sequentially.

If *SRCSTMT is specified, statement numbers for the listing are generated from the source ID andSEU sequence numbers as follows: stmt_num = source_ID * 1000000 +source_SEU_sequence_number

For example, the main source member has a source ID of 0. If the first line in the source file has sequencenumber 000100, then the statement number for this specification would be 100. A line from a /COPY filemember with source ID 27 and source sequence number 000100 would have statement number 27000100.

Note: When OPTION(*SRCSTMT) is specified, all sequence numbers in the source files must contain valid numericvalues. If there are duplicate sequence numbers in the same source file, the behavior of the debugger may beunpredictable and statement numbers for diagnostic messages or cross reference entries may not be meaningful.

If *DEBUGIO is specified, breakpoints are generated for all input and output specifications.*NODEBUGIO indicates that no breakpoints are to be generated for these specifications. This meansthat during debug sessions, doing a Step function on an IO statement required many steps (one foreach field in the format).

Note: These options were made available as H spec options only via a PTF on some previous releases of the RPGcompiler. NOTE: NEITHER of these new options is the default! Default behavior is as in prior releases.



5/23

Have the same effect as using an edit code or word on output

BUT - you can work with the resulting field!

%EDITC ( numexpr : editcode { : option } )Returns the edited value of the numeric expression

optioncan be *ASTFILL, *CURSYM, or a character literal representing acurrency symbol

%EDITW ( numexpr : editword )

The edit word is applied to the value of the numeric expression.

D Text S 50

C Eval Text = 'Your balance of ' +

C %Trim(%EditC(Balance:'A':CurSym))

C + ' is now seriously overdue'

Editing BIFs (V3R7+)

The same edit codes available for use on the O specs in RPG are available via the BIF.

Copyright Partner400, 2002. Did You Know ...... Page 9-1


6/23

%CHAR (V4R2+)

%CHAR converts numeric, date, time fields to character

Allows for easier concatenation into strings

For numeric fields / expressions (V4R4+)Provides a simple alternative to %EDITC when only simple editing isrequired

Inserts decimal point and blanks leading zeros

In the example below if Balance was 275.00 and DueDate wasJanuary 21st 2001 the field Text contains:

"Your balance of 275.00 is due on 01/21/2001"

D Text S 50

D DueDate S D DATFMT(*MDY)

D Balance S 9 2

C Eval Text = 'Your balance of ' +

C %Char(Balance)

C + ' is due on '

C + %CHAR(DueDate)

In V4R2, %CHAR was added but it only supported date, time and timestamp data types. In V4R4, it

was enhanced to work with numeric fields as well. This makes it much easier string togethernumbers with character fields using the concatenate support.

Note that if you wanted to add the dollar sign to the Balance field, you could use the %EDITC BIFdiscussed on the previous chart.



7/23

Varying Length Fields

Variable length fields can provide a performance boost

When you append data to them the compiler knows just where to start

Guess which of these code samples runs faster !!

D OutString S 256a VARYING

C Eval OutString = %Trim(InputFields(1))

C For Count = 2 to 10

C Eval OutString = OutString + ','

C + %Trim(InputFields(Count))

C EndFor

* Build content of InputFields into a comma delimited string

D OutString S 256a

C Eval OutString = %Trim(InputFields(1))

C For Count = 2 to 10

C Eval OutString = %TrimR(OutString) + ','

C + %Trim(InputFields(Count))

C EndFor

Varying length fields make it easier and more efficient to concatenate character fields.



8/23

D MsgText S 100A Varying

D BaseText C 'Dear &S, thank you for your +

D recent order'

C Read Customer

C If Not %EOF(Customer)

C Eval MsgText = %Replace( %TrimR(Salutation)

C : MsgText

C : %Scan('&S':MsgText)

C : 2 )

C EndIf

%REPLACE makes string handling easier & more flexible.

When used in conjunction with other built-in functions, such as%SCAN and %EDITC, this is particularly powerful

For example - code similar to the following could be used to substitutethe marker &S with the content of the variable Salutation in amail-merge type of operation.

"Mail Merge" with %REPLACE

The syntax of the %Replace BIF is:

%REPLACE ( replacement : source { : start { : length } } )start - defaults to 1 if not specified

length - defaults to the length of the string "replacement"- if length is zero, string is simply inserted



9/23

Performance Data Collection

Application profiling support

Collects statistical information on the way your code is actually runduring a specific span of time

The ILE optimizer can subsequently apply this information to morespecifically optimize the code to the way the users run it

e.g., re-order options on nested IF or SELECT statements (block order)

or re-order subprocedures based on usage (procedure order)

Steps to collect/apply performance data:

1. Modules must be enabled to collect performance data

2. Modules must have the profiling data attribute set onSteps 1 & 2 can be done at compile time or later with CHGPGM/SRVPGM

3. Start the profiling data collection processSubsequently end data collection

4. Apply the profiling data to the program(s)/service programs

To allow the program optimizer to more specifically optimize a module based on the way the users

actually use the program, you can enable application profiling. This can only be done on programsthat are Optimize(*Full) and Target Release(*Current). It can be useful in some situations,particularly if you have many subprocedures or if you have large and complicated logic in the form ofstatements such as IF/ELSE or SELECT. Based on the most popular options taken by the usersduring the data collection process, the optimizer may actually choose to re-order some of the logicblocks or re-order the subprocedures in the module to improve locality of reference.

Note that, of course, when this level of optimization is done, it can cause some interesting sideeffects, especially during a source debug session if the code has been moved around in thecompiled code! Any modules with *FULL optimization can exhibit these kinds of side effects, butthose optimized with profiling data are more likely to exhibit them.



10/23

Profiling Command Parameters

1. Enable performance collection (ENBPRFCOL) parameter

CRTRPGMOD, CRTBNDRPG, CHGPGM, CHGSRVPGM commandsOptions are: *PEP, *ENTRYEXIT, *FULL

2. Set Profiling data attribute on (PRFDTA) parameter

CRTRPGMOD, CRTBNDRPG, CHGPGM, CHGSRVPGM commandsOptions are: *NOCOL, *COL

3. Start profiling data collection process

STRPGMPRF command (no parameters)Collects for ALL programs / service programs with PRFDTA(*COL)

ENDPGMPRF comand (no parameters) ends the collection process

Apply profiling data to program(s)

CHGPGM ... PRFDTA parameterOptions are: *APYBLKORD (block order), *APYPRCORD (procedure order),*APYALL (both block and procedure order)

Note that profiling data can only be collected on modules where Optimize(*Full) and Target release(*Current) have been selected.

ENBPFRCOL - This parameter tells the system to include the necessary information to allow thismodule (or the modules in this program or service program) to be able to collect profiling data. Itdoes NOT ensure that profiling data will be collected when collection is started. To do that, you mustuse the PRFDTA parameter. If you select *PEP here, statistics are kept only for entry and exit of thePEP (program entry procedure) itself. Note that this does NOT include any RPG code -- not eventhe main procedure. *ENTRYEXIT collects data on the entry and exit of all procedures in themodule (the main and any subprocedures). *FULL collects all the *ENTRYEXIT did, plus statisticson calls to external procedures.

PRFDTA - This parameter causes data to be collected for this module (or the modules in thisprogram or service program) the next time profiling data collection is started. Changing this attributedoes not cause data to be collected immediately. After STRPGMPRF and ENDPGMPRFcommands have been run, this parameter on CHGPGM / CHGSRVPGM is used to apply the

profiling data to the modules for potential optimization.

STRPGMPRF - This is the command that actually begins the profiling data collection. Profiling datawill be collected for ALL programs and service programs on the system for which PRFDTA iscurrently set to *COL. Note that the profiling data process puts extra workload on the system. It isadvised to collect profiling data for limited periods of time and for specific groups of programs at atime.



11/23

OS/400 Parameter Passing

When one program calls another, no data is passed

Only pointers containing the address(es) of the parameter(s)

These pointers reference the data back in the originating program

Which could be many levels back

In the example below, what does Part2 contain after the call ?

D Part1 S 15

C *Entry PListC Parm Part1

C Eval Part1 = *Blanks

C Return

D TestData DS

D Part1 10 Inz('Test Data1')


C Call 'TEST2'

C Parm Part1

Program

TEST2

ProgramTEST1

These programs demonstrate the danger of mis-specifying a parameter in the called program.

This problem can also occur with numeric fields, but it is more likely to be obvious at the time of thecall.With mis-sized character fields the effect may not be noticed until much later. The writer has encountered atleast one program where such an error went undetected for over 7 years!

If you have difficulty believing this, try compiling a running the two programs below.

* Program TEST1

D TestData DS



C 'In TEST1' Dsply

C TestData Dsply

C Call 'TEST2'

C Parm Part1

C 'In TEST1' Dsply

C TestData Dsply

C Eval *InLR = *On

* Program TEST2 - Demonstrates effect of mistreating parametersD Part1 S 15

C *Entry PList

C Parm Part1

C 'In TEST2' Dsply

C Parm Dsply

C Eval Part1 = *Blanks

C Parm Dsply

C Return



12/23

D TaxCalc PR ExtPgm('PX027C')

D GrossPay 8 2

D Allowances 8 2

C CallP TaxCalc( GrossPay : Allowances )

Parameter mismatches can become a thing of the past!

The compiler will validate your program calls by checking:The number of parameters

Their data type and size

Prototypes can accommodate differences in data definition

For example, allowing an integer to be passed when the callee expectsa value with decimal places

They can also allow a different name to be used on the call

Helps in documenting the function

Call is implemented by the new freeform op-code - CALLP

Prototyping Program Calls

One of the really annoying problems with RPG III is that errors with parameter lists are notdiscovered until run-time. It would be much better if we could have the compiler validate theparameter lists for us.

Prototypes were added to the RPG IV language in the V3R2 and V3R6 releases. Although theirinitial purpose was to support Prototyping of Subprocedures (more on these later) the RPGdevelopers realized that they could be used to provide this support. As you'll see they also provideda number of other capabilities as well.

The type of error that can result from the incorrect use of parameters can often cause RPGprogrammers sleepless nights and a difficult debugging tasks.

For example:A 20 character field was expected but only a 10 character field was passed.

The called program is modified and now moves blanks to the field instead of the 10 character field it used tomove in. This results in a corruption of data in the calling program.

A character field is expected but a signed numeric is passed.A situation like this can continue for years since the internal representation of a character "1" is identical to

the representation of the value 1 in a signed numeric field. A programmer makes a "simple change" andpasses a different numeric parameter. Suddenly the called program starts producing incorrect output. Why?Because the new parameter while numeric is a packed field and the representation of the digit 1 is now completelydifferent causing the called program to fail to recognize it correctly.

In this section we will look at some of the powerful options that prototypes give us to deal withsituations such as these.

The important thing to note is that because the compiler is now able to validate parameters, errors ofthe kind described above cannot occur



13/23

C Call 'PX027C'

C Parm GrossPay

C Parm Allowances

Simple Prototype Example

If we are using these field definitions:

Then the following CALL sequence:

Can be replaced by this Prototype and CALLP

D GrossPay 8S 2

D Allowances 8S 2

D TaxCalc PR ExtPgm('PX027C')D Gross 8S 2

D Allow 8S 2

C CallP TaxCalc( GrossPay : Allowances )

In our example the prototype has been hard coded in the calling program.

Normally we would expect to see it being /COPY'd in from a source file supplied by the programmerwho wrote PX027C. It is good practice to always produce a prototype when coding a new program.Who knows better what parameters the program is expecting? For existing programs, code theprototype when you next do maintenance.

While it may seem like more work at first glance, it is important to remember that one of our aims isto reduce the opportunity for errors to be introduced during maintenance.

With a prototype in place, any change in the size and/or type parameters which in a conventionalCALL/PARM situation would produce an error, with CALLP will be detected by the compiler and willtherefore never get into production.

There are two main parts to a prototypeThe first line is the PR line itself

This supplies the name of the program or procedure to be called

It also marks the beginning of the parameter list

The second and subsequent lines describe the parameters in sequenceThe parameters are identified by a blank in positions 24-25 just as the subfields of a data structure are.

The parameter list is terminated by the appearance of any non-blank entryFor example a DS, S, C, PI (more on this later) or another PR

Note that the names used for the parameters do not match the names of the fields in the CALLPIn fact they could be completely blank and the compiler would be quite happy

It only cares about the number and type of parameters - the names used are irrelevant

Some people use a standard whereby the name used in the prototype identifies the type of fielde.g. Currency, Integer, Name, etc.



14/23

D TaxCalc PR ExtPgm('PX027C')

D GrossAmount 8S 2 CONST

D AllowanceAmount 8S 2 CONST

: : :

D Gross S 7P 2

D Base S 6P 2

D PersAllow S 5P 4

: : :

C CallP TaxCalc( Gross : Base + PersAllow )

C* Eval Temp1 = Gross

C* Eval Temp2 = Base + PersAllow

C* CallP TaxCalc( Temp1 : Temp2 )

Read-only Parameters

Specified by the keyword CONST

Implies that the called program will not modify the fieldi.e. It will treat the parameter as Read-only

Allows the compiler to generate temporary fields when neededFor example if the size and/or type of the parameter don't match exactly

It also allows an expression to be used instead of a variable !

The use of the CONST keyword allows the compiler to accommodate mismatches in the definition of

the parameters between the callee and the caller.For example, the program we are calling expects a packed decimal value of five digits with nodecimal places, but the field we would like to use as a parameter is a three digit signed numeric.

Normally we would have to create a temporary variable (packed - five digits) and move the threedigit number to it. We would then pass the temporary field as the parameter. In fact the PARMop-code provides this support though the use of Factor 2.

When you use the CONST keyword, you are telling the compiler that it is OK for it to make a copy ofthe data prior to passing it to accommodate such mismatches. This avoids the need for us toexplicitly define a working variable of the correct size and type.

The compiler can accommodate differences in:For Numeric fields: Size, decimal places, and type (zoned, packed, integer, etc.)

For Date fields: The date format

For Character fields: Length and type (fixed or varying)

Another benefit of using CONST is that it also allows an expression to be passed as a parameter.



15/23

What Else Can Prototypes Do?

They are the key to many APIs shipped with the AS/400

The C function libraryWhich includes:

Random number generationMath functions (Sin, Cos, Tan, etc.)

MI instructions (MI programming in RPG!)

Much more. . .

TCP/IP functionsYou can use TCP/IP Sockets functions directly from RPG

ILE APIsFor Dynamic Memory, Error Handling and more

System APIsMost new system APIs are written with the C programmer in mind

For example the Domino Hi-Test APIs

Prototypes can also be used to call procedures in other languages, most notably C. This means that

RPG IV programs now have access to all the functions in the C function library, which is shipped aspart of OS/400 on all systems. Other system APIs, previously available only to C programmers,such as TCP/IP sockets and direct program access to the IFS, are also enabled by the prototypingsupport associated with subprocedures.

Referring back to the QCMDEXC example, you might be interested to know that through the powerof prototyping the C "system" function is available. Some people prefer this to using QCMDEXC inthat it allows a more direct determination of the sucess/failure of a command. More on this later.



16/23

Using Simple C Math Functions

Functions are available for Sine, Cosine, Tan, ArcTan, etc.

Here are sample prototypes for Sine and Cosine

Both return a double length floating point valueThese are the C definitions

double sin(double x)

double cos(double x)

These translate in RPG IV to the following:

D Sine PR 8F ExtProc('sin')

D Double 8F Value

D Cosine PR 8F ExtProc('cos')

D Double 8F Value

* Once the prototypes are defined, the functions can be used just* as if they were built into RPG IV. Like this:

C Eval SineX = Sine(X)

C Eval CosineY = Cosine(Y)

C math functions include acos, asin, atan, cos, cosh, sin, sinh, tan, tanh. All accept double floating

point parameters (8F in RPG IV) passed by value, and all return a double floating point value.

It may seem to you that these kinds of math functions are rarely used in RPG programs, and you areright. However, on those occasions when they are needed then you will really appreciate the factthat you don't have to try and "fake" the function out in RPG.

The new RPG Redbook (referenced later in this handout) includes an example of these C functionsin action.



17/23

Is that all there is to it ?

There are two more things we need to do to use C functions

First we must specify that the program is a "real" ILE oneWe do this by specifying DFTACTGRP(*NO)

Second we must bind the C library functions to our programThe easy way is to specify QC2LE as the Binding Directory

This saves us from having to worry about which Service Program(s) contain thefunctions we need.

Embedding the parameters on the H-spec works well

You won't forget them that way !

You can also specify an Activation Group if you wishOtherwise the default will be QILE

H BndDir('QC2LE') DftActGrp(*No)

C function calls are bound calls and can only be used from "real" ILE programs, as opposed to the

OPM compatible programs produced by DFTACTGRP(*YES). So we have to specifyDFTACTGRP(*NO)

Note that if you are compiling the program with the CRTBNDRPG command, when you first promptthe command you will not see the Binding Directory parameter. This will not appear until you haveentered *NO for the DFTACTGRP parameter - not even if you press F10.

IBM supplies a Binding Directory for each compiler. These are used to allow the Binder to locate therequired run-time routines. The compiler automatically passes the name of this Binding Directory tothe Binder, there is no need for the programmer to specify it.

The C compiler operates in a similar fashion. The name of its Binding Directory is (you guessed it!)QC2LE. By specifying that Directory we enable the Binder to link us to the C run-time library as wellas the RPG one.

If we want to run the program in an Activation group other than QILE we can specify the ACTGRPparameter on the H spec.



18/23

D TrgBufferLen S 10I 0

D ORecord E DS Based(TOldPtr) ExtName(Product)

D Prefix(O_)

D NRecord E DS Based(TNewPtr) ExtName(Product)

C *ENTRY PLIST

C PARM TrgBuffer

C PARM TrgBufferLen

C Eval TOldPtr = %ADDR(TrgBuffer) + TOldOffSet

C Eval TNewPtr = %ADDR(TrgBuffer) + TNewOffSet

Mapping Trigger Buffers

A very practical use of pointers

Use externally described DS(s) to map record images to field namesUse pointers to base the DS and map it to the trigger buffer

Much simpler and safer than laying out the whole buffer

And changes in V5 render many such hard coded solutions obsoleteIn fact they may not even work !!

We haven't got the time to teach you about Triggers, but those of you familiar with them may find thisexample of mapping the Before and After buffers useful.

V5R1 introduced a "small problem" for some users of triggers. Although IBM has always said thatthe offsets should be used to locate the record images, many RPGers have continued to hard codetheir data structures on the assumption that they would follow the 16 byte reserved area. It seemsthat at V5R1 this can no longer be guaranteed. On the following pages we will show you how to do itthe safe way using pointers and the image offsets.

Through the use of pointers and based externally described data structures, as illustrated in thisexample, you can make the programming to map the trigger buffer record images to record formatfield names a breeze! Note that we have prefixed the field names in the data structure for the oldrecord image with O_ to distinguish them from the fields in the new record image.

If your records include null capable fields, you can map the null flag array in a similar fashion.

Note that this example uses pointer addition, which was introduced into the compiler at V3R7. Youcould still use pointers on systems prior to V3R7, but it would require some additional code to set thepointer addresses.

Note: Of course, the TrgBufferLen field would need to be defined on a D spec (as a 10 I) somewherein the program. It was omitted from this example due to space considerations. Also, note that Fieldsis a named constant containing the number of fields in the record format. Unfortunately, the value ofthis field must be manually set for each case. If (as in our application's case) there are no nullcapable fields in the record format, you could omit all the null map information.



19/23

/IF DEFINED(TESTING)

* Insert special degugging code here

/ENDIF

/IF DEFINED(CANADA)

* Canadian tax calcs

/ELSEIF DEFINED(MEXICO)* Mexican tax calcs

/ELSE

* USA tax calcs

/ENDIF

Conditional Compilation Directives

Used to condition which source lines are compiled

For example to only include additional debug logic when testing

Conditions can be set on the compile commands

Or in the source itself via the /DEFINE directiveMore on this in a moment

The examples on this chart will rely on the condition (e.g., Testing, Canada, Mexico) being set on

the compile command - either CRTBNDRPG or CRTRPGMOD.

On the next charts, we will have some examples of setting the condition inside the source memberitself.



20/23

/DEFINE DSPEC

/COPY CopyCode

< Only the D spec code will be copied here

/UNDEFINE DSPEC

. . ./DEFINE CSPEC

/COPY CopyCode

< and only the C spec code here

/IF DEFINED(DSPEC)D MyData .............

D MoreData ...........

/ENDIF

/IF DEFINED(CSPEC)

C Eval MyData = MyData + 1

C Eval MoreData = 0

/ENDIF

If the member COPYCODEcontains this:

Then the main programcan do this:

Conditional Compilation Directives

This technique allows multiple source types (e.g. D & C specs) in asingle /COPY member.

Because RPG IV does not support the specifcation sorting feature of RPT member types, using

Conditional Compiler Directives like these provide a workaround to meet this need. It is necessaryto put 2 /Copy statements in the program (such as in the bottom example). But it does still allow youto keep the D specs and the C specs in the same member to be copied in.



21/23

1 * Main program source

2

3 D MainProgData S 20A

4

5 /DEFINE DSPEC6 * Copy D specs only

7 /COPY CopyCode

*--------------------------------------------------------------

* RPG member name . . . . . : COPYCODE

* External name . . . . . . : HSBC/QRPGLESRC(COPYCODE)

* Last change . . . . . . . : 00/00/00 00:00:00

*--------------------------------------------------------------

8+

9+ /IF DEFINED(DSPEC)

10+ * Definitions used by Subroutine "Demo"

11+D MyData S 5P 0 Inz

12+D MoreData S 7P 0 Inz

13+ /ENDIF

14+ /IF DEFINED(CSPEC)

15+ /ENDIF

16+

17

18 D MoreProgData S 20A

19

20 /UNDEFINE DSPEC

Note that the compilerdirectives are printed butno C-Specs are copied

Identification of Copymember is printed asnormal

Sample Source Listing

21

22 * Regular C-specs

23

24 C Eval MoreProgData = MainProgData

25 C ExSr Demo

26 C Eval *InLR = *On

27

28 /DEFINE CSPEC

29 * Copy C specs only

30 /COPY CopyCode

*--------------------------------------------------------------

* RPG member name . . . . . : COPYCODE

* External name . . . . . . : HSBC/QRPGLESRC(COPYCODE)* Last change . . . . . . . : 00/00/00 00:00:00

*--------------------------------------------------------------

31+

32+ /IF DEFINED(DSPEC)

33+ /ENDIF

34+ /IF DEFINED(CSPEC)

35+C Demo BegSr

36+C Eval MyData = MyData + 1

37+C Eval MoreData = 0

38+C EndSr

39+ /ENDIF

40+

Again the compiler directivesare printed but no D-Specs.

Sample Source Listing (Cont.)



22/23

/If Not Defined(OnlyProtos)

H DatFmt(*ISO) NoMain

/EndIf

D EndOfMonth Pr D DatFmt(*ISO)

D WorkDate D DatFmt(*ISO) Value

/If Defined(OnlyProtos)

/EOF

/EndIf

Conditional Compilation & Prototypes

Code the Prototype(s) directly in the subprocedure source

Then use conditional compilation directives to "extract" them for use inprograms that will use the procedure(s).

When /Copy'd with the "OnlyProtos" condition set

The H spec is ignored

The Prototype is copied

The compiler skips to end-of-file and continues with the main source

The chart above shows the relevant portion of the subprocedure source file.

When compiling this source we would not set the "OnlyProtos" condition. The compiler proceeds asfollows:

The test IF NOT DEFINED(OnlyProtos) is true (because the condition is not set) and the H-spec istherefore included in the compile.

The second directive IF DEFINED(OnlyProtos) is not true and so the compiler ignores the linesenclosed within the IF/ENDIF and therefore will not jump to the end of file but rather will continueprocessing the source as normal.

Any program that wishes to use the subprocedures contained in the source member can do so byincluding code similar to the following:

/Define OnlyProtos

/Copy sourcefilename



23/23

Check out the RPG IV Redbook

Who Knew You Could Do That

with RPG IV?A Sorcerer's Guide to System Access andMore

SG24-5402

International Technical Support Organization

Rochester, Minnesota

IBM Redbook SG24-5402

You can read it on-line, download thePDF file, or order hardcopy

Includes worked examples ofTCP/IP Sockets

CGI programming

Using the C function library

ILE Error handling

and much more ....

Don't forget to download the source filesfor the examples!

Use our link to get easy instructions ondownloading everything from IBM's site:www.partner400.com/RPGRedbook.htm

did you know [pdf library]

Documents