
	Version 8.1.4	SEARCH INDEX CONTENTS \| PDF PAGE PDF BOOKS \| HOME UP PREV NEXT

— Triggers and Stored Procedures —

Installation and Configuration

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:

Software Requirements
Overview
Install Trigger Maintenance
Install the Adabas Trigger Driver
Install the Natural Trigger Driver
NATPARM Considerations
Printer Considerations
Work File Considerations
Natural Security Considerations

Software Requirements

The Adabas triggers and stored procedures facility delivered with Adabas is available with Natural 3.1 or above for:

z/OS
VSE
z/VM
BS2000

The facility requires Adabas Online System (AOS).

Note:
You must apply solution ADA813L002 before you can use triggers and stored procedures in z/VM environments. For more information about this solution and its documentation, please contact your Software AG support representative.

Natural Optimizer Compiler is not required, but can significantly improve performance when using triggers and stored procedures.

Overview

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 Trigger Maintenance

1. Install AOS

Install the Adabas Online System (AOS) add-on product. Use the instructions provided in the Adabas Online System documentation.

2. Load the trigger file

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.

3. Modify the NATPARMs and relink

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

4. Start the facility and create the profile

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

Install the Adabas Trigger Driver

The modules ADATSP and STPEND are located in the Adabas load library. TRGMPMJ is the JCL/JCS used to start the Adabas nucleus.

1. Set the ADARUN SPT parameter

Set ADARUN SPT=YES to activate the Adabas triggers and stored procedures facility in the nucleus, or SPT=NO to deactivate it.

Notes:

SPT=YES requires PROG=ADANUC and MODE=MULTI. SPT is a global parameter and must be set the same on all nuclei in a cluster.
Do not specify OPENRQ=YES. It causes problems with Natural subsystems; i.e., they receive response code 148 and are not able to initialize.

2. Set up each Natural subsystem

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.

3. Set up all Natural work files and print files

Specify additional labels for all specified Natural work files and print files.

BS2000 Exception

No labels need to be specified in the BS2000 jobs. Printout is found in the file

L.L.db_task_nr.natural_load_name.timestamp

where:

`db_task_nr`	is the task number of the database that is running the triggers and stored procedures facility
`natural_load_name`	is the name of the batch Natural module
`timestamp`	is a character representation of the time when the subtask was started

Example for Steps 2 and 3

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 z/OS JCL:

//TSPRT01  DD  SYSOUT=X
//TSPRT02  DD  SYSOUT=X
//TSPRT03  DD  SYSOUT=X
//TSPRT04  DD  SYSOUT=X
//TSPRT05  DD  SYSOUT=X

The following labels must be specified for the VSE JCS:

// ASSGN SYS041,DISK,VOL=PACK01,SHR
// DLBL TSPRT01,'PRINT.OUTPUT1',0,SD
// EXTENT SYS041,PACK01,1.0,SSSS,LLL
// ASSGN SYS042,DISK,VOL=PACK01,SHR
// DLBL TSPRT02,'PRINT.OUTPUT2',0,SD
// EXTENT SYS042,PACK01,1.0,SSSS,LLL
// ASSGN SYS043,DISK,VOL=PACK01,SHR
// DLBL TSPRT03,'PRINT.OUTPUT3',0,SD
// EXTENT SYS043,PACK01,1.0,SSSS,LLL
// ASSGN SYS044,DISK,VOL=PACK01,SHR
// DLBL TSPRT04,'PRINT.OUTPUT4',0,SD
// EXTENT SYS044,PACK01,1.0,SSSS,LLL
// ASSGN SYS045,DISK,VOL=PACK01,SHR
// DLBL TSPRT05,'PRINT.OUTPUT5',0,SD
// EXTENT SYS045,PACK01,1.0,SSSS,LLL

The following labels must be specified for the z/VM EXEC:

"FILEDEF TSPRT01 DISK TSPRT01 LISTING A"
"FILEDEF TSPRT02 DISK TSPRT02 LISTING A"
"FILEDEF TSPRT03 DISK TSPRT03 LISTING A"
"FILEDEF TSPRT04 DISK TSPRT04 LISTING A"
"FILEDEF TSPRT05 DISK TSPRT05 LISTING A"

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

for z/OS:

//CMPRT01  DD  SYSOUT=X
//CMPRT02  DD  SYSOUT=X
//CMPRT03  DD  SYSOUT=X
//CMPRT04  DD  SYSOUT=X
//CMPRT05  DD  SYSOUT=X

for VSE:

// ASSGN SYS051,DISK,VOL=PACK01,SHR
// DLBL CMPRT01,'PRINT.CMPRT01',0,SD
// EXTENT SYS051,PACK01,1.0,SSSS,LLL
// ASSGN SYS052,DISK,VOL=PACK01,SHR
// DLBL CMPRT02,'PRINT.CMPRT02',0,SD
// EXTENT SYS052,PACK01,1.0,SSSS,LLL
// ASSGN SYS053,DISK,VOL=PACK01,SHR
// DLBL CMPRT03,'PRINT.CMPRT03',0,SD
// EXTENT SYS053,PACK01,1.0,SSSS,LLL
// ASSGN SYS054,DISK,VOL=PACK01,SHR
// DLBL CMPRT04,'PRINT.CMPRT04',0,SD
// EXTENT SYS054,PACK01,1.0,SSSS,LLL
// ASSGN SYS055,DISK,VOL=PACK01,SHR
// DLBL CMPRT05,'PRINT.CMPRT05',0,SD
// EXTENT SYS055,PACK01,1.0,SSSS,LLL

for z/VM:

"FILEDEF CMPRT01 DISK CMPRT01 LISTING A"
"FILEDEF CMPRT02 DISK CMPRT02 LISTING A"
"FILEDEF CMPRT03 DISK CMPRT03 LISTING A"
"FILEDEF CMPRT04 DISK CMPRT04 LISTING A"
"FILEDEF CMPRT05 DISK CMPRT05 LISTING A"

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

for z/OS:

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

for VSE:

// ASSGN SYS061,DISK,VOL=PACK01,SHR
// DLBL CMWKF01,'WORK.CMWKF01',0,SD
// EXTENT SYS061,PACK01,1.0,SSSS,LLL
// ASSGN SYS062,DISK,VOL=PACK01,SHR
// DLBL CMWKF02,'WORK.CMWKF02',0,SD
// EXTENT SYS062,PACK01,1.0,SSSS,LLL
// ASSGN SYS063,DISK,VOL=PACK01,SHR
// DLBL CMWKF03,'WORK.CMWKF03',0,SD
// EXTENT SYS063,PACK01,1.0,SSSS,LLL
// ASSGN SYS064,DISK,VOL=PACK01,SHR
// DLBL CMWKF04,'WORK.CMWKF04',0,SD
// EXTENT SYS064,PACK01,1.0,SSSS,LLL
// ASSGN SYS065,DISK,VOL=PACK01,SHR
// DLBL CMWKF05,'WORK.CMWKF05',0,SD
// EXTENT SYS065,PACK01,1.0,SSSS,LLL

for z/VM:

"FILEDEF CMWKF01 DISK CMWKF01 LISTING A"
"FILEDEF CMWKF02 DISK CMWKF02 LISTING A"
"FILEDEF CMWKF03 DISK CMWKF03 LISTING A"
"FILEDEF CMWKF04 DISK CMWKF04 LISTING A"
"FILEDEF CMWKF05 DISK CMWKF05 LISTING A"

Notes:

File name assignments are not required if the procedures do not need work file support or additional printer file definitions.
The MPM JCL/JCS should include any other assignments that are normally used in your batch Natural JCL/JCS to execute a particular Natural subprogram or program.

Changes Required for z/VM Support

z/VM multitasking is used to support the Adabas triggers and stored procedures facility. As a result, changes are required to the sample RMTNUC EXEC.

Modify your own RMTNUC EXEC using the following sample as a guide:

/*              Sample RMTNUC Exec                                    */
/*                                                                    */
Address COMMAND
 user.set = word('HT RT',cmsflag(cmstype)+1)
"SET CMSTYPE HT"

trce = 'OFF'
htype = 'HT'
interpret trace trce
/*  The following variable may have the following values:             */
/*       'DISK' to spool a dump to the virtual printer & read to disk */
/*       'PRT'  to spool a dump to the virtual printer                */
/*       'NO'   to suppress a dump                                    */
dump = 'NO'
/*                                                                    */
dbid = '00052'
restart = 'NO'
if 'ARG'() = 1 then parse upper arg dbid restart .
dbid = 'STRIP'(dbid)
if dbid = '' then dbid = '00052'
             else dbid = 'RIGHT'(dbid,5,'0')
