Child pages
  • Callback Routines
Skip to end of metadata
Go to start of metadata

Introduction

Callback routines permit IFD files to "call back" to the main image (or a sharable image) for help and validation services. This permits IFD routines to perform cross field validations or validations which depend on values that can only be determined at run-time. For example, a field may require a particular value if another field contains a value, or the values may be determined by a users data files (e.g. pay groups).

Specify /CALLBACK in IFD file

Callback routines must be written in a high-level language and linked to the program which calls DYNFORM. The routine's name and address must be passed to DYNFORM. See DYNFORM for the arguments passed to DYNFORM and for and example of specifying a callback address.

SSDT programmers must use DYNFORM.F to specify the call to DYNFORM.

There are two ways to provide a callback routine to DYNFORM:

  1. Write the subprogram and specify it's name to DYNFORM in the main calling program. The routine is the name of the subprogram, e.g. /CALLBACK=(HELP="IRN_HELP"). This form of /CALLBACK cannot be used with IFPRC.
  2. Place subprogram in a sharable image. In this case, the routine should be the name of the image and the routine, e.g.:
    {{/CALLBACK=HELP="SYS$SHARE:OECNSHR,IRN_HELP"""

Arguments Passed to a Callback Routine

Callback routines must accept parameters as described below. The parameters for help and validation routines are identical although some parameters may not apply to all types of routines. This allows a single routine to be used for both help and validation.

Argument Type Description

Function

x(01)

Function being requested, ( H = help, V =validate, D = Default) Other callback functions may be implemented in the future, therefore callback routines should not assume that only H, V or D will be passed.

Token_name

x(32)

Name of token being validated

Token_value

x(80)

Value of token

Add_parm1

x(80)

Value of parameter when /PARAMETER is specified (first value)

Add_parm2

x(80)

Value of parameter when /PARAMETER is specified (second value)

Message Count

9(4) COMP

Number of messages returned. Callback routine must set this to the number of messages. Must not exceed 100.

Messages array

x(80)

Occurs up to 100 times For Help routines. Up to 100 lines of help may be returned. For Validation routines only the first occurrence is used.

Error_flag

x(1)

Validation only. Must return Y (valid), N (invalid) or W (warning). If W is returned then the validation message is treated as a warning and displayed to the user only once.

Position

S9(4) COMP

The position of the field on the screen. This is the the number of characters from the beginning of the screen. This value may be used in positioning help/validation popup windows.

SSDT programmers must use CALLBACK.F in the callback routine to specify the LINKAGE and USING clauses.

Help callback routines may use the message array to return up to 100 lines of help. If additional lines or dialog is necessary then help routine may do its own terminal I/O.

For SSDT: PW*.F routines are recommended but CAPscreens may also be
used.

The default callback permits the callback routine to provide a default value for the field at run-time. The default callback is called whenever a screen is initially loaded, or the user presses the Reset key.

The callback may may modify the "Token_value" field. The modified value will be placed onto the screen (this is true for help, validation and default callbacks).

  • No labels