The ON APPEND trigger

The ON APPEND trigger defines an action named "append", which is dedicated to row creation at the end of the record list.

Inside a DISPLAY ARRAY dialog, defining the ON APPEND block will automatically create an "append" action for the dialog, that can be fired by the user with the Append button, to create a new row.

Best practice is to use the UNBUFFERED attribute with DISPLAY ARRAY modification triggers.

The ON APPEND block typically implements an INPUT instruction, binding a record variable to the form fields of a new row at the end of the TABLE container used by the DISPLAY ARRAY dialog.

After the INPUT dialog terminates, the int_flag register is used to validate or cancel the row creation, when the control goes back to the DISPLAY ARRAY dialog. If the user input is validated, the program can try to insert a new row into the database table. If the SQL INSERT succeeds, assign the entered values to the new row of the program array. If the SQL INSERT fails, display an error message and force the int_flag to TRUE in order to cancel the operation. If int_flag is TRUE, the DISPLAY ARRAY dialog resets the current row data as before the INPUT. If int_flag is FALSE, the DISPLAY ARRAY dialog keeps the new created row, with the data of the corresponding row of the program array.

The INPUT instruction must be defined with the FROM clause and the screen array of the form, with a screen array index equal to the current screen line returned by the scr_line() build-in function. This is the new append line in the TABLE container, as seen by the user.

ON APPEND code example:

  1      ON APPEND       
  2         LET x = DIALOG.getCurrentRow("sa_cust")
  3         INITIALIZE rec.* TO NULL
  4         LET rec.cust_num = 1000 + x
  5         LET rec.cust_name = "<undefined>"
  6         INPUT rec.* WITHOUT DEFAULTS FROM sa_cust[scr_line()].* ;
  7         IF NOT int_flag THEN
  8             TRY
  9                 INSERT INTO customer VALUES (rec.*)
 10                 LET custarr[x] = rec 
 11             CATCH
 12                 ERROR SQLERRMESSAGE
 13                 LET int_flag = TRUE
 14             END TRY 
 15         END IF

Note:

Line 1 declares the ON APPEND trigger.
Line 2 assigns the current row index to the x variable defined as INTEGER.
Line 3 resets all fields of the rec record to NULL.
Line 4 sets a new primary key value for the cust_num field. Best practice would be to use an SQL SEQUENCE, to produce a unique number. For convenience, in this sample we just add 1000 to the new row index.
Line 5 sets a default value of the customer name.
Line 6 implements the INPUT dialog to let the user enter new customer record data. Note that the INPUT uses the FROM clause, with the sa_cust screen array, at the current screen line returned by the build-in scr_line() function.
Line 7 checks the int_flag register.
Line 8 thru 14: here we try to INSERT the new record into the SQL table. This SQL statement may fail because of some SQL table constraints (NOT NULL, UNIQUE, etc). Therefore, we want to protect the code in a TRY/CATCH block and show an error message in case of problem. If the SQL fails we must set int_flag to TRUE to force the dialog to cancel the new row creation in the record list.
Line 9 implements the SQL INSERT statement, using the rec record values.
Line 10 assigns the values of the input record to the new row created in the dynamic array variable custarr. This is mandatory, otherwise the new row would be empty when the control goes back to the DISPLAY ARRAY dialog.