Trigger Maintenance

The Trigger Maintenance facility is a Natural application that allows you to

• add, delete, modify, and list trigger definitions;

• generate, modify, display, and delete file-field tables;

• display and modify profile information for the definition of the run-time triggers system;

• monitor trigger operations and permanently or temporarily activate or deactivate triggers.

To start Trigger Maintenance

• Select "Trigger Maintenance" from the Adabas Online System (AOS) main menu or enter MENU at the Natural NEXT prompt in library SYSTRG.

  The Trigger Maintenance main menu appears:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Main Menu - DBnr 105 Code Function ---- --------------------------------- A Administrator Functions F File-Field Table Definitions R Procedure Reports T Create/Modify Trigger Definitions ? Help . Exit ---- --------------------------------- Code ... Command ==> Enter--PF1--PF2--PF3--PF4---PF5---PF6---PF7--PF8--PF9--PF10--PF11--PF12 Help Exit Field Trigr Admin Procs FTRG FDIC Canc

  The main menu functions are described briefly in the following table:

  Code	Function	Description
  A	Administrator Functions	Display or modify the profile information, i.e., the run-time parameter settings of the triggers and stored procedures. Obtain Natural subsystem information. Monitor subsystem activity and trigger activity.
  F	File-Field Table Definitions	Display, generate, modify, delete, or select a file-field table. View the origin of the file-field table.
  R	Procedure Reports	Display a list of procedures for the defined triggers, sorted by file or by name.
  T	Create/Modify Trigger Definitions	Add, display, modify, delete, or select a trigger definition.
  ?	Help	Display help information about the Trigger Maintenance facility.
  .	Exit	Exit to the Natural NEXT screen. Enter TRIGGERS to return to the main menu.

This document covers the following topics:

• Overview

• File-Field Tables

• Trigger Definitions

• Procedure Reports

• Administrator Functions

Overview

The Trigger Maintenance facility comprises a set of menus and submenus that lead to data screens and pop-up windows. Each menu contains a list of functions and function codes, a group of input fields, a command line, a set of PF keys, and a message area. Adabas Online System (AOS) must be installed in the same environment.

Wildcard Notation

Wildcard notation is allowed wherever possible. For example, most menus require that you specify a file name. If you do not know the file name, you can enter a wildcard character instead. A range of values will appear in a pop-up window, allowing you to select an item or entry from the range.

The term "wildcard" refers to the use of a special character as follows:

Input Fields

Each menu in the Trigger Maintenance facility includes the following input fields:

Other input fields vary. For example:

• The File-Field Table Definitions Menu includes a Generation Type input field. Generation Type identifies the source from which the file-field table is to be generated (Natural DDM, Adabas FDT, or Predict Adabas file definition).

• The Trigger Definitions Menu includes the Field Name and Command Type input fields. File Name, Command Type, and Field Name comprise the selection criteria that you specify when you create the trigger definition.

Messages

The message area at the top or bottom of the screen is used to display one-line error or action messages. Each message includes a message number and a brief explanation. For more information, see the Adabas Messages and Codes documentation.

Commands

The following table describes the commands that can be entered at the command line. Not all commands apply to all screens.

Commands are not case-sensitive and can be entered in upper-, lower-, or upper- and lower-case. Commands are converted to upper-case before being processed.

The underlined portion of the command indicates the minimum abbreviation allowed.

PF Keys

The following table describes the standard PF keys.

File-Field Tables

Triggers require access to a file-field table that maps long file names to file numbers and field names to Adabas two-character field identifiers.

The file-field table should contain an entry for

• all fields used in trigger definitions;

• all fields that will be referenced by an access or update command in a triggered procedure;

• all fields that must be queried by the record buffer extraction routine (STPRBE).

File-field tables can be generated from an Adabas FDT, a Natural DDM, or a Predict Adabas file, with the following restrictions:

• Superdescriptors, subdescriptors, hyperdescriptors, and phonetic descriptors are supported for histograms (L9) only.

After the file-field table entries are defined, the external field names and the internal field names and numbers can be correlated, and a trigger can be defined for any of the fields in the file-field table. If, for example, you refer to the EMPLOYEES file and the SALARY field, Adabas will be able to identify this as file 1 and field AS.

Record Buffer Extraction

When the record buffer extraction routine (STPRBE) extracts the value of a field in the record buffer, it must extract the value from the correct position and length. In order to position to the correct place, STPRBE must step past each superfluous field and must therefore know the length of each field.

• If the field length is not explicitly specified in the format buffer, it must be obtained from the file-field table definitions.

• If the length of a field is always found in the format buffer, as in Natural, then there is no need to include the field in the file-field table.

If the field length is not in the format buffer and a definition does not exist on the trigger file, an error will occur. The procedure will be unable to continue processing and will terminate.

Group-Field Table

When the group name is specified in the format buffer, STPRBE uses the group-field table to locate the elementary fields belonging to the group. Each entry in the group-field table contains specific information about an elementary field and its offset within a group. Offsets are maintained for up to seven group levels. Up to 50 elementary fields may have entries in the group-field table for a specific file.

Entries for the group-field table can be generated from either the Generate File-Field Table function or the Modify File-Field Table function.

File-Field Table Definitions Menu

File-field tables are generated and maintained using the File-Field Table Definitions function of the Trigger Maintenance facility. Any combination of fields can be added or subsequently deleted from the file-field table.

To access the File-Field Table Definitions function

