Version 6.3.13 for Windows
 —  Natural Remote Procedure Call (RPC)  —

Starting a Natural RPC Server

This section describes how to start a Natural RPC server on the different platforms.

The following topics are covered:


Preliminaries before Starting a Natural RPC Server

Any kind of Natural session can be used as a Natural RPC server, but typically a Natural server is a Natural session which is started as an asynchronous task or as a background task.

On Mainframes:

For the purpose of starting a server, you have the following options:

On Windows, UNIX or OpenVMS:

For the purpose of starting a server, you have the following options:

How a Natural server is started depends on the environment and is described in the corresponding paragraphs below. For the sake of simplicity, only the mandatory RPC server-specific profile parameters are shown. The optional RPC server-specfic profile parameters may be specified analogously.

Top of page

Starting a Natural RPC Server in a Mainframe Online Environment (all TP Monitors)

Start of instruction setTo start a Natural server in a mainframe online environment

Where <natural> is the name with which you start your Natural (transaction code, transaction ID, environment-dependent nucleus name) and serverprofile is the name of the Natural profile.

Top of page

Starting a Natural RPC Server in a Mainframe Online Environment (CICS only)

In a CICS environment, you will typically start a Natural RPC server in asynchronous mode. In addition to the options described above for all TP monitors, you have the following options for this purpose:

When starting the asynchronous Natural RPC server, it is recommended to specify the Natural profile parameters TTYPE, INTENS, SENDER in addition, using the following settings:

TTYPE=ASYL,INTENS=1,SENDER=CSSL

This will cause each output to the primary output destination to be written in line mode rather than in 3270 mode. Instead of CSSL, you may specify any other CICS output destination.

Starting a Natural RPC Server in Asynchronous Mode with STARTSRV

STARTSRV is a sample front-end for RPCSSRV that starts the asynchronous Natural session.

By default, the asynchronous Natural is started with the same transaction ID in the same library as the current session.

If Natural Security Security (NSC) is used, the user ID of the current Natural session is propagated, too. You may adapt the input to your requirements.

Note that some Natural profile parameters are implicitly added by RPCSSRV. This applies especially to the keyword subparameter RPCSIZE of profile parameter RPC. RPCSIZE defaults to MAXBUFF+4, where MAXBUFF is the value entered in the map field Receiving buffer. You may overwrite the default value for RPCSIZE by entering RPC=(RPCSIZE=n) in the map field Session parameter.

If you want to execute a Natural program during startup of the Natural session, you may use the map field User Stack. The content of User Stack is put on the Natural STACK and executed before the Natural server is activated.

To show the Natural profile parameters involved, enter *SHOW* in the Transaction ID field. STARTSRV will show you all dynamic profile parameters that will be used by RPCSSRV to start the asynchronous Natural session.

Starting a Natural RPC Server Session in Asynchronous Mode during Startup of CICS

To start a Natural RPC server session in asynchronous mode during startup of CICS, proceed as follows:

Use the PLTPI to start a program that uses EXEC CICS START to start a Natural session with all required RPC specific Natural profile parameters. You may adapt the sample PLTPI program XNCIFRNP that is provided in the Natural CICS source library.

Please note that the Natural session is started under the CICS default user ID, which, by default, is CICSUSER. This user ID is assigned to the Natural system variables *INIT-USER and *USER. If your Natural session is running under Natural Security, you may therefore have to put a Natural LOGON command on the Natural STACK.

Top of page

Starting a Natural RPC Server in a Mainframe Online Environment (Com-plete only)

In a Com-plete environment, you will typically start a Natural RPC server in asynchronous mode. In addition to the options described above for all TP monitors, you have the following options for this purpose:

Starting a Natural RPC Server in Asynchronous Mode with STARTSRV

STARTSRV is a sample front-end for RPCSSRV that starts the asynchronous Natural session.

By default, the asynchronous Natural is started with the same Natural name in the same library as the current session.

If Natural Security Security (NSC) is used, the user ID of the current Natural session is propagated, too. You may adapt the input to your requirements.

Note that some Natural profile parameters are implicitly added by RPCSSRV. This applies especially to the keyword subparameter RPCSIZE of profile parameter RPC. RPCSIZE defaults to MAXBUFF+4, where MAXBUFF is the value entered in the map field Receiving buffer. You may overwrite the default value for RPCSIZE by entering RPC=(RPCSIZE=n) in the map field Session parameter.

