7.33.1 DEFINE_MAP Parameters

FOR

CLASS

NAME

PASS

MANDATORY

DESC

HELP

FOR

Parameter will be received by the associated routine.

Allowable values are:

*Input
*Output
*Both
*Result

*Output

Parameter will be returned by the associated routine

*Both

Parameter will be received and subsequently returned by the associated routine.

*Result

Parameter will be returned by the associated routine.

*Result is only valid for a method routine, and only one *Result is allowed per Method. To return multiple results, use *Output.

A DEFINE_MAP of *Result indicates that a method routine has a defined result parameter. This is similar in concept to Intrinsic functions, and allows a method routine to be used as part of an expression.

CLASS

CLASS defines the type of value that is passed. The value of CLASS can be a repository-defined field. The field can be a simple field such as #SALARY or any of its visualizations such as #SALARY.VISUAL or #SALARY.MYPART.

*VARIANT allows the use of a variant variable. You can read or write values from a variant variable, but it has no properties. At the moment a better alternative is to use a Variant Variable (#PRIM_VAR).

Note that you can pass only a single value in a single DEFINE_MAP statement.

NAME

Name uniquely identifies the mapped value. The name can be up to 20 characters long and it has to be preceded by a hash, just like a field name.

Make sure the name is unique in your system. It should not be the same name as any other field or component in your program nor should it be the same as any field or component defined in the repository.

There are few things you should note about the name:

• When you use it in a CHANGE command to set a value for a field, you must refer to its value property:

     change #empno #curemp.value

• When you want to change its value, use the SET command:

     set com(#curemp) value('A0070')

• You can refer to the name without the value property in subroutines and built-in functions

     use builtin(reverse) with_args(#curemp) to_get(#revname)

• The same name can be used in different event, method and property routines.

• The name should not contain any prefixes reserved for LANSA such as #PRIM_, #LANSA, #SYS, #COM and #LP.

PASS

Use this parameter to specify how the supplied parameter is mapped to the variable name.

By default the parameter is supplied *BY_VALUE. This means that a copy of the value is passed.

If the value is passed *BY_REFERENCE, the routine can access the value of the field and change it.

MANDATORY

Use this parameter to specify whether the parameter being specified is mandatory (*YES).

Specify *NULL to allow users of the method to not supply a reference parameter by default when Pass is *BY_REFERENCE. The method code can then use the IF_REF command to work out whether the parameter has been supplied or not.

If the parameter is optional, you must specify here the default value for the parameter.

The following code defines a default value for the optional parameter #this_emp:

define_map *input class(#empno) name(#this_emp) mandatory('A1234')

The following code defines that the default value for the optional parameter #this_emp is blank:

define_map *input class(#empno) name(#this_emp) mandatory('')

You can also supply a value for non-mandatory output parameters. This value is used to initialize the variable at the beginning of the routine and the value is replaced if the parameter is supplied when the routine is invoked.

The following code initializes #mNumberOfTimes to a default of 99 and #mValid to false: 

define_map *output class(#std_count) name(#mNumberofTimes) mandatory(99)

define_map *result class(#prim_boln) name(#mValid) mandatory(false)

DESC

You can specify a brief description for the mapped value using the DESC parameter. It can be 40 characters long.

HELP

You can specify a longer description for the mapped value using the HELP parameter. The help text can be viewed using the Features option of the Help menu. It can be 250 characters long.