gtpm2m25 | Migration Guide: Program Update Tapes |
The following section discusses the migration considerations for remote procedure call (RPC).
See the APEDIT for APAR PJ26575 for information about prerequisite APARs.
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.
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:
There are no changes.
The following section summarizes interface changes.
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.
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. |
There are no changes.
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 |
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 |
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. |
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. |
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. |
Table 681 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).
Notes:
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. |
There are no changes.
There are no changes.
There are no changes.
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. |
There are no changes.
The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.
There are no changes.
There are no changes.
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 |
There are no changes.
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 |
There are no changes.
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. |
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 |
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 |
There are no changes.
There are no changes.
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 |
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. |
There are no changes.
There are no 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.
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. |
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 |
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:
If a thread application (for example, RPC) is using a large number of threads compared to the number defined in keypoint A (CTKA), you can enter the ZCTKA ALTER command to change the maximum number of threads.
Frames that are released by threaded entry control blocks (ECBs) are placed on the frames pending list until it is safe to reuse them; for example, after a purge of the translation look-aside buffer (PTLB) is performed on all I-streams. If a large number of frames exist on the frames pending list, additional 4-KB frames should be generated in the TPF 4.1 system using the CORREQ macro. See TPF System Generation for more information about the CORREQ macro.
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.
No modifications are needed for SIP parameters; however, the GENSIP macro was updated for internal use thread support.
There are no 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.
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. |
There are no 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 |
There are no changes.
There are no changes.
There are no changes.
Use the following procedure to install RPC in your TPF 4.1 system.
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.