Session AD081

Advanced Array Handling in COOL:2E

Virgil Green SynapTech Consulting
vjg@obsydian.com www.obsydian.com

April 18-21, 1999 Adams Mark Hotel Dallas, TX

Agenda
Using External Arrays Displaying or Editing an Array Printing Arrays Printing with Level Breaks Templating record structures Array Gotchas

External Arrays
Access to array shared by all programs in the same job Allows array contents to be passed from one program to

another
Array server program houses the contents of the array and

provides services for accessing the array

Array Service Wrappers provide standard parameter

interfaces to hide the non-standard server program interface

Array server program

Implement as an EXCEXTFUN Specify Closedown No function option By not closing down, subsequent calls within the same job

will execute the same instance of the program

Generated code does not initialize arrays on subsequent

calls to the function

Array services are simply calls to traditional Create, Change,

Delete and Retrieve functions built on the array

Array Services
Clear - calls DLTOBJ with no parameters to clear the array Create - calls CRTOBJ built over the array Change - calls CHGOBJ built over the array Delete - calls DLTOBJ built over the array Retrieve - calls RTVOBJ built over the array Count - calls RTVOBJ that reads all the records in the array,

counts them, and returns the total

Retrieve Next - calls RTVOBJ built over the array positioning

with the key values of the previous record

All but the last are traditional functions

Retrieve Next Service

Positions on the array using previous record keys as Input

Positioner parameters
Returns retrieved keys in separate Output parameters Non-key attributes are also returned in Output parameters

Reads for the next non-matching key

Important to remember that you need to control the exit of

the function and the reporting of Record not found.

Parameter sets for a Retrieve Next