signal on error
interpret call adf || dbid 'ADANUC MULTI' trce htype
pull . device
if result = 99 then signal error
/*                                                                    */
errtype ='CMS'
'COPY RUNNUC CONTROL A RDV' || dbid 'CONTROL A ADANUC DDCARD A (REPLACE)'
'COPY RUNMULTI CONTROL A ADANUC DDCARD A (APPEND)'
'COPY RDB' || dbid 'CONTROL A ADANUC DDCARD A (APPEND)'
'COPY STP' || dbid 'CONTROL A ADANUC DDCARD A (APPEND)'
If restart = 'RESTART' then
  'COPY RUNDIB CONTROL A ADANUC DDCARD A (APPEND)'
/*                                                                    */


errtype ='DATADEF'
/*
'DATADEF DDPRINT,DSN=NUC' || dbid'.DDPRINT,MODE=A'
'DATADEF DDDRUCK,DSN=NUC' || dbid'.DDDRUCK,MODE=A'
*/
'DATADEF DDPRINT,DSN=.TEMP,UNIT=SFS,FNAME=NUC' || dbid',FTYPE=DDPRINT'
'DATADEF DDPRINT,DSN=.TEMP,UNIT=SFS,FNAME=NUC' || dbid',FTYPE=DDDRUCK'
'DATADEF DDCARD,DSN=ADANUC.DDCARD,MODE=A'
select ;
   when dump = 'DISK' then 'DATADEF DUMP,DSN=ADANUC.DUMP,MODE=A'
   when dump = 'PRT'  then 'DATADEF DUMP,UNIT=PRT'
   when dump = 'NO'   then 'DATADEF DUMP,DUMMY'
   otherwise do
      say '..         Invalid dump request'
      signal error
   end
end
signal off error
  /*-----------------------------------------------------------------*/
  /*  Add the filedef's for Adabas triggers and stored procedures    */
  /*-----------------------------------------------------------------*/

  "FILEDEF *      CLEAR"     /*  Let's start clean                   */

/* Filedefs for Adabas triggers & stored procedures facility         */

  "FILEDEF TSPRT01 DISK TSPRT01 LISTING  A"
  "FILEDEF TSPRT02 DISK TSPRT02 LISTING  A"
  "FILEDEF TSPRT03 DISK TSPRT03 LISTING  A"
  "FILEDEF TSPRT04 DISK TSPRT04 LISTING  A"
  "FILEDEF TSPRT05 DISK TSPRT05 LISTING  A"

  "FILEDEF CMPRT01  DISK CMPRT01  LISTING  A"
  "FILEDEF CMPRT02  DISK CMPRT02  LISTING  A"
  "FILEDEF CMPRT03  DISK CMPRT03  LISTING  A"
  "FILEDEF CMPRT04  DISK CMPRT04  LISTING  A"
  "FILEDEF CMPRT05  DISK CMPRT05  LISTING  A"

  "FILEDEF CMWKF01  DUMMY"
  "FILEDEF CMWKF02  DUMMY"
  "FILEDEF CMWKF03  DUMMY"
  "FILEDEF CMWKF04  DUMMY"
  "FILEDEF CMWKF05  DUMMY"

/* End of Filedefs for Adabas triggers & stored procedures facility  */


/*---------------------------------------------------------------------*/
/*  Now set the language file to SSFume                                */
/*---------------------------------------------------------------------*/

"SET LANGUAGE ( ADD SSF USER"

"LOADMOD  SSFRUN"
"PROGMAP  SSFRUN"
  'SSFRUN'                    /* This will run ADARUN                */

   rcode = rc
  "EXECOS"

  'FINIS * * *'

  Exit rcode
error:
'SET CMSTYPE' origtype
return 99

4. Specify the local libraries

Specify the correct local libraries in the MPM JCL STEPLIB / JCS LIBDEF. Include

the Adabas load library containing the modules STPEND and ADATSP;
the user load library containing the user exits;
the Natural load library containing the specially linked batch Natural nucleus.

Install the Natural Trigger Driver

