This document covers the following topics:
The parameters of the IDL program must contain an A field with a length of at least 254 bytes or of unlimited length.
You need to have dynamic data types in your IDL. You must use COMPR=2 (send buffer completion).
To write a Natural client
Use CALLNAT for the Natural RPC client.
Provide a context for EntireX as described under Interface RPC-CNTXfor the Natural RPC Client Programmer below. See the Natural documentation for details.
The RPC-ACI Bridge reports errors on the ACI side or the
Broker for ACI with Natural error 998 (Internal error details). The details
contain the error number followed by a description. Use Natural subroutine
USR2030N to retrieve error class, error code and description. The
error class for the RPC-ACI Bridge is 1018. See Message Class 1018 - EntireX RPC-ACI Bridge.
For error handling, use for example (the declarations of the variables are omitted):
ON ERROR
IF *ERROR-NR = 998 THEN
CALLNAT 'USR2030N' ERR-PARM(*) OCC RESPONSE
IF OCC > 0 THEN
MOVE SUBSTRING(ERR-PARM(1), 1, 8) to #ERR-CODE
MOVE SUBSTRING(ERR-PARM(1), 10) to #ERR-DETAIL
WRITE #ERR-CODE
WRITE #ERR-DETAIL (AL=79)
ESCAPE ROUTINE
END-IF
END-IF
END-ERROR
API RPC-CNTX is used for providing a context for RPC client applications. RPC-CNTX combines the functionality of several APIs and is available in library SYSTEM. There is no need for extra preparations such as setting a STEPLIB or copying APIs from SYSEXT to user libraries.
RPC-CNTX makes the following interfaces from SYSEXT obsolete: USR1071N, (USR4371N), USR6304N, USR2007N, USR4008, USR4009, USR2071N.
For the usage of RPC-CNTX refer to the test programs generated by the Natural Wrapper, see Sample Generation Result for the Client Side.
For further information refer to the Natural RPC documentation.
Application error codes enable the RPC server to return customer-invented errors back to the RPC client in a standardized way without defining an error code field in the IDL file.
USR4012N from Natural library SYSEXT may be used to enforce Natural error NAT1999 on the Natural RPC server and to pass back the provided error text to the RPC client.
/* Application Error COMPRESS "ERROR: " #ERR-TEXT INTO #LOG-TEXT /* Send back Application Error to Client CALLNAT 'USR4012N' USING #ERR-TEXT
For more information:
Logon to the Natural library SYSEXT within your Natural installation,
enter command MENU and select
USR4012N.
Refer to the http://documentation.softwareag.com > Natural Product Family.
The Natural library SYSEXT provides APIs for RPC programming. Log on to
the library SYSEXT and enter MENU. To list only
RPC-related APIs, enter the keyword RPC.
To make these APIs available, make the necessary STEPLIP settings or copy the APIs from SYSEXT to user libraries.
For more information, refer to the API documentation provided by SYSEXT.
| Interface | Comment |
|---|---|
| USR1071N | Set user ID and password for RPC |
| USR2007N | Set/get RPC default server information. |
| USR2015N | EBCDIC or ASCII translation table for Natural RPC. |
| USR2032N | Support of commit for CLOSE CONVERSATION. |
| USR2035N | Support of SSL. |
| USR2071N | Support of EntireX Security on client side. |
| USR2072N | Support of EntireX Security on server side. |
| USR2073N | Ping or terminate an RPC server. |
| USR2074N | Set new password for NSC user in RPC context. |
| USR2075N | Terminate EntireX Broker service. |
| USR4008N | Set library for RPC execution. |
| USR4009N | Set parameters for EntireX. |
| USR4010N | Retrieve runtime settings of server. |
| USR4012N | Support of application error. |
| USR4371N | Set user ID and ETID for RPC. |
| USR6304N | Set/get reliable state for RPC execution. |
| USR6305N | Commit/rollback reliable RPC message(s). |
| USR6306N | Status of UOWs of current EntireX Broker user. |
| etc. |
RPC client applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based clients are always SSL clients. The SSL server can be either the EntireX Broker or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation. This section describes using SSL with the Natural Wrapper on the following platforms:
SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).
For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.
With the Natural Wrapper you can use IBM's Application Transparent Transport Layer Security (AT-TLS), where the establishment of the SSL connection is pushed down the stack into the TCP layer.
Configure the AT-TLS rules for the policy agent (PAGENT) 
using an appropriate client 
and the z/OS Management Facility (z/OSMF) 
.
Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by
using the application 
job name and remote TCP port number.
If the rules match, the TCP connection is turned into an SSL connection 
.
Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.
|
Client to interact with z/OS Management Facility (z/OSMF). |
|
AT-TLS rules are defined with z/OSMF policy management. |
 |
Policy Repository with AT-TLS rules stored as z/OS files. |
|
Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
|
|
Application using TCP connection. |
|
If AT-TLS rules match, the TCP connection is turned into an SSL connection. |
Notes:
may vary per operating system, for example a Web browser for z/OS 2.1.
includes other administration and management tasks in addition to policy management.
includes other rules, such as IP filtering, network address translation etc.
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection,
using a client to interact with the z/OS Management Facility (z/OSMF) See z/OSMF Considerations in the z/OS Administration documentation.
The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files.
This file is the configuration file for the Policy Agent, MVS task PAGENT.
Make sure the SSL server to which the RPC component connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:
Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.
Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup
job BSTTATLS .
If the rules match, the socket connection is turned into an SSL connection .
Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.
|
BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6). |
|
ATLS rules are defined manually. See Sample ATLS Daemon Configuration below. |
|
BSTTATLS is associated with a TCP/IP stack. |
|
Application using TCP connection. |
|
BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections. |
To set up SSL with ATLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:
ETB024:1699:TCP
Configure ATLS to turn the TCP/IP connection to an SSL connection, see above.
Make sure the SSL server to which the RPC component connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:
* Converting inbound EntireX Broker connection * Converts listen port 1971 to SSL listen port 1972 OPTION SERVER ATTLS 1971 AS 2071 SSL * * Converting outbound client connection * Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL OPTION CLIENT ATTLS 1972 TO 192.168.2.100 AS 2072 SSL
Note:
We recommend setting SETPARM value SUBTASK to a value greater than 0 in the ATLS daemon startup job (valid values 0-16, default=0). For example:
// SETPARM SUBTASK=8
See also BSI SSL Installation, Programming and User's Guide.