• Enter F on the Main Menu.

  The screen that appears is similar to the example shown below:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - File-Field Table Definitions Menu - DBnr 105 Code Function ---- ------------------------------------ D Display File-Field Table G Generate File-Field Table M Modify File-Field Table P Delete File-Field Table R Rename File-Field Table S Select File-Field Table V View the Origin for File-Field Table ? Help . Exit ---- ------------------------------------ Code ......... _ File Name .... ___________________ File Number .. _____ Gen. Type .... __ Command ==> Enter-PF1--PF2--PF3--PF4--PF5---PF6---PF7---PF8--PF9--PF10--PF11--PF12 Help Menu Exit Trigr Admin Procs FTRG FDIC Canc

  The following table briefly describes each of the functions on the File-Field Table Definitions Menu:

  Function	Description
  Display File-Field Table	Display the table for a specified file.
  Generate File-Field Table	Generate a new table by adding or deleting fields. Requires a generation type code.
  Modify File-Field Table	Modify the table by deleting one or more individual fields. A field cannot be deleted if it is used in a trigger definition.
  Delete File-Field Table	Delete an entire table. A table cannot be deleted if it contains one or more fields that are used in a trigger definition.
  Rename File-Field Table	Rename a table. All fields and triggers for the specified table are renamed.
  Select a File-Field Table	Select a table from a selection list.
  View the Origin for File-Field Table	Display the FDT, DDM, or Predict file from which the table was generated. Allows you to add selected fields to the table.

Display a File-Field Table

To display a file-field table

• Enter D on the File-Field Table Definitions Menu.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Display File-Field Table - DBnr 105 File Name ... AUTOMOBILES Fnr ... 4 Field Name Long Field Name Status Message ---------- -------------------------------- ------ ------------------ AC BODY-TYPE Triggr CA COLOR Triggr AA MAKE Active FB MILEAGE Triggr AB MODEL Active BD WEIGHT Active DA YEAR Active Enter 'F'(Fwd), 'T'(Top), 'B'(Bck), '.'(Exit) Command==> Enter-PF1---PF2---PF3---PF4--PF5---PF6--PF7--PF8--PF9---PF10---PF11--PF12 Help Menu Exit Next -- - + Grp GFld Canc

  • Press ENTER to scroll through the information on this screen.

  • Press PF9 or continue scrolling to display the group table. If a group table has been generated for the file, the table is displayed at the end of the file-field table.

  • Press PF10 to display the group-field table.

Display a Group Table

To display the group table

• Press PF9 (Grp) or scroll to the end on the Display File-Field Table screen:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Display Group Table - DBnr 105 File Name ... AUTOMOBILES Fnr ... 4 Name Level Type Length Name Level Type Length Name Level Type Length ---- ----- ---- ------ ---- ----- ---- ------ ---- ----- ---- ------ AB 1 G 60 A1 1 G 53 A2 1 G 21 AQ 1 P 13 A3 1 G 4 AW 1 P 12 Enter 'F'(Fwd), 'T'(Top), 'B'(Bck), '.'(Exit) Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Menu Exit -- - + GFld FFT Canc

  • Press ENTER to scroll through the information on this screen.

  • Press PF10 or continue scrolling to display the group-field table. The group-field table is displayed at the end of the group table.

  • Press PF11 to return to the Display File-Field Table screen.

  Each group field on the file is listed. A "G" in the Type column represents a simple group field; a "P" represents a periodic (PE) group. Group-field table entries can only be created for fields that are part of a group or a PE group.

  The Length column displays

  • for a simple group, the total length of all fields included in the group

  • for a PE group, the total length for each occurrence.

Display a Group-Field Table

To display the group-field table

