Version 8.2.5 SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT
 —  Triggers and Stored Procedures  —

Trigger Maintenance

Note:
The Trigger Maintenance subsystem is available only when the Adabas Online System (AOS) add-on product is installed. It is not available with the AOS demo version.

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

Start of instruction setTo start Trigger Maintenance

Note:
The database ID and file number are required by the Trigger Maintenance facility. If these values were not specified by default using the NATPARM LFILE parameters or the NTLFILE macro, they must be entered before the main menu functions can be used. You can enter these values by pressing PF10 on the main menu; otherwise, the system automatically prompts you for the information.

This document covers the following topics:

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:

Char. Example Select any name . .
* PERS* beginning with "PERS"
> PERS> with a value greater than "PERS"
< PERS< with a value less than "PERS"

Input Fields

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

Field Entry
Code
Enter the code for the function. For example, codes on the main menu are
A administrator functions
F file-field table definitions
R procedure reports
T create/modify trigger definitions
Depending on the function, a submenu, a pop-up, or a data screen appears.
File Name Enter the file name, or enter a wildcard to display a selection list of file names and numbers (for example, the entry "a*" returns a list of all files with names that begin with the letter "a").
File Number Enter the file number. When generating a file-field table from an FDT, you may enter "99999" instead of the actual file number to get a list of valid files.

Other input fields vary. For example:

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.

Command Display...
ACTIVITY or DISPLAY ACTIVITY the Current Trigger Activity screen, which contains information about currently executing triggers.
DISPLAY PROFILE the Display Profile Information screen, which contains the Trigger Maintenance facility profile.
DISPLAY TASKS or DISPLAY SYSTEMS the Subsystem Activity screen, which contains information about currently executing Natural subsystems.
MENU the Main Menu.
EXIT, QUIT, or . (period) the previous screen.
FIELD the File-Field Table Definitions Menu.
TRIGGER the Trigger Definitions Menu.
ADMIN the Administrator Menu.
PROFILE the Profile Information Menu.
SET FILE the database and file assignments for the current trigger file. You can enter a different database and file, which must be a valid trigger file.
SET FDIC the database and file assignments for the current Predict file. You can enter a different Predict system file.
FORWARD or + the next screen.
TOP, or -- from the top (beginning); for example, the start of a file-field table list.
BACK, or - the previous screen.

PF Keys

The following table describes the standard PF keys.

Key Label Description Menu or Screen
PF1 Help Display information about the current function. All screens
PF2 Menu Return to the Main Menu. All screens
PF3 Exit Return to the previous screen. In most cases, if the update option has not been selected, this results in any updates being ignored. All screens
PF4 Field Display the File-Field Table Definitions Menu. Main, Profile Information, Procedure Reporting, and Trigger Definitions menus
PF5 Trigr Display the Trigger Definitions Menu. Main, File-Field Table Definitions, Profile Information, and Procedure Reporting menus; Define Trigger Info, Add Function pop-up
PF6 Admin Display the Administrator Menu. Main, File-Field Table Definitions, and Trigger Definitions menus
PF7 Procs Display the Procedure Reporting Menu. Main Menu
PF10 FTRG Display the File Assignments for Triggers pop-up, where you can enter a database and file different from the one currently used. Main Menu and File-Field Table Definitions Menu
PF11 FDIC Change the setting of the Predict file (for triggers only) from one value to another. Main Menu and File-Field Table Definitions Menu
PF12 Canc Cancel the current process and return to the previous screen. If the update option has not been selected, this results in any updates being ignored. All screens

Top of page

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

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

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 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.

Start of instruction setTo access the File-Field Table Definitions function

Display a File-Field Table

Start of instruction setTo display a file-field table

Display a Group Table

Start of instruction setTo display the group table

Display a Group-Field Table

Start of instruction setTo display the group-field table

Modify a File-Field Table

Start of instruction setTo modify a file-field table

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.

Start of instruction setTo generate group-field table entries

Start of instruction setTo display the attributes for an individual field

Start of instruction setTo delete one or more fields

Modifying the Group-Field Table

Start of instruction set To modify the group-field table

Start of instruction setTo delete one or more entries

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.

Start of instruction setTo delete an entire file-field table

Generate a File-Field Table

Start of instruction setTo generate a file-field table

Start of instruction setTo add one or more fields

Start of instruction setTo delete one or more fields

Start of instruction setTo generate group-field table entries

Start of instruction setTo display the attributes for an individual field

Top of page

Trigger Definitions

Note:
For information about TRGMAIN, and API for maintaining triggers from a user program, see TRGMAIN: An API To Maintain Triggers.

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.

Note:
Database commands from the procedure that is executed as a result of a trigger are not limited to the database against which the initiating Adabas command is executed.

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:

Command Class Command Code
FIND S1, S2, S4
READ L1, L2, L3, L4, L5, L6, L9
UPDATE A1, A4
INSERT N1, N2
DELETE E1, E4

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:

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.

Start of instruction setTo access the Trigger Definitions Menu

Start of instruction setTo access all trigger definitions for a particular file

