This document provides an overview of the general prerequisites and a short description of the facilities that are available in Natural for implementing a Natural RPC (Remote Procedure Call) environment.
The following topics are covered:
If the RPC environment is to be implemented on different platforms, the corresponding current versions of Natural for Mainframes, Windows, UNIX or OpenVMS will be required. In addition, the following required or optional products, subproducts and facilities are available for use in a Natural RPC environment:
|EntireX Communicator (EntireX Broker)||The EntireX Broker of the Software AG product EntireX Communicator usually establishes the middleware layer between the Natural client and a Natural server. It uses the ACI protocol and comprises the appropriate client/server stubs.|
|Entire Net-Work||This Software AG product is required if the transport method used by EntireX Broker is Entire Net-work. This is the preferred transport method.|
|TCP/IP||Required if the transport method used by EntireX Broker
See also Using TCP/IP as a Transport Method in Setting Up a Natural RPC Environment.
|EntireX Developer's Kit||Included in the EntireX Communicator product, this kit is required for non-Natural programming language support.|
|Directory Services||A remote directory server (RDS) enables you to define directory definitions in one place so that its services can be used by all clients in an RPC environment.|
This Software AG add-on product is required on the server side to protect Natural RPC servers and services when security is active on the client and vice versa.
|International Components for Unicode for Software AG (ICU)||Optional.
This Software AG add-on product is required on the server side if the Natural RPC server is protected by Natural Security and the RPC clients have to provide user ID and password to access services.
Natural RPC fully supports EntireX RPC for 3GL. EntireX RPC is included in the EntireX Communicator product.
Natural RPC fully supports EntireX Security on the client and on the server side. EntireX Security is included in the EntireX Broker product.
For the supported Software AG product versions, refer to Software AG Product Versions Supported by Natural in the current Natural Release Notes for Mainframes.
For information on other products that may be involved in a Natural RPC-based environment, see the corresponding product documentation.
The following Natural statements are used in the creation of a Natural RPC environment:
In the section Restrictions and Limitations, the paragraphs Natural Statement Reactions and Notes on Natural Statements on the Server provide information on what you should know about any deviating behavior of these statements when they are used in a Natural RPC environment.
The following Natural utilities are used in the creation and maintenance of a Natural RPC environment:
This utility is used to maintain remote procedure call environments.
This utility is used to locate and test Natural Application
Programming Interfaces (APIs, see below) contained in the current system
On mainframes, this utility is used for creating and maintaining a set of Natural profile parameters that is stored under a profile name.
Under Windows, UNIX and OpenVMS, this utility is used to modify global and local configuration files and to create or modify parameter files.
The purpose of Natural Application Programming Interfaces (API) is to retrieve or modify information or use services that are not accessible by Natural statements.
The following Application Programming Interfaces available in the
SYSEXT are intended for being used with the
||Set user ID, password and ticket criteria for Natural
See Using Security.
||Specify a default server address that is to be used each time a remote program cannot be addressed via the service directory.|
||Support the commit for a
||Set the required SSL parameter string if the Secure Socket Layer (SSL) for the TCP/IP communication to the EntireX Broker is used.|
Has to be called in case of non-Natural Security clients for specifying logon data which are then passed to the server.
||Specify a password which is used for the
||Ping or terminate an RPC server from within your application.|
||Change the Natural Security password on the RPC server via a Natural RPC service request.|
||Terminate an EntireX Broker Service from within your application.|
||On the client side, specify an alternate name of a library to which the server will logon.|
||Set or get parameters for EntireX in a Natural RPC client or server environment.|
||On the client side, retrieve the runtime settings of a server.|
||On the client side, set the user ID and ETID for Natural RPC servers which were configured with Impersonation = A (automatic logon).|
||Set or get the reliable state for the reliable Natural RPC.|
||Commit or rollback reliable RPC message(s). This API is required if the reliable RPC state has been set to "client commit"|
||Retrieve the status of all reliable RPC messages of the user who is currently logged on to the EntireX Broker.|
||An enhanced version of API
||Trigger termination of current RPC server.|
Note that the RPC-specific APIs accept all values also in mixed
mode. An uppercase translation will take place only if the example program
USRnnnnP (source object) is used to
invoke the corresponding subprogram
USRnnnnN. Exception: All
USRnnnnP programs that deal with
passwords provide an option to enter the passwords in mixed case mode.
For an explanation of the Natural object types that are typically
provided for each API, see the Natural utility
This section describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the Natural programming language. Please note also the remarks and hints on the IDL data types valid for all language bindings found in the Software AG IDL File (in the EntireX documentation).
In the table below, the following metasymbols and informal terms are used for the IDL.
The metasymbols [ and ] surround optional lexical entities.
The informal term number (or in some cases number.number) is a sequence of numeric characters, for example 123.
|Software AG IDL||Description||Natural Data Format||Note|
|AV||Alphanumeric variable length||A DYNAMIC|
|AVnumber||Alphanumeric variable length with maximum length||A DYNAMIC|
|BV||Binary variable length||B DYNAMIC|
|BVnumber||Binary variable length with maximum length||B DYNAMIC|
|F4||Floating point (small)||F4||2|
|F8||Floating point (large)||F8||2|
|KV||Kanji variable length||A DYNAMIC||1|
|KVnumber||Kanji variable length with maximum length||A DYNAMIC||1|
|NUnumber[.number]||Unpacked decimal unsigned||Nnumber[.number]|
|PUnumber[.number]||Packed decimal unsigned||Pnumber[.number]|
|UV||Unicode variable length||U DYNAMIC|
|UVnumber||Unicode variable length with maximum length||U DYNAMIC|
See also the hints and restrictions on the Software AG IDL Data Types (in the EntireX documentation) valid for all language bindings.
Data type K is an RPC-specific data format that is not part of the Natural language.
When floating-point data types are used, errors due to rounding can occur, so that the values of senders and receivers might differ slightly. This is especially true if client and server use different representations for floating point data (IEEE, HFP).
Count of days AD (anno domini, after the birth of Christ). The valid range is from 1.1.0001 up to 28.11.2737. Mapping of the number to the date in the complete range from 1.1.0001 on, follows the Julian and Gregorian calendar, taking into consideration the following rules:
Years that are evenly divisible by 4 are leap years.
Years that are evenly divisible by 100 are not leap years unless rule 3, below, is true.
Years that are evenly divisible by 400 are leap years.
Before the year 1582 AD, rule 1 from the Julian calendar is used. After the year 1582 AD, rules 1, 2 and 3 of the Gregorian calendar are used.
See the following table for the relation of the packed number to a real date:
|Date / Range of Dates||Value / Range of Values|
|1.1.0000||0 (special value - no date)|
|undefined dates||1 - 364 (do not use)|
|1.1.1970||719527 (start of C-time functions)|
|28.11.2737||999999 (maximum date)|
Count of tenth of seconds AD (anno domini, after the birth of Christ). The valid range is from 1.1.0001 00:00:00.0 up to 16.11.3168 9:46:39 plus 0.9 seconds. See the following table for the relation of the packed number to a real time:
|Time / Range of Times||Value / Range of Values|
|1.1.0000 00:00:00.0||0 (special value - no date)|
|undefined times||1 - 315359999|
|1.1.1970 00:00:00.0||621671328000 (start of C-time functions)|
The relation between the packed number of a Date and Time data type is as follows:
tenths of a second per day = 24*60*60*10 = 864000
|number of time||= number of date||* 864000|
|315360000||= 365||* 864000 1.1.0001 00:00:00.0|
|621671328000||= 719527||* 864000 1.1.1970 00:00:00.0|
|number of date||= number of time||/ 864000|
|365||= 315360000||/ 864000 1.1.0001|
|719527||= 621671328000||/ 864000 1.1.1970|
The library name as specified in the IDL file is not supported by
Natural. By default, a Natural client sends the library name
SYSTEM to the server. To send a library name other than
SYSTEM from a client to a server, the following steps are required
for the client:
To send a library name other than
SYSTEM from a
client to a server
On the client, turn on the logon option.
Call application programming interface
USR4008N to specify
the name of the library, otherwise the name of the current library is sent
The length of the library name is limited to 8 characters.
The program name is sent from a client to the server. Special characters are not replaced. The program alias is not sent to the server.
The generated Natural interface object has the same name.
In the RPC server, the IDL program name sent is used to locate the Natural subprogram.
The length of the program name is limited to 8 characters.
The parameter names as given in the parameter-data-definition of the IDL file are replaced by artificial names in the generated Natural interface object.
See parameter-data-definition in the section Software AG IDL Grammar in the EntireX documentation.
Fixed arrays within the IDL file are mapped to fixed Natural arrays. The lower bound is set to 1 and the upper bound is set to the upper bound given in the IDL file.
See the array-definition (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax on how to describe fixed arrays within the IDL file and refer to fixed-bound-array-index.
Unbounded arrays within the IDL file are mapped to Natural X-arrays. The lower bound is always fixed and set to 1.
See the array-definition (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax of unbounded arrays within the IDL file and refer to unbounded-array-index.
Natural variable arrays (Natural notation (../1:V)) can be used on the Natural RPC server side instead of Natural fixed arrays or X-arrays. An RPC client can pass either an IDL fixed array or IDL unbounded array to a Natural RPC server with such a Natural variable array. In the RPC server, the variable array cannot be resized; this means the number of array occurrences cannot be changed, and the Natural RPC server will always pass back the same number of occurrences.
Groups within the IDL file are mapped to Natural groups. See group-parameter-definition (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax on how to describe groups within the IDL file.
Structures within the IDL file are mapped to Natural groups. See structure-definition (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax on how to describe structures within the IDL file.
The IDL syntax allows you to define parameters as IN parameters, OUT parameters, or INOUT parameters (which is the default if nothing is specified). This direction specification is reflected by Natural as follows:
Parameters with the
attribute are sent from the RPC client to the RPC server. They are always
provided with the call by reference method.
Parameters with the
attribute are sent from the RPC server to the RPC client. They are always
provided with the call by reference method.
Parameters with the
attribute are sent from the RPC client to the RPC server and then back to the
Only the direction information of the top-level fields (level 1) is relevant. Group fields always inherit the specification from their parent. A different specification is ignored.
See attribute-list (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax on how to describe attributes within the IDL file and refer to direction-attribute.
If you define an interface object layout in the Natural application
SYSRPC, the meaning of the direction attributes IN and
OUT are reversed compared to the IDL:
OUT in IDL
IN in IDL
ALIGNED attribute is not
relevant for the programming language Natural. However, a Natural client can
ALIGNED attribute to an RPC server
where it might be needed. To do this you need a Natural interface object that
has been generated from an IDL file.
See attribute-list (in the section Software AG IDL Grammar in the EntireX documentation) for the syntax of attributes in the IDL file and refer to the aligned-attribute.
The IDL syntax allows definitions of procedures only. It does not have the concept of a function. A function is a procedure which, in addition to the parameters, returns a value. Procedures and functions are transparent between clients and server. This means a client using a function can call a server implemented as a procedure, and vice versa.
The Natural RPC does not support functions.