You are here: LANSA for i User Guide > Appendix C. Technical Notes > Trigger Functions > The TRIG_OPER and TRIG_RETC Variables and TRIG_LIST Working List

The TRIG_OPER and TRIG_RETC Variables and TRIG_LIST Working List

When a trigger function is invoked it receives 2 things from the invoker:

TRIG_OPER

TRIG_OPER: is an A(6) field which must be defined in the data dictionary. The content of this field defines what database operation has, or is about to be, performed. Refer to What Codes Are Passed in TRIG_OPER to the Trigger? for details.

TRIG_LIST

TRIG_LIST: is a 2 entry working list containing 0,1 or 2 entries. The number of entries passed depends upon the database operation being performed. Refer to How Many Entries Are Passed in the TRIG_LIST? for details.

You must define TRIG_LIST as a working list with 2 entries but you must not define any fields within it. The required fields are automatically defined by the RDML compiler.

If your trigger is for field #CUSTNO then the single field #CUSTNO is automatically defined in the list just as if you had typed in:

DEF_LIST NAMED(#TRIG_LIST) FIELDS(#CUSTNO)

If your trigger was for file Z which contained real fields X, A, T and virtual fields Q and B then the list is automatically defined just as if you had typed in:

DEF_LIST NAMED(#TRIG_LIST) FIELDS(#X #A #T #Q #B)

This automatic definition ensures that the correct names are used and that you do not have to know or key in the correct names in the correct order.

Remember that the automatic definition is done from the "active" definition of file Z. So if you changed file Z to have X, A, V, T, Q and B as fields and then recompiled the trigger before you made the changed file Z "operational" it would automatically define from the unchanged "active" (X, A, T, Q, B) version of file Z.

If you then made the file Z "operational" it would set up its trigger invocations using X, A, V, T, Q, B as the list layout. This is a clear mismatch and would cause unpredictable results.

This mistake would be typified by decimal data errors or by data being "offset" within fields in the list. If this type of problem occurs when a trigger is invoked you should recompile it.

So, when changing a file definition, always make the file "operational" before attempting to recompile its associated trigger functions.

To "get" values from the list use the GET_ENTRY command.

This means that when using a trigger for field #CUSTNO you must "get" the correct value of #CUSTNO from the list by using GET_ENTRY NUMBER(?) FROM_LIST(#TRIG_LIST).

Likewise, to get the values of #X through #B in the file Z example you would need also need to "get" them by using GET_ENTRY NUMBER(?) FROM_LIST(#TRIG_LIST).

Only use the list operations SELECTLIST, GET_ENTRY and UPD_ENTRY against the list TRIG_LIST. Only ever issue UPD_ENTRY operations against entry number 1. When a trigger function terminates it returns 2 things to the invoker:

TRIG_RETC: is an A(2) field which must be defined in the data dictionary. At the point of return it must be set to "OK", "ER", and in some situations, "VE". See the following sections for more details of the meaning and use of these return codes.

TRIG_LIST: is the 2 entry working list containing 0,1 or 2 entries previously described. You may alter the data in the first entry passed by using the UPD_ENTRY command. If you do this in a "before" operation then you will actually alter the data that is inserted or updated into the file.

Likewise if you do this in an "after read" operation you will alter the data that is passed back to the function that issued the read request.

It is strongly recommended that you do not use this facility to "communicate" between serially invoked trigger functions.

Only use the list operations SELECTLIST, GET_ENTRY and UPD_ENTRY against the list TRIG_LIST. Only ever issue UPD_ENTRY operations against entry number 1.