8.6.4 DEFINE_MAP in PTYROUTINE
When you define a property for a component, you can optionally use the PTYROUTINE command to specify routines for setting the value of the property and for returning its value. You only use a property routine when you want to manipulate the value in some way, for example to derive the value or format it.
The property routine that sets the value contains a DEFINE_MAP statement for specifying the type of value that can be input (*INPUT) to the routine. The property routine that returns the value of the property has a DEFINE_MAP statement defining what kind of value the routine returns (*OUTPUT).
Let's use a Form B as an example. The form has a user-defined property EMP_NAME. This property can be used by an owner form of Form B for setting the value of the employee name on Form B. The property can also be used by an owner form for retrieving the current value of the employee name on Form B. In Form B the employee name is handled as two separate fields #GIVENAME and #SURNAME.
The following code in Form B defines the property and specifies that its value is set using a property routine called SET_EMP_NAME and returned by a property routine called GET_EMP_NAME.
define_pty name(EMP_NAME) set(SET_EMP_NAME) get(GET_EMP_NAME)
Define Input Parameter
FormB contains this SET_EMP_NAME routine:
ptyroutine name(SET_EMP_NAME)
define_map *input class(#fullname) name(#this_emp)
* <<logic to split #this_emp to #GIVENAME and #SURNAME>>
endroutine
The DEFINE_MAP statement in this routine specifies that the EMP_NAME property can take a value which is valid for a #FULLNAME field and that the value is identified by the name #this_emp inside this routine.
An owner form can now set the value of the EMP_NAME property in Form B.
set #FORMB EMP_NAME(#fullname)
or
set #FORMB EMP_NAME('John Smith')
Define Output Parameter
FormB also contains the GET_EMP_NAME routine which returns the value of the EMP_NAME property:
ptyroutine name(GET_EMP_NAME)
define_map *output class(#fullname) name(#this_emp)
* <<logic to concatenate #GIVENAME and #SURNAME to form #this_emp>>
endroutine
The DEFINE_MAP statement in this routine specifies that the EMP_NAME property will return a valid value for #FULLNAME field. The output value is referred to with the name #this_emp. The routine then concatenates the values of #GIVENAME and #SURNAME to form the value #this_emp which will be returned as the value of the EMP_NAME property.
An owner form can now query the value of EMP_NAME for example like this:
IF COND(#FormB.Emp_Name *eq 'John Smith')