This document describes the use of special functions available with the Natural IMS Interface.
The following topics are covered:
Some of these functions require the Natural Authorized Services Manager (ASM).
If the ASM is required, it must have been started before the function is used.
The Natural subsystem used by the ASM must be the same as the one used by the Natural session.
For accounting and monitoring, the SIP server must have been enabled in addition.
The accounting function is only available in dialog-oriented
environments. It is activated by setting the environment table parameter
ACTACTV to YES.
With each terminal I/O, information about the specific Natural session
is written to the IMS log or to SMF, depending on the setting of the Natural
IMS parameter ACTLOG.
If the ACTACTV parameter is set to
CMD, a /LOG command is issued that
writes the accounting record to the IMS TM log. All transaction codes must
therefore be allowed to use the /LOG command. At the beginning of
each record an 8-byte header is inserted. This header helps to easily select
the accounting records using the IMS utility DFSERA10. The header
string is defined by the environment table parameter
ACTAHDR.
If the ACTACTV parameter is set to
LOG, the accounting record is written to the IMS TM log using the
LOG call. With the Natural IMS parameter
ACTARID, you specify the log code to be used.
If the ACTACTV parameter is set to
"SMF", the accounting record is written to SMF using the
Authorized Services Manager. With the Natural IMS parameter
ACTARID, you specify the SMF record type to be used.
The following information about each Natural user session is stored with each terminal I/O:
IMS ID of the IMS system in which the user is active,
LTERM name of the IMS terminal on which the session was started,
user ID of the user of the Natural session (taken from the IOPCB),
number of dialog steps currently performed,
currently active transaction code,
currently active PSB name,
current Natural library name to which the user is logged on,
currently active Natural program name,
non-Natural transaction code to which the session is possibly suspended to,
time and date when the session was started,
time and date of the last ENTER operation,
DBID and FNR of the Natural system file (FNAT) for this
session,
DBID and FNR of the Natural user file (FUSER) for this
session,
DBID and FNR of the Natural dictionary file (FDIC) for
this session,
DBID and FNR of the Natural Security system file (FSEC)
for this session,
DBID and FNR of the Natural spool file (FSPOOL) for this
session,
DBID and FNR of the Super Natural system file for this session,
last encountered Natural error number,
compressed thread length of the last terminal output.
The information is mapped by the DSECT NIMACTR. There are
two areas for storing the DBID and FNR of the Natural system files used. In the
first area, one byte is used for each DBID and FNR; this is supported for
compatibility reasons. In the second area, a fullword is used for each DBID and
FNR to support Adabas Version 6. The accounting record is prefixed with a
length and version field.
Before the accounting record is written to the IMS TM log, respectively
to SMF, the user exit NIIXACCT is called. You can use this user
exit to tailor the accounting record to your requirements. You may also append
information to the accounting record. In this case, you must set the length
field to the new length.
Since the accounting record is built in the command buffer, the total
length must not exceed the value specified with the Natural IMS parameter
CMBSIZE minus 17 bytes. The maximum length allowed is
passed as parameter.
If NIIXACCT returns with a non-zero value in register 15,
no accounting record is written.
The monitoring function is only available in dialog-oriented
environments. It is activated by setting the environment table parameter
MONACTV to YES and uses the SIP function of
the Authorized Services Manager. The Natural subsystem must be the same as the
one used by the Natural session to be monitored.
You can follow the ongoing activity of all Natural sessions which use
the same Natural subsystem by using the Monitoring (M) function of the
SYSTP utility. For more information on this utility, see
SYSTP in
the Natural Utilities documentation. The
SYSTP session must also use the same Natural subsystem.
The broadcasting function is only available in dialog-oriented
environments. It is activated by setting the environment table parameter
BROACTV to YES and uses the SIP function of
the Authorized Services Manager.
Once broadcasting is active, it is possible to send broadcast messages to targeted users of a given Natural subsystem. Such users can be:
all users of the Natural subsystem to which the sender is connected;
all users of the Natural subsystem within the same IMS system as the sender of the message;
all users of the Natural subsystem within the same IMS system as the sender of the message, but additionally restricted to a given transaction code;
all users of the Natural subsystem within the same IMS system as the sender of the message, but additionally restricted to a Natural application;
all users of the Natural subsystem within the same IMS system as the
sender of the message, but additionally restricted to a Natural application and
to a given FUSER system file.
When a session comes to a terminal output, a check is made to see whether the session has to receive a message or not. If not, the normal Natural output is sent. If yes, the message is sent instead of the normal output and, when pressing ENTER, the Natural nucleus is instructed to re-send the last screen. In this way, you first see the message and afterwards receive the normal Natural output screen.
If more than one broadcast message is available, the messages are displayed one after the other until the last message has been shown. Afterwards, the normal Natural output screen is displayed.
A broadcast message will be displayed only if its expiration time specified in the message creation procedure has not been exceeded.
When a broadcast message is sent, you must press RESET before you can press ENTER again. All possible attention IDs have the same effect as pressing ENTER.
The utility SYSTP can be used to
create broadcast messages and to display the contents of all active messages
together with the LTERM/IMSID of the sender. The text of a message is limited
to 72 bytes.
Messages to be broadcast are saved in a pool maintained by the SIP
server. They remain there until you delete them using the SYSTP
utility or until you shut down the Authorized Services Manager.
 |
Warning: When a broadcast message is deleted or created, all expired messages are deleted as well. |
The following topics are covered below:
The multi-session feature is only available in dialog-oriented
environments. It is activated by setting the Natural IMS parameter
MSACTV to YES and allows to run up to nine
simultaneous Natural sessions on the same logical terminal.
Creating and resuming Natural sessions is controlled using PF keys.
The Natural IMS parameters MSCRKEY and
MSRSKEY define the create and resume keys.
If the create key is pressed, the current Natural session is suspended and a new Natural session is created.
If the resume key is pressed, any input field may contain the string
x, with x between 1 and
MSSESMX. In this case, the currently active session is
suspended and the specified session is resumed. If x
is greater than MSSESMX, the input is passed to the
active application.
If the resume key is entered without any input, the next suspended
session is resumed in a wrap-around manner. If, for example, the active session
is session number 4, the next suspended session in the range 5 through
MSSESMX or 1 through 3 is resumed. If there is no
suspended session, the input is passed to the active application.
If the session to be resumed is using a different transaction code than the current session, an implicit program-to-program switch is done in order to resume the suspended session with the correct transaction code.
If conversational and non-conversational environments are used in
parallel, the modnames NIIMODNC and NIIMODMS are used
for switching between the environments. The format definitions are delivered in
the source modules NIIMODMS and NIIMODNC and have to
be defined to MFS using MFSUTL.
If the active session is terminated, the next suspended session (if there is any) is resumed in the same order as with the resume key.
If the active session is terminated by a program-to-program switch, all suspended sessions are discarded.
If the Natural IMS parameter MSMAX is set to
"2" (two parallel sessions are allowed), the create key must be
identical with the resume key. In this case, pressing the create key creates a
second session if only one session is active, if not, it switches the
session.
Note:
The Natural IMS Interface Version 2.2 mode is still supported for
compatibility reasons, but is no longer documented. The Version 2.2 mode is
activated by setting the Natural IMS parameter MSCMPTB
to YES.
The session ID is the internally used unique identification of a
session. It has the form XXXXXXxY,
where XXXXXXx is the prefix and
Y is the session number in the form of a numeric
digit in the range of 1 to 9.
The session prefix is built by compressing the logical terminal name into a 6-byte binary number XXXXXX and by setting x to binary zero.
If the compression algorithm is not suitable for the LTERM names used
(error 3635 is issued in this case), the user exit NIIXMSSP must
be used in order to build a unique 7-byte prefix of the session ID.
The multi-session database is a HDAM root-only database which contains the Natural-reserved area of the SPA for each suspended session.
The model DBD for the description of the multi-session database is delivered in the source module NIIMSDBD and must be defined to IMS TM.
The DBD name must be specified in the Natural IMS parameter module
using the parameter MSDBD. The PCB number must be
specified in the transaction code table using the parameter
MSPCB of macro NIMTRNTG.
The server environment allows 3GL applications to execute Natural
programs using a call interface. It is available in all supported IMS TM
environments and consists of the Natural IMS driver NIISRVD of the
server call interface NIIBOOTS and of the service API
NIIPCOM.
NIISRVD and NIIBOOTS are delivered as source
modules and must be assembled and link-edited on your site. For details, see
Installing the Natural IMS
Interface in the Natural Installation
documentation.
The server environment allows you to start a Natural session by calling
NIIBOOTS from any 3GL program. After the Natural session has been
started, it returns to the calling 3GL program and waits for further input. The
input would normally be expected from CMSYNIN, which means that
the 3GL program has to simulate Natural's primary input dataset.
It is strongly recommended to always put the server Natural on the
NEXT line. This allows the next call to NIIBOOTS to
either execute a Natural command or a Natural program. Otherwise, the next call
to NIIBOOTS would be treated as input for a Natural program which had been
started by a previous call to NIIBOOTS.
Similarly as with the message-oriented interface, all output normally
written to CMPRINT is sent to the IMS TM destination specified
with the Natural profile parameter SENDER. For details
about special destinations used by the Natural IMS interface, refer to
Sender
Destination in the section Natural under IMS TM -
Environments.
|
Warning: In an MPP Environment, the same server Natural will be used by all transactions scheduled in this region by default. If you want to use multiple server Naturals in the same MPP region, you must generate multiple server call interfaces. Each server call interface must be generated with a unique name specified with the NIMBOOT parameter
SERVERN and must be linked under a unique name. It is
recommended to name the load module with the name specified with
SERVERN. |
NIIBOOTS is the default name as used in the documentation
and in the delivered sample programs. This default name can be changed during
installation.
NIIBOOTS requires the following parameters:
the PSB address (the address of the PCB address list),
the command area,
the reply area.
In the command area, the following may be passed:
the startup parameters,
any Natural command followed by its input data,
the NIIBOOTS-specific commands, such as
STAT and REFR (in
combination with the startup parameters).
The startup parameters are passed in two contiguous 80-byte areas. The first area contains the name of the environment table and the name of the transaction code to be used as follows:
ENV-TAB=environment-table-name TRNCODE=transaction-code-name
The transaction code is only honored if TRNCODE=YES is
specified on the NIMDRIV macro. For details about the usage of the
transaction code, refer to the NIMBOOT macro in the section
Natural under IMS TM - Environments).
The second area contains the dynamic Natural parameters with which the Natural session is to be started.
The reply area is the area in which a reply is to be entered from the
executed Natural program using the service API NIIPCOM.
Each time it is invoked, NIIBOOTS checks whether the
server Natural has been initialized.
If Natural has not been initialized, a new Natural session is started and the received command is passed to Natural as a dynamic parameter.
If Natural has been initialized, the string received in the command area is passed to Natural as a Natural command or as a Natural program.
The NIIBOOTS-specific commands
STAT and REFR do the
following:
STAT returns COLD in the
reply area if Natural has not been initialized and WARM if it has
been initialized.
REFR forces the
initialization/reinitialization of Natural, regardless of the current state of
Natural.
It is highly recommended to use an ON ERROR routine in
the executed Natural programs in order to give back to the calling 3GL program
some information in the reply area using NIIPCOM.
NIIBOOTS passes the return code provided by Natural on
the termination of Natural.
To illustrate usage of NIIBOOTS and
NIIPCOM, the sample programs NIPBOOTS and
NIPPCOM are provided. NIPBOOTS plays the role of the
calling 3GL program, NIPPCOM is a sample Natural program executed
in the server environment and writes the string NIISRVR into the
reply area. The ON ERROR routine places the Natural error number
in the reply area.
With the sample programs, you can go through the following scenario:
Pass the command STAT. The string
COLD is returned to the reply area.
Pass the command: STACK=(LOGON
SYSEXTP),SENDER=S0201, where S0201 is the LTERM name
of the assigned printer device in the server Natural. Natural will be
initialized and will be ready to receive a Natural command in library
SYSEXTP. The successful logon message is issued on the assigned
printer. Nothing is returned in the reply area.
Pass the command STAT. The string
WARM is returned to the reply area.
Pass the command NIPPCOM. Program
NIPPCOM is executed and the string NIPSRVR is
returned to the reply area. Natural is ready to accept the next command in
library SYSEXTP.
Pass the command: REFR STACK=(LOGON
SYSEXTP;NIPPCOM),SENDER=S0201
Natural is reinitialized and program NIPPCOM in
library SYSEXTP is executed. The reply area contains the string
NIPSRVR.
Pass the command FIN. Natural is
terminated and no information is passed to the reply area. The return code will
contain the return code of the Natural termination. The Natural termination
message is issued on the assigned printer device.
Pass the command STAT. The string
COLD is returned to the reply area.
