gtpm2m25Migration Guide: Program Update Tapes

Remote Procedure Call (APAR PJ26575)

The following section discusses the migration considerations for remote procedure call (RPC).

Prerequisite APARs

See the APEDIT for APAR PJ26575 for information about prerequisite APARs.

Functional Overview

The TPF 4.1 system is enabled to run remote procedure call (RPC) servers through a partial port of the Distributed Computing Environment (DCE) RPC run-time library. RPC allows applications on one workstation to call functions that reside on and are run by another workstation. The RPC run-time library allows you to develop RPC server applications that can be accessed using Transmission Control Protocol (TCP) or User Datagram Protocol (UDP) Internet protocols. The RPC library application programming interfaces (APIs) establish required client/server connections by using socket APIs. Two new socket APIs, sendmsg and recvmsg, were added. See TPF Transmission Control Protocol/Internet Protocol for more information about socket APIs. You can use RPC to call various types of new and existing applications. RPC servers are started and ended by entering the ZINET commands. See TPF Operations for more information about the ZINET commands.

Client applications running on any IBM or non-IBM DCE platform are able to run remote procedure calls to a TPF server. All DCE services are available to client applications; however, the TPF 4.1 system supports only a subset of the DCE RPC services.

Elements of a traditional DCE RPC environment that can be used with the TPF implementation are:

DCE RPC is based on a thread model; therefore, server applications must be thread-safe. See TPF Application Programming for more information about RPC and threads.

Architecture

The DCE model of RPC is being implemented by the TPF 4.1 system, and only the RPC run-time library APIs for server applications are supported. Client API support is not provided. Other standard DCE environment services that are not implemented by the TPF 4.1 system are:

Operating Environment Requirements and Planning Information

There are no changes.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

Table 675 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 675. Changes to Build Scripts for RPC

Build Script Type New, Changed, or No Longer Supported? Description of Change
COMXBS LIB Changed Added the sendmsg and recvmsg APIs.
CPG2BS DLM New Added ISO8859-1 to the IBM-1047 code page conversion.
CPG3BS DLM New Added IBM-1047 to the ISO8859-1 code page conversion.
CRPCBS DLL New Added the dynamic link libraries (DLLs) for RPC APIs.
CRP1BS DLM New Added the dynamic load module (DLM) for RPC server activation.
CRP2BS DLM New Added the dynamic load module (DLM) for RPC server activation.
CTHDBS LIB New Added the threads library.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 676 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 676. Changes to General Use C/C++ Language Header Files for RPC

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$eb0eb.h Changed No
errno.h Changed No
rpc.h New Not Applicable
socket.h Changed No
sysdef.h Changed No
sysgtime.h Changed No
types.h Changed No

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

Table 677 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 677. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for RPC

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$iscfdt.h Changed No
c$isclnt.h Changed No
c$proc.h Changed No
c$thgl.h New Not Applicable
i$netd.h Changed No

Library Interface Scripts

Table 678 summarizes changes to the library interface scripts used by the library interface tool and the build tool. This information is presented in alphabetic order by the name of the library interface script.

Table 678. Changes to Library Interface Scripts for RPC

Library Interface Script New, Changed, or No Longer Supported? Description of Change
COMXXV Changed Added the sendmsg and recvmsg APIs.
CTHDXV New Added the thread APIs.

Library Members (Object Files)

Table 679 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 679. Changes to Library Members (Object Files) for RPC

Library Member (Object File) Library Source File New, Changed, or No Longer Supported? Type Description of Change
CBSTER CISO Changed C Language Added strings for new errno.h values.
CLMINT CISO Changed Real-Time Assembler Removed wxtrn for @@PT_BAS.
CSSDLL CISO Changed C Language Added the CRPC subsystem shared list.
C301 COMX New C Language Added sendmsg support.
C302 COMX New C Language Added recvmsg support.
C513 COMX Changed C Language Added setsockopt support.
C520 COMX Changed C Language Added setsockopt support.
C533 COMX Changed C Language Added setsockopt support.
C539 COMX Changed C Language Added setsockopt support.
C541 COMX Changed C Language Added setsockopt support.

Link-Edited Modules

Table 680 summarizes changes to the link-edited modules shipped by IBM, which should go into a data set with attributes DCB=(RECFM=U,LRECL=80,BLKSIZE=1200). This information is presented in alphabetic order by the name of the link-edited module.

