synon cool2e Parameters

VIRGIL GREEN 1 SYNAPTECH CONSULTING

“I am functioningwithin

established parameters.”

(But then, if you work in Synon

you don’t have a choice.)

- Lieutenant Commander Data


What are parameters?

Primary vehicle for function communication in Synon Pervasive - even moving data from one field to

another requires parameters Two types: Formal and Actual

• Formal Parameters– Define interface for a function

– Control flow of data from function to function

• Actual Parameters– Define values passed from one function to another

– Vary with each reference (call) to a function


Defining the “formal” parameter

Sets - buckets of things (fields) Passed As - types and shapes of buckets Entries - what’s in the buckets? Usage - do the things in the buckets bite? Role - if they bite can you get sick too? Error Flagging - if they don’t bite, do they

scream when you grab them?


Parameter Sets Access by using ‘P’ option on a function Up to 9 buckets (sets) can be used You can fill your bucket from

• An Access Path• A File Definition• Any Field in the Model• An *Array

Use each set or bucket for a particular Purpose For CRT/CHG/DLTOBJ functions, the first set must

contain database fields for implicit *Move all to work


Function ParametersEDIT FUNCTION PARAMETERS MRT development model Function name. . : Clc Schedule Priority Type : Execute external function Received by file : Nomination Array: *NONE Passed ? File/*FIELD Array as Seq *Arrays Clc Sched Priority PRM FLD *Arrays Clc Sched Priority PRM FLD *FIELD Count FLD *FIELD Save Array Index Y FLD *FIELD NLK Job Lock Level FLD *FIELD Job name FLD *FIELD User FLD *FIELD Job Number FLD | 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


Understanding “Passed As”

Determines which fields from source are available Applies to a set and describes your bucket

• RCD - big buckets; sometimes hard to put things into

• KEY - smaller, specialized buckets; still hard to fill

• FLD - a bucket of buckets; only one thing to a bucket- required when using *Arrays, *Field, or

*None access path

Does not affect internal functions FLD is recommended for external functions


RCD, KEYand the External function

Causes a data structure to be passed which both caller and called must map internally

Data structure is always the length of the entire key or record structure whether all fields are used or not

Hex problems when numeric parameters are involved and program is called from command line, menu, or CL

A B ED GC F

Entire structure passed as one physical parameter ...

... even if only these fields are used


FLD and the External function

Uses separate physical parameter for each defined parameter

Allows greatest flexibility for calling from different sources

B

C

D

F

A E G

Only fields needed are passed as separate physical parameters

Unwanted fields are ignored


Parameter Set Entries

Drawn from the list of fields identified by a set Any subset of fields in the set can be used Each field can have different role and usage but it is

recommended that you standardize set usage When using *FIELD to declare the set there is only

one entry for the set


Parameter Entries

EDIT FUNCTION PARAMETER DETAILS MRT development model Function name. . : Clc Schedule Priority Type : Execute external function Received by file : Nomination Array: Clc Sched Priority PRM Parameter (file) : *Arrays Passed as: FLD ? Field Usage Role Flag error Contract ID I NM Received Date I NM Received Time I Service Type Latest Eff Date for Nom Effective MDQ Remaining MDQ Distribute Zone Cap? Distribute Z-L Prty? Distribute Point Cap? Priority Level PT Path Type Tot Nom MMBtu Counter + 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


Understanding Usage

Controls the direction of data flow on function calls Four different kinds of Usage:

• Input - hears but cannot speak

• Output - speaks but cannot hear (may bite)

• Both - hears and speaks with aplomb

• Neither - quiet and keeps to itself


InputFinally, someone who will listen

For data coming into function Try to avoid using these to let the calling function

direct processing in the called function Function should be able to perform based on data

rather than external decisions Cannot be changed by function


OutputJust like a teenager, never listens

For data going out Function should guarantee that a value is set If on an external function, automatically initialized by

the calling Synon function Cannot be referenced by function

• Cannot be used as accumulator

• Cannot be passed to subordinate function


BothListens and jabbers, just like a talk show host

For data going in to be modified and then returned Avoid using as an accumulator since the data (total) is

really going out, not in and out Reserve these for when data is being sent into a

function explicitly to be modified in some way


NeitherNever swayed by the outside world

May be used as a local variable Good choice for accumulator; better than Both Allows reference and change but calling function

cannot see it Can be passed to and received from subordinate

functions but higher level functions cannot change or reference value

Automatically initialized to blanks or zeros Not included in implicit *Move All from PAR to DB1


Tricky things about Usage

A field may not be used more than once unless it is used once for input and once for output• This is not recommended because the two parameters appear

to be a single parm - either a both or a neither

Output parameters on create and change object functions are automatically loaded if the parameter is a database field

Calling functions should take care to not use the same actual parameter for both an input and an output formal parameter


Understanding Role

Controls how the passed value of the parameter affects functions actions

Five different roles:• None (or blank) - leaves it just for you

• Restrictor - gets you just what you ask for

• Positioner - always starting something

• Mapped - likes to pass the buck

• Vary - used to let you break the rules


RestrictorKeeps your function from running away

Any higher order keys must also be restrictors Limits set of data to be accessed by limiting to high

order keys Used on all function types except messages,

Excintfun, Excextfun, and Excusrsrc If high order key is also foreign key, causes relation to

be validated before screen is displayed. Allows display of virtual fields without having them

on the based-on access path


PositionerA nice way to start something

Any higher order keys must be restrictors or positioners

Allows you to start at a certain position in the index• processing starts at specified or next available item in index

There is nothing available to stop processing Used on Rtvobj, Prtfil, and Prtobj Multiple positioners allow starting point within

multiple continuous variables• Start at first record after a given Date and Time


MappedHelps data find its way to the screen

Used only on *External functions with screens Moves data from parameter to screen field Places field on screen if not already there

• In Control record for Edtfil, Edttrn, Dspfil, and Dsptrn

• In Detail record for Pmtrcd, Edtrcd, and Dsprcd

• Neither Mapped parms allow database fields that are not on based-on access path to be placed on screen

Initializes screen field with value• In Control, Subfile, and Detail record on all function types


VaryLets you get by with just about anything

Turns off domain checking but still requires character/numeric compatibility

Not necessary since release 4.0, but recommended Only valid for Excusrsrc, Excusrpgm, Excextfun, and

Error messages Allows easier integration with non-Synon programs Useful for including field value in generic error

messages


Understanding Error Flagging

For Error Messages• Causes screen fields passed in to have error attribute set

For *External Functions• Causes screen fields passed in to have error attribute set if

*Return code comes back not *Normal

By default error flagging is on Error checking prone to change can be externalized Turn off to include screen field in error message

without turning on field’s error attribute


How parameters are implemented

Passing by reference vs. passing by value• Passing by reference means that the field or data passed into

the function are accessed and changed directly by the subordinate function

• Passing by value means that the original field or data is not directly accessed, but a copy is made into a temporary field which is then referenced or changed

Passing by value protects the data in the calling function from possible failures in called function which could leave a set of values partially changed


Parameters on *Internal functions

Passed by reference Called function has direct access to field passed into it Generated code actually uses field or constant passed

in wherever the parameter is referenced Allows you to issue error messages from deep inside

nested internal functions and still set error attributes on screen


Parameters on *External functions

Passed by value Actual AS/400 level implementation is pass by

reference Synon “shields” us from AS/400 implementation by

placing values in temporary variables when calling a program


Actual parameter defaulting

At generation time, Synon will attempt to default a context and field for any parameter on a called function for which a parameter has not been specified

Allows use of fields other than keys for F4 prompt functions

Can reduce maintenance time by not requiring a visit to every action diagram that calls a function whose parameters have changed

Be cautious about relying on this; understand it first


What we would like to see

Local variables other than Neither parms Option to exit without save when mistakes are made Verification of value assignment Ignore feature to discard unwanted, returned values Expanded sets without having to use Arrays

Documents

synon cool2e Parameters