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 version 7.4 is available with Natural 3.1 or above for
OS/390 or z/OS
VSE/ESA
z/VM
BS2000
The facility requires the selectable unit 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 selectable unit Adabas Online System (AOS). 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 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.
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.
The modules ADATSP and STPEND are located in the Adabas load library. TRGMPMJ is the JCL/JCS 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.
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 |
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 OS/390 and 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/ESA 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 OS/390 and z/OS:
//CMPRT01 DD SYSOUT=X //CMPRT02 DD SYSOUT=X //CMPRT03 DD SYSOUT=X //CMPRT04 DD SYSOUT=X //CMPRT05 DD SYSOUT=X
for VSE/ESA:
// 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 OS/390 and 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/ESA:
// 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:
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.
/* 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
Specify the correct local libraries in the MPM JCL STEPLIB / JCS LIBDEF. 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; 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 OS/390 and z/OS; in the Adabas partition for VSE/ESA; 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.
As part of your Adabas install, you loaded the dataset 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 dataset 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.
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:
OS/390 and z/OS environments, the link pack area (LPA) or the extended link pack area (ELPA).
VSE/ESA, 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.
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.
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.
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:
After the batch Natural driver has been assembled, use the LNKBATCH job to link it.
For OS/390 and z/OS, use the example job ASMNTOS from the ADAvrs.JOBS dataset to assemble the batch Natural driver.
For VSE/ESA, use JCS example ASMNTVSE. Also refer to your Natural job NATI055.
For BS2000, use job example ASMNTBS2 from the ADAvrs.JOBS library.
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.
Include STPDRV and STPRBE in the CSTATIC parameter specification for the NATPARM module as follows:
CSTATIC=(STPDRV,STPRBE)
For VSE/ESA, z/VM, specify the following parameters as well:
ADAPRM=ON EXTBUF=10 MT=0
Include STPNAT and SPAENA in the CSTATIC parameter specification for the NATPARM module as follows:
CSTATIC=(STPNAT,SPAENA)
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.
Customize the LNKBATCH job supplied in the ADAVrs.JOBS library for the libraries concerned and run the job.
Ensure that the REGION / SIZE parameter in the Adabas start-up 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.
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 (dataset ADABAS.Vvr.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.Vvr.LOAD
DD DISP=SHR, DSN=NATURAL.Vvr.LOAD
Ensure that the Natural module created in step 3 is linked into the Adabas library used in the Adabas nucleus start-up job LIBDEF SEARCH statement. Add the Natural library (where the phase is located) to the LIBDEF SEARCH statement in the Adabas nucleus start-up job.
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 BLSLIB<nn>,<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.
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 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.
Must be set to ON in VSE/ESA and VM/CMS environments.
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.
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.
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.
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 | the Natural trigger driver |
| STPRBE | the record buffer extraction routine |
| SPAENA | enables access to the database command queue (BS2000 only) |
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.
The default DYNPARM=ON processes dynamic parameters that are supplied during Natural start-up. 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 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.
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.
Set the EXTBUF parameter to at least 10 in VSE/ESA, z/VM environments. EXTBUF is not mandatory in OS/390 or z/OS environments.
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.
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
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.
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.
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 start-up 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.
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.
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 |
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.
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 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.
Define the library SYSTRG. Set start-up 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 start-up, 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:
Do not specify an error program. Errors are handled internally by the Adabas triggers and stored procedures facility.
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 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.
Set to 0 (zero) to prevent any limits being exceeded since the Natural subsystems may run for an indefinite period of time.
Set to 0 (zero) to prevent any limits being exceeded since the Natural subsystems may run for an indefinite period of time.
Set to 0 (zero) to prevent any limit being exceeded since the Natural subsystems may run for an indefinite period of time.
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.
Do not specify. Restarts are handled internally by the Adabas triggers and stored procedures facility.
No limitations. The Adabas triggers and stored procedures facility logs on to SYSSPT. Therefore, all procedures must be in the steplibs as required.
Do not specify. Startup is automatic during the logon by Adabas Online System or the Natural trigger driver.