TRGMAIN: An API To Maintain Triggers

#### Search Results

Search

# TRGMAIN: An API To Maintain Triggers

The Adabas triggers and stored procedures facility provides a callable routine TRGMAIN to maintain trigger definitions from user-written programs. TRGMAIN functions include

- add new triggers

- modify existing triggers

- purge existing triggers

- display a specific trigger definition

- activate triggers

- deactivate triggers

To call the trigger maintenance routine

- Enter the following:

      CALL 'TRGMAIN' function calling-parameters

where the functions and calling parameters are as described in the following sections.

This document covers the following topics:

- Functions (Format A5)

- Calling Parameters (Format A209)

- Sample User Program

- Response Codes

## Functions (Format A5)

The FUNC parameter specifies what action is to be performed on the trigger definition. Valid values are

ADD | Add
MOD | Modify
DEL | Purge
DISP | Display
ACT | Activate
DEACT | Deactivate

## Calling Parameters (Format A209)

The parameters that compose CALLING-PARMS provides the information needed to complete the actions. These parameters are consistent with the information requested by the online Trigger Maintenance facility and include the following fields (default values are underlined):

Field Name | Length | Description
--- | --- | ---
TRG-DBNR | N5 | Trigger file DBnr
FILE-NAME | A32 | File name defined in the FFT
CMD-TYPE | A1 |
Command type that causes trigger to fire:
D | delete
F | find
I | insert
R | read
U | update
* | all commands
FIELD-NAME | A32 | Field name defined in the FFT
TRIGGER-PROG | A8 | Name of the Natural trigger program
PRIORITY | N3 | Trigger priority
PRE-CMD-SELECT | A1 |
Trigger timing relative to the command execution:
N | post-command trigger
Y | pre-command trigger
PART-NON-FLAG | A1 |
Participation flag. Valid values are
A | asynchronous (default)
N | nonparticipating
P | participating
CALLNAT-FLAG | A1 |
CALLNAT parameters. Valid values are
C | control parameters with ACB and response code (default)
E | response code only
N | no parameters passed
X | control parameters with ACBX and response code
RECBUFF-OPTION | A1 |
Record buffer access. Valid values are
A | access only
N | no access to record buffer (default)
U | updates allowed
ACT-TYPE | A4 |
Type of activation/deactivation to be processed:
PERM | permanent
TEMP | temporary
TRG-RSV | A39 | Reserved for future use
RESP | N4 | Response code returned from the API
RETURN-MSG | A68 | Text description of the response code
VERSION | N3 | GCB version
PRODVERN | N3 | Database version
NUCID | P5 | Nucleus ID