If you want to execute a Natural program during startup of the Natural session, you may use the map field User Stack. The content of User Stack is put on the Natural STACK and executed before the Natural server is activated.

To show the Natural profile parameters involved, enter *SHOW* in the Transaction ID field. STARTSRV will show you all dynamic profile parameters that will be used by RPCSSRV to start the asynchronous Natural session.

Starting a Natural RPC Server Session in Asynchronous Mode during Start-up of Com-plete

To start a Natural RPC server session in asynchronous mode during startup of Com-plete, proceed as follows:

Use the startup option (sysparms) STARTUPPGM to start a Natural session with all required RPC-specific Natural profile parameters. You may either specify the required RPC-specific parameters individually or use a Natural profile to specify them as follows:

STARTUPPGM='<natural> PROFILE=<serverprofile>'

Please note that the Natural session is started under the user ID under which Com-plete is started. This user ID is assigned to the Natural system variables *INIT-USER and *USER. If your Natural session is running under Natural Security, you may therefore have to put a Natural LOGON command on the Natural STACK.

Top of page

Starting a Batch Server in a Mainframe Environment

A batch server is a standard Natural batch session that is started with the RPC parameters described in the section Setting Up a Natural RPC Environment, Set the RPC Server-Specific Natural Parameters.

The following topics are covered below:

Note:
For a sample JCL using the trace facility, refer to Operating a Natural RPC Environment, Using the Server Trace Facility.

Starting a Batch Server under z/OS

Sample JCL for z/OS

