This document describes the service programs of the Natural IMS TM Interface.
The following topics are covered:
Introduction to the Natural IMS TM Interface Service Programs
Description of the Natural IMS TM Interface Service Programs
NIIDEFT - Prepare Deferred Switch to Natural Transaction Code
NIIDEFTX - Prepare Deferred Switch to Non-Natural Transaction Code
NIIGCMD - Retrieve Next Reply Segment of Previous IMS TM Command
Service programs are Natural subprograms which provide Natural under
IMS TM with additional functionality. You can call them from within a Natural
program using a standard CALLNAT
statement.
The service programs are provided in the library SYSEXTP
and you must copy them to the SYSTEM
or steplib library. Sample
Natural programs to invoke the service programs are also provided in the
library SYSEXTP
.
The last parameter in each service program is the return code whose format is (I4).
The following return code values are common for all service programs:
0 | OK |
-1 | Non-supported function. This is an internal error, please contact Software AG support. |
For specific return code values, refer to the individual service program descriptions below.
If an error occurs, either a Natural error message is issued or the session is terminated with a Natural IMS TM error message; see Natural under IMS TM Error Messages in the Natural Messages and Codes documentation.
The following service programs are described below:
NIIBRCST
|
NIICMD
|
NIIDEFT
|
NIIDEFTX
|
NIIDIRT
|
NIIDIRTX
|
NIIEMOD
|
NIIGCMD
|
NIIGMSG
|
NIIGSEG
|
NIIGSPA
|
NIIIMSIN
|
NIIISRTF
|
NIIISRTM
|
NIIPCBAD
|
NIIPCOM
|
NIIPMSG
|
NIIPSBAD
|
NIIPSPA
|
NIIPURG
|
NIIRETRM
|
NIISASD
|
NIIU3962
Sends the passed message to the specified terminal using the message
output descriptor specified in the MOD_name
parameter.
The following parameters are provided:
Parameter | Format/Length |
---|---|
Terminal_name |
(A8) |
Message |
(A1/1:V) |
Message_length |
(I4) |
MOD_name |
(A8) |
Return_code |
(I4) |
Specific Return Code Values: None.
Sample Program: NIPGMSG
Passes the IMS TM command specified to IMS TM. If there is a reply, it is moved into the reply area provided. If the reply does not fit into the reply area, it is truncated and the return code is set to 4.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Command |
(A1/1:V) | Input |
Command_length |
(I4) | Input |
Reply_area |
(A1/1:V) | Input/Output |
Reply_area_length |
(I4) | Input |
Reply_length |
(I4) | Output |
Status_code |
(A2) | Output |
Return_code |
(I4) | Output |
Specific Return Code Values: 4 (reply truncated)
Sample Program: NIPCMD
Prepares a deferred switch to the specified Natural transaction code.
With the next terminal I/O, the output is sent to the terminal and the next
input from this terminal is processed by the transaction code specified in the
parameter Transaction_code
.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Transaction_code |
(A8) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPDEFT
Prepares a deferred switch to a non-Natural transaction code. With the
next terminal I/O, the output is sent to the terminal using the given
MOD_name
and the next input from this terminal is
processed by the transaction code specified in the parameter
Transaction code
.
If the suspend flag is set to Y
, the Natural session will
be suspended and can be resumed later. If the Natural session is resumed, it
will first issue the last Natural screen.
If the suspend flag is set to Y
you may not switch from a
conversational Natural session to a non-conversational transaction code. If you
try to do so, a Natural error message is issued.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Transaction_code |
(A8) | Input |
Transaction_type |
(A4) | Input
Possible values:
|
Suspend_flag |
(A1) | Input
Possible values:
|
MOD_name |
(A8) | Input |
Message |
(A1/1:V) | Input |
Message_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPDEFTX
Prepares a direct switch to a specified Natural transaction code. On the
next terminal write, the CHNG
command to the
specified transaction code is issued and the Natural screen is inserted using
the alternate TP PCB.
If you switch from a conversational Natural session to a
non-conversational one, the conversation is terminated and a dummy message
using MOD_name
NIIMODNC
is inserted. This
message unprotects the screen temporarily, and is thus overwritten by the first
screen of the non-conversational Natural session.
Parameter | Format/Length | Type |
---|---|---|
Transaction_code |
(A8) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPDIRT
Prepares a direct switch to the specified transaction code. On the next
terminal write, the CHNG
call for the new transaction code is
issued and the message and or the SPA are inserted using the alternate TP PCB.
The transaction type defines the type of the new transaction code.
If you switch from a conversational transaction code to a
non-conversational one, the conversation is finished by issuing a dummy message
using MOD_name
NIIMODN
, which unprotects
the screen temporarily, thus it will be overwritten by the screen issued from
the non conversational transaction code.
If the suspend flag is set to Y
, the Natural session is
suspended and may be resumed at a later time. When the Natural session is
resumed, the last Natural screen is issued.
If the suspend flag is set to Y
you may not switch from a
conversational Natural to a non conversational transaction code. If you try to
do so, a Natural error message will be issued.
If message length is set to zero, no message at all is inserted. This however is only possible if you switch to a conversational transaction code.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Transaction_code |
(A8) | Input |
Transaction_type |
(A4) | Input
Possible values:
|
Suspend_flag |
(A1) | Input
Possible values:
|
Message |
(A1/1:V) | Input |
Message_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPDIRTX
Modifies the current setting of the module output descriptor to be used
in the insertion of the last message in a Natural session and sets it to the
value specified in the parameter MOD_name
.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
MOD_name |
(A8) | Input |
Return_code |
(I4) | Output |
Sample Program: NIPEMOD
Retrieves the next reply segment of a previously issued IMS TM command. The length of the reply is return in the parameter reply length. If the reply does not fit into the reply area, the reply is truncated and return code 4 is issued.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Reply_area |
(A1/1:V) | Input/Output |
Reply_area_length |
(I4) | Input |
Reply_length |
(I4) | Output |
Status_code |
(A2) | Output |
Return_code |
(I4) | Output |
Specific Return Code Values: 4 (reply truncated)
Sample Program: NIPCMD
Retrieves the first segment of the next message from the message queue
by issuing a GU. The message area will contain the retrieved message including
the leading LLZZ
bytes. If there are no messages in the message
queue, LLZZ
is set to zero.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Message_area |
(A1/1:V) | Output |
Message_area_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Programs: NIPGMSG
, NIPGSEG
Retrieves the next segment of the input message by issuing a GN call.
The message area will contain the retrieved message including the leading
LLZZ
bytes. If there are no more message segments in the current
message, LLZZ
is set to zero.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Message_area |
(A1/1:V) | Output |
Message_area_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPGSEG
Retrieves data from the SPA beginning at the specified offset in the specified length.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Offset |
(I4) | Input |
Length |
(I4) | Input |
Area |
(A1/1:V) | Input/Output |
Return_code |
(I4) | Output |
Specific Return Code Values: 4
The retrieved data resides entirely or partially within the part of the SPA reserved for Natural.
Sample Program: NIPGSPA
Retrieves the IMS TM environment information using the INQY
ENVIRON
call. If you specify a Reply_area_length
smaller than 102, the reply will be truncated and you will receive return code
X'0100'
with reason code X'000C'
.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Reply_area |
(A1/1:V) | Output |
Reply_area_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values:
nnxx
nn: The first two bytes contain the AIB
return code. xx: The second two bytes contain the
AIB reason code. AIB denotes "Application Interface Block" and is
used when calling IMS TM through the AIBTDLI
interface.
Sample Program: NIPIMSIN
Creates multi-segment messages. NIIISRTF
performs the
CHNG
call for the specified destination and inserts the first
message segment without performing a PURG
call. Further message
segments may be inserted using NIIISRTM
. The message has to be
terminated using NIIPURG
.
The LLZZ
bytes are created by the service module.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Destination |
(A8) | Input |
Message |
(A1/1:V) | Input |
Message_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPISRTM
Inserts the next message segment into the message queue without
performing a CHNG
or a PURG
call. The
LLZZ
bytes are created by the service module.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Message |
(A1/1:V) | Input |
Message_length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPISRTM
Returns the currently scheduled PSB name and the address of the PCB identified by the logical name. If the logical PCB name is not defined in the transaction code table, a Natural error message is issued.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
PSB_name |
(A8) | Output |
Logical_PCB_name |
(A8) | Input |
PCB_address |
(B4) | Output |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPPCBAD
Moves the data provided in the data area into the reply area specified
in the NIIBOOTS
call at the specified offset in the specified
length. NIIPCOM
may be called from the server environment
only.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Offset |
(I4) | Input |
Data_area |
(A1/1:V) | Input |
Length |
(I4) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: 4 (calling environment, not server environment)
Sample Program: NIPPCOM
Sends a message using a given MOD_name
to the
destination which is represented by the I/O PCB. The message is taken from the
message area in the specified message area length. The message area must not
contain the leading LLZZ
bytes. In this way you can send
MFS-formatted output messages back to the originator of the input message.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Message |
(A1/1:V) | Input |
Message_length |
(I4) | Input |
MOD_name |
(A8) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPPMSG
Returns the address of the PSB which is the address of the PCB address list.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
PSB_address |
(B4) | Output |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPBOOTS
Replaces the data located in the SPA at the specified offset in the given length by the data provided in the data area.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Offset |
(I4) | Input |
Length |
(I4) | Input |
Data_area |
(A1/1:V) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
An attempt to override the header of the SPA (first 14 bytes) and/or data residing in the Natural-reserved area is refused and a Natural error message is issued.
Sample Program: NIPPSPA
Issues a PURG
call.
The following parameter is provided:
Parameter | Format/Length | Type |
---|---|---|
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPISRTM
Moves data from the input message beginning at the specified offset in the specified length into the provided message area.
The offset is calculated from the LLZZ
bytes.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Offset |
(I4) | Input |
Length |
(I4) | Input |
Message_area |
(A1/1:V) | Input/Output |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPRETRM
Modifies the current setting of the Natural profile parameters
SENDER
and OUTDEST
.
The following parameters are provided:
Parameter | Format/Length | Type |
---|---|---|
Sender |
(A8) | Input |
Outdest |
(A8) | Input |
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPNTRD
Terminates the session with user abend code U3962 and produces a dump.
The following parameter is provided:
Parameter | Format/Length | Type |
---|---|---|
Return_code |
(I4) | Output |
Specific Return Code Values: None.
Sample Program: NIPU3962