User exits

Description

Both the user preference and file preference windows allow the entry of a user-exit. These are subprograms that PEEK will CALLNAT under certain circumstances. You can use these exits to tailor the way PEEK works.

The user user-exit is called at the beginning and end of every PEEK session, allowing you to issue terminal commands to modify the environment in some way. Here is an example:

DEFINE DATA
PARAMETER
  1 #ACTION                   (A1)
END-DEFINE
*
DECIDE ON FIRST VALUE OF #ACTION
VALUE 'E'                           /* E=Enter
  SET CONTROL 'D=BW'                /* Toggle frame highlighting
  SET CONTROL 'F=   '               /* Remove frame characters
VALUE 'L'                           /* L=Leave
  SET CONTROL 'D=BW'                /* Toggle frame highlighting
NONE
  WRITE 'Unknown action :' #ACTION 'in' *PROGRAM
END-DECIDE
*
END

The file user-exit is called at the beginning of each session with that particular file, and then each time certain fields are about to be read or written to the file. This way you can change the format or value of the fields. Here is an example to modify the NAME field on the EMPLOYEES file:

DEFINE DATA
PARAMETER
  1 #ACTION                   (A1)
  1 #FLD-LIST                 (A2/1:V)
  1 #DATA-B1                  (B1/1:V)
LOCAL
  1 #LOCAL-DATA-B1            (B1/253)
  1 REDEFINE #LOCAL-DATA-B1
    2 #NAME                   (A20)
END-DEFINE
*
DECIDE ON FIRST VALUE OF #ACTION
VALUE 'I'                                       /* I=Initialise
  #FLD-LIST (1) := 'AE'                         /* AE=EMPLOYEES.NAME
VALUE 'R'                                       /* R=Read value
  DECIDE ON FIRST VALUE OF #FLD-LIST (1)
  VALUE 'AE'
    #LOCAL-DATA-B1 (1:20) := #DATA-B1 (1:20)
    EXAMINE SUBSTRING (#NAME, 2, 19) TRANSLATE INTO LOWER CASE
    #DATA-B1 (1:20) := #LOCAL-DATA-B1 (1:20)
  NONE
    WRITE 'Unknown field' #FLD-LIST (1) 'in' *PROGRAM
  END-DECIDE
VALUE 'W'                                      /* W=Write value
  DECIDE ON FIRST VALUE OF #FLD-LIST (1)
    #LOCAL-DATA-B1 (1:20) := #DATA-B1 (1:20)
    EXAMINE #NAME TRANSLATE INTO UPPER CASE
    #DATA-B1 (1:20) := #LOCAL-DATA-B1 (1:20)
  NONE
    WRITE 'Unknown field' #FLD-LIST (1) 'in' *PROGRAM
  END-DECIDE
NONE
  WRITE 'Unknown action :' #ACTION 'in' *PROGRAM
END-DECIDE
*
END

The file user-exit is called many times during each session with that file. The first call is made with an #ACTION of 'I'. This is to allow your routine to define a list of fields which you wish to modify. You may specify up to 10 fields in the #FLD-LIST array.

Thereafter, each time PEEK is about to read or write a field in this list, the user-exit is called again with an #ACTION of 'R' or 'W'. The field being read or written is identified in #FLD-LIST (1).