//NATRPC   JOB  CLASS=K,MSGCLASS=X
//         EXEC PGM=NATOS,REGION=8M
//STEPLIB  DD   DISP=SHR,DSN=SAG.NAT.LOAD
//         DD   DISP=SHR,DSN=SAG.EXX.LOAD
//         DD   DISP=SHR,DSN=SAG.ADA.LOAD         <== Note 1
//         DD   DISP=SHR,DSN=DB2_load_library     <== Note 2
//         DD   DISP=SHR,DSN=SAG.SSX.LOAD         <== Note 3
//CMPRMIN  DD   *
IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
RPC=(SERVER=ON,SRVNAME=servername,SRVNODE=nodename)
RPC=(RPCSIZE=m,MAXBUFF=n),
STACK=(LOGON serverlibrary,userID,password)
/*
//CEEOPTS  DD *                                   <== Note 4
POSIX(ON)
/*
//SYSUDUMP DD SYSOUT=X
//CMPRINT  DD SYSOUT=X
/*

Notes:

  1. Applies only if the Adabas link routine ADAUSER or the Natural profile parameter ADANAME is used.
  2. Applies to DB2 users only.
  3. Applies only if the Integrated Authentication Framework (IAF) is used.
  4. Applies only if SSL is used.

Sample JCL for a Started Task

A sample JCL for a started task is provided in the Natural for mainframes installation documentation; see Installing Natural on z/OS.

Running a Batch Server with Replicas

You can also run a batch server with replicas by setting the keyword subparameter NTASKS of profile parameter RPC or parameter macro NTRPC to a value greater than 1.

Replicas are attached to a Natural main task as additional server tasks. They enable you to start several identical servers in the same region.

Starting a Batch Server under z/VSE

Sample JCL for z/VSE

// LIBDEF PHASE,SEARCH=(SAGLIB.NATvrs,SAGLIB.EXXvrs,SAGLIB.ADAvrs),TEMP
// ASSGN SYS000,READER
// ASSGN SYSLST,FEE
// EXEC NATVSE,SIZE=AUTO,PARM='SYSRDR'
IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
RPC=(SERVER=ON,SRVNAME=servername,SRVNODE=nodename)
RPC=(RPCSIZE=m,MAXBUFF=n),
STACK=(LOGON serverlibrary,userID,password)
/*

where vrs represents the relevant product version.

Running a Batch Server with Replicas

You can also run a batch server with replicas by setting the keyword subparameter NTASKS of profile parameter RPC or parameter macro NTRPC to a value greater than 1.

Replicas are attached to a Natural main task as additional server tasks. They enable you to start several identical servers in the same region.

Starting a Batch Server under BS2000/OSD

Sample JCL for BS2000/OSD

/.NATRPC      LOGON
/             SYSFILE   SYSOUT=output-file
/             SYSFILE   SYSDTA=(SYSCMD)
/             SYSFILE   SYSIPT=(SYSCMD)
/             STEP
/             SETSW      ON=2
/             EXEC NATBS2
IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
RPC=(SERVER=ON,SRVNAME=servername,SRVNODE=nodename)
RPC=(RPCSIZE=m,MAXBUFF=n),
STACK=(LOGON serverlibrary,userID,password)
/             EOF

Top of page

Starting a Natural RPC Server in a Windows Environment

Start of instruction setTo start a Natural RPC server under Windows

  1. Create a shortcut for Natural.

  2. Enter the shortcut properties.

  3. In the Target text box, edit the Natural path and append:

    "<Path>\natural.exe" batchmode parm=serverparm

    where serverparm is the name of the parameter file,

    Or:

    "<Path>\natural.exe" batchmode
    server=on srvname=servername srvnode=nodename maxbuff=n cmsynin=cmsynin cmobjin=cmobjin cmprint=cmprint
    

Top of page

Starting a Natural RPC Server in a UNIX Environment

Start of instruction setTo start a Natural RPC server under UNIX

Top of page

Starting a Natural RPC Server in an OpenVMS Environment

Start of instruction setTo start a Natural RPC server under OpenVMS

  1. In the DCL command procedure myserver.com, enter the following commands:

    $ DEFINE NATOUTPUT NLA0:
    $ NAT batchmode parm=serverparm
  2. Then submit myserver.com to a batch queue:

    $ SUBMIT myserver.com

Top of page

Considerations for Mainframe Natural RPC Servers with Replicas

This section applies to mainframe Natural servers under z/OS and z/VSE.

Natural RPC Batch Server with NTASKS >1

The main task and all replicas run in the same z/OS region or z/VSE partition.

  1. Use the reentrant batch link routine ADALNKR instead of ADALNK.

    If you want to use ADAUSER, you must not link ADAUSER with your front-end, because ADAUSER is non-reentrant (see Item 5). Instead, use the Natural profile parameter ADANAME and set ADANAME=ADAUSER. This will cause Natural to load ADAUSER dynamically at runtime.

    Note for z/VSE: If you use ADAUSER, you must rename ADALNKR to ADALNK.

  2. In the NATPARM module:

  3. When using dynamic Natural profile parameters:

    Use the dynamic parameter dataset CMPRMIN to pass the dynamic Natural profile parameters to Natural. Do not use the PARM card or the primary command input dataset CMSYNIN.

  4. When using a local buffer pool (z/OS only):

    Each subtask allocates its own local buffer pool unless you specify a shared local buffer pool. See subparameter LBPNAME of profile parameter OSP or parameter macro NTOSP (in the Parameter Reference documentation).

  5. In the Natural front-end link job (z/OS only):

    Link the front-end reentrant by using the RENT option of the linkage editor.

    If the front-end were not linked with the RENT option, only the main task would start the communication with the EntireX Broker. All subtasks would be set to a WAIT status by z/OS, until the main task would have been terminated. If you would terminate the RPC server lateron, the address space would hang and would have to be cancelled.

  6. Make sure that any other modules that are additionally linked to the Natural nucleus are reentrant. Any dynamically loaded programs must also be reentrant.

    Note for z/OS: If you cannot make a module reentrant, link the module as non-reusable; this means, you should not specify the link option RENT or REUS. This is to ensure that each subtask will get its own copy.

Running a Batch Server with Replicas

For a sample JCL, see Using the Server Trace Facility.

Top of page

Starting a Natural RPC Server Using the RPC Server Front-End (z/OS Batch Mode only)

In z/OS batch mode, a Natural RPC server may alternatively be started using the RPC server front-end. This approach is required with impersonation and is optional in other cases.

If you use the RPC server front-end without impersonation, you are recommended to set the keyword subparameter NTASKS of profile parameter RPC or parameter macro NTRPC to a value greater than 1. Otherwise, there will be no benefit. The Considerations for Mainframe Natural RPC Servers with Replicas apply also when you are using the RPC server front-end.

The RPC server front-end uses the Natural Server functionality; see Natural as a Server under z/OS (in the Natural Operations documentation). It is characterized by the following features:

Startup Parameters:

The required startup parameters are passed in the PARM= parameter of the EXEC statement in the JCL. These parameters are:

These parameters must be separated by commas and must be entered without leading or trailing blanks:

PARM='Natural-z/OS-batch-nucleus,size-of-thread,number-of-threads[,UCTRAN]'

See also the Sample JCL below.

Execution Notes:

With impersonation only:
When the impersonation feature is used, the RPC server front end must be executed from an Authorized Program Facility (APF) library. You are recommended to execute the RPC server front-end from an APF-authorized LINKLIST library. This eliminates the need of providing the whole steplib concatenation APF authorized.

With Natural Security only:
If the Natural RPC server front-end is started with profile parameter AUTO=OFF, you must provide a Natural LOGON command with library ID, user ID and password on the Natural stack: STACK=(LOGON library-id;user-id;password).

Sample JCL:

//NATRPC   JOB  CLASS=K,MSGCLASS=X
//         EXEC PGM=RPC-FRONT,REGION=8M
//         PARM='Natural-z/OS-interface-module,1000,5'
//STEPLIB  DD   DISP=SHR,DSN=SAG.NAT.LOAD
//         DD   DISP=SHR,DSN=SAG.EXX.LOAD
//         DD   DISP=SHR,DSN=SAG.ADA.LOAD         <== Note 1
//         DD   DISP=SHR,DSN=DB2_load_library     <== Note 2
//         DD   DISP=SHR,DSN=SAG.SSX.LOAD         <== Note 3
//CMPRMIN  DD   *
IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
PRINT=((10),AM=STD)
RPC=(SERVER=ON,SRVNAME=servername,SRVNODE=nodename,NTASKS=3)
RPC=(RPCSIZE=m,MAXBUFF=n,TRACE=2),
RCA=BROKER,RCALIAS=(BROKER,BKIMBTSO)
STACK=(LOGON serverlibrary,userID,password)
/*
//CEEOPTS  DD *                                   <== Note 4
POSIX(ON)
*
//SYSUDUMP DD SYSOUT=X
//CMPRT10  DD SYSOUT=X
//CMPRT101 DD SYSOUT=X
//CMPRT102 DD SYSOUT=X
//CMPRT199 DD SYSOUT=X
//CMPRINT  DD SYSOUT=X
//CMPRINT1 DD SYSOUT=X
//CMPRINT2 DD SYSOUT=X
//CMPRIN99 DD SYSOUT=X
/*

Notes:

  1. Applies only if the Adabas link routine ADAUSER or the Natural profile parameter ADANAME is used.

  2. Applies to DB2 users only.

  3. Applies only if the Integrated Authentication Framework (IAF) is used.

  4. Applies only if SSL is used.

Top of page

Starting a Natural RPC Server Using the RPC Server Front-End (CICS only)

In CICS, a Natural RPC server may alternatively be started using the RPC server front-end. This approach is required when impersonation is used and is optional in other cases.

If you use the RPC server front-end without impersonation, you are recommended to set the keyword subparameter NTASKS of profile parameter RPC or parameter macro NTRPC to a value greater than 1. Otherwise, there will be no benefit.

The RPC server front-end uses the Natural Server functionality. It is characterized by the following features:

Startup Parameters:

The required startup parameters are passed with the transaction ID. These parameters are:

Sample Start at a Terminal:

<natural> <ncistart>[,UCTRAN]
RPC=(SERVER=ON,SRVNAME=servername,SRVNODE=nodename,RPCSIZE=n, MAXBUFF=n)
RCA=BROKER,RCALIAS=(BROKER,CICSETB)

Where <natural> is the transaction ID with which you start your Natural RPC server front-end and <ncistart> is the name of your Natural CICS interface nucleus.

Execution Notes:

With impersonation only:
When the impersonation feature is used, the RPC server front-end starts worker tasks. Ensure that the setting of the CICS system initialization parameter MXT of your CICS installation is high enough.

With Natural Security only:
If the Natural RPC server front-end is started with profile parameter AUTO=OFF, you must provide a Natural LOGON command with library ID, user ID and password on the Natural stack: STACK=(LOGON library-id;user-id;password).

Top of page