## Sample User Program

    0010 ************************************************************************
    0020 * Application .. ADABAS Triggers Subsystem
    0030 * Program ...... UMAINT
    0040 * Function ..... Sample call program to call API TRGMAIN that
    0050 * maintains trigger definitions.
    0060 * (Add,Delete,Modify,Display,Activate,Deactivate).
    0070 *
    0080 * Parameters ... The following parameters are passed when calling
    0090 * the API:
    0100 * FUNCTION (A5) Action to perform on Trigger Definition
    0110 * Valid values are ADD - Add
    0120 * MOD - Modify
    0130 * DEL - Delete
    0140 * DISP - Display
    0150 * ACT - Activate
    0160 * DEACT - De-activate
    0170 * TRG-DBNR (N5) Trigger File DBnr
    0180 * FILE-NAME (A32) File Name defined in the FFT
    0190 * CMD-TYPE (A1) Command type that causes trigger to fire
    0200 * Valid values are R - Read
    0210 * F - Find
    0220 * I - Insert
    0230 * U - Update
    0240 * D - Delete
    0250 * * - All commands
    0260 * FIELD-NAME (A32) Field Name defined in the FFT
    0270 * TRIGGER-PROG (A8) Name of the NATURAL Trigger Program
    0280 * PRIORITY (N3) Trigger Priority
    0290 * PRE-POST-FLAG (A1) Pre-trigger or Post-trigger
    0300 * Valid values are Y - Pre trigger
    0310 * N - Post trigger
    0320 * PART-NON-FLAG (A1) Participation flag
    0330 * Valid values are A - Asyncronous
    0340 * N - Non-Participating
    0350 * P - Participating
    0360 * CALLNAT-FLAG (A1) CALLNAT Parameters
    0370 * Valid values are N - No parmeters passed
    0380 * E - Response code only
    0390 * C - Control Parms and
    0400 * Response code
    0410 * RECBUFF-OPTION (A1) Record Buffer Access
    0420 * Valid values are A - Access only
    0430 * U - Updates allowed
    0440 * N - No access to RB
    0450 * ACT-TYPE (A4) Type of Activation/De-activation
    0460 * Valid values are: TEMP - Temporary
    0470 * PERM - Permanent
    0480 * VERSION (N3) Version of the GCB
    0490 * Valid values are: 201 for v81
    0500 * 202 for v82
    0510 * PRODVERN (N3) Version of the Adabas
    0520 * Valid values are: 812, 813, 814 for v81x
    0530 * 822, 823, 824, 825, 826 for v82x
    0540 * NUCID (P5) NUCID
    0550 * RESP (N4) Response Code returned from the API
    0560 * RETURN-MSG (A68) Text description of the response code
    0570 **********************************************************************
    0580 DEFINE DATA
    0590 LOCAL USING TRGPMAIN
    0600 LOCAL
    0610 01 MAP-MSG (A68)
    0620 01 HOLD-FUNCTION (A5)
    0630 01 HOLD-PRE-POST-FLAG (A1)
    0640 01 PAGE-TITLE (A50)
    0650 01 #ATTR (C)
    0660 END-DEFINE
    0670 RESET CALLING-PARMS MAP-MSG
    0680 MOVE 233 TO TRG-DBNR
    0690 VERSION := 202
    0700 PRODVERN := 822
    0710 NUCID := 0
    0720 SET KEY PF3
    0730 **
    0740 ** Request function and required fields
    0750 **
    0760 REPEAT
    0770 INPUT (AD=TMIL'_' CD=NE)
    0780 MAP-MSG (IP=OFF AD=O)
    0790 / 9T 'API Maintenance of Trigger Definitions' (YEI)
    0800 // 'Function..........' FUNCTION 30T '(Add, Del, Mod, Disp, or ".")'
    0810 // 'File Name.........' FILE-NAME
    0820 / 'Field Name........' FIELD-NAME
    0830 / 'Command Type......' CMD-TYPE 30T '(R, F, I, U, D, or *)'
    0840 / 'Pre-Command.......' PRE-POST-FLAG 30T '(Y, N, or blank)'
    0850 RESET MAP-MSG
    0860 **
    0870 ** Escape out of here
    0880 **
    0890 IF FUNCTION = MASK('.') OR *PF-KEY = 'PF3'
    0900 ESCAPE BOTTOM
    0910 ** Set up Page Titles
    0920 DECIDE ON FIRST VALUE OF FUNCTION
    0930 VALUE 'DISP' MOVE 'Display' TO PAGE-TITLE
    0940 VALUE 'ADD' MOVE 'Add' TO PAGE-TITLE
    0950 VALUE 'MOD' MOVE 'Modify' TO PAGE-TITLE
    0960 VALUE 'DEL' MOVE 'Delete' TO PAGE-TITLE
    0970 VALUE 'X' ESCAPE BOTTOM
    0980 NONE REINPUT 'Invalid Function Code'
    0990 END-DECIDE
    1000 COMPRESS PAGE-TITLE 'Trigger Definition' INTO PAGE-TITLE
    1010 IF FILE-NAME = ' '
    1020 REINPUT 'File Name can not be BLANK' MARK *FILE-NAME
    1030 **
    1040 ** Handle Request to Display a Trigger
    1050 **
    1060 IF FUNCTION = 'DISP'
    1070 DO
    1080 PERFORM GET-TRIGGER
    1090 INPUT (AD=O CD=NE)
    1100 MAP-MSG (IP=OFF AD=O)
    1110 / 9T 'API Maintenance of Trigger Definitions' (YEI)
    1120 // 10T PAGE-TITLE (IP=OFF)
    1130 // 'File name.........' FILE-NAME
    1140 / 'Field Name........' FIELD-NAME
    1150 / 'Command Type......' CMD-TYPE
    1160 // 'Trigger Program...' TRIGGER-PROGRAM
    1170 / 'Priority..........' PRIORITY
    1180 / 'Pre-Command.......' PRE-POST-FLAG
    1190 / 'Trigger Type......' PART-NON-FLAG
    1200 / 'CALLNAT Params....' CALLNAT-FLAG
    1210 / 'RecBuffer Access..' RECBUFF-OPTION
    1220 RESET FUNCTION
    1230 MOVE RETURN-MSG TO MAP-MSG
    1240 DOEND
    1250 **
    1260 ** Handle Request to Alter Trigger Definitions
    1270 **
    1280 IF FUNCTION = 'ADD' OR= 'MOD' OR= 'DEL'
    1290 DO
    1300 IF (FUNCTION = 'MOD' OR= 'DEL')
    1310 PERFORM GET-TRIGGER
    1320 IF FUNCTION = 'DEL'
    1330 DO
    1340 MOVE 'Press ENTER to Delete or PF-3 to Cancel' TO MAP-MSG
    1350 MOVE (AD=P) TO #ATTR
    1360 DOEND
    1370 ELSE DO
    1380 MOVE 'Press ENTER to confirm data or PF-3 to Cancel' TO MAP-MSG
    1390 MOVE (AD=D CD=NE) TO #ATTR
    1400 DOEND
    1410 REPEAT
    1420 INPUT (AD=TMIL'_' CD=NE)
    1430 MAP-MSG (IP=OFF AD=O)
    1440 / 9T 'API Maintenance of Trigger Definitions' (YEI)
    1450 // 10T PAGE-TITLE (AD=O IP=OFF)
    1460 // 'File Name.........' FILE-NAME (AD=O)
    1470 / 'Field Name........' FIELD-NAME (CV=#ATTR)
    1480 / 'Command Type......' CMD-TYPE (CV=#ATTR)
    1490 // 'Trigger Program...' TRIGGER-PROGRAM (CV=#ATTR)
    1500 / 'Priority..........' PRIORITY (CV=#ATTR)
    1510 / 'Pre-Command.......' PRE-POST-FLAG (CV=#ATTR)
    1520 / 'Trigger Type......' PART-NON-FLAG (CV=#ATTR)
    1530 / 'CALLNAT Params....' CALLNAT-FLAG (CV=#ATTR)
    1540 / 'RecBuffer Access..' RECBUFF-OPTION (CV=#ATTR)
    1550 RESET MAP-MSG
    1560 IF *PF-KEY = 'PF3'
    1570 DO
    1580 MOVE 'Function cancelled per user request' TO MAP-MSG
    1590 ESCAPE BOTTOM
    1600 DOEND
    1610 **
    1620 ** Perform the update of data (add, del, or mod)
    1630 ** and handle the response
    1640 **
    1650 CALLNAT 'TRGMAIN' FUNCTION CALLING-PARMS
    1660 DECIDE ON FIRST VALUE OF RESP
    1670 VALUE 0 MOVE RETURN-MSG TO MAP-MSG
    1680 EXAMINE MAP-MSG FOR 'confirmed' REPLACE 'successful'
    1690 ESCAPE BOTTOM
    1700 VALUE 20 REINPUT WITH TEXT RETURN-MSG MARK *FIELD-NAME
    1710 VALUE 23 REINPUT WITH TEXT RETURN-MSG MARK *FIELD-NAME
    1720 VALUE 25 REINPUT WITH TEXT RETURN-MSG MARK *CMD-TYPE
    1730 * VALUE 37 REINPUT WITH TEXT RETURN-MSG MARK *PRIORITY
    1740 * VALUE 38 REINPUT WITH TEXT RETURN-MSG MARK *PRIORITY
    1750 VALUE 39 REINPUT WITH TEXT RETURN-MSG MARK *TRIGGER-PROGRAM
    1760 VALUE 40 REINPUT WITH TEXT RETURN-MSG MARK *PRE-POST-FLAG
    1770 VALUE 41 REINPUT WITH TEXT RETURN-MSG MARK *PART-NON-FLAG
    1780 VALUE 42 REINPUT WITH TEXT RETURN-MSG MARK *CALLNAT-FLAG
    1790 VALUE 43 REINPUT WITH TEXT RETURN-MSG MARK *RECBUFF-OPTION
    1800 NONE MOVE RETURN-MSG TO MAP-MSG
    1810 END-DECIDE
    1820 LOOP
    1830 RESET FUNCTION
    1840 DOEND
    1850 ** Loop back up to display the starting screen
    1860 LOOP
    1870 *******************************
    1880 ** Subroutine to retrieve the *
    1890 ** trigger information *
    1900 *******************************
    1910 DEFINE SUBROUTINE GET-TRIGGER
    1920 MOVE FUNCTION TO HOLD-FUNCTION /* Go get the existing
    1930 MOVE 'DISP' TO FUNCTION /* Trigger Information
    1940 MOVE PRE-POST-FLAG TO HOLD-PRE-POST-FLAG
    1950 CALLNAT 'TRGMAIN' FUNCTION CALLING-PARMS
    1960 MOVE HOLD-FUNCTION TO FUNCTION
    1970 IF RESP NE 0
    1980 REINPUT WITH TEXT RETURN-MSG
    1990 IF RESP = 0
    2000 DO
    2010 IF PRE-POST-FLAG NE HOLD-PRE-POST-FLAG
    2020 AND HOLD-PRE-POST-FLAG NE ' '
    2030 DO
    2040 MOVE HOLD-PRE-POST-FLAG TO PRE-POST-FLAG
    2050 MOVE 'Trigger does not exist' TO MAP-MSG
    2060 IF HOLD-PRE-POST-FLAG = 'Y'
    2070 COMPRESS 'Pre-' MAP-MSG INTO MAP-MSG
    2080 ELSE COMPRESS 'Post-' MAP-MSG INTO MAP-MSG
    2090 MOVE HOLD-FUNCTION TO FUNCTION
    2100 ESCAPE TOP
    2110 DOEND
    2120 IF CMD-TYPE = ' '
    2130 MOVE '*' TO CMD-TYPE
    2140 DOEND
    2150 RETURN
    2160 *** End of Subroutine ***
    2170 END
    2180 **

## Response Codes

Code | Meaning
--- | ---
000 | Function completed successfully.
013 | Invalid file-field entry specified. The triggers facility requires access to a file-field table that maps long file names to file numbers and field names to Adabas two-character field identifiers. See section File-Field Tables for more information.
016 | No trigger definition found with this criteria.
020 | Field name must be blank for delete command class.
023 | Field name not found for this file. The field name specified does not exist in the file-field table for this file. See section File-Field Tables for more information.
025 | Invalid command type. See list above for valid values.
027 | No field found for this file and command type.
029 | No trigger found for this file, command, and field criteria.
037 | Priority must be between 1 and 900.
038 | Priority cannot be set if Adabas field name is **.
039 | Natural subprogram name is invalid.
040 | Specify "Y" for pre-trigger and "N" for post-trigger.
041 | Trigger type may be "A", "N", or "P" only.
042 | CALLNAT type may be "C", "E", or "N" only.
043 | Record buffer usage may be "A", "N", or "U" only.
044 | Invalid parameter combination. No record buffer available with asyncronous triggers.
045 | Invalid parameter combination. No record buffer available for pre-triggers for read or find commands.
046 | Invalid parameter combination. No record buffer available for delete commands.
047 | A trigger already exists for this parameter combination.
048 | Invalid request. Trigger is already in the specified state.
052 | Change in trigger state not possible now.
103 | File name must not be blank.
111 | Invalid function code.
112 | TYPE must be temp or perm. The type of activation or deactivation of a trigger must be either temporary (lasting for this nucleus session only) or permanent.
1xxx | Function resulted in an Adabas response code 22 (ADARSP022) where xxx represents the subcode.
3xxx | Non-zero Adabas response code was returned, where xxx is the actual Adabas response code.
9999 | Function not successful. Verify parameters and existing trigger definitions. Contact your Software AG technical support representative with questions.

### On this page

- Functions (Format A5)
- Calling Parameters (Format A209)
- Sample User Program
- Response Codes