Table 680. Changes to Link-Edited Modules for RPC

Link-Edited Module New, Changed, or No Longer Supported? Description of Change
COMX Changed Added sendmsg and recvmsg APIs.
CPG2 New Added ISO8859-1 to the IBM-1047 code page conversion.
CPG3 New Added IBM-1047 to the ISO8859-1 code page conversion.
CPGS Changed Added CPG2 and CPG3 DLMs to the code page table.
CRPC New Added RPC API dynamic link libraries (DLLs).
CRP1 New Added support for the ZINET START command for the RPC server.
CRP2 New Added support for reactivating the RPC server.
CTHD New Added the thread library.

Members (Object Files)

Table 681 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).

Notes:

  1. You must recompile or reassemble a member (object file) if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 681. Changes to Members (Object Files) for RPC

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CINET1 CLTV Changed C Language Added RPC model support to the ZINET ADD and ZINET ALTER commands.
CINET3 CLTW Changed C Language Added RPC model support to INETD.
CINET5 CLTV, CLTY Changed C Language Added RPC model support to INETD.
CINET6 CRPC, CTFT Changed C Language Added RPC model support to INETD.
CPGS CPGS Changed C Language Added new code page conversion DLMs.
CRPCIN CRP1 New C Language Added RPC server startup.
CRPCMS CRP1, CRP2 New C Language Added RPC error routines.
CRPCRS CRP2 New C Language Added RPC server restart.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

Table 682 summarizes copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 682. Changes to Copy Members for RPC

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CCEB Control Program CCENBK Not Applicable Changed Updated thread termination.
CHSZ Control Program CCNUCL Not Applicable Changed Updated CE2RPC field initialization.
CIEF Control Program CCCIEF Not Applicable Changed Updated event processing for threads.
CLHH Control Program CCSTOR Not Applicable Changed Updated the RALOC macro to support threads.
CLHP Control Program CCCLHR Not Applicable Changed Updated data collection fields.
CLHV Control Program CCSTOR Not Applicable Changed Updated page and segment tables.
CLWP Control Program CCLAW3 Not Applicable Changed Updated TCP/IP error processing.
CPSL Control Program CCCPSE Not Applicable Changed Updated dump formatting for thread blocks.
CTH0 Control Program CCTHDS Not Applicable Changed Added thread support.
CTH2 Control Program CCTHDS Not Applicable Changed Added thread support.
CTH3 Control Program CCTHDS Not Applicable Changed Added thread support.
CTH4 Control Program CCTHDS Not Applicable Changed Added thread support.
CTR0 Control Program CCISOC Not Applicable Changed Updated C function trace thread support.
CT40 Control Program CCCTIN Not Applicable Changed Updated ITSDT block initialization.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 683 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 683. Changes to Data Macros for RPC

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs That Use This Data Macro?
CZ3CP Changed No
ICPTH New Not Applicable
IEQCE2 Changed No
IPROC Changed No
ITHGL Changed Yes
ITSUT New Not Applicable
ITTCB New Not Applicable

General Macros

There are no changes.

Selected Equate Macros

Table 684 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 684. Changes to Selected Equate Macros for RPC

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZ1SE Changed No

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 685 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 685. Changes to SIP Skeleton and Internal Macros for RPC

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed. Also, changed for PJ26806.

System Initialization Program (SIP) Stage I Macros and Statements

Table 686 summarizes system initialization program (SIP) Stage I macro and statement changes. This information is presented in alphabetic order by the name of the SIP Stage I macro. See TPF System Generation for a complete description of the SIP Stage I macros. If the SIP Stage I macro is changed, you must run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

See System Initialization Program (SIP) and System Generation Changes for a description of other system generation changes you must make.

Table 686. Changes to SIP Stage I Macros and Statements for RPC

SIP Stage I Macro New, Changed, or No Longer Supported?
GENSIP Changed

System Initialization Program (SIP) Stage II Macros

Table 687 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If the IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 687. Changes to SIP Stage II Macros for RPC

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

There are no changes.

System Macros (IBM Use Only)

Table 688 summarizes system macro changes. This information is presented in alphabetic order by the name of the system macro.

