This section covers the following topics:
In all environments, Natural must know the name of the scheduled PSB,
not only the address of the PCB list. In the online environments, the
application developer must have the ability to change the scheduled PSB during
a Natural session. This is accomplished by the Natural command
NATPSB (in batch or CICS environments) or by calling
CMDEFSWX/CMDIRSWX (in IMS TM environments).
The NATPSB command handles PSB scheduling
status and can be invoked with one of the following three options:
| Option | Description |
|---|---|
INQ |
Performs an inquiry on PSB scheduling status. |
ON psbname |
Issues a PSB schedule of the PSB
psbname.
|
OFF |
Issues a SYNCPOINT to commit all
updates and terminate the PSB.
|
Note:
The NATPSB INQ command is valid in an
IMS TM environment, too.
The following command, for example, issues a PSB schedule of
ED00PSB:
NATPSB ON ED00PSB
A PSB scheduling operation is allowed only if there is no active PSB.
If a PSB is active and another PSB is to be scheduled, the ON
request for this new PSB must be preceded by an OFF request.
Otherwise, the following message is issued:
NAT3900 PSB ... scheduled, but PSB ... already active
Since NATPSB is actually a Natural program, it can also be
invoked with a FETCH or FETCH RETURN statement. The
options described above should then be passed in the FETCH
statement as two parameters. The first parameter would be an alphanumeric field
of three bytes for INQ, ON or OFF. If
the first parameter is ON, the second parameter must also be
passed. It is an alphanumeric field of eight bytes and contains the name of the
PSB to be scheduled.
Execution time errors of NATPSB can be intercepted by an
ON ERROR statement. The error messages from NAT3900 to NAT3903 and
from NAT3817 to NAT3820 are generated by NATPSB.
FETCH RETURN 'NATPSB' 'ON' 'PBNDL01'
ON ERROR
IF *ERROR = 3900 /* PSB already scheduled
STACK TOP COMMAND 'NATPSB' 'ON' PBNDL01'
STACK TOP COMMAND 'NATPSB' 'OFF'
STOP
END-IF
END-ERROR
END
To execute a batch program that accesses a DL/I database, it is
necessary to use the DL/I batch procedure which executes an application program
under DL/I control. Therefore in the JCL/JCS used to execute Natural batch
accessing DL/I databases, the first program in the step is a DL/I system
program (DFSRRC00 for z/OS, DLZRRC00 for z/VSE).
PSB scheduling is performed by DL/I before control is passed to
Natural. Since Natural requires the name of the scheduled PSB, it is necessary
to invoke the Natural PSB scheduling program NATPSB before
executing a Natural application program. This can be achieved by specifying the
command NATPSB ON psbname
as the first command in the batch input stream to
Natural.
Under z/OS, the DL/I region controller program (DFSRRC00)
invokes the NDLSINIB bootstrap module for Natural for DL/I by specifying
MBR=NDLSINIB in the PARM field of the
EXEC card. NDLSINIB reads two statements from the
NDINPUT DD card:
Statement 1 contains the name of the Natural module to be executed.
Statement 2 contains the dynamic Natural parameters.
Before executing the user program, the command NATPSB ON
psbname must be specified in the input stream
to pass the name of the current PSB to Natural.
// EXEC DLIBATCH,PSB=psbname,MBR=NDLSINIB //G.STEPLIB DD ... Steplibs //G.NDINPUT DD * Input for NDLSINIB natbatch Natural load module name STACK=(LOGON user),DU=ON Any Natural parameters //DDCARD DD * Primary input file ADARUN MODE=MULTI,PR=USER ADARUN cards //G.CMSYNIN DD * Primary input file NATPSB ON psbname Mandatory Natural PSB scheduling pgmname Natural user program name /* End of Natural commands
// EXEC DLIBATCH,PSB=psbname,MBR=NDLSINIB //G.STEPLIB DD ... Steplibs //G.NDINPUT DD * Input for NDLSINIB natbatch Natural load module name STACK=(LOGON user),DU=ON Any Natural parameters //G.CMSYNIN DD * Primary input file NATPSB ON psbname Mandatory Natural PSB scheduling pgmname Natural user program name /* End of Natural commands
In both examples, natbatch is
assumed to be the load module produced by the respective link-edit
procedure.
Under z/VSE, the DL/I region controller program
(DLZRRC00) invokes the NDLSINID bootstrap module for
Natural for DL/I.
The SYSIPT cards are as follows:
DL/I control statements:
DLI,NDLSINID,
psbname
natbatch
where:
DLI is a parameter for DLZRRC00,
NDLSINID is the name of the bootstrap module,
psbname is the name of
the PSB,
natbatch is the name of
the Batch Natural nucleus;
dynamic parameters to be passed to Natural;
ADARUN statements (only if Adabas system file is being
used);
Natural input cards.
A /* delimiter card is required before the
ADARUN statements (if present) and before the Natural dynamic
parameters and input cards.
Before executing the user program, the NATPSB ON
psbname command must be specified in the
input stream to pass the name of the current PSB to Natural.
// EXEC DLZRRC00 DLI,NDLSINID,psbname DL/I control statements natbatch Batch Natural nucleus name /* STACK=(LOGON user),DU=ON Any Natural parameters /* End of Natural parameters ADARUN MODE=MULTI,PR=USER ADARUN cards /* End of ADARUN cards NATPSB ON psbname Mandatory Natural PSB scheduling pgmname Natural user program name /* End of Natural commands
// EXEC DLZRRC00 DLI,NDLSINID,psbname DL/I control statements natbatch Batch Natural nucleus name /* STACK=(LOGON user),DU=ON Any Natural parameters /* End of Natural parameters NATPSB ON psbname Mandatory Natural PSB scheduling pgmname Natural user program name /* End of Natural commands
In both examples, natbatch is
assumed to be the load module produced by the respective link-edit
procedure.
Under CICS, the PSB must be scheduled using the
NATPSB command, which actually invokes the
appropriate scheduling or termination calls.
The active PSB can be changed dynamically during the Natural session
using the NATPSB command. Therefore, more than one
PSB can be used during a Natural session. Only one PSB, however, can be active
for a CICS task at a time.
The NATPSB command can be entered in the
Natural Command line or passed to Natural dynamically with the Natural
STACK statement when starting a Natural session.
MOVE 'STACK=(NATPSB ON ED00PSB)'
TO DYNAMIC-PARM-KEYWORD-LIST.
EXEC CICS
XCTL PROGRAM('NATvrs')
END-EXEC.
This example taken from a COBOL/CICS program assumes that
NATvrs is the value supplied for the
PROGRAM keyword in the CICS PPT; where
vrs is the current Natural version
number.
Another possibility is to assign NATPSB
commands to one or more PF keys when starting a Natural session as illustrated
in the following example:
NATD STACK=(KEY PF1 = ED00PSB)
This example assumes that NATD is the value supplied for
the TRANSID keyword in the CICS PCT. ED00PSB is the
following Natural program (cataloged in the library SYSTEM):
STACK TOP COMMAND 'NATPSB ON ED00PSB' STACK TOP COMMAND 'NATPSB OFF' END
Whenever PF1 is pressed, the commands NATPSB
OFF and NATPSB ON ED00PSB are
executed.
Under IMS TM, Natural for DL/I runs as a conversational transaction. It
has the ability to perform direct or deferred message switching. This means
that several different Natural transactions and PSBs can be invoked during a
single Natural session. It is also possible to invoke multiple PSBs and provide
the user with access to databases defined in different PSBs. This is
accomplished by calling CMDEFSWX or CMDIRSWX.
Under IMS TM, PSB scheduling is performed by the IMS Control Region
before control is passed to the Natural transaction running as an MPP (Message
Processing Program) or BMP (Batch Message Processing). As in the batch
environment, Natural needs to know the name of the scheduled PSB. This is
accomplished internally at Natural session start by the driver which stores the
pointer to the PCB address list and the name of the PSB into IOCB fields. The
NATPSB INQ command can be issued in this environment
but the NATPSB ON/NATPSB
OFF commands cannot.
The Natural subprograms NDLPCBAD and NDLPSBSC
are provided, which can be invoked with a CALLNAT statement from
within a Natural program.
See the following sections:
The Natural subprogram NDLPCBAD provides the calling
Natural program with the name of the currently scheduled PSB and the pointer to
the PCB address list.
DEFINE DATA LOCAL 01 PSBNAME (A8) 01 PCBADDR (B4) END-DEFINE CALLNAT 'NDLPCBAD' PSBNAME PCBADDR DISPLAY PSBNAME PCBADDR END
This pointer can then be used by non-Natural programs to obtain the
individual PCB addresses and to establish addressability to the PCBs. For
example, move these addresses to the BLL cells (COBOL/VS) or use the SET
ADDRESS instruction (COBOL II).
The Natural subprogram NDLPSBSC allows for scheduling a
PSB in CICS or batch environments. It performs the same functions as the
NATPSB
command.
Using CALLNAT 'NDLPSBSC' (instead of FETCH RETURN
'NATPSB') avoids the NAT1108 error message, which is issued if a PSB is
scheduled in an INPUT loop as follows:
INPUT ... FETCH RETURN 'NATPSB' 'ON' 'psbname' REINPUT ... /* returns NAT1108
DEFINE DATA LOCAL 01 COMMAND (A3) * 'ON' * 'OFF' * 'INQ' 01 PSBNAME (A8) 01 RETCODE (B1) * 01: Command invalid * 02: PSB name missing * 03: PSB psbname active * 04: PSB psbname not active * 05: Not used * 06: No PSB active END-DEFINE MOVE 'ON' TO COMMAND MOVE 'psbname'TO PSBNAME CALLNAT 'NDLPSBSC' COMMAND PSBNAME RETCODE DISPLAY PSBNAME RETCODE END
Under IMS TM, NDLPSBSC can only be used with parameter
'INQ', because PSB scheduling is performed by the IMS control
region before control is passed to Natural.
This section covers the following topics:
A Natural program can make use of the IMS TM symbolic checkpoint and
restart facilities by using the statements GET
TRANSACTION DATA and END TRANSACTION.
The executing program can checkpoint user data on the IMS system log
datasets by supplying an 8-byte checkpoint ID as the first operand in the
END TRANSACTION statement and by specifying the areas to be
checkpointed as additional operands.
To ensure that the checkpoints are written to the IMS log dataset, the
Natural profile parameter ETDB (see the Natural
Parameter Reference documentation) must be specified, and
the database specified with the ETDB parameter must be a
DL/I database.
If no operands are specified with the END TRANSACTION
statement, Natural uses NATDLICK as the default checkpoint ID.
This checkpoint data are retrieved by executing the GET
TRANSACTION DATA statement. The first operand of this statement must
also be an 8-byte checkpoint ID. The remaining operands must be listed in the
same sequence, length and format as in the corresponding END
TRANSACTION statement.
RESET CKPID(A8) KEY(A10) AREA1(A20) AREA2(N6) AREA3(A120) GET TRANSACTION DATA CKPID KEY AREA1 AREA2 AREA3 IF CKPID NE ' ' /* checkpoint restart MOVE KEY TO START-KEY(A10) ELSE RESET START-KEY /* normal restart MOVE *PROGRAM-ID TO CKPID : READ DLI-DB BY XKEY > START-KEY : UPDATE : END TRANSACTION CKPID XKEY AREA1 AREA2 AREA3 : END
| Normal Restart: | Simply run the job. The checkpoint ID parameter in the
program's GET TRANSACTION DATA statement is set to blanks by the
DL/I call handler NDLSIOBA.
|
||||
| Checkpoint Restart: |
To restart after an abnormal termination, specify one of the
following checkpoint IDs in the
|
These are the usual IMS TM restart procedures. Each checkpoint ID used
in an END TRANSACTION statement is displayed in the job output
once the extended checkpoint has been successfully executed by IMS.
The checkpoint ID parameter of the program's GET TRANSACTION
DATA statement is set to the actual checkpoint ID used by IMS.
The data areas are restored into the areas you specify in your
GET TRANSACTION DATA statement.
Ensure that the //IMSLOGR DD statement specifies the
correct IMS log dataset.
When Natural is started in a BMP region, the initialization routine
issues an XRST call, to ensure that symbolic
checkpointing is available. This is done whether the Natural user programs to
be executed make use of IMS symbolic checkpoint logic or not. If the
XRST was unsuccessful, Natural returns the following
error message:
NAT3959 XRST call failed with DL/I status code xx
When a GET TRANSACTION DATA statement is directed to the
Natural call handler and the initial XRST call has
been flagged as successfully executed, the restart checkpoint ID and contents
of this buffer are copied into the program's user fields.
When an END TRANSACTION statement is directed to the
Natural call handler, the user fields to be checkpointed are copied into the
buffer before a symbolic checkpoint call (CKPT) is issued.
If the database specified with the profile parameter
ETDB (see
the Natural Parameter Reference documentation) is not the
same as the database affected by the transaction, the first operand of the
END TRANSACTION statement will be used as checkpoint ID for the
ETDB database, while NATDLICK will be used as
checkpoint ID for the other database not specified with the
ETDB parameter.
The total area to be checkpointed must not exceed 1992 bytes.
If the INITCAL parameter of NDLPARM
is set to YES, Natural issues an INIT
call during session initialization and during each MPP transaction start. The
character string in the I/O area is STATUS GROUPA. This informs
IMS that Natural is prepared to accept status codes regarding data
unavailability. IMS returns status codes BA or BB
when the DL/I call requires access to unavailable data (for example, if the
accessed database has been stopped).
The corresponding error messages of Natural for DL/I are:
NAT3897 DL/I status code 'BA' NAT3898 DL/I status code 'BB'
For compatibility reasons, the default setting of
INITCAL is NO.
The INIT call is issued only if Natural runs
in a BMP or MPP region.
Natural supports Fast Path databases.
Fast Path database types include Main Storage Databases (MSDB) and Data Entry Databases (DEDB).
MSDB:
MSDBs have root only segments that are fixed-length. There are two types of MSDBs: terminal-related and non-terminal-related.
To read segments in an MSDB, GU and
GN are used.
To update segments in an MSDB, REPL,
DLET, ISRT, and
FLD are used.
DEDB:
DEDBs use the design concept that database content can be physically partitioned by ranges of root keys or by groupings produced by a randomizing algorithm.
As a basic requirement, the non-conversational NATIMS
driver must be used. This is because Fast Path programs cannot be
conversational programs, that is, they cannot use an SPA.
For DEDB databases, no special processing is required by Natural for DL/I.
For MSDB databases, the (one and only) SSA is built without command codes because DL/I does not allow for it (not even the null command code must be used in case of MSDB databases).
When updating segments in an MSDB database, Natural for DL/I uses the
REPL call (rather than the
FLD call) because the UPDATE statement
of the Natural language does not provide a search condition that indicates
which segments must be updated (searched update).
Natural for DL/I supports the Generalized Sequential Access Method (GSAM), with which a sequential dataset can be handled as a sequential non-hierarchic database by IMS.
Although GSAM databases have no segments, keys or parentage, they are handled internally by Natural as root-only databases with fixed or variable-length segment types. Thus, it is possible to use DDMs instead of work files for GSAM record types.
For variable-length GSAM records, Natural maintains the record length; you need not reserve a field for the record length in the DDM.
A FIND or READ statement generates a
GN (get next) call sequence for GSAM. Due to GSAM
restrictions, UPDATE and DELETE statements are not
allowed. Due to GSAM restrictions, a STORE statement must insert
records at the end of the database.
IMS repositions GSAM databases for sequential processing, which means that the position need not be re-established by the application program after checkpoint calls. Therefore, Natural performs no repositioning after checkpoint calls in the case of PCBs for GSAM.
In order to use the extended restart feature of IMS, the Natural job has
to terminate abnormally. This can be accomplished by calling the Natural IMS TM
service module CMSVC13D. If the job terminates either normally or
with a condition code, IMS does a clean-up and no restart is possible.
Every GSAM database structure which is to be used by Natural must be
processed by the NATDBD procedure. The assembly step of this
procedure extracts the relevant information from the DBD source and simulates
an appropriate SEGM statement as shown in the following
examples.
DBD NAME=TESTDB,ACCESS=(GSAM,BSAM) DATASET DD1=INPUT,DD2=OUTPUT,RECFM=F,RECORD=80 DBDGEN END
From the above source statements, NATDBD would simulate a
segment with the name of the DBD and the length as specified with the
RECORD keyword:
SEGM NAME=TESTDB,BYTES=80
DBD NAME=TESTDB,ACCESS=(GSAM,BSAM) DATASET DD1=INPUT,DD2=OUTPUT,RECFM=VB DBDGEN END
From the above source statements, NATDBD would simulate a
segment with the name of the DBD, a maximum length of 32760 and a
minimum length of 8:
SEGM NAME=TESTDB,BYTES=(32760,8)
In both examples, the NDB name and the segment name are
TESTDB, and the generated DDM name would be
TESTDB-TESTDB.
The Natural program to read this GSAM database would be as simple as:
READ TESTDB-TESTDB DISPLAY FIELDS-OF-TESTDB LOOP END
When Natural is running under CICS in pseudo-conversational mode (that
is, with NATPARM parameter PSEUDO=ON) or under IMS
TM, the Natural task/transaction is terminated following each write to a
terminal, and a new task/transaction is started when new input is entered
through the terminal. Because a Syncpoint is forced at the end of the
task/transaction, all resources are released when the message is sent to the
terminal. Therefore, the DL/I PSB is no longer active, nor are any DL/I
GET HOLD calls in effect.
To avoid consistency problems on the DL/I databases, Natural performs additional processing when it is running in CICS pseudo-conversational mode or under IMS TM:
If a DL/I GET HOLD call is still active at
the end of the task/transaction, the values of the fields read by the program
that issued the corresponding READ or FIND (only the
fields used, not the whole segment) are saved in an internal table of Natural
for DL/I.
When a new task/transaction resumes the Natural session and the
program issues an UPDATE or DELETE statement, Natural
checks whether the field contents have been changed. If the check shows that
the field contents have not been changed, the
UPDATE/DELETE is executed. If they have been changed,
an error message is returned by Natural notifying the user that the field
values just read were changed by another user in the system and that,
therefore, the UPDATE/DELETE operation is not carried
out.
Natural also performs automatic PSB repositioning following resumption of the task/transaction. A Natural application is, therefore, not affected by pseudo-conversational mode, unless it uses conventional programming techniques, for example COBOL or PL/1.
If the task/transaction is terminated due to a screen I/O while a
READ or FIND loop is being executed on a segment
without a unique sequence field, Natural is not able to reposition the PSB in
the database when the task/transaction is resumed. The same may occur when
using secondary indices with non-unique key fields in pointer segments. Natural
is not able to reposition the PSB in these instances because DL/I does not
provide a method of re-establishing position in the middle of non-unique keys
or non-keyed segments.