The Adabas triggers and stored procedures facility uses Natural subsystems to execute user-written procedures. These subsystems are run as subtasks; a maximum of ten subsystems can be active at any given time. A Natural subsystem is fundamentally a batch Natural nucleus.

Subtasks run in the Adabas address space for z/OS; in the Adabas partition for VSE; and in the Adabas region for z/VM. For BS2000, subtasks are not run in the same address space as Adabas, but are spawned jobs that communicate with the Adabas nucleus using group common memory and P1 eventing.

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.

Adabas Example Jobs

As part of your Adabas install, you loaded the data set ADAvrs.JOBS (library ADAvrs.SRC on BS2000) from tape. As a result, the following examples are installed:

Name	Description
ASMNTOS	NATOS assembly (z/OS only)
ASMNTVSE	NATVSE assembly (VSE only)
ASMNTBS2	NAMBS2 assembly (BS2000 only)
ASMPARM	NATPARM assembly
LNKBATCH	Natural nucleus link
LNKNATNS	non-shared Natural nucleus link for a split nucleus (not for BS2000)
LNKNATSH	shared Natural nucleus link for a split nucleus (not for BS2000)
TRGMPMJ	startup MPM JCL (not for BS2000)
TRGPARM	NATPARM with changes required for the Adabas triggers and stored procedures facility (not for BS2000)
TSPBLDM	builds TSP Natural version 4.2.3 module
TSP$LOAD	called by the TSPBLDM EXEC

Note:
If the examples are modified, they should be kept in a different library; otherwise, they will be overwritten when you install subsequent versions.

Batch Natural Driver NATOS / NATVSE / NAMBS2

As part of your Natural install, you loaded the data set NATvrs.SRCE. The source library member NATOS / NATVSE / NAMBS2 contains the batch Natural driver that must be used to create the batch Natural nucleus for the Adabas triggers and stored procedures facility.

Prepare the Batch Natural Nucleus

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" (the "reentrant" part in BS2000), resides in the shared area of the operating system:
- z/OS environments, the link pack area (LPA) or the extended link pack area (ELPA).
- VSE, the shared virtual area (SVA).
- BS2000, the common memory pool (CMP).
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, also called the "front-end" part in BS2000, significantly reduced in size by the removal of the environment-independent parts, is loaded into the batch address space (or partition or region) and is designated specifically for use by triggers and stored procedures.

z/OS Environments

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.

VSE Environments

The batch Natural nucleus used for the Adabas triggers and stored procedures facility must include the special NATPARM module created using example job ASMPARM.

Also add the module STPNAT to the Natural link. See example job LNKBATCH for more information.

The link modules must be placed in a library that is concatenated to the MPM JCS LIBDEF.

z/VM Environments

The batch Natural nucleus used for the Adabas triggers and stored procedures facility must include the special NATPARM module created using example job TSPBLDM. Build the Natural nucleus used for the Adabas triggers and stored procedures facility using TSPBLDM EXEC as an example. Note that it calls TSP$LOAD, which has additional INCLUDEs for TSP support.

BS2000 Environments

Set the NAMBS2 macro parameter to ADACOM=ADABAS.

Customize the ASMPARM and ASMNTBS2 module according to your library naming conventions. You can use ASMPARM to assemble the NATPARM module. The ASMNTBS2 module assembles the Natural driver NAMBS2.

Link the following modules to the Natural: STPDRV, STPNAT, STPUES, and SPAENA

In versions of Natural older than version 4.2 modify the LNKBATCH job to link it. Perform this in Natural 42 by putting the following settings in the LNATFRNT source and run the P.LINK procedure in the Natural jobs Library:

//       INCLUDE-MODULES  ELEMENT = (SPAENA, STPNAT, STPEND, STPUES, DEPLD)           -
//          LIBRARY = $SAG.ADABAS.MOD

The STPNAT module allows access from the Natural subtask to Adabas. It contains the symbol ADABAS and should replace the ADAUSER module for this application. ADAUSER should not be linked to the Natural triggers subtask.

In addition, in Natural version 4.2, ensure that the BATRENT parameter ILCS is set to NO, otherwise the STPNAT cannot load ADALNK. This also requires that the NATPARM module has the following macros set:

NTCFICU OFF
NTXML OFF

1. Assemble the batch Natural driver

For z/OS, use the example job ASMNTOS from the ADAvrs.JOBS data set to assemble the batch Natural driver.