Table 688. Changes to System Macros (IBM Use Only) for RPC

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
TERMC New Not Applicable
CFMCC Changed Yes
CFMDC Changed Yes

Segments

Table 689 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 689. Changes to Segments for RPC

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CLH0 Assembler Not Applicable Changed Updated for ZCTKA command parsing.
CLH2 Assembler Not Applicable Changed Added ZCTKA DISPLAY command updates.
CLH3 Assembler Not Applicable Changed Added ZCTKA ALTER commnd updates.
CTHA Assembler Not Applicable Changed Included process deactivation processing.
CVOE Assembler Not Applicable Changed Added ZASER and ZDSER command processing.
CVOR Assembler Not Applicable Changed Added ZSTAT command processing.
CVOU Assembler Not Applicable Changed Added ZASER and ZDSER command parsing.
CVRA Assembler Not Applicable Changed Added ZASER and ZDSER command processing.
ICDF Assembler Not Applicable Changed Assemble for CFMCC and CFMDC changes.
JCD4 Assembler Not Applicable Changed Added data collection and data reduction changes.
JCS0 Assembler Not Applicable Changed Added data collection and data reduction changes.
JRA2 PL/I Dataread Changed Added data collection and data reduction changes.
JRF4 PL/I Dataread Changed Added data collection and data reduction changes.
JRS3 PL/I Dataread Changed Added data collection and data reduction changes.
STPP Assembler PPCP Changed Assemble for CFMCC and CFMDC changes.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

Table 690 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for a complete description of all commands.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 690. Changes to Commands for RPC

Command New, Changed, or No Longer Supported? Description of Change
ZASER Changed Added the THEAPON and THEAPOFF parameters.
ZCTKA ALTER Changed Added support for the MTHD and TSTK parameters.
ZDSER Changed Added the THEAPON and THEAPOFF parameters.
ZINET ADD Changed Added MODEL-RPC support.
ZINET ALTER Changed Added MODEL-RPC support.

Messages and System Errors

Table 691 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. See Messages (System Error and Offline) and Messages (Online) for a complete description of all messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 691. Changes to Messages and System Errors for RPC

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
008508 System Error New
008509 System Error New
00850B System Error New
00850C System Error New
00850D System Error New
00850E System Error New
00850F System Error New
008510 System Error New
008531 System Error New
008532 System Error New
008533 System Error New
CTKA0017I  Online New
CTKA0018I  Online New
CTKA0065E  Online New
CTKA0066E  Online New
CTKA0067E  Online New
CTKA0068E  Online New
CT400008I  Online New
CT400010I  Online New
FKPA0012A  Online New
RPCR0001A  Online New
RPCR0002E  Online New
RPCR0003I  Online New
RPCR0004I  Online New
RPCR0005E  Online New
STAT0012I  Online New

Performance or Tuning Changes

Three fields have been added to the System Summary Report. Two fields contain information on the number of threads and the third field contains information on the number of frames:

Storage Considerations and Changes

See Performance or Tuning Changes for information about frame usage.

RPC servers run in a threaded environment. You need to consider both the size of the ECB heap area and the maximum number of threads in a process. As each thread is created in a process, the heap area of the initial thread is shared with the new thread. The maximum number of threads in a process affects the size of the collective heap.

You can enter the ZCTKA command to modify heap storage values. The maximum size of the ECB heap is set by specifying the EMPS parameter. The maximum number of 4-KB frames that an ECB can acquire for heap storage is set by specifying the MMHS parameter. Specifying these parameters affects all ECBs in the TPF 4.1 system. In a threaded environment, the value in the MMHS parameter may be too small to accommodate the collective heap. You can modify the CE2MPF field in the ECB to override the value in the MMHS parameter; this will allow for the number of 4-KB frames required by the collective heap.

When a thread issues a request for heap storage, frames are attached to the initial thread. For RPC, this is the ECB that issued the rpc_server_listen API. These frames are not released until the initial ECB exits. For RPC, this means that the server has been shut down.

Additionally, the required size of the 31-bit core resident program area (CRPA) must be increased about 3 MG.

System Initialization Program (SIP) and System Generation Changes

No modifications are needed for SIP parameters; however, the GENSIP macro was updated for internal use thread support.

Loading Process Changes

There are no changes.

Online System Load Changes