• Press PF10 (GFld) on the Display File-Field Table screen;

  Or:
  scroll to the end on the Display Group Table screen

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYY-MM-DD User USR01 - Display Group-Field Table - DBnr 105 File Name ... AUTOMOBILES Fnr ... 4 Field Group Offsets Message ---------------- ------------------------------------ -------------------- 2,AS,5,P AQ(3) 2,AT,5,P AQ(8) 2,AU,2,U A3(0) 2,AV,2,U A3(2) 2,AX,6,U AW(0) 2,AY,6,U AW(6) Enter 'F'(Fwd), 'T' (Top), 'B' (Bck), or '.'(Exit) Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---

  • Press ENTER to scroll through the information on this screen.

  • Press PF9 to display the group table.

  • Press PF11 to return to the Display File-Field Table screen.

  Fields are shown in ADACMP FNDEF format: level, name, length, format [options]. See the Adabas Utilities documentation for more information.

  The Group Offsets column names the group in which the field participates and the offset of the field within that group. If a field is a member of more than one group, the additional groups (and the field's offset within) are also listed.

  For example, field AS belongs to group AQ and is located at offset 3. Field AT also belongs to group AQ but is located at offset 8.

Modify a File-Field Table

To modify a file-field table

• Enter M on the File-Field Table Definitions Menu.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Modify File-Field Table - DBnr 105 File Name ... AUTOMOBILES Fnr ...4 Sel Field Name Long Field Name Status Message ---- ---------- -------------------------------- ------ -------------- __ AC BODY-TYPE Triggr __ CA COLOR Triggr __ AA MAKE Active __ FB MILEAGE Triggr __ AB MODEL Active __ BD WEIGHT Active __ DA YEAR Active Mark fields with 'A' Add, 'D' Delete, 'G' Generate, 'I' Info, or '.' Exit Command==> Enter-PF1---PF2---PF3---PF4--PF5---PF6--PF7--PF8--PF9---PF10---PF11--PF12 Help Menu Exit Next -- - + Grp GFld Canc

  • Press ENTER to scroll through the information on this screen.

  • Press PF9 or scroll to the end to display the group table. The group table cannot be modified.

  • Press PF10 to modify the group-field table.

  On the Modify File-Field Table screen, fields with a "Status" of

  • "Triggr" are used in a trigger definition.

  • "Active" are included in the file-field table but are not used in any trigger definition.

Modifying Fields

From the Modify File-Field Table screen, you can generate group-field table entries, display field attributes, or delete fields from the file-field table.

To generate group-field table entries

• Mark each field for which an entry is to be generated by typing a G in the Sel column next to the field name. Then press ENTER.

  Group-field table entries can only be created for fields that are part of a group or a PE group.

To display the attributes for an individual field

• Mark the field by typing an I in the Sel column next to the field name. Then press ENTER.

  The resulting window displays the field name, format, length, type (SP for superdescriptor; SB for subdescriptor), and an indicator if a group-field entry has been generated for the field.

To delete one or more fields

• Mark each field to be deleted by typing a D in the Sel column next to the field name. Then press ENTER.

  The following rules apply:

  • You can cancel a field deletion by typing an A in the Sel column next to the field name before pressing ENTER.

  • Only "Active" fields can be deleted.

  • "Triggr" fields cannot be deleted unless the trigger definition is deleted first.

Modifying the Group-Field Table

To modify the group-field table

• Press PF10 (GFld) on the Modify File-Field Table screen;

  Or:
  scroll to the end on the Display Group Table screen

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYY-MM-DD User USR01 - Modify Group-Field Table - DBnr 105 File Name ... AUTOMOBILES Fnr ... 4 Sel Field Group Offsets Message --- ---------------- ------------------------------------ --------------- _ 2,AS,5,P AQ(3) _ 2,AT,5,P AQ(8) _ 2,AU,2,U A3(0) _ 2,AV,2,U A3(2) _ 2,AX,6,U AW(0) _ 2,AY,6,U AW(6) Mark Fields with 'D'(Delete) or '.'(Exit) Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Menu Exit -- - + Grp FFT Canc

  • Press ENTER to scroll through the information on this screen.

  • Press PF9 to display the group table. The group table cannot be modified.

  • Press PF11 to return to the Modify File-Field Table screen.

  Fields are shown in ADACMP FNDEF format: level, name, length, format [options]. See the Adabas Utilities documentation for more information.

  The Group Offsets column names the group in which the field participates and the offset of the field within that group. If a field is a member of more than one group, the additional groups (and the field's offset within) are also listed.

  For example, field AS belongs to group AQ and is located at offset 3. Field AT also belongs to group AQ but is located at offset 8.

To delete one or more entries

• Mark each entry to be deleted by typing a D in the Sel column next to the field name. Then press ENTER

Delete a File-Field Table

Use the delete function on the File-Field Table Definitions Menu only if the entire file-field table is to be deleted. Deleting the file-field table also deletes any associated group-field table for that file.

To delete an entire file-field table

• Enter P for Delete File-Field Table on the File-Field Table Definitions Menu.

  If a TRG0109 error occurs, it indicates that the table cannot be deleted until all triggers are removed. Display the file-field table and determine whether any of the fields in the table are marked "Triggr" (used in a trigger definition). If not, then the trigger definitions should be checked. It is likely that a trigger with the "all fields" option (i.e., field name **) has been defined for this file.

Generate a File-Field Table

To generate a file-field table

• Enter G on the File-Field Table Definitions Menu as well as the file name and a generation type code as shown in the following table:

  Code	Source
  F	Adabas FDT
  D	Natural DDM
  P	Predict file

  • FDT generations always originate from the DBID of the database for the current setting of the Trigger File.

  • DDM and Predict generations always originate from the database and file number of the Predict file. This may be taken from the current setting of FDIC; or it may be overwritten using PF10 or by issuing the command SET FDIC from the command line of the Trigger Maintenance facility.

  Note:
  Wildcard notation cannot be used for the FDT file name. However, for the generate function only, "99999" can be entered for file number to display a list of all files loaded to the database.

  The screen that appears contains the source (FDT, DDM, or Predict file) from which the file-field table will be generated. You can select fields to be added to or deleted from the file-field table. See the sample FDT.

  When the file-field table is generated, a check is done to see if the field name (long) changed for a field (determined by the Adabas short name). If so, the status field contains the value "Alias" and the name of the new field is placed in the message field, preceded by a colon ( : ). Type an A in the Sel column next to the field name to update the entry with the new name.

  In the case of FDT generations, the field name is always generated as the Adabas short name followed by "-FIELD". When the Trigger Maintenance facility finds a name that was not generated, it is used as the long field name with the "xx-FIELD" name in the message. Again, type an "A" in the Sel column to confirm the change. The sample FDT includes the status for each field. Fields marked "Active" are already contained in the file-field table.

  If the generation type is "F" (Adabas FDT), field names are generated as "xx-FIELD", where "xx" is the Adabas field name. Subsequently, if a DDM or Predict Adabas file has the same file number and file name as that given for the FDT definition, these fields may be updated with the user-defined names of the DDM or Adabas file.

  Note:
  Fields in the Field Definition column are shown in ADACMP FNDEF format where type "U" stands for unpacked numeric and field lengths are in bytes, not digits.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Generate/Modify File-Field Table - DBnr 105 FDT File Name .. AUTOMOBILES FDT Fnr ... 4 Sel Field Definition Long Field Name Status Message --- ----------------- --------------- ------ -------------- _ 01,AA,020,A,DE,NU MAKE Active _ 01,AB,020,A,DE,NU MODEL Active _ 01,AC,015,A,DE,NU BODY-TYPE Active _ 01,BA,002,U,DE,NU BA-FIELD _ 01,BB,003,U,DE,NU BB-FIELD _ 01,BC,005,U,NU BC-FIELD _ 01,BD,005,U,NU WEIGHT Active _ 01,CA,010,A,DE,NU COLOR Active _ 01,DA,002,U,DE,NU YEAR Active _ 01,DB,016,A,NU DB-FIELD _ 01,FA,006,U,DE,NU FA-FIELD _ 01,FB,006,U,DE,NU MILEAGE Active Mark Fields with 'A' Add, 'D' Delete, 'G'Generate, 'I' Info, or '.' Exit Command==> Enter-PF1---PF2---PF3---PF4--PF5---PF6--PF7--PF8--PF9--PF10--PF11--PF12 Help Menu Exit Next -- - + Canc

To add one or more fields

• Mark each field to be added by typing an A in the Sel column next to the field name. Then press ENTER.

  If you want to add all fields to the file-field table, enter ALL at the command line.

To delete one or more fields

• Mark each field to be deleted by typing a D in the Sel column next to the field name. Then press ENTER.

To generate group-field table entries

• Mark each field for which an entry is to be generated by typing a G in the Sel column next to the field name. Then press ENTER.

  Group-field table entries can only be created for fields that are part of a group or a PE group.

To display the attributes for an individual field

• Mark the field by typing an I in the Sel column next to the field name. Then press ENTER.

  The resulting window displays the field name, format, length, type (SP for superdescriptor; SB for subdescriptor), and an indicator if a group-field entry has been generated for the field.

Trigger Definitions

Conceptually, a trigger has two parts: the triggering event and the triggered procedure. The triggering event is defined by a set of selection criteria. When the criteria are fulfilled, the triggered procedure is executed in response.

The selection criteria, i.e., file name, command type, and field name, are stored in the target database as part of the trigger definition. The file-field table maps them to the corresponding physical Adabas file number and two-character field ID. The file name and the field name are meaningful names of up to 32 characters.

The following sections describe the selection criteria in more detail.

• File Name

• Command Type

• Field Name

• Trigger Definitions Menu

File Name

File name specifies the file against which the initiating Adabas command operates. A trigger is defined for one and only one Adabas file. If you want a trigger to apply to more than one file, define multiple triggers (one for each file) that are identical except for the file name.

Command Type

Command type specifies the command class of the initiating Adabas command. Triggers are defined to execute based on the presence of the specified command type.

One or all of the following Adabas command classes can be specified for a single trigger definition:

If you want a trigger to apply to all command classes, leave the command type field blank. It defaults to "All" (all commands).

If you want a trigger to apply to more than one but not all command classes, define multiple triggers (one for each class) that are identical except for the command class.

Field Name

A trigger can be associated with a command that operates on a single field in the file or all fields in the file. It is possible, for example, to define a trigger that fires every time an UPDATE command is executed against the SALARY field in the EMPLOYEES File.

It is not always appropriate to specify a field. For example:

• It does not make sense to associate a specific field with a DELETE command, because the DELETE command does not require a format buffer.

• In the case of a pre-command trigger read command, the field will contain no data. Therefore, there is no need to specify a field unless you want to validate either the fields to be read or the user ID of the user issuing the request.

If you want a trigger to apply to more than one but not all fields, define multiple triggers (one for each field) that are identical except for the field name.

A trigger will be fired for only one field, i.e., the field that is specified in the format buffer, depending on the event selection criteria. However, if triggers need to be fired for multiple fields, it is possible to define the trigger file for a specific command and field, then have the procedure itself check for the existence of other fields. See the section Implementing Support for Multi-Triggers.

The procedure can verify whether additional procedures should be invoked and, if so, for what fields. This mechanism also allows the "main" procedure to handle errors and decide whether another procedure should be invoked even if the previously executed procedure resulted in an error. The user therefore has the flexibility to control situations where a precise set of rules is needed to determine whether a procedure should or should not be fired.

Trigger Definitions Menu

The Trigger Definitions Menu (shown below) contains the functions that allow you to create and maintain trigger definitions.

To access the Trigger Definitions Menu

• Enter T for Create/Modify Trigger Definitions on the main menu.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Trigger Definitions Menu - DBnr 105 Code Function ---- -------------------------- A Add Trigger Definition D Display Trigger Definition M Modify Trigger Definition P Delete Trigger Definition S Select Trigger Definition ? Help . Exit ---- ------------------------- Code ........ _ Active/Deactive Opt... _ File Name ... _________________ Cmd Type .... _ Field Name .. _________________ Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7--PF8--PF9--PF10--PF11--PF12-- Help Menu Exit Field Admin Procs FTRG FDIC Canc

  The functions on the Trigger Definitions Menu allow you to add, display, modify, or delete trigger definitions. You can display a screen that contains multiple trigger definitions for the same file, or a pop-up window that contains a single trigger definition for a specific field within the file.

To access all trigger definitions for a particular file

• Enter the function code (A for add, D for display, M for modify, or P for purge/delete) and the file name. Enter a wild card value for command type and field name.

  A screen containing all trigger definitions for the file appears. Depending on the function code entered to access the screen (A, D, M, or P), you can add, display, modify, or delete one or more trigger definitions. See the section Multiple Trigger Definitions.

To access a specific trigger definition

• Enter the function code (A, D, M, or P), the file name, and the field name.

  A pop-up window containing the trigger definition appears. Depending on the function (A, D, M, or P), you can add, display, modify, or delete the trigger definition. See the section Single Trigger Definition.

You can also use the Trigger Definitions Menu to select one or more triggers.

To select a trigger or triggers

1. Enter function code S and a file name or a wildcard value for file name, e.g., >G.

   The screen that appears is similar to the following example:

   Note:
   If a specific file name is selected, the screen contains the long field names and not the file names.

   HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - List Trigger Definitions - DBnr 105 Sel File Name / Long Field Name Commnd Type ProcName Para RecB --- --------------------------- ------- ---- -------- ------ ---- _ MISCELLANEOUS Delete Pre Non-P SYMP0003 Cont None ** Any Field ** _ VEHICLES-FILE Delete Pre Non-P SYMP0003 Cont None ** Any Field ** _ VEHICLES-FILE Read Pre Async ANYONE Contrl None ** Any Field ** _ VEHICLES-FILE Read Pre Async MAKE0001 Cont None MAKE _ VEHICLES-FILE Read Pre Async MODEL001 Cont None MODEL _ VEHICLES-FILE Read Pre Async COLOR001 Contrl None COLOR _ VEHICLES-FILE Read Pre Async CLASS001 Contrl None CLASS _ GDMUSIC (All) Pre Async PROC008 Contrl None ** Any Field ** Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7--PF8---PF9---PF10--PF11--PF12 Menu Exit -- - + Canc

2. In the Sel field next to the file name, enter D for display, M for modify, S for select, or P for purge.

   If you enter D, P, or M, a pop-up window containing the trigger definition appears. See the section Single Trigger Definition.

   If you enter S, the trigger is selected and the Trigger Definitions Menu appears.

This section also covers the following topics:

• Multiple Trigger Definitions
• Single Trigger Definition

Multiple Trigger Definitions

To add, display, modify, or delete one or more trigger definitions

1. On the Trigger Definitions Menu, enter the code (A, D, M, or P) and the file name. The command type is optional; if you leave it blank, it defaults to "All" (all commands).

   Depending on the code entered, one of the following screens appears:

   • Add Trigger Definitions

   • Display Trigger Definitions

   • Modify Trigger Definitions

   • Delete Trigger Definitions

   These screens contain the trigger definitions for the specified file. For example, the Modify Trigger Definitions screen is similar to the following:

   HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Modify Trigger Definitions - DBnr 105 Pre-Post .. Pre File ... VEHICLES-FILE (3) Command ... Read Prty Long Field Name Fld Type ProcName Params RecBuff Msg ---- -------------------------------- --- ----- -------- ------ ------- 010 COLOR___________________________ AF Async COLOR001 Contrl None___ 020 CLASS___________________________ AH Async CLASS001 Contrl None___ 030 MAKE____________________________ AD Async MAKE0001 Contrl None___ 040 MODEL___________________________ AE Async MODEL001 Contrl None___ 050 ** Any Field **_________________ ** Async SAMP0002 Contrl None___ ___ ________________________________ __ _____ ________ ______ _______ ___ ________________________________ __ _____ ________ ______ _______ ___ ________________________________ __ _____ ________ ______ _______ ___ ________________________________ __ _____ ________ ______ _______ ___ ________________________________ __ _____ ________ ______ _______ ___ ________________________________ __ _____ ________ ______ _______ Modify Entries, or enter '.'(Exit), or '?'(Help) to see options ... _ Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12 Help Menu Exit Updat - + Reseq Post Canc

2. After entering the appropriate information, press PF5 to update the trigger table.

   A message informs you that the update has been confirmed. An error message appears if you enter information that is invalid or incomplete.

Entry Fields

The following paragraphs describe the entry fields in the Trigger Definitions screens.

Prty (priority)

The Adabas trigger driver scans the format buffer for a match with the selection criteria defined for each trigger. When multiple field names are specified for the same file and command, the priority assigned to each field determines the order in which it is processed. When a match is found, the trigger is fired. The Prty field allows you to set or modify the sequence.

The highest priority is 1. Priorities are represented, however, in steps of ten from 10-900. Other values are entered to change the sequence or "priority" of the fields. Values entered between the steps of ten are resequenced (using the RESEQ command; see the section Commands) to the next higher 10s values; for example, entering priorities of 11 and 12 for fields resequences them to represented values 20 and 30, respectively.

To change a field's priority, specify a value between 1 and 9

• higher than the represented value of the field you want it to follow; or

• lower than the represented value of the field you want it to precede.

Example:

To change the priority of MAKE on the List Trigger Definitions screen from the represented value 30 to 10 with the other fields changing priority accordingly, assign MAKE a value between 1 and 9.

When the RESEQ command is used, the priorities of all fields are changed to 10-900 with MAKE as 10, COLOR as 20, CLASS as 30, etc.

Long Field Name

The Adabas long field name for the field. Enter a wildcard to display a selection list of field names. If the long field name is not known, it can be derived from the Fld (short field name).

Fld (short field name)

The Adabas short field name, that is, the unique name used by the DBMS to identify a particular field for a particular file. It must correspond to the long field name for the field. If the short field name is not known, it can be derived from the long field name.

Type

Type is asynchronous, participating, or non-participating. The default value is asynchronous.

ProcName

The name of the Natural subprogram that should be invoked when the selection criteria for the trigger are met. The value must be a valid Natural subprogram name of 1-8 characters. There is no default value.

Important:
The name of the user job that calls the trigger must be different from the trigger's ProcName.

Params

When the trigger procedure is invoked, the parameters passed may be:

Contrl	Using the ACB interface, control parameters are used to pass information about the trigger request as well as the trigger command and a modifiable response code field. Contrl is the default value.
Contrx	Using either the ACB or ACBX interface, control parameters are used to pass information about the trigger request as well as the trigger command and a modifiable response code field.
Resp	A modifiable response code field is used to prevent the execution of a command in the case of a pre-command trigger. Response code is used with synchronous triggers only; it has no value or meaning with asynchronous triggers, which may already have completed.
None	No parameters are passed.

 

RecBuff

Value may be access (read only), update (read and write), or none.

Msg

An error message text may be displayed in this field when an error occurs. An explanation of the error is displayed at the bottom of the screen.

Commands

The following table describes the commands that can be entered at the command line in the Trigger Definitions screens:

Note:
Commands can be entered in upper-, lower-, or mixed-case.

Command	Description
PRTY	Display the Modify Trigger Definitions screen, where you can modify the priority assigned to a trigger.
UPDATE	Update the trigger file with the values entered.
BACK, -	Display the previous screen.
FWD, +	Display the next screen.
RESEQ	Resequence the list of trigger definitions, in order by priority.
POST	Display the post-command triggers for this file and command.
PRE	Display the pre-command triggers for this file and command.
ACTIVATE	Activate pre-command triggers or post-command triggers.
DEACTIVATE	Deactivate pre-command triggers or post-command triggers.
DELETE	Delete selected trigger definitions from the trigger file.
MODIFY	Modify the trigger definitions.

Single Trigger Definition

To add, display, modify, or delete a single trigger definition

• Enter the code (A, D, M, or P), the file name, and the field name on the Trigger Definitions Menu.

  The command type is optional; if you leave it blank, it defaults to "All" (all commands).

  Depending on the code entered, an add, display, modify, or delete function pop-up window appears. These windows contain trigger information and procedure information about the specified trigger definition (see the example Modify Function Screen):

  • Trigger information includes the file name and number, command type (read, update, etc.), the long field name and the Adabas field name. Also displayed is the current status of the trigger, as shown in the following table:

    Status	Description
    Active	The trigger is currently active on the trigger file and for the currently active nucleus.
    Inactive	A permanent deactivation of the trigger was requested; the trigger will remain in this state until activated.
    Temp Active	The trigger is active for the running nucleus only. A temporary "activate" was requested; the trigger remains in this state until a "deactivate" is issued.
    Temp Inactive	The trigger is inactive for the running nucleus only. A temporary "deactivate" was requested; the trigger remains in this state until an "activate" is issued.
    File Not Used	The file number specified in the trigger definition is greater than the maximum file number for the database (highest file number used plus 10). See Creating the Trigger Table.
    Not Loaded	A trigger has been added to the file since the last time the nucleus was activated. The trigger will become active the next time a REFRESH command is issued or the nucleus is restarted.
    Not Checked	The Trigger Maintenance facility is not active in the nucleus; therefore, no checking for the status of a trigger can be done.
    Inaccessible	The Adabas nucleus is not accepting any requests for trigger status.

  • Procedure information includes the procedure name, pre-command or post-command status, the trigger type (asynchronous, participating or non-participating), the CALLNAT parameters type (cntrl, resp, or none) and the record buffer option (access, update, or none).

To add a trigger definition

1. Enter the name of the procedure.

2. Modify options as required.

3. Press PF5 to confirm the addition.

To modify a trigger definition

1. The Modify Function pop-up is similar to the following:

   Modify Details and press 'PF5' to Confirm Update. HH:MM:SS *** Define Trigger Info *** YYYY-MM-DD - Modify Function - Trigger Information ** Active ** File Number ....... 4 File Name ......... AUTOMOBILES Command Type ...... Read Long Field Name ... BODY-TYPE Adabas Field ...... AC Field Prty/Seq .... 010 Procedure Information Name (Subpgm)...... _________ Pre Cmd Select .... N (Post) Trigger Type ...... N (Non-Participating) CALLNAT Params .... C (Cntl Info + Resp) RecBuffer Access .. A (May be Accessed) Command ==> Enter-PF1--PF2--PF3--PF4--PF5--PF6--PF7--PF8-- Help Menu Exit Prty Updat Act Deact

2. Modify the Field Prty/Seq (priority or sequence) and/or any of the fields under Procedure Information.

3. If you want to activate or deactivate the trigger, enter ACTIVATE or DEACTIVATE at the command line. Then choose whether the trigger's status should be changed temporarily or permanently:

   Command		means...
   Activate	temporarily	activate the trigger in the nucleus but retain its inactive status in the trigger file.
   	permanently	activate the trigger in the nucleus and remove its inactive status from the trigger file.
   Deactivate	temporarily	ignore the trigger for any checking of event criteria for any command issued to the database; that is, no trigger can be fired for this definition.
   	permanently	store the trigger on the trigger file with the status "deactive"; do not activate when the nucleus is started. The trigger may, however, be started at a later time. An active Adabas session is deactivated immediately.

4. Press PF5 to confirm the update.

To delete a trigger definition

• Press PF5 to confirm the deletion.

To display all fields for the file in sequence by priority

• Press PF4 or enter PRTY at the command line.

  Note:
  If the trigger specifies the command type "Delete", the screen that appears allows the user to define a pre- and/or post-trigger definition at the same time.

Procedure Reports

The Procedure Reporting Menu shown below allows you to obtain an alphabetic list of triggered procedures sorted by file or by procedure name. You can limit the report to a specific file or include all files. Procedure reports can be used, for example, to locate duplicate procedures or identify each instance where a particular procedure is used.

To access the Procedure Reporting Menu

• Enter R for Procedure Reports on the Main Menu.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Procedure Reporting Menu - DBnr 105 Code Function ---- -------------------------- F Display Procedures by File N Display Procedures by Name ? Help . Exit ---- ------------------------- Code ......... N File Number .. _____ Procedure .... PROC0001 Command ==> Enter PF1---PF2--PF3--PF4---PF5---PF6---PF7---PF8--PF9--PF10--PF11--PF12 Help Menu Exit Field Trigr Admin Canc

To list the procedures for a particular file only

• Enter code F for Display Procedures by File and the file number.

To list procedures beginning with a particular name

• Enter code N for Display Procedures by Name, and the procedure name.

In either case, the screen displayed contains the type of information shown in the following example.

HH:MM:SS              ***** TRIGGER MAINTENANCE *****        YYYY-MM-DD
User USR01               - List Procedure Names -            DBnr 105

 File Name ... AUTOMOBILES                                       Fnr ... 4 


 Sel  ProcName   Command  Field Name                   When  Type   ParmTy 
 --- --------   -------  ----------------------------  ----  -----  ------ 
  _   PROC0001   Read     BODY-TYPE                     Post  NonP   Cntrl 
  _   PROC0001   Update   ** Any Field **               Pre   Async  Cntrl 
      PRO001     (All)    MILEAGE                       Pre   Async  Cntrl 
  _   SUBPGM     Read     COLOR                         Pre   Async  Cntrl 




 Select 'D' to Display, or enter 'F'(Fwd), 'T'(Top), 'B'(Bck), '.'(Exit)  
 Command ==>
Enter-PF1---PF2---PF3---PF4---PF5---PF6--PF7--PF8---PF9--PF10--PF11--PF12
      Help  Menu  Exit              --    -    +                     Canc

The procedure report contains the database number, the file number, the file name, and the following information for each procedure:

To obtain more information about a specific procedure

• Enter D in the Sel column next to the procedure name.

  A pop-up window displays information about the trigger definition as well as the procedure, and is similar to the following example:

  Trigger Information currently displayed HH:MM:SS *** Define Trigger Info *** YYYY-MM-DD - Display Function - Trigger Information File Number ....... 4 File Name ......... AUTOMOBILES Command Type ...... Read Long Field Name ... BODY-TYPE Adabas Field ...... AC Field Prty/Seq .... ____ Procedure Information Name (Subpgm)...... PROC0001 Pre Cmd Select .... N (Post) Trigger Type ...... N (Non-Participating) CALLNAT Params .... C (Cntl Info + Resp) RecBuffer Access .. A (May be Accessed) Command ==> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8- Help Menu Exit Prty

  • Trigger information includes the trigger event criteria, i.e., file name and number, command type, long field name and the Adabas field name.

  • Procedure information includes the Natural subprogram name, whether the procedure is pre-command or post-command, the trigger type (asynchronous, participating or non-participating), the CALLNAT parameters category (cntrl, resp, none) and the RecBuffer access status (A=access, N=no access, U=access/update).

Administrator Functions

The Administrator Functions allow you to monitor trigger activity, display and modify the profile, and maintain job status settings and buffer sizes.

To access the Administrator Functions Menu

• Enter A for Administrator on the Main Menu.

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Administrator Functions Menu - DBnr 105 Code Function ---- --------------------------- A Active Session Settings D Display Profile Information M Modify Profile Information S Subsystem Activity T Trigger Activity ? Help . Exit ---- --------------------------- Code ... D Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6--PF7--PF8---PF9---PF10--PF11--PF12-- Help Menu Exit Field Trigr Procs FTRG Canc

Active Session Settings

Active session settings includes job status settings and buffer sizes.

To modify the active session settings

1. On the Administrator Functions Menu, enter A for Active Session Settings.

2. Modify the field values and press PF5 to update the settings.

In a nucleus cluster environment, any changes to the active session settings are populated to all active nuclei in the cluster.

The Active Session Settings screen is similar to the example shown below:

HH:MM:SS              ***** TRIGGER MAINTENANCE *****           YYYY-MM-DD
User USR01              - Active Session Settings -             DBnr 105  

 Job Name ..........SAGDT077           Trigger File Number ......12    

 SVC Number ........217                Max File to be accepted...60    
 Nucleus .......... Active__                                           
 Triggers ......... Active__           Session Buffer Sizes in Bytes   
 Stored Proc. ..... Active__             Trigger Table Buffer....8192  
 Error Action ..... Halt                 Pre Trigger Queue.......15244 
 Trigger Logging .. Active__             Post Trigger Queue......2960  
 Activity Timeout.. 600                  Waiting Subsys Queue....80    
 Subsystems                              Acquired Storage........31232 
   Maximum ........5                     Used Storage............31232 
   Active .........5                                                   
   Inactive ...... 0                                                   
   Waiting ........5                                                   
   In Progress ....0                                                   

Change Parameters as required or press 'PF3' to Exit           

Command ==>                                                         
Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12-
      Help  Menu  Exit  Sact  Updat                                     Canc

The following table describes the Active Session Settings fields:

Updating the Trigger Table

By using the REFRESH command, you can add new triggers to the trigger table without shutting down the database. In nucleus cluster environments, the REFRESH command updates the trigger table on all cluster nuclei.

If the number of additional triggers to be loaded is far greater than the number loaded initially, manually allocate enough additional space to handle the increased number of triggers. If the trigger table buffer is not large enough, an inconsistency may occur that terminates Adabas Triggers and Stored Procedures based on the value of the error action field in the Adabas triggers profile.

The need to update the trigger table can be avoided by preloading the required triggers before the applications that use them are implemented.

To update the trigger table,

• Enter REFRESH at the command line, or enter "refresh" in the triggers field.

Buffer Size Calculations

Buffers are required for the trigger table, the pre-trigger queue, and the post-trigger queue:

Trigger Table

The trigger table buffer size is calculated using the following formula.

((((HIFNRLD+10)*4)+HIFNRLD+10+TOTTRG)*24)+4096

where:

After the Adabas trigger driver has calculated the total buffer size, the result is rounded down to a multiple of 256.

Pre-Trigger Queue and Post-Trigger Queue

Depending on how many commands per second are passed to the database, how long the actual procedures run, and whether the triggers are synchronous or asynchronous, queuing may or may not occur. Each buffer is set up to independently queue the pre- and post-triggers. If the queues become full, subsequent commands that would result in triggers being fired receive a response code 154 (ADARSP154). After the queuing has eased, the DBA should consider increasing the queue size.

In setting up the buffer sizes, consideration must also be given to the ratio of pre-triggers to post-triggers. For instance, if no pre-triggers are used, the pre-trigger queue is not required; all buffer space should be allocated to the post-trigger queue.

• The pre-trigger queue is required only if pre-command triggers are defined on the trigger file. Its buffer size is calculated as follows:

  (NC / 2) * 352  = TOTAL SIZE

  where "NC" is the value of the ADARUN parameter NC.

  This calculation is valid if all triggers are synchronous. If asynchronous triggers are used, commands may be issued continuously before the procedure resulting from the previous command has completed. This results in queuing, which requires a larger buffer size.

  Whether the amount the buffer should be increased depends on the number of commands being issued and the speed at which they are issued (i.e., the amount of time between the response from one command and the issue of the next command), and the amount of time required for each trigger's procedure to complete. For example, a batch job issuing thousands of commands that fire asynchronous triggers would require a very large buffer.

• The post-trigger queue is required only if post-command triggers are defined on the trigger file. Buffer size is calculated exactly the same as the pre-trigger queue buffer size, and the same size considerations apply.

Display/ Modify Profile Information

The profile contains system information required by Adabas Triggers and Stored Procedures and is generated from the database ID and file number that you specify. After the profile is generated, you can display it and modify the values it contains.

To access the profile,

• Enter D for Display Profile Information on the Administrator Functions Menu.

  The Display Profile Information screen appears, and is similar to the following example:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Display Profile Information - DBnr 105 Triggers Status .......... Active__ Total Triggers ..34 Stored Proc. Status ...... Active__ Natural Subsystem Parameters Batch Natural Name ..... NATAPT Maximum Subsystems ..... 6_ Activity Timeout ....... 600/80 NATPARM Parameters ..... DU=OFF,INTENS=1,ETID=' ' __________ ____________________________________ Fixed NATPARM Parm ..... STACK=(LOGON:SYSSPT;STP),PROGRAM=STPEND CMPRINT Assignment ..... TSPRT Required .. N UserID ... USER**__ Password .. PSWD**__ Adabas Session Parameters Error Action .......... Halt__ Trigger Table Size ....... __10K Log Trigger Activity ... Active__ Pre Trigger Queue Size ... __35K Post Trigger Queue Size .. __50K Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12- Help Menu Exit Mod Canc

Adabas Triggers and Stored Procedures assigns default values to the fields in the profile and uses these values at initialization time. This information is valid only at initialization time, i.e., when the Adabas nucleus is started. If the profile is modified, the new values take effect the next time the nucleus is bounced.

To modify the profile

1. On the Display Profile Information screen, press PF5. On the Administrator Functions Menu, enter M for Modify Profile Information.

   The Modify Profile Information screen appears.

2. Enter the new values and press PF5 or enter UPDATE at the command line.

   A message informs you that the profile has been updated successfully.

Profile Fields

The following table describes the fields in the profile:

STACK=(LOGON:SYSSPT;STP)

Subsystem Activity

Subsystem activity provides information about currently executing Natural subsystems.

To access subsystem activity information

• Enter S for Subsystem Activity on the Administrator Functions Menu.

  The Subsystem Activity screen is similar to the example shown below:

  HH:MM:SS - Subsystem Activity - YYYY-MM-DD Nmbr Started Status Type Start / TimeOut of Trigger Trig Count ---- ------- ------ ----- ---------------------------- ---------- 01 09:25:57 Busy Sync 09:41:37 09:46:37 350 02 09:25:57 Busy Async 09:41:39 09:46:39 280 03 09:25:57 Wait 212 04 09:25:57 Wait 156 05 09:25:57 Wait 51 Subsystems . . 5 of 5 Command ==>

  The following table describes the information in the Subsystem Activity screen:

  Field	Description
  Nmbr	The number of the Natural subsystem.
  Started	The time that the subsystem was initialized. If different from the Started time for the other subsystems listed, it indicates that a timeout, cancellation, or termination occurred. This should be cross-checked.
  Status	The current status of the subsystem: busy, active, wait (waiting for work), shutdown, canceled, or abended (if an error occurred).
  Type	The type of trigger: sync (synchronous) or async (asynchronous).
  Start	The time when the procedure started executing.
  Timeout	The time when a procedure will be canceled if it executes beyond the maximum time limit. If an error occurs prior to the timeout, the error is displayed.
  Trig Count	The number of triggers that have been executed by the subsystem since initialization.
  Command	The DBA may cancel any active or waiting subsystem by first entering the CANCEL command and then entering a C in the cursor position under "Status" for the subsystem that should be canceled.

To cancel an active or waiting subsystem

1. Enter CANCEL at the command line.

2. Enter C (for cancel) in the Status field of the subsystem that is to be canceled.

3. Press PF3 to exit.

Trigger Activity

Trigger activity provides information about currently executing triggers.

To access trigger activity information

• Enter "T" for Trigger Activity on the Administrator Functions Menu.

  The Current Trigger Activity screen is similar to the example shown below:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Current Trigger Activity - DBnr 105 Nmbr Status Cmd Fnr Field ProcName Type RecBu UserID (hex) ---- ------ --- --- ----- -------- ---------- ----- ------------- 01 Active PROC0002 Pre Non-P None ABD6EA375DE96A01 Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting L3 11 ** SYMP0002 Pre Async None Waiting S4 11 ** SYMP0002 Pre Async None Waiting N1 11 LE SYMP0001 Pre Non-P Upd Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12- Menu Exit Sact Refr -- - + > Canc

The following table describes the information in the Current Trigger Activity screen:

To display additional information

• Press PF10.

  The screen scrolls to the right, as shown below:

  HH:MM:SS ***** TRIGGER MAINTENANCE ***** YYYY-MM-DD User USR01 - Current Trigger Activity - DBnr 105 Nmbr Status Cmd Fnr Field ProcName CID CID (hex) ISN in ACB Timeout ---- ------ --- --- ----- -------- --- --------- ---------- --------- 01 Active ** PROC0002 00000000 11:30:41 Waiting L3 11 ** SYMP0002 ??? 00200101 Waiting L3 11 ** SYMP0002 ??? 00200101 1 Waiting L3 11 ** SYMP0002 ??? 00200101 16 Waiting L3 11 ** SYMP0002 ??? 00200101 15 Waiting L3 11 ** SYMP0002 ??? 00200101 14 Waiting L3 11 ** SYMP0002 ??? 00200101 20 Waiting L3 11 ** SYMP0002 ??? 00200101 23 Waiting L3 11 ** SYMP0002 ??? 00200101 2 Waiting S4 11 ** SYMP0002 ???? 02100101 Waiting N1 11 LE SYMP0001 00000000 Command ==> Enter PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12- Menu Exit Sact Refr -- - + < Canc

  Field	Description
  Nmbr	The number of the Natural subsystem executing the trigger. Valid values are 01-10.
  Status	The current status of the subsystem: active or waiting.
  Cmd	The Adabas command that initiated the trigger.
  Fnr	The file number against which the command is invoked. If the value of this field is the same as the trigger file, then this is a stored procedure.
  Field	The name of the field that resulted in the trigger being fired.
  ProcName	The name of the triggered procedure.
  CID	The command ID in the Adabas control block (ACB).
  CID (hex)	The command ID repeated in hexadecimal format.
  ISN in ACB	The ISN from the Adabas control block (ACB).
  Timeout	The time when a procedure will be canceled if it executes beyond the maximum time limit.