Start of instruction setTo access a specific trigger definition

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

Start of instruction setTo 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.

Multiple Trigger Definitions

Start of instruction setTo 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:

    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.

Note:
You are not required to enter both the long field name and the Fld (short field name). If either is entered, the other is derived from the file-field table entry.

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

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

Start of instruction setTo add, display, modify, or delete a single trigger definition

Start of instruction set To add a trigger definition

  1. Enter the name of the procedure.

  2. Modify options as required.

  3. Press PF5 to confirm the addition.

Start of instruction setTo 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.

Start of instruction setTo delete a trigger definition

Start of instruction setTo display all fields for the file in sequence by priority

Top of page

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.

Start of instruction setTo access the Procedure Reporting Menu

Start of instruction setTo list the procedures for a particular file only

Start of instruction setTo list procedures beginning with a particular 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:

Field Description
ProcName The name of the triggered procedure.
Command The Adabas command that initiates the trigger.
Field Name The trigger field name.
When When the procedure executes:

  • "pre-command": The procedure executes before the initiating Adabas command.

  • "post-command": The procedure executes after the initiating Adabas command.

Type The type of trigger:

  • "non-participating": The triggered procedure does not participate in the initiating Adabas command's transaction logic.

  • "participating": The triggered procedure may participate in the initiating Adabas command's transaction logic.

  • "asynchronous": The Adabas command and the triggered procedure execute separately and do not affect each other. The triggered procedure's transaction logic does not participate in the Adabas command transaction logic.

ParmTy The type of parameters passed when the procedure is invoked:

  • "control": ACB-style control parameters are used to pass information about the trigger request as well as the trigger command and a modifiable response code field. This is the default value.

  • "controlx": ACB- or ACBX-style control parameters are used to pass information about the trigger request as well as the trigger command and a modifiable response code field.

  • "response": 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.

Start of instruction setTo obtain more information about a specific procedure

Top of page

Administrator Functions

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

Start of instruction setTo access the Administrator Functions Menu

Active Session Settings

Active session settings includes job status settings and buffer sizes.

Start of instruction set 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

Note:
Press PF4 to display the Subsystem Activity screen.

The following table describes the Active Session Settings fields:

Field Description
Job Name The job name for the Adabas nucleus.
SVC Number The SVC number being used by the database.
Nucleus Indicates when Adabas Triggers and Stored Procedures is active for the current database.
Triggers If "active" (the default), triggers can be executed for this database; if "inactive", they cannot. This field can be modified. You may enter "refresh" to update the trigger table (see the section Updating the Trigger Table).
Stored Procedures If "active" (the default), stored procedures can be executed for this database; if "inactive", they cannot. This field can be modified.
Error Action The action ("reject", "halt", or "ignore") to be taken by Trigger Maintenance when a processing error occurs. This field can be modified.
Trigger Logging The logging function is "active" or "inactive".
Activity Timeout The number of seconds before a task is canceled. The default value is 60; the maximum value is 9999. This field can be modified. If set to zero, it will default to the Adabas TT parameter value.
Subsystems
Maximum The number of assigned Natural subsystems. The value can be 01-10.
Active The number of Natural subsystems initiated. The value may be less than the maximum allowed if an error from which the system cannot recover occurs and the subsystem becomes inactive.
Inactive The number of Natural subsystems currently terminated or shut down due to the occurrence of errors from which the system could not recover.
Waiting The number of subsystems currently waiting for work.
In Progress The number of subsystems currently processing triggers.
Trigger File Number The file number of the trigger file for the database.
Max File to be accepted The maximum file number that Adabas Triggers and Stored Procedures will accept. This is set as the highest file loaded plus 10 when the database comes up and/or is initialized. If a higher file number is subsequently added to the database, any triggers found for the file are ignored. To activate triggers beyond the Max File value, the database must be shut down and restarted.
Session Buffer Sizes in Bytes
Trigger Table Buffer The size of the trigger table buffer. This field can be modified using the Modify Profile function.
Pre-Trigger Queue The size of the queue for all pre-command triggers being processed at any given time.
Post-Trigger Queue The size of the queue for all post-command triggers being processed at any given time.
Waiting Subsys Queue The size of the queue for tasks waiting to process triggers; currently fixed at 80 bytes.
Acquired Storage The total amount of storage to be acquired for use by Adabas Triggers and Stored Procedures.
Used Storage The actual amount of storage used by Adabas Triggers and Stored Procedures during processing.

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.

Start of instruction setTo update the trigger table,

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:

HIFNRLD is the highest file number loaded
TOTTRG is the total number of triggers defined on the trigger table

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.

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.

Start of instruction setTo access the profile,

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.

Start of instruction set 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:

Field Description
DBnr The database ID of the trigger file to which this profile applies. The value is entered using NTLFILE, LFILE, or PF10 (FTRG).
Trigger Status
This field can be modified.
active (the default) triggers can be executed for this database.
inactive triggers cannot be executed for this database.
Stored Proc. Status
This field can be modified.
active (the default) stored procedures can be executed for this database.
inactive stored procedures cannot be executed for this database.
Total Triggers The total number of triggers defined for this database ID. May be used, by default, to calculate the size of the trigger table buffer. Value is derived from the trigger definitions added to the trigger file. As a safety mechanism, this number is verified as correct when the NUMBER command is issued.
Batch Natural Name The Natural nucleus that will be started by the Adabas trigger driver to run the 1-10 Natural subsystems that are responsible for the actual execution of the procedures. The name is assigned to the Natural nucleus component during the installation procedure.
Maximum Subsystems This field can be modified.
The number of Natural subsystems that should be activated for a given Adabas session. The value may be 01-10.
Activity Timeout This field can be modified. The number of seconds before a task is canceled. The default is 60; the maximum value is 9999. If set to zero, it defaults to the Adabas TT parameter value.
NATPARM Parameters Dynamic parameter overrides for the NATPARM module linked to the Natural nucleus (the NATPARM module specifies the options to be in effect for the Natural session). See the section NATPARM Considerations.
Fixed NATPARM This value is generated by Adabas Triggers and Stored Procedures. 
STACK=(LOGON:SYSSPT;STP)
where SYSSPT is the library where the procedures are executed and STP is used to invoke the Natural driver.
CMPRINT Assignment This field can be modified. Dynamic assignment for the CMPRINT label. The default value is TSPRT. Printing from any procedure within a specific subsystem must be directed to this label unless the specific printer number notation is used in Natural syntax; for example, PRINT(01), DISPLAY(02), or WRITE(03).
NATSEC LOGON Required This field applies only if the Natural subsystems are running under Natural Security. It indicates whether logon to Natural Security is required (Y) or not (N). Pertains to AUTO=OFF, AUTO=ON, respectively.
UserID This field can be modified. This field applies only if the Natural subsystems are running under Natural Security. This is the Natural Security user ID.
The default value is USER**. The ** is replaced by the dynamic task number or subsystem number (value 01-10). Although the default uses ** as a suffix, it may occur anywhere in the user ID provided that at least one nonblank character is specified as well.
Password This field can be modified. This field applies only if the Natural subsystems are running under Natural Security. This is the Natural Security password.
The default value is PSWD**. The ** is replaced by the dynamic task number or subsystem number. Although the default uses ** as a suffix, it may occur anywhere in the password provided that at least one nonblank character is specified as well.
Error Action
This field can be modified. This is the action to be taken by Adabas Triggers and Stored Procedures after a processing error from which the system cannot recover.
Halt (the default) terminates the Adabas nucleus as if ADAEND were issued for both cluster and noncluster nuclei.
Reject keeps Adabas Triggers and Stored Procedures active, but any command for which a trigger is fired receives a response code 157 (ADARSP157); In a cluster environment, if one nucleus switches to "reject", all other nuclei also switch. However, if there is a problem during a refresh and the error action is "reject", the nucleus shuts down: it cannot reject commands if it has a damaged or incomplete trigger table.
Ignore shuts down Adabas Triggers and Stored Procedures, but keep the nucleus active as if Adabas Triggers and Stored Procedures had never been activated. In a cluster environment, if one nucleus switches to "ignore", all other nuclei also switch. If there is a problem during a refresh and the error action is "ignore", then all nuclei switch to "ignore".

Note:
The "ignore" option may cause application integrity problems.

Log Trigger Activity
This field can be modified.
active trigger activity is recorded in the log.
inactive (the default) trigger activity is not recorded in the log.
Whenever a trigger or a stored procedure is invoked, information about the procedure can be printed to the print spool, as defined by the user. This information may be useful for auditing or debugging purposes.
Trigger Table Size This field can be modified. This is the size (in bytes) of the trigger table buffer. If additional triggers are loaded to the trigger table, you may need to increase the buffer size (see the section Updating the Trigger Table). The default value is calculated based on the number of triggers defined in the trigger file. (See the section Buffer Size Calculations.)
Pre-Trigger Queue Size This field can be modified. This is the size (in bytes) of the pre-trigger queue buffer, that contains pre-command triggers prior to selection for processing. The default value is calculated (see the section Buffer Size Calculations.)
Post-Trigger Queue Size This field can be modified. This is the size (in bytes) of the post-trigger queue buffer that contains post-command triggers prior to selection for processing. The default value is calculated (see the section Buffer Size Calculations.)

Subsystem Activity

Subsystem activity provides information about currently executing Natural subsystems.

Start of instruction setTo access subsystem activity information

Start of instruction set 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.

Start of instruction setTo access trigger activity information

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

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.
Type The type of trigger: pre (pre-command) or post (post-command), non-P (non-participating), part (participating), or async (asynchronous).
RecBu The RecBuff setting for the trigger: access (read only), update (read and write), or none.
UserID The (hexadecimal) ID of the user who issued the actual Adabas command.

Start of instruction setTo display additional information

Top of page

 www.softwareag.com  Copyright © 1971-2013 Software AG, Darmstadt, Germany.   SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT