The field property *help-parms is normally used whenever you use the *helproutine field property to generate active help for a field. The *help-parms property controls what gets passed to the helproutine and what gets passed back.
In most cases, helproutines are called from forms to assist the user in entering database values. The field on which the helproutine is referenced is automatically passed into the helproutine and a value us passed back to this field from the helproutine. If this is the only field being used, and if the name of the field used by the helproutine matches that of the field name of the form there is no need to code a *help-parms parameter.
If you are only passing static values to the helproutine, *help-parms takes the form of a simple query string. For example *help-parms:detail=y&year=current
Sometimes other form fields are used to control what is shown in the helproutine, in such a case, the current field values for these fields need to be passed into the helproutine. Some helproutines may populate several form fields and the *help-parms parameter can designate which fields are to be returned.
To simplify the passing of form field values, *help-parms can be divided into field groupings. Where each grouping is identified as one of the following:
Fields following the in keyword will be passed into the helproutine. The general form for these parameters is form-field-name=help-field-name. In many cases these field names will be identical so we can abbreviate this to just specify the field name by itself.
Fields returned from the helproutine are also specified as form-field-name=help-field-name and can be abbreviated when these names match.
This are fields that are passed into the helproutine and sent back from the helproutine. This is the default designation of the field on which the helproutine is attached.
These are query string parameters that you want to propagate to the helproutine. That is, querystring parameter that are defined on your form whose value you also want to pass to the helproutine.
These can be any other values to be added to the query string.
Consider the following form used to maintain film rentals:
Notice that the form has two fields with a helproutine link.
For the first field, we want the helproutine to return the rental-id. Since this is the field on which we are attaching the helproutine there is no need to include this in the parameter list. Since we only want to pass a simple querysting we can just specify the desired querystring values as in:*helproutine:rental-browse,*help-parms:click=db_object_display&layout=help
In this case we are asking the helproutine to click your display button after populating the rental_id. We are also overriding the layout that the helproutine will be using.
Next consider the helproutine for the customer_id. In this case, in addition to returning the customer_id, we also want the helproutine to pass back the corresponding customer's first_name and last_name. To achieve this the help parameters would be coded as:*helproutine:customer-browse,*help-parms:out/customer_first_name=first_name/customer_last_name=last_name/other/layout=help
In this example, customer_first_name is the name used on the form whereas first_name is the name used within the helproutine. Always put the form field name on the left side of the equal sign. Once again, if the names match you can just list the matching name.
Consider the following set of help parameters for the field manager_staff_id*helproutine:staff-browse,*help-parms:in-out/manager_staff_id=staff_id/out/first_name/last_name/other/layout=help
In this case, we needed to include the key for which the help is requested in the parameter list because the name used on the form differs from what is used on the helproutine. Therefore we needed to add in-out/manager_staff_id=staff_id to map these field names. On the other hand, first_name and last_name field names matched so we did not need to code this as first_name=field_name, etc.