Whenever a loadset is activated, deactivated, or excluded by the E-type loader, all RPC servers in the subsystem are recycled to ensure that the correct version of all loaded functions is used by the RPC server.

Publication Changes

Table 692 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 692. Changes to TPF Publications for RPC

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP0A Updated with a new chapter for RPC.
TPF Concepts and Structures GTPCON08 Updated with information on the RPC server and the RPC process model.
TPF C/C++ Language Support User's Guide GTPCLU0B Updated with information about the RPC APIs.
TPF Library Guide GTPDOC0B Updated with definitions for RPC terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for RPC.
TPF Migration Guide: Program Update Tapes GTPMG201 Updated with migration considerations for RPC.
TPF Operations GTPOPR0B Updated with information about the commands that were added and changed for RPC.
TPF Program Development Support Reference GTPPDR0B Updated with information about dump labels for RPC.
TPF System Performance and Measurement Reference GTPSPR0A Updated with information about entries to the System Summary Report for RPC.
TPF Transmission Control Protocol/Internet Protocol GTPCLW07 Updated with information about sendmsg and recvmsg socket APIs.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

The following is a list of supported RPC run-time library APIs:

rpc_binding_copy rpc_binding_free
rpc_binding_inq_object rpc_binding_to_string_binding
rpc_binding_vector_free rpc_if_id_vector_free
rpc_if_inq_id rpc_mgmt_inq_if_ids
rpc_mgmt_inq_stats rpc_mgmt_is_server_listening
rpc_mgmt_stats_vector_free rpc_mgmt_stop_server_listening
rpc_network_inq_protseqs rpc_network_is_protseq_valid
rpc_object_inq_type rpc_object_set_inq_fn
rpc_object_set_type rpc_protseq_vector_free
rpc_server_inq_bindings rpc_server_inq_if
rpc_server_listen rpc_server_register_if
rpc_server_unregister_if rpc_server_use_all_protseqs_if
rpc_server_use_protseq_ep rpc_server_use_protseq_if
rpc_ss_allocate rpc_ss_free
rpc_string_binding_compose rpc_string_binding_parse
rpc_string_free uuid_compare
uuid_create uuid_create_nil
uuid_equal uuid_from_string
uuid_hash uuid_is_nil
uuid_to_string  

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Use the following procedure to install RPC in your TPF 4.1 system.

  1. Install program update tape (PUT) 11.
  2. Compile, assemble, and link all code associated with this APAR. See the APEDIT for the complete list.
  3. Load all code to the TPF 4.1 system.
  4. Generate a universal unique identifier (UUID) for the new RPC interface by using the UUID Generator Utility on an IBM OS/390 system.
  5. Create an Interface Definition Language (IDL) file that includes the UUID and the remote procedures with their input and output parameters.
  6. Compile the IDL file with an IDL compiler to generate header files and stub files for client and server applications on an IBM OS/390 system.
  7. Include the header file in the server application. Compile and link the server stub file and the server application on the server platform (this would be where you compile and link all your TPF code).
  8. Include the header file in the client application. Compile and link the client stub file and the client application on the client platform.
  9. Load the server code to your TPF 4.1 system. RPC servers are processor and subsystem unique.
  10. Cycle the TPF 4.1 system to 1052 state or higher.
  11. To increase thread resources, change the thread parameters in keypoint A (CTKA) by entering the ZCTKA ALTER command with the MTHD and TSTK parameters specified. Restart your system by entering the ZRIPL command.
  12. Define an Internet daemon (INETD) entry for the new server by entering the ZINET ADD command with the S, MODEL-RPC, and PGM parameters specified.
  13. Cycle the TPF 4.1 system to CRAS state or higher.
  14. Verify that TCP/IP support is active in the TPF 4.1 system and that required offload devices or Internet Protocol (IP) routers are available and active. Enter the ZCLAW DISPLAY command with the ACTIVE parameter specified to check the active CLAW workstations, and the ZTTCP DISPLAY command with the ACTIVE parameter specified to display all active IP routers.
  15. Start the server using the INETD by entering the ZINET START command with the S parameter specified.

Clients can now access remote procedures from any client platform.

See TPF Operations for more information about the ZCLAW DISPLAY, ZCTKA ALTER, ZINET ADD, ZINET START, ZRIPL, and ZTTCP DISPLAY commands.