EDIT FUNCTION PARAMETERS Function name. . : Rtv Nxt ShScSmRR Received by file : *Arrays ? File/*FIELD *Arrays *Arrays *Arrays SYS/2000 DEVELOPMENT Model Type : Retrieve object Array: Shp Scd Smry Rng-Rail Passed Access path/Field/Array Seq Shp Scd Smry Rng-Rail KEY p:Scd Smry FLD 20 Shp Scd Smry Rng-Rail FLD 20

| Values FLD: One parameter per field RCD: One parameter for all fields KEY: One parameter for key fields only
SEL: Z-Details (field selection). F3=Exit F5=Reload F21=Copy from *Template

Positioning the Retrieve Next

EDIT FUNCTION PARAMETER DETAILS SYS/2000 DEVELOPMENT Model Function name. . : Rtv Nxt ShScSmRR Type : Retrieve object Received by file : *Arrays Array: Shp Scd Smry Rng-Rail Parameter (file) : *Arrays Passed as: KEY ? Field Usage Role Scd Dte Type U I RST Lcn Cde I POS Carr Cde I POS Leased Car? U I POS Com Cde I POS Grd Cde I POS Scd Date U I POS

SEL: Usage: I-Input, O-Output, B-Both, N-Neither, D-Drop. Role: R-Restrict, M-Map, V-Vary length, P-Position. F3=Exit

New key from Retrieve Next

EDIT FUNCTION PARAMETER DETAILS SYS/2000 DEVELOPMENT Model Function name. . : Rtv Nxt ShScSmRR Type : Retrieve object Received by file : *Arrays Array: p:Scd Smry Parameter (file) : *Arrays Passed as: FLD ? Field Usage Role Next Lcn Cde U O Next Com Cde U O Next Grd Cde U O Next Scd Date U O Next Carr Cde U O Next Leased Car? U O

SEL: Usage: I-Input, O-Output, B-Both, N-Neither, D-Drop. Role: R-Restrict, M-Map, V-Vary length, P-Position. F3=Exit

New data from Retrieve Next

EDIT FUNCTION PARAMETER DETAILS SYS/2000 DEVELOPMENT Model Function name. . : Rtv Nxt ShScSmRR Type : Retrieve object Received by file : *Arrays Array: Shp Scd Smry Rng-Rail Parameter (file) : *Arrays Passed as: FLD ? Field Usage Role Scd Dte Type U Lcn Cde Carr Cde Leased Car? U Com Cde Grd Cde Scd Date U Scd Open Rail Cnt U O

SEL: Usage: I-Input, O-Output, B-Both, N-Neither, D-Drop. Role: R-Restrict, M-Map, V-Vary length, P-Position. F3=Exit

10

No Data in a Retrieve Next

> USER: Processing if Data record not found .-. . ** Clear the output fields . PAR = CON By name . '

> USER: Exit processing .-. . ** We didn't exit so we must have not found a "next" record . PGM.*Return code = CND.*Record does not exist . . ** Clear the output fields . PAR = CON By name . '

11

The heart of the Retrieve Next

> USER: Process Data record .-. > Skip record matching positioning criteria; select any other . .-CASE . > Record matches positioning data . - c1 AND c2 AND c3 AND c4 AND c5 AND c6 . - c1: DB1.Scd Date U EQ PAR.Scd Date U . - c2: DB1.Lcn Cde EQ PAR.Lcn Cde . - c3: DB1.Com Cde EQ PAR.Com Cde . - c4: DB1.Grd Cde EQ PAR.Grd Cde . - c5: DB1.Carr Cde EQ PAR.Carr Cde . - c6: DB1.Leased Car? U EQ PAR.Leased Car? U . '. -*OTHERWISE . . ** Return the data . PAR = DB1 By name . . ** Return the keys of the record returned . PAR.Next Scd Date U = DB1.Scd Date U . PAR.Next Lcn Cde U = DB1.Lcn Cde . PAR.Next Carr Cde U = DB1.Carr Cde . PAR.Next Leased Car? U = DB1.Leased Car? U . PAR.Next Com Cde U = DB1.Com Cde . PAR.Next Grd Cde U = DB1.Grd Cde . . ** Exit after returning data . <-- *QUIT . '-ENDCASE '

12

Encapsulating the Services

The Array server program contains calls to each of the

services
A Service indicator Input parameter is necessary to request

the appropriate service from the server program

A Count Output parameter is necessary if you wish to

implement the count service

All array fields must be defined as Both parameters to allow

them to be used by the create, update and retrieval functions

A multi-condition Case statement is used to select

processing based upon the service requested

Service return code is returned to caller

13

Service Indicator values

EDIT FIELD CONDITIONS SYS/2000 DEVELOPMENT Model Field name. . . . . : Array Service Attr. : STS Position . . . . . : Enter condition . . : and type to add new condition. type . : (Type: LST, VAL)

? Condition *ALL values Build Change Clear Count Create Delete Retrieve Rtv Nxt

Type Op File/From value LST ** VAL B VAL H VAL L VAL O VAL C VAL D VAL R VAL N

Display/To value
B H L O C D R R

MN

SEL: Z-Details, D-Delete, U-Where used, N-Narrative. F3=Exit

14

Server program parameter sets

EDIT FUNCTION PARAMETERS Function name. . : Srv ShScSmRR Received by file : Nbr ? File/*FIELD *FIELD *FIELD *Arrays SYS/2000 DEVELOPMENT Model Type : Execute external function Acpth: *NONE Passed Access path/Field/Array Seq Array Service FLD 10 Count Total FLD 20 Shp Scd Smry Rng-Rail FLD 30

| Values FLD: One parameter per field RCD: One parameter for all fields KEY: One parameter for key fields only
SEL: Z-Details (field selection). F3=Exit F5=Reload F21=Copy from *Template

15

Server program parameters (merged)

EDIT FUNCTION PARAMETER DETAILS Function name. . : Srv ShScSmRR Received by file : Nbr Parameter (file) : *FIELD ? Field Array Service . . . Count Total . . . Scd Dte Type U Lcn Cde Carr Cde Leased Car? U Com Cde Grd Cde Scd Date U Scd Open Rail Cnt U SYS/2000 DEVELOPMENT Model Type : Execute external function Acpth: Array Service Passed as: FLD Usage Role Flag error I O B B B B B B B B

SEL: Usage: I-Input, O-Output, B-Both, N-Neither, D-Drop. Role: R-Restrict, M-Map, V-Vary length, P-Position. Error: E-Flag Error. F3=Exit

16

Server program logic

> Srv ShScSmRR .-. ** Perform requested service . .-CASE . -PAR.Array Service is Clear . Clr ShScSmRR - *Arrays * . -PAR.Array Service is Create . Crt ShScSmRR - *Arrays * . -PAR.Array Service is Change . Chg ShScSmRR - *Arrays * . -PAR.Array Service is Delete . Dlt ShScSmRR - *Arrays * . -PAR.Array Service is Retrieve . Rtv ShScSmRR - *Arrays * . -PAR.Array Service is Rtv Nxt . Rtv Nxt ShScSmRR - *Arrays * . -PAR.Array Service is Count . Cnt ShScSmRR - *Arrays * . '-ENDCASE . . ** Return any return code to caller . *Exit program - return code PGM.*Return code '
17

Service Wrapper functions

Both type parameters on Server function require calling

function to use fields that can be passed properly

Wrapper functions allow you to normalize the interface

based upon the type of service you are requesting

LCL context fields can be initialized from Input parameters,

passed to/from the Server program, and then moved into Output parameters
Must be built over a file other than *Arrays - only

CRT/CHG/DLT/RTV allowed on that file

Use same parameter interface as actual Service function

called inside the Server function

18

Create Service Wrapper code

> Crt ShScSmRR .-. ** Load all data into LCL fields . LCL.Scd Dte Type U = PAR.Scd Dte Type U . LCL.Lcn Cde = PAR. Lcn Cde . LCL.Carr Cde = PAR. Carr Cde . LCL.Leased Car? U = PAR. Leased Car? U . LCL.Com Cde = PAR. Com Cde . LCL.Grd Cde = PAR. Grd Cde . LCL.Scd Date U = PAR. Scd Date U . LCL.Scd Open Rail Cnt U = PAR. Scd Open Rail Cnt U . . ** Request Create Service . Srv ShScSmRR - Nbr * '--

19

Retrieve Next Service Wrapper code

> Rtv Nxt ShScSmRR .-. ** Load all keys into LCL fields . LCL.Scd Dte Type U = PAR.Scd Dte Type U . LCL.Lcn Cde = PAR. Lcn Cde . LCL.Carr Cde = PAR. Carr Cde . LCL.Leased Car? U = PAR. Leased Car? U . LCL.Com Cde = PAR. Com Cde . LCL.Grd Cde = PAR. Grd Cde . LCL.Scd Date U = PAR. Scd Date U . . ** Request Retrieve Next Service . Srv ShScSmRR - Nbr * . . ** Move retrieved key into PAR . PAR.Next Scd Date U = LCL. Next Scd Date U . PAR.Next Lcn Cde U = LCL. Next Lcn Cde U . PAR.Next Carr Cde U = LCL. Next Carr Cde U . PAR.Next Leased Car? U = LCL.Next Leased Car? U . PAR.Next Com Cde U = LCL.Next Com Cde U . PAR.Next Grd Cde U = LCL.Next Grd Cde U . . ** Move returned data into PAR . PAR.Scd Open Rail Cnt U = LCL.Scd Open Rail Cnt U '-20

The Nbr file

Is a single-field file containing a list of consecutive numbers A new RSQ access path with a descending key makes it easy

to build functions that process a specific number of records

A special Check function is used to see if the number of

records you need is in the file and, if not, creates the records
Create as an EXCEXTFUN so it can be called by functions

that might be running under commitment control

21

The Chk/Gen Nbr function

> Chk/Gen Nbr .-. . ** Check to see if there are as many records in the file . as needed. . Chk Nbr - Nbr * . > If the number needed is not found, generate backwards . .-CASE . -...NOT PGM.*Return code is *Normal . . ** Start at the number needed . LCL.Nbr next = PAR.Nbr needed . . > Build missing records until end of existing range is hit . .=REPEAT WHILE . |-PAR.Nbr next is GT 0 . |

. . . Continued on next slide . . .

22

The Chk/Gen Nbr function - continued

. . . Continued from previous slide . . .

. | ** Create the next record in the sequence . | Chk Nbr - Nbr * . | > If found, quit building; if not found, create the record . | .-CASE . | -PGM.*Return code is *Normal . | *Exit Program - return code CND.*Normal . | -*OTHERWISE . | Create Nbr - Nbr * . | '-ENDCASE . | . | ** Decrement to prepare the next record . | LCL.Nbr next = LCL.Nbr next - CND.1 . | > Exit if we hit zero (or less) . | .-CASE . | -...NOT LCL.Nbr next is GT 0 . | *Exit Program - return code CND.*Normal . | '-ENDCASE . '-ENDWHILE . '-ENDCASE '-23

Displaying an array in a subfile

May use internal or external arrays DSPFIL built over the Nbr file - data to be displayed is added

as user fields on the screen

Uniquely keyed arrays must be used

Array must be keyed in the desired presentation sequence -

a surrogate may be used to create a unique key

Retrieve Next service is required in the Initialise subfile

record user point to retrieve the array data for each displayed record
Build DSPFIL over Descending Nbr access path, positioning

using the number of entries in the array

24

DSPFIL details
In Initialize Subfile Control, Program Initialization, or a

previous program (if using external arrays), load the array in the most efficient manner
Count records in the array, either by making a pass through

the array or by counting them as they are created

In Initialize subfile control, clear the fields used to hold last

array key(s)
In Initialize subfile record, use last array key(s) and call

Retrieve Next function (whether internal or external) to get record data

Multiple arrays can be displayed in a single subfile

25

Two arrays displayed in a single subfile

SCHA00 DISPLAY Shipping Schedule Summary 3/04/99 19:24:34 REG/LOC: XXX /YYY ENVIRONMENT: TEST From 111098 To 111698 Lcn YYY Dtl Prd 5=Display Schedule for Day |-- Scheduled --| |--- Shipped ---| ? Date To Date Lcn Dtl Prd Rail Truck Other Rail Truck Other 11/10/98 YYY ZZM255 1 0 0 0 0 0 11/10/98 YYY ZZ401 1 0 0 0 0 0 11/11/98 YYY ZZF600 0 1 0 0 0 0 11/11/98 YYY ZZM250 0 1 0 0 1 0 11/11/98 YYY YYM 0 0 0 2 0 0 11/12/98 YYY ZZM250 0 1 0 0 0 0 11/13/98 YYY ZZM250 0 2 0 0 0 0 11/13/98 YYY ZZM255 2 0 0 0 0 0 11/14/98 YYY YYM 1 0 0 0 0 0 11/15/98 YYY ZZM250 0 1 0 0 0 0 11/16/98 YYY ZZF600 0 1 0 0 0 0 11/16/98 YYY YYM 1 0 0 0 0 0 11/10/98 11/11/98 YYY ZZF600 0 1 0 11/10/98 11/13/98 YYY ZZM250 0 1 0 11/14/98 11/15/98 YYY ZZM250 0 3 0 11/16/98 11/16/98 YYY ZZM250 0 1 0 Bottom F3=Exit F12=Previous
26

Loading arrays when Subfile loaded

> USER: Initialize subfile control .-. ** Load all data for requested criteria . Send status message - 'Building Summary Data...' . Bld ShScSm Data - Sls Shp * . . ** Get count of records to display . Add the counts from both arrays to get nbr of rcds to process. . Cnt ShScSmD - *Arrays * . Cnt ShScSmR - *Arrays * . CTL.nbr = LCL.Nbr Date-specific rcds U + LCL.Nbr Range rcds U . . > If data available, verify Nbr rcds; else, position to EOF . .-CASE . -CTL.nbr is GT 0 . ** Verify/generate enough NBR records for display . Chk/Gen Nbr - Nbr * . -*OTHERWISE . ** Position to EOF (leaving zero would fail to position) . CTL.nbr = CND.EOF for Descending (a value of -1) . '-ENDCASE

. . . Continued on next slide . . .

27

and preparing to read arrays

. . . Continued from previous slide . . . . . ** Initialize fields used to detect change in criteria . CTL.Prv Scd Rng beg Dte U = CTL.Scd Rng Beg Dte U . CTL.Prv Scd Rng End Dte U = CTL.Scd Rng End Dte U . CTL.Prv Lcn Cde U = CTL.Lcn Cde . CTL.Prv Com Cde U = CTL.Com Cde . CTL.Prv Prd Cde U = CTL.Prd Cde . . ** Initialize keys for retrieving array records . LCL.Last Scd Date U = CND.not specified . LCL.Last Lcn Cde U = CND.not specified . LCL.Last Com Cde U = CND.not specified . LCL.Last Grd Cde U = CND.not specified . . ** Trigger reading of first array . LCL.Array being read U = CND.First '--

28

Reading the First array

> USER: Initialize subfile record from DBF record .-. > Handle reading of first array . .-CASE . -LCL.Array being read U is First . . ** Read the record to display . Rtv Nxt ShScSmD - *Arrays * . RCD.Scd Date U = LCL.Next Scd Date U . > Process record or trigger read of next array . .-CASE . -PGM.*Return code is *Normal . . ** Flag the type of record that is on the screen . RCD.Scd Dte Type U = CND.Date . . ** Process the record just read and perform record selection . . . . Continued on next slide . . .

29

 and handling first End of File

. . . Continued from previous slide . . .

. . . . . . . . . . . . . . . . . .

-*OTHERWISE ** No record returned from array, so EOF must have been hit. Set up to start reading the second array. ** Initialize keys for retrieving array records LCL.Last Scd Date U = CND.not specified LCL.Last Lcn Cde U = CND.*BLANK LCL.Last Com Cde U = CND.EQ *BLANK LCL.Last Grd Cde U = CND.*BLANK ** Trigger reading of second array LCL.Array being read U = CND.Second '-ENDCASE '-ENDCASE

. . . Continued on next slide . . .

30

 then reading the Second array

. . . . . . . . . . . . . . . ** Reset positioners for next read . LCL.Last Scd Date U = LCL.Next Scd Date U . LCL.Last Lcn Cde U = RCD.Lcn Cde . LCL.Last Com Cde U = RCD.Com Cde . LCL.Last Grd Cde U = RCD.Grd Cde . . ** Check against common record selection criteria . . ...If still selected, Process record '-31

. . . Continued from previous slide . . . > Handle reading of second array .-CASE -LCL.Array being read U is Second ** Read the next record Rtv Nxt ShScSmR - *Arrays * ** Flag the type of record that is on the screen RCD.Scd Dte Type U = CND.Range ** Process the record just read and perform record selection '-ENDCASE

Editing an array
Loading of the data into the subfile is just like in Displaying

an array
Calls to CRT/CHG/DLTOBJ functions are replaced by calls to

corresponding service wrapper functions

32

Printing simple arrays

Printing simple lists is very similar to building a DSPFIL Retrieve Next service is required in the Record selection

user point to retrieve the array data for each printed record
Use a Neither Positioner parameter to position on the Nbr file

to read the appropriate number of records

33

Printing arrays with level breaks

Nbr file concept must be expanded to include as many fields

as there are level breaks needed

Each Nbr file record contains the same value in each field on

the record - but still key by a single field

Multiple access paths are created to accommodate different

numbers of needed level breaks

Every Nbr record read initiates all level breaks Retrieved array record is analyzed to determine whether a

real level break has occurred

Totaling and level break processing occurs as usual

34

Setup for printing with level breaks

> USER: Initialize program .-. ** If using internal array, load the array . . ** Get the count of the array (passed in, calculated, whatever) . . ** Chk/Gen necessary records . . ** Set all positioner keys to number of array entries . . ** Initialize *Last array keys to low (or high) values . . ** Initialize *Prv Nbr fields to zero '--

35

Abstract view of testing for level break

> USER: Record selection processing .-. ** Assume no level break . LCL.Brk Key U = CON.10 . . ** Rtv next Array record (whether internal or external array) . using *Prv array keys . . > Detect highest order level break . .-CASE . -LCL.Key 1 NE LCL.Prv Key 1 . LCL.Brk Key = CON.1 . -LCL.Key 2 NE LCL.Prv Key 2 . LCL.Brk Key = CON.2 . . . . . . . -LCL.Key 9 NE LCL.Prv Key 9 . LCL.Brk Key = CON.9 . '-ENDCASE . . ** Save current array keys as *Prv array keys . . ** Reset non-breaking keys . Reset Level Breaks (9) - Nbr for Break
36

Resetting level breaks

An EXCUSRSRC is used to turn off unneeded breaks A separate EXCUSRSRC needed for each number of keys to

be processed
PRTOBJs will require additional EXCUSRSRC functions

Define an input parameter to pass in the highest order key

that actually broke

Define Input parameters that match the keys of the Nbr file

access path
All higher order key breaks are suppressed by moving the

current DB1 field into the level break test field

37

EXCUSRSRC to reset Level Breaks

* RESET BREAK TEST VALUE FOR IF USR-PARM-I-AKTL > 1 MOVE USR-PARM-I-AJPX TO END-IF IF USR-PARM-I-AKTL > 2 MOVE USR-PARM-I-AKPM TO END-IF IF USR-PARM-I-AKTL > 3 MOVE USR-PARM-I-AKPN TO END-IF . . . Keys 4, 5, and 6 IF USR-PARM-I-AKTL > 7 MOVE USR-PARM-I-AKR9 TO WZA007 END-IF IF USR-PARM-I-AKTL > 8 MOVE USR-PARM-I-AKSA TO WZA008 END-IF IF USR-PARM-I-AKTL > 9 MOVE USR-PARM-I-AKSB TO WZA009 END-IF KEYS THAT DID NOT CHANGE WZA001

WZA002

WZA003

38

Templating record structures

Single element arrays can be used to build or break down

strings of data with fixed structures

Can be useful for reading or building EDI data or for

communicating with other systems that use multi-format files or program described data structures
Use CVTVAR with the ELM context to move a field to the

array element and then parse by executing a RTVOBJ

Use CRTOBJ to add a record to an array, then use CVTVAR

and ELM to move the array element to a field

Be sure to Clear the array before Creating a new record

39

Using ELM and Arrays to parse/build data

> Parse EDI format 145 .-. ** Move structured field into array for parsing . ELM.EDI format 145 Arr = CVTVAR(PAR.EDI format 145 data) . . ** Parse data by calling RTVOBJ . Rtv EDI format 145 - *Arrays * '--

> Build EDI format 722 .-. ** Clear EDI format array . Clr EDI format 722 - *Arrays * . . ** Build data by calling CRTOBJ . Crt EDI format 722 - *Arrays * . . ** Move array into structured field for parsing . PAR.EDI format 722 data = CVTVAR(ELM.EDI format 722 Arr) '--

40

Array Gotchas
Cannot use standard RTVOBJ to read through an array and

write records to the end of the same array

Cannot use standard RTVOBJ to read through an array and

change records other than current record in the same array

Cannot use standard RTVOBJ to read through an array and

delete either the current or another record in the same array

It is safe to change the current record in the array from within

a RTVOBJ
Using CRTOBJ or DLTOBJ and generating RPG can result in

an immediate keysort of the array causing poor performance

Be sure Array Server programs are Closedown No

41