For VSE, use JCS example ASMNTVSE. Also refer to your Natural job NATI055.

For BS2000, use job example ASMNTBS2 from the ADAvrs.SRC library.

2. Assemble the NATPARM module

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

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.

z/OS, VSE, and z/VM Environments

Include STPDRV and STPRBE in the CSTATIC parameter specification for the NATPARM module as follows:

CSTATIC=(STPDRV,STPRBE)

For VSE and z/VM environments, specify the following parameters as well:

ADAPRM=ON
  EXTBUF=10
  MT=0

BS2000 Environments

Include STPNAT, STPDRV, and SPAENA in the CSTATIC parameter specification for the NATPARM module as follows:

CSTATIC=(STPNAT,STPDRV, STPEND, SPAENA)

3. Link the batch Natural driver

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.

BS2000 Environments

Customize the LNKBATCH job supplied in the ADAvrs.SRC library for the libraries concerned and run the job.

4. Check the REGION / SIZE parameter setting

Ensure that the REGION / SIZE parameter in the Adabas startup JCL/JCS 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.

5. Make the Natural nucleus accessible to the Adabas nucleus

z/OS Environments

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.

Example:

//STEPLIB  DD  DISP=SHR, DSN=ADABAS.ADAvrs.LOAD
           DD  DISP=SHR, DSN=NATURAL.NATvrs.LOAD

VSE Environments

Ensure that the Natural module created in step 3 is linked into the Adabas library used in the Adabas nucleus startup job LIBDEF SEARCH statement. Add the Natural library (where the phase is located) to the LIBDEF SEARCH statement in the Adabas nucleus startup job.

BS2000 Environments

Ensure that the Adabas nucleus is executed with the following statement:

/START-PROGRAM *M(&ADALIB,ADARUN),-
/  RUN-MODE=ADV(ALT-LIB=YES)

Access the library where the batch nucleus is located by

/SET-FILE-LINK DDLNKPAR,DDLNKPAR_file
/SET-FILE-LINK BLSLIBnn,batch_natural_library

where:

nn is 00-99, the next available number in the BLSLIB link cards

batch_natural_library is the batch Natural library

DDLNKPAR_file

is a file containing the following statements:

ADARUN DBID=dbid

ADARUN IDTNAME=idtname

where dbid is the database ID of the Adabas nucleus idtname is the ID table name when the Adabas nucleus runs

Important:
DDLNKPAR_file must not be a temporary file.

Note:
Make sure that the nucleus is started with the ADARUN parameter SUBMPSZ set to "2000000" (or larger). Otherwise, the Natural subtask will deliver the message "ADAI2S - 04000004 no mother task common memory" error.

6. Check the ADALNK link options

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.

NATPARM Considerations

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.

Special Requirements

ADAPRM

Must be set to ON in VSE and VM/CMS environments.

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:

SPAENA	enables access to the database command queue (BS2000 only)
STPEND	performs backend processing for the trigger driver
STPNAT	Adabas triggers user interface
STPRBE	the record buffer extraction routine (not on BS2000)

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.

EXTBUF

Set the EXTBUF parameter to at least 10 in VSE and z/VM environments. EXTBUF is not mandatory in z/OS environments.

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

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 NTFILE 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 Dynamic Overrides

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

SYSSPT	is the library where the stored procedure application was INPLed during the installation procedure. It is also the library where the executable procedures should be located.
STP	is the Natural trigger driver startup routine.

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.

Printer Considerations

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.

Dynamic CMPRINT Assignment

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

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.

Example:

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

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.

BS2000 Only

If not declared, CMPRINT writes to SYSLST. The subtasking automatically assigns a file with the following structure:

L.L.<db_task_number>.<natural_load_name>.<timestamp>

where

<db_task_number>	is the task number of the database that is running the triggers and stored procedures facility
<natural_load_name>	is the name of the batch Natural module
<timestamp>	is a character representation of the time when the subtask was started

Work File Considerations

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

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.

Natural Security Considerations

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.

Logging On

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 or 48 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 or 48 being issued by the Natural subsystems.

Library Settings

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.

Security Limits

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.

Parameter Settings

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

SEARCH INDEX CONTENTS | PDF PAGE PDF BOOKS | HOME UP PREV NEXT