Version 9.5 SP1	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

The EntireX z/OS Batch RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS running in batch mode. It supports the programming languages COBOL, PL/I and C.

This document covers the following topics:

• Inside the RPC Server

• Impersonation

• Usage of SVM Files

• Scenario I: Calling an Existing COBOL Server

• Scenario II: Writing a New COBOL Server

• Scenario III: Calling an Existing PL/I Server

• Scenario IV: Writing a New PL/I Server

• Scenario V: Writing a New C Server

• Scenario VI: Writing a New Assembler Server

• Returning Application Error Codes from a Server to a Client

Inside the RPC Server

This section covers the following topics:

• Worker Models

• Inbuilt Services

Worker Models

RPC requests are worked off inside the RPC server in worker threads, which are controlled by a main thread. Every RPC request occupies during its processing a worker thread. If you are using RPC conversations, each RPC conversation requires its own thread during the lifetime of the conversation. The Batch RPC Server provides two worker models:

• FIXED
  The fixed model creates a fixed number of worker threads. The number of worker threads does not increase or decrease during the lifetime of an RPC server instance.

• SCALE
  The scale model creates worker threads depending on the incoming load of RPC requests.

  A maximum number (thru value of the workermodel parameter) of worker threads created can be set to restrict the system load. The minimum number (from value of the workermodel parameter), allows you to define a certain number of threads - not used by the currently executing RPC request - to wait for new RPC client requests to process. In this way the RPC server is ready to handle many RPC client requests arriving at the same time.

See parameter workermodel under Configuring the RPC Server.

Inbuilt Services

Batch RPC Server provides several services for ease-of-use:

• Extractor Service
• Deployment Service
• SMH Listener Service

Extractor Service

The Extractor Service is a prerequisite for remote extractions with the IDL Extractor for COBOL and IDL Extractor for PL/I. See Extractor Service for more information.

Deployment Service

The Deployment Service allows you to deploy server mapping files (SVM files) interactively using the Deployment Wizard (see Server Mapping Deployment). On the RPC server side, the SVM files are stored in a VSAM file as the container. See Deployment Service for configuration information.

SMH Listener Service

With the SMH Listener Service you use the System Management Hub to monitor the RPC server. See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows.

The SMH Service is switched on if the parameter smhport is set. See parameter smhport under Configuring the RPC Server.

Impersonation

The Batch RPC Server can be configured so that worker threads authenticate the RPC client user ID before execution of the RPC request request with a mainframe security repository (RACF, CA Top Secret or CA ACF2), using the SAF interface. If the RPC user ID is valid, the worker thread gets the identity of the RPC client. This is necessary when accessing (security) protected data sets, for example with the Extractor Service. The way authentication is carried out can be controlled by the RPC parameter impersonation.

• For impersonation value AUTO, the Batch RPC Server does not validate RPC passwords, so you have to make sure the RPC client is correctly authenticated, either by using a secure EntireX Broker (validation must be against the correct mainframe security repository where z/OS user IDs are defined) or with your own security implementation.

• For impersonation value YES, the Batch RPC Server uses the RPC user ID and password supplied by the RPC client for authentication and impersonation of the client. This means that the RPC server validates the password.

The picture above shows the configuration impersonation=yes.

The lifetime of an impersonated task starts when an open request for an RPC conversation or a non-conversational RPC request is received. It ends when the RPC conversation stops (after a commit operation or timeout) or when the non-conversational RPC request has been performed.

Usage of SVM Files

To correctly support special COBOL syntax such as JUSTIFIED, SYNCHRONIZE and OCCURS DEPENDING ON clauses, LEVEL-88 fields, etc., the Batch RPC Server requires in many situations a server mapping file.

SVM files contain COBOL-specific mapping information that is not included in the IDL file and therefore not sent by an EntireX RPC client to the RPC server. See also When is an SVM File Required? under Handling SVM Files.

The RPC server marshalls the data in a two-step process: the RPC request coming from the RPC client (Step 1) is completed with COBOL-specific mapping information taken from the SVM file (Step 2). In this way the COBOL server can be called as expected.

The SVM files are retrieved as a result of the IDL Extractor for COBOL extraction process and the COBOL Wrapper if a COBOL server is generated.

You can customize the usage of the SVM file using parameter svm. See Configuring the RPC Server.

Note:
SVM files are used for COBOL only.

Scenario I: Calling an Existing COBOL Server

To call an existing COBOL server

1. Use the IDL Extractor for COBOL to extract the Software AG IDL and, depending on the complexity of the extraction, also an SVM file.

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

See Client and Server Examples for z/OS Batch for COBOL RPC Server examples.

Scenario II: Writing a New COBOL Server

To write a new COBOL server

1. Use the COBOL Wrapper to generate a COBOL server skeleton and, depending on the complexity of the extraction, also an SVM file. Write your COBOL server and proceed as described under Using the COBOL Wrapper for the Server Side.

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

See Client and Server Examples for z/OS Batch for COBOL RPC Server examples.

Scenario III: Calling an Existing PL/I Server

To call an existing PL/I server

1. Use the IDL Extractor for PL/I to extract the Software AG IDL.

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

See Client and Server Examples for z/OS Batch for PL/I RPC Server examples.

Scenario IV: Writing a New PL/I Server

To write a new PL/I server

1. Use the PL/I Wrapper to generate a PL/I server skeleton. Write your PL/I server and proceed as described under Using the PL/I Wrapper for the Server Side.

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

See Client and Server Examples for z/OS Batch for PL/I RPC Server examples.

Scenario V: Writing a New C Server

To write a new C server

1. Use the C Wrapper to generate a C server skeleton and a C server interface object. Write your C server and proceed as described under Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000/OSD, IBM i).

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

Scenario VI: Writing a New Assembler Server

To write a new Assembler (IBM 370) server

1. Build an RPC server in Assembler. Here are some hints:

   • The RPC server is dynamically callable (no pre-initialization required).

   • The parameter interface is either compatible with the COBOL or PL/I calling convention (IDL level parameter will be passed in the address list). Configure the parameter marshalling accordingly for COBOL or PL/I.

   • The alignment of integer or float data types is considered. The HASM Assembler aligns integer or float data types to appropiate boundaries. For example:

     ...
           MyLabel   DSECT
           MyField1  DS   H                      I2
           MyField2  DS   F                      I4
           MyField3  DS   E                      F4
           MyField4  DS   L                      F8

   • The Batch RPC Server will not align these data types by default.

   • To force alignment by definition in your IDL file (see the aligned attribute within the attribute-list) before generating your RPC client. For information on whether your client supports the aligned attribute, see Mapping the aligned Attribute to C | COBOL | DCOM | .NET | Java | Natural | PL/I.

2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

   • use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation

   • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester

Returning Application Error Codes from a Server to a Client

See Returning Application Errors from a Server under z/OS Batch to a Client in the COBOL Wrapper documentation under Writing Applications with the COBOL Wrapper.

www.softwareag.com

Copyright © 1997-2013 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT