Child pages
  • Callback Routines

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Panel
Table of Contents

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.

Info

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

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

Ordered List (ol)
List Item (li)
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.
List Item (li)
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.

HTML Table
border3
width75%
Table Row (tr)
Table Head (th)
Argument
Table Head (th)
Type
Table Head (th)
Description
Table Row (tr)
Table Cell (td)

Function

Table Cell (td)

x(01)

Table Cell (td)

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.

Table Row (tr)
Table Cell (td)

Token_name

Table Cell (td)

x(32)

Table Cell (td)

Name of token being validated

Table Row (tr)
Table Cell (td)

Token_value

Table Cell (td)

x(80)

Table Cell (td)

Value of token

Table Row (tr)
Table Cell (td)

Add_parm1

Table Cell (td)

x(80)

Table Cell (td)

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

Table Row (tr)
Table Cell (td)

Add_parm2

Table Cell (td)

x(80)

Table Cell (td)

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

Table Row (tr)
Table Cell (td)

Message Count

Table Cell (td)

9(4) COMP

Table Cell (td)

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

Table Row (tr)
Table Cell (td)

Messages array

Table Cell (td)

x(80)

Table Cell (td)

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.

Table Row (tr)
Table Cell (td)

Error_flag

Table Cell (td)

x(1)

Table Cell (td)

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.

Table Row (tr)
Table Cell (td)

Position

Table Cell (td)

S9(4) COMP

Table Cell (td)

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.

Info

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.

Info

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).