Configuring the Natural Development Server CICS Adapter

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:

Configuration File

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).

Configuration Parameters

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 z/OS.

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


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

Default Value none

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




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.

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

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


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
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

The development server parameters THREAD_NUMBER and THREAD_SIZE are obsolete when the NDV CICS Adapter is used.

NDV CICS Adapter User Exits

User Exit NRFEUX01

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 NATRFE01.

The exit should abort if the first six bytes of the eyecatcher do not match. The 01 suffix may increase if the area is expanded at the end. So the exit should accept any number between 01 and 99.


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.


Current event.

Session start (x'00'), end (x'01'), roll-in (x'02'), roll-out (x'03').

  XL3   Unused.

The return code of the exit (not equal to 0 means session abort).


Length of the following error text.

A maximum of 80 characters is transmitted to the client. Any longer text is truncated.


Error text to be returned to the client.

This area is allocated by the exit and released by NATCNRFE.


Length of following session parameter.


Session parameter can be modified by the exit.

If the length is not appropriate, the exit can release the memory space pointed by SPRM and allocate a larger space.

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),           +
         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                                                         
         B     RFEM9000                                                   
RFEM0102 DS    0H                                                         
         B     RFEM9000                                                   
RFEM0103 DS    0H                                                         
         B     RFEM9000                                                   
RFEM0104 DS    0H                                                         
         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'                             
* ====================================================================
* 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