This document describes how to configure the CICS connection for a Natural Development Server (product code NDV) running on z/OS or under SMARTS on z/VSE.
The following topics are covered:
After the installation of the NDV CICS Adapter is complete, the configuration of the NDV CICS Adapter has to be done in the Natural Development Server configuration file of the corresponding Natural Development Server.
To enable the CICS Adapter, specify the remote front-end module in the
NDV configuration parameter FRONTEND_NAME
(FRONTEND_NAME=NATCSRFE).
The following CICS-relevant configuration parameters exist:
This configuration parameter specifies the CICS transaction to be used
for starting the remote front-end in CICS. This transaction must be defined in
CICS and must refer to the program NATCNRFE. See also
Installing the NDV CICS
Adapter under SMARTS on z/VSE.
Note:
At logon, this transaction name can be overridden by the user in
order to switch to a different CICS transaction on a mainframe. See the section
Dynamically Changing the CICS Transaction Name when Starting a
Session in the NDV client documentation.
| Default Value | none |
|---|---|
| Example | RFE_CICS_TA_NAME=NRFE |
This configuration parameter specifies the Natural CICS nucleus you have installed with the applicable Natural for Mainframes installation under CICS. This program must be defined in CICS. For further information, see Empower at https://empower.softwareag.com/.
| Default Value | none |
|---|---|
| Example | RFE_CICS_FE_NAME=NCIvrNUC |
See also the Natural Installation for Mainframes documentation, Installing the Natural CICS Interface, Customize CICS.
This configuration parameter specifies the TCP/IP address of the host the desired CICS is running. This parameter can be omitted if the development server and CICS are running on the same TCP/IP node.
| Default Value | The host address of the development server. |
|---|---|
| Example | RFE_CICS_TA_HOST=node1
or
|
This configuration parameter specifies the TCP/IP port of the CICS supplied listener.
You can acquire this port number using the CICS supplied transaction
EZAC. The CICS command EZAC DISPLAY
LISTENER shows the definitions of the CICS standard listener.
Note:
This port number is not used in Natural Studio to map to a remote
development server. This port number (and the
RFE_CICS_TA_HOST definition) is used internally by the
development server to communicate with the CICS region.
| Possible Values | 1 - 65535 |
|---|---|
| Default Value | none |
| Example | RFE_CICS_TA_PORT=3010 |
If Natural Studio sends a request to a Natural Development Server that
is configured to use the CICS remote front-end, the remote front-end launches a
CICS transaction (NRFE) for processing the request. The CICS
transaction in turn listens to the TCP/IP to receive the data from the
development server required for processing the request.
This configuration parameter specifies the timeout value (in seconds) a launched transaction waits until the expected request data arrive from the development server. If this timeout expires, the request aborts with a NAT9940 error.
| Default Value | 5 |
|---|---|
| Example | RFE_CICS_TA_INIT_TOUT=20 |
Note:
Do not define a value below 5.
For each request sent by Natural Studio, the Natural Development Server
opens a TCP/IP connection to the CICS region and launches a CICS transaction
(NRFE) for processing the request. With
RFE_CICS_KEEP_TA=YES, the CICS transaction remains active for
processing further requests of the same client. This saves the overhead for
creating the TCP/IP connection and transaction initialization for successive
requests, but consumes more resources within the CICS region due to waiting
transactions.
The transaction wait time (for successive requests) is limited by
RFE_CICS_TA_INIT_TOUT.
That is, if the time slice between two successive requests exceeds the time
specified by RFE_CICS_TA_INIT_TOUT, the CICS transaction
and the TCP/IP connection is terminated independent of the
RFE_CICS_KEEP_TA definition.
RFE_CICS_TA_INIT_TOUT=5 is a reasonable value to reuse
transactions for multiple requests initiated by a single action in Natural
Studio and to save CICS resources if Natural Studio waits for the next action
of the user.
| Default Value | None |
|---|---|
| Example | RFE_CICS_KEEP_TA=YES |
This configuration parameter specifies the trace level for the remote front-end.
The trace level is similar to the trace implemented for the development server. It is a bit string where each bit is responsible for a certain trace information:
| Bit 31 | Trace main events (transaction initialization/termination, request processing). |
| Bit 30 | Detailed functions. |
| Bit 29 | Dump internal storage areas. |
| Bit 27 | Dump buffer header exchanged between development server and CICS. |
| Bit 26 | Dump entire buffer exchanged between development server and CICS. |
| Bit 25 | Dump the Natural Development Server relevant buffer only (remote gateway buffer). |
| Bit 23 | Trace error situations only. |
| Bit 07 | Activate trace in the development server region. |
| Bit 06 | Activate trace in the CICS region. |
| Bit 00 | Reserved for trace-level extension. |
The trace destination is the data set defined for
STDOUT.
| Default Value | 0 |
|---|---|
| Example | RFE_CICS_TRACE=31+27+7
Dump main events and buffer header in the CICS region (Bits 31 + 27 + 7). |
The following is a sample development server configuration file using the Natural Development Server CICS Adapter:
# the development server parameter
SESSION_PARAMETER=PROFILE=(NDV,10,930)
FRONTEND_NAME=NATCSRFE # use the CICS Adapter front-end
PORT_NUMBER=4711 # the port number used by Natural Studio
# the CICS Adapter parameter
RFE_CICS_TA_NAME=NRFE # the CICS transaction for remote front-end
RFE_CICS_TA_PORT=3010 # the port of the CICS listener
# no RFE_CICS_TA_HOST is defined. This requires
# that CICS runs on the same node as the
# development server.
RFE_CICS_FE_NAME=NCI41NUC # the name of the installed Natural CICS nucleus
RFE_CICS_TA_INIT_TOUT=20 # transaction timeout is 20 seconds
Many customer environments have 3-GL front-ends in their Natural for CICS installation which get control before Natural for CICS gets active in order to prepare the CICS environment for Natural for CICS.
With the NDV CICS Adapter, such a 3-GL front-end is not called.
A user-exit NRFEUX01 is called by the NDV CICS Adapter
before Natural for CICS is invoked. Any functionality necessary to prepare the
CICS environment for Natural for CICS can be implemented in that exit.
The exit is called before session initialization, before roll-in, after roll-out and after session termination. Special attention must be payed if the exit maintains any resources related to the task number. Under the Natural Development Server, the CICS task number can change during the lifetime of a Natural session. These resources must be saved at roll-out indexed by the session ID. At roll-in these resources must be obtained using the session ID and reallocated under the current task number. The session ID is a unique identifier of a Natural session. This identifier is passed to the exit.
The user exit NRFEUX01 is called by NATCNRFE
with EXEC CICS LINK. The exit must return with EXEC CICS
RETURN. This exit has the following COMAREA layout:
| Name | Format | In/Out | Description |
|---|---|---|---|
Eye |
CL8 | I |
Eyecatcher The exit should abort if the first six bytes of the eyecatcher do
not match. The |
SID
|
XL8 | I |
Unique session identifier. A Natural session under Natural Development Server does not necessarily run under one task. The task number may change at each roll-out/roll-in sequence. The only unique identifier of a session is the SID. |
EVNT
|
XL1 | I |
Current event. Session start ( |
| XL3 | Unused. | ||
RC
|
F | O |
The return code of the exit (not equal to 0 means session abort). |
ETXTL
|
F | O |
Length of the following error text. A maximum of 80 characters is transmitted to the client. Any longer text is truncated. |
ETXT
|
A | O |
Error text to be returned to the client. This area is allocated by the exit and released by
|
SPRML
|
F | I/O |
Length of following session parameter. |
SPRM
|
A | I/O |
Session parameter can be modified by the exit. If the length is not appropriate, the exit can release the memory
space pointed by |
UID
|
CL8 | I | The user ID of the NDV client. |
To install the user exit, implement the program NRFEUX01
and define it to CICS.
Sample User Exit:
* ====================================================================
* NDV CICS Adapter sample user exit NRFEUX01
* At each invocation this sample writes a line to the CICS log.
* If the user-ID is KSP1, it appends the session parameter with the
* string SPRMFORKSP1.
* If the user-ID is KSP2, it aborts the session with an error message.
* ====================================================================
NRFEUX01 DFHEIENT CODEREG=(11),DATAREG=(13),EIBREG=(12)
NRFEUX01 AMODE 31
NRFEUX01 RMODE ANY
EXEC CICS GETMAIN SET(10) FLENGTH(WK#L)
CLC EIBRESP,DFHRESP(NORMAL)
BNE RFEM0101 bif error, issue message
USING WORK,RA
EXEC CICS ADDRESS COMMAREA(9)
C R9,=XL4'FF000000'
BE RFEM0102 bif no commarea, issue message
* -------------------------------------------------------------
* Validate input parameter
* -------------------------------------------------------------
USING COMA,R9
CLC CA#EYE,=C'NATRFE'
BNE RFEM0103 bif unknown area, issue message
CLI CA#EYEV,C'0'
BL RFEM0103 bif unknown area, issue message
CLI CA#EYEV,C'9'
BH RFEM0103 bif unknown area, issue message
CLI CA#EYEV+1,C'0'
BL RFEM0103 bif unknown area, issue message
CLI CA#EYEV+1,C'9'
BH RFEM0103 bif unknown area, issue message
SLR RF,RF
ST RF,CA#RC set good return code
* -------------------------------------------------------------
* Perform action depending the given event
* -------------------------------------------------------------
SLR R1,R1
ICM R1,B'0001',CA#EVENT
SLL R1,2 *4
C R1,MAXEVENT
BH RFEM0104 unknown event, issue message
B RFEX0020(R1)
RFEX0020 DS 0H
B RFEX0100 Session start
B RFEX0200 Session end
B RFEX0300 Session rollin
B RFEX0400 Session rollout
MAXEVENT DC A(*-4-RFEX0020)
RFEX0100 DS 0H
* -------------------------------------------------------------
* Session start. Allocate resources for that user/SID
* -------------------------------------------------------------
CLC CA#USID,=CL8'KSP1'
BNE RFEX0150
* -------------------------------------------------------------
* Append given session parameter with TSTPRMS
* -------------------------------------------------------------
LA R1,L'TSTPRMS my param len
A R1,CA#PARML + existing param len
LA R1,1(,R1) + one delimiter blank
ST R1,WK#PARML
EXEC CICS GETMAIN SET(4) FLENGTH(WK#PARML)
ST R4,WK#PARM
ICM R1,B'1111',CA#PARML
BZ RFEX0105 bif no existing parms
L R0,WK#PARM
L R2,CA#PARM
LR R3,R1
MVCL R0,R2 move existing params
LR R4,R0
MVI 0(R4),C' ' delimit with one blank
LA R4,1(,R4)
RFEX0105 DS 0H
MVC 0(L'TSTPRMS,R4),TSTPRMS append with TSTPRMS
ICM R2,B'1111',CA#PARM
BZ RFEX0110 bif no memory allocated
EXEC CICS FREEMAIN DATAPOINTER(2)
RFEX0110 DS 0H
MVC CA#PARM,WK#PARM return new memory
MVC CA#PARML,WK#PARML return new length
RFEX0150 DS 0H
CLC CA#USID,=CL8'KSP2'
BNE RFEX0180
* -------------------------------------------------------------
* Abort this session
* -------------------------------------------------------------
LA R1,L'ATXT
ST R1,WK#PARML
EXEC CICS GETMAIN SET(1) FLENGTH(WK#PARML)
ST R1,WK#PARM
MVC 0(L'ATXT,R1),ATXT
LA R1,4
ST R1,CA#RC
RFEX0180 DS 0H
B RFEX1000
RFEX0200 DS 0H
* -------------------------------------------------------------
* Session end. Deallocate resources for that user/SID
* -------------------------------------------------------------
B RFEX1000
RFEX0300 DS 0H
* -------------------------------------------------------------
* Session rollin. Obtain resources by SID and index by task,
* Task has possibly changed.
* -------------------------------------------------------------
B RFEX1000
RFEX0400 DS 0H
* -------------------------------------------------------------
* Session rollout. Index resources by SID, task may change.
* -------------------------------------------------------------
B RFEX1000
RFEX1000 DS 0H
MVI WK#TEXT1,C' '
MVC WK#TEXT1+1(L'WK#TEXT1-1),WK#TEXT1
LA R1,WK#TEXT1
MVC 0(8,R1),=C'RFEUX01 '
LA R1,8(,R1)
MVC 0(L'CA#SID,R1),CA#SID
LA R1,L'CA#SID(,R1)
MVI 0(R1),C' '
LA R1,1(,R1)
MVC 0(L'CA#USID,R1),CA#USID
LA R1,L'CA#USID(,R1)
MVI 0(R1),C' '
LA R1,1(,R1)
SLR R2,R2
ICM R2,B'0001',CA#EVENT
SLL R2,3 *8
LA R2,EVNT(R2)
MVC 0(L'EVNT,R1),0(R2)
EXEC CICS WRITEQ TD QUEUE(=C'CSSL') FROM(WK#TEXT1), +
LENGTH(L'WK#TEXT1)
B RFEX9000
TST DC C'NREFUX01 Was active'
* -------------------------------------------------------------
* Home section
* -------------------------------------------------------------
RFEX9000 DS 0H
LTR RA,RA
BZ RFEX9010 bif no work area aquired
EXEC CICS FREEMAIN DATAPOINTER(10)
RFEX9010 DS 0H
EXEC CICS RETURN
RFEM0101 DS 0H
EXEC CICS WRITEQ TD QUEUE(=C'CSSL') FROM(MSG1) LENGTH(L'MSG1)
B RFEM9000
RFEM0102 DS 0H
EXEC CICS WRITEQ TD QUEUE(=C'CSSL') FROM(MSG2) LENGTH(L'MSG2)
B RFEM9000
RFEM0103 DS 0H
EXEC CICS WRITEQ TD QUEUE(=C'CSSL') FROM(MSG3) LENGTH(L'MSG3)
B RFEM9000
RFEM0104 DS 0H
EXEC CICS WRITEQ TD QUEUE(=C'CSSL') FROM(MSG4) LENGTH(L'MSG4)
B RFEM9000
RFEM9000 DS 0H
B RFEX9000
* ====================================================================
* Constants
* ====================================================================
MSG1 DC C'RFEUX01 Getmain failed'
MSG2 DC C'RFEUX01 Cannot address commarea'
MSG3 DC C'RFEUX01 COMMAREA layout not supported'
MSG4 DC C'RFEUX01 COMMAREA event not supported'
EVNT DS 0CL8
DC CL8'START'
DC CL8'FIN'
DC CL8'ROLLIN'
DC CL8'ROLLOUT'
TSTPRMS DC C'SPRMFORKSP1'
ATXT DC C'KSP2 aborted by my exit'
LTORG
* ====================================================================
* DSECTs
* ====================================================================
COMA DSECT
CA#EYE DS CL6 'NATRFE'
CA#EYEV DS CL2 > x'F0F1'
CA#SID DS CL8 the unique session identifier
CA#EVENT DS XL1 the session event
EV_START EQU 0 Session start
EV_END EQU 1 Session end
EV_ROLIN EQU 2 Session rollin
EV_ROLOU EQU 3 Session rollout
DS XL3
CA#RC DS F Exit return code
CA#ETXTL DS F Error text len
CA#ETXT DS A Error text
CA#PARML DS F Profile parameter len
CA#PARM DS A Profile Parameter
CA#USID DS CL8 The Natural user ID
WORK DSECT
WK#TEXT1 DS CL80
WK#PARM DS F
WK#PARML DS F
WK#L EQU *-WORK
*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
RA EQU 10
RB EQU 11
RC EQU 12
RD EQU 13
RE EQU 14
RF EQU 15
END