This document tells you how to install the Adabas triggers and stored procedures facility. It includes information about setting NATPARMs, assigning printers and work files, accommodating a Natural Security environment, and setting up the stored procedure link routine.
This document covers the following topics:
The Adabas triggers and stored procedures facility delivered with Adabas is available with any supported version of Natural.
The facility requires Adabas Online System (AOS).
Natural Optimizer Compiler is not required, but can significantly improve performance when using triggers and stored procedures.
The Adabas triggers and stored procedures facility is installed in three parts:
Install Trigger Maintenance, the online user interface.
Install the Adabas trigger driver, the Adabas nucleus component.
Install the Natural trigger driver, the Natural nucleus component.
Install the Adabas Online System (AOS) add-on product. Use the instructions provided in the Adabas Online System documentation.
Use the ADALOD utility to load the trigger file to the Adabas database.
Specify the keyword TRIGGER in the ADALOD parameters to indicate that the trigger file is to be loaded. (Do this the same way you would specify the CHECKPOINT or SECURITY parameter when loading the checkpoint or security file, respectively.)
Omit the ADACMP step, which is not required because the FDT definitions are already known to the nucleus.
The trigger file is currently not permitted to have Adabas security; that is, no Adabas password and cipher or security-by-value.
Update the NATPARMs to use triggers and stored procedures in the online Natural nucleus and relink them to the Natural nucleus. Use either:
a logical file definition with the NTLFILE macro specification in the NATPARM; or
the LFILE parameter as a dynamic parameter at session initialization.
The logical file number for the trigger file is 154.
Note:
If you do not use either the NTLFILE macro or the
LFILE parameter, you will be required
to enter the database ID and file number every time you start the Adabas
triggers and stored procedures facility.
Start the Adabas triggers and stored procedures facility from a Natural session and create the profile.
Log on to Adabas Online System and select the option "Trigger Maintenance". Press ENTER.
From the main menu, select "A" for Administrator Functions and press ENTER. If required, enter the database ID and file number, and press ENTER twice.
Note:
The database ID and file number are required only if you
did not use either the NTLFILE macro or the LFILE parameter in step 3 above; or the value
specified in the definition is incorrect.
From the Administrator Functions Menu, select "M" for Modify Profile Information and press ENTER.
The Modify Profile Information screen contains a number of default values that can be overwritten now or later. However, the profile must be correctly installed before running the Adabas triggers and stored procedures facility. For more information, see section Display/ Modify Profile Information.
Note:
Trigger Maintenance is not fully operational until
the required file-field tables and trigger definitions are added. For more
information, see section Trigger
Maintenance.
The modules ADATSP and STPEND are located in the Adabas load library. TRGMPMJ is the JCL used to start the Adabas nucleus.
Set ADARUN SPT=YES to activate the Adabas triggers and stored procedures facility in the nucleus, or SPT=NO to deactivate it.
Notes:
Specify labels and job control assignments for each subsystem.
These depend on the "maximum subsystems" value and on the CMPRINT assignments in the Adabas triggers profile, as well as the printer and work files used by the procedures.
Specify additional labels for all specified Natural work files and print files.
The following example is provided to illustrate steps 2 and 3 above. In this example:
the dynamic CMPRINT assignment (an option to be specified in the Adabas triggers profile) is set to TSPRT, and
the maximum number of subsystems defined in this example is 5.
The following labels must be specified for the JCL:
//TSPRT01 DD SYSOUT=X //TSPRT02 DD SYSOUT=X //TSPRT03 DD SYSOUT=X //TSPRT04 DD SYSOUT=X //TSPRT05 DD SYSOUT=X
If each of the five subsystems defined in the profile can WRITE, PRINT, or DISPLAY to a print file, the following definitions must be provided in the MPM JCL
//CMPRT01 DD SYSOUT=X //CMPRT02 DD SYSOUT=X //CMPRT03 DD SYSOUT=X //CMPRT04 DD SYSOUT=X //CMPRT05 DD SYSOUT=X
See the section Printer Considerations for information about CMPRTnn labels and assigning logical printers.
If each of the five subsystems defined in the profile can WRITE WORK or READ WORK to a work file, the following definitions must be provided in the MPM JCL
//CMWKF01 DD DISP=SHR,DSN=WORK.CMWKF01 //CMWKF02 DD DISP=SHR,DSN=WORK.CMWKF02 //CMWKF03 DD DISP=SHR,DSN=WORK.CMWKF03 //CMWKF04 DD DISP=SHR,DSN=WORK.CMWKF04 //CMWKF05 DD DISP=SHR,DSN=WORK.CMWKF05
Notes:
Specify the correct local libraries in the MPM JCL STEPLIB. Include
the Adabas load library containing the modules STPEND and ADATSP.
the Natural load library containing the specially linked batch Natural nucleus.
The Adabas triggers and stored procedures facility uses Natural subsystems to execute user-written procedures. These subsystems are run as subtasks in the Adabas address space; a maximum of ten subsystems can be active at any given time. A Natural subsystem is fundamentally a batch Natural nucleus.
To optimize resource usage during Adabas execution, it is important to configure the Natural trigger driver (the Natural nucleus component) in a way that minimizes the resources used by the Natural subsystems.
As part of your Adabas install, you loaded the data set ADAvrs.JOBS from tape. As a result, the following examples are installed:
Note:
If the examples are modified, they should be kept in a
different library; otherwise, they will be overwritten when you install
subsequent versions.
As part of your Natural install, you loaded the data set NATvrs.SRCE. The source library member NATOS contains the batch Natural driver that must be used to create the batch Natural nucleus for the Adabas triggers and stored procedures facility.
Software AG recommends that you split Natural into two functional parts: an environment-independent nucleus and an environment-dependent nucleus. See the Natural Installation for more information.
The environment-independent nucleus, also called "shared nucleus," resides in the shared area of the operating system in the link pack area (LPA) or the extended link pack area (ELPA).
By executing from these special areas of the operating system, the independent nucleus can be commonly accessed (shared) by multiple address spaces (or partitions or regions) within the same operating system.
The advantages of the shared nucleus are virtual storage relief; less paging activity since there is only one copy of the nucleus in the system; and less maintenance since ZAPs are applied only once.
The environment-dependent nucleus significantly reduced in size by the removal of the environment-independent parts, is loaded into the batch address space and is designated specifically for use by triggers and stored procedures.
The batch Natural nucleus used for the Adabas triggers and stored procedures facility must include the NATPARM module with the entry points for STPDRV and STPRBE.
It must be linked with the STPNAT module. The link should not use the options RENT or REUSE; otherwise, results are unpredictable. In addition, ensure that the ADALNK routine used by stored procedures and triggers (ADARUN SPT=YES) is linked with NOREUSE and NORENT, or results will be unpredictable.
The link modules must be placed in a library that is concatenated to the MPM JCL STEPLIB.
Important:
For Natural version 8, this job is not needed.
Use the example job ASMNTOS from the ADAvrs.JOBS data set to assemble the batch Natural driver.
See the section NATPARM Considerations for more information.
Member STPNAT is supplied in the Adabas load library and has three entry points: STPDRV, STPRBE, and ADABAS.
STPNAT replaces ADAUSER. It has the same Adabas entry point and performs all the normal functionality of ADAUSER. In addition, STPNAT contains logic specifically for triggers and stored procedures.
Note:
With Natural 8.2.6 and below, it is necessary to specify
CSTATIC entries for STPDRV and STPRBE.
CSTATIC=(STPDRV,STPRBE)
If your installation uses Natural version 8.2 or higher, the license key for Natural must be prepared and assembled and linked.
For more information, refer to your Natural documentation.
When linking the batch Natural driver that was assembled in step 1, include the NATPARM assembled in step 2 and STPNAT to create the batch Natural nucleus for the Adabas triggers and stored procedures facility.
Ensure that the Natural nucleus link deck contains an INCLUDE STPNAT statement and does not contain the usual INCLUDE ADAUSER statement. The AOSASM module is not required.
Ensure that the REGION / SIZE parameter in the Adabas startup JCL is not set to impose a size limitation.
Such a size limitation, such as 8 megabytes, may have been specified when the operating system environment was set up.
Ensure that the Natural module created in step 3 is accessible to the Adabas nucleus during Adabas initialization by
placing it in the Adabas load library in the MPM JCL steplib or joblib; or
concatenating the Natural load library (where the module is located) to the Adabas MPM JCL steplib or joblib.
The Adabas load library (data set ADABAS.ADAvrs.LOAD) also contains the module STPEND, which must be in one of the libraries of the MPM JCL steplib.
//STEPLIB DD DISP=SHR, DSN=ADABAS.ADAvrs.LOAD
DD DISP=SHR, DSN=NATURAL.NATvrs.LOAD
Ensure that the ADALNK routine used by stored procedures and triggers (ADARUN SPT=YES) is linked with NOREUSE and NORENT, or results will be unpredictable.
The NATPARM definitions specified in the Natural parameter module for a Natural nucleus are used to tailor the environment for the Natural session.
To successfully execute the Natural nucleus component, you must specify the correct values for certain NATPARM parameters. For more information, see the Natural documentation.
- ADAMODE
Must be set to zero.
- Buffer Pool
Use the local buffer pool or the global buffer pool depending on the needs and configuration of the local environment:
If the local buffer pool is used, a procedure that is invoked by the user can remain in the local buffer pool for the duration of the Natural session; as a result, a new copy may be ignored.
If the global buffer pool is used, the procedure can be deleted from the buffer pool if the DBA wants it to be activated at the earliest possible time.
- Buffer Sizes
Because the Natural trigger driver is a run-time system only (not a development system), various buffers can be kept to a minimum size, depending on how your programs are written. For example, ESIZE can be set to the maximum GDA size that any Natural program may use. The size of the GDA used by the Adabas triggers and stored procedures facility is 12K.
- CDYNAM
The parameter regulates dynamic loading of non-Natural programs. Set with no consideration for triggers and stored procedures because the procedures will be linked to the Natural nucleus. The default value is 5.
- CSTATIC
The CSTATIC parameter regulates programs that are statically linked to Natural. There is no default value. The parameter must specify the routines used by the Adabas triggers and stored procedures facility:
STPDRV trigger driver entry (see Note below) STPEND performs backend processing for the trigger driver STPNAT Adabas triggers user interface STPRBE the record buffer extraction routine (see Note below) Note:
With Natural 8.2.7 and above, it is not necessary to specify CSTATIC entries for STPDRV and STPRBE.
- DU(mp)
The default DU=OFF prevents the generation of a memory dump for an abend. This setting ensures that the Natural ESTAE will be active for the duration of the session. When the Natural ESTAE is active, all program abends are trapped and the Natural session is restarted instead of terminated. This is an important performance consideration.
- DYNPARM
The default DYNPARM=ON processes dynamic parameters that are supplied during Natural startup. This default must be used because each batch Natural subsystem is started with at least one parameter (STACK=). See section NATPARM Dynamic Overrides for more information.
- ETA
ETA is the error transaction program. It must not be specified. The Adabas triggers and stored procedures facility sets up the error transaction program for the Natural session according to its own requirements.
Note:
The Adabas triggers and stored procedures facility alone uses 1500 bytes; therefore, if the ETA program uses 4K in the GDA, the ESIZE is approximately 6K.- ETID
If ETID is used; that is, if ETID=' ' (blank) is not specified, each task (maximum of ten tasks) must be given a unique ETID (Adabas user ID). If Natural Security is used, and if a NATPARM value is not specified for ETID, the RESTART option in the library profile and the ETID option in the user profile can be set to "N" to prevent error messages NAT3048 and NAT3009.
- Limit Parameters
Because the batch Natural subsystems are long-running transactions, the LE, LT, MADIO, MAXCL, and MT parameters should not be set with limits. Setting these parameters with limits can result in an error during the execution of a procedure; in that case, the command that fired the trigger receives response code 155 (ADARSP155) or 156 (ADARSP156).
Note:
A timeout parameter in the Adabas triggers profile automatically resolves the problem of long-running procedures. Alternatively, the DBA can cancel a subsystem that is busy executing a procedure.- NTLFILE
The NTLFILE parameter should be coded to point to the Adabas trigger file. The logical file number for the trigger file is 154. Another alternative to the NTLFILE parameter would be a dynamic override using the Natural NTLFILE parameter
- PROFILE
The PROFILE parameter must not be specified. This parameter causes Adabas calls to be issued before all of the Natural control blocks are initialized. This will cause unpredictable results during the initialization of stored procedures and triggers.
- PROGRAM
The PROGRAM parameter must not be specified. It is used when starting the batch Natural subsystem and is set to STPEND. This module is located in the Adabas triggers and stored procedures load library and should be added to the MPM JCL steplib so that it can be loaded as required.
- STACK
The STACK parameter must not be specified. It is used in starting the batch Natural subsystems and is specified by the Adabas triggers and stored procedures facility.
NATPARM values specified in the Natural nucleus can be defined dynamically by using the Adabas triggers profile, or a Natural Security user profile if Natural Security is installed.
NATPARM parameter values are obtained from the Adabas triggers profile and used when the Natural subsystems are initialized. NATPARM values specified in the profile override the values specified in the Natural nucleus.
Before modifying the NATPARM definitions, read the section Special Requirements. Because each Natural subsystem can accept trigger requests pertaining to a variety of applications and/or files, it is essential that the Natural environment be set appropriately.
The STACK parameter must be passed; it ensures that the Natural subsystem will give control to the Natural trigger driver after it is initialized. The value of the STACK parameter is fixed as follows and cannot be changed by the user:
STACK=(LOGON:SYSSPT;STP)
where
All other NATPARM values should be set by the user as required.
The Natural session normally continues to run as long as the Adabas nucleus is active. This means that each Natural subsystem is a long-running task; limit parameters for the Natural session must be set accordingly. Session settings cannot be modified while a Natural subsystem is running. However, certain session parameters can be modified using procedures in the same manner as normal Natural programming options.
For batch Natural subsystems, the printer is always determined by the setting of the CMPRINT label and the number of the subsystem. When running under a single address space, it becomes necessary to have different assignments for CMPRINT in order to prevent contention; multiple Natural subsystems are running and any or all of these may want to print.
Even if the different subsystems are doing opens and closes of the assigned printer, there is no guarantee that these will not conflict. Any conflicts result in an error from the operating system.
For example, if you use the WRITE (nn), PRINT (nn), or DISPLAY (nn) option, the "nn" is a permanent (unlike CMPRINT) assignment specifically for all subsystems.
If a procedure that is running in subsystem 01 executes a WRITE (01), and another procedure that is running in subsystem 02 executes a WRITE (01), an error is received from the operating system and ultimately from Natural: this should be prevented.
When the Natural subsystems are started, the Adabas trigger driver determines a dynamic printer assignment based on the "CMPRINT assignment" definition in the Adabas triggers profile.
The CMPRINT assignment in the triggers profile is a 1 to 6-byte field that must be consistent with the file assignments in the MPM JCL. This printer assignment is used as a prefix to the subsystem task number when the subsystem is started.
For example, if you specify printer TSPRT, subsystems 01 and 02 will expect labels TSPRT01 and TSPRT02 to be defined in the MPM startup JCL.
The Adabas triggers and stored procedures facility is a subtask or subsystem that runs in the background. There are multiple Natural subsystems, and it is not possible to force a procedure to be executed from any specific subsystem: a dynamic assignment for CMPRINT is made available when any WRITE, PRINT, or DISPLAY statements are used for printing information.
The PDA that is passed to the procedure contains a unique subsystem identifier, which allows you to print to CMPRT01 through CMPRT31 using a DECIDE statement.
DECIDE ON FIRST VALUE OF RQ-TASK /*check subsystem number VALUE '01' WRITE (1) NOTITLE NOHDR text VALUE '02' WRITE (2) NOTITLE NOHDR text VALUE '03' WRITE (3) NOTITLE NOHDR text VALUE '04' WRITE (4) NOTITLE NOHDR text VALUE '05' WRITE (5) NOTITLE NOHDR text NONE WRITE NOTITLE NOHDR text END-DECIDE
In the last case (NONE), the output will go to the printer specified by the dynamic assignment for the CMPRINT label.
If a procedure running in subsystem 01 does any printing, the output can go to the dynamic assignment of CMPRINT or, as the DECIDE statement shows, the output can go to printer 01 (CMPRT01), as specified by the MPM JCL.
If more than one printer is required, ranges of print files can be defined. For example, if five Natural subsystems are defined, the range of print files could be CMPRT01 through CMPRT05 or CMPRT06 through CMPRT10, and so on.
The label for a work file is in the following format:
CMWKFnn
where "nn" is the work file number.
Work file usage is an issue that may require some consideration; however, if there are no reads or writes to any work files, there is no need to put them in the JCL.
If work files are required, a method must be developed to ensure that contention does not occur. The same considerations that apply to printers also apply to work files.
For example, the read/write operations of a procedure could be directed to a particular work file, depending on the task number, i.e., the number of the Natural subsystem in which the procedure is run. In this case, task 01 would read/write to CMWKF01; task 02 would read/write to CMWKF02; and so on.
Since you can identify the subsystem where your procedure is executing, you can use a work file that is permanently assigned to that subsystem.
This can be accomplished using the DECIDE statement, as described in the section Printer Considerations. Other solutions can be found, of course, depending on how the procedure is being used.
This section describes the security for running the Natural subsystems when using stored procedures. The information is relevant when using Adabas triggers and stored procedures in a Natural Security environment.
When logging on to Natural, you may use either AUTO=ON or AUTO=OFF.
If you use AUTO=OFF, you must supply a user ID and password and specify "Y" for the "NATSEC LOGON Required" value in the Adabas triggers profile. Otherwise, problems occur.
The password and user ID you provide can be variable or fixed. The value ** must be used with the variable name. It will be replaced by the Natural subsystem number to make the value unique. For example, if USER** and PSWD** are specified, the user IDs and passwords (assuming three tasks) are generated as follows:
| Task | UserID | Password |
|---|---|---|
| 01 | USER01 | PSWD01 |
| 02 | USER02 | PSWD02 |
| 03 | USER03 | PSWD03 |
The user ID must be defined to Natural Security, with consideration given to the ETID and the batch user ID. If the same user ID is used, response code 9 (ADARSP009) or 48 (ADARSP048) may be received, thus invalidating the Natural session. It is important to remember that the Natural subsystems are all running concurrently and must be kept separate from each other.
If you use AUTO=ON, the job name or the assigned batch user ID is used for the actual logon ID. More than one user will be signed on, depending on the maximum number of tasks. This should be taken into account in order to prevent response code 9 (ADARSP009) or 48 (ADARSP048) being issued by the Natural subsystems.
Define the library SYSTRG. Set startup to " " (blank) when logging on from SYSAOS, or to "menu" when logging on directly from the logon screen.
Define the library SYSSPT. The Natural subsystem logs on to this library.
Do not include any startup, error, or restart settings in the definition for either library. These settings are established automatically when the Adabas triggers and stored procedures facility initializes.
The libraries can be protected; however, the user(s) as defined using the Adabas triggers profile must have sufficient authority to log on and perform all the required processing. For example, it would not be useful to disallow a module for the subsystem user IDs and then have an error occur when the Natural trigger driver invokes that routine.
Natural Security allows you to override certain NATPARM settings, including
non-activity logoff limit
transaction duration
CPU time (MT=)
maximum Adabas calls (MADIO=)
The Natural subsystems are one long transaction that will execute multiple "subtransactions". If security limits are set for one or more of these, the limits apply to all programs for that session.
The following describes Natural Security parameter settings that affect the Adabas triggers and stored procedures subtasks:
- Error Program
Do not specify an error program. Errors are handled internally by the Adabas triggers and stored procedures facility.
- ETID
Any procedure that stores transaction data may subsequently be invoked from a different subsystem. In order to work, the routine GET TRANSACTION DATA must know which subsystem invoked the procedure. If this is a problem, the user may build in another form of data recovery. The ETID option should be used with caution to prevent response code 9 (ADARSP009) or 48 (ADARSP048).
- Library Protection
Library protection is not required, but Adabas Online System users must be able to log on to SYSTRG and the batch Natural trigger driver must be able to log on to SYSSPT.
- MADIO
Set to 0 (zero) to prevent any limits being exceeded since the Natural subsystems may run for an indefinite period of time.
- MAXCL
Set to 0 (zero) to prevent any limits being exceeded since the Natural subsystems may run for an indefinite period of time.
- Non-Activity Logoff Limit
Set to 0 (zero) to prevent any limit being exceeded since the Natural subsystems may run for an indefinite period of time.
- Password Change Option
The Natural Security user profile includes an option that can be used to request that users change their passwords every "n" number of days. If this option is used, the NATSEC password in the Adabas triggers profile must also be modified.
- Restart Program
Do not specify. Restarts are handled internally by the Adabas triggers and stored procedures facility.
- Steplibs
No limitations. The Adabas triggers and stored procedures facility logs on to SYSSPT. Therefore, all procedures must be in the steplibs as required.
- Startup Transaction
Do not specify. Startup is automatic during the logon by Adabas Online System or the Natural trigger driver.