OpenTP1 Version 7

TP1/Client User's Guide TP1/Client/W, TP1/Client/P

3000-3-D58-20(E)


Contents

Notices
Summary of amendments
Preface

1. Overview
1.1 TP1/Client features
1.2 TP1/Client operation

2. Facilities
2.1 User authentication
2.1.1 Implementing user authentication
2.1.2 Specifying TP1/Server for authentication request
2.1.3 Suppressing user authentication
2.1.4 Communicating with a server other than TP1/Server
2.2 Permanent connection
2.2.1 Establishing and releasing the permanent connection
2.2.2 Definitions needed for permanent connection
2.2.3 Reporting terminal identification information to the DCCM3 logical terminal
2.2.4 Notes on using permanent connection
2.3 Remote procedure calls
2.3.1 RPC initiation
2.3.2 RPC data transfer
2.3.3 RPC types
2.3.4 Chained RPC
2.3.5 Scheduler
2.3.6 Inter-node load-balancing facility
2.3.7 RPC time monitoring
2.3.8 Authentication RPC
2.3.9 RPC to servers other than OpenTP1
2.3.10 RPC using the name service
2.3.11 RPC using the multi-scheduler facility
2.3.12 Switching facility of TP1/Server as a gateway
2.3.13 Load distribution for TP1/Server as a gateway
2.3.14 Data compression
2.3.15 Remote API facility
2.3.16 Reducing server loads during timeout at synchronous response type PRC
2.4 Transaction control
2.4.1 Starting a transaction and acquiring a synchronous point
2.4.2 Acquiring a synchronous point
2.4.3 Relationship between remote procedure call modes and synchronous points
2.4.4 Collecting identifiers for current transactions
2.4.5 Posting information for current transactions
2.4.6 Detecting the synchronous point of a transaction when an error occurs
2.4.7 Notes on transaction control
2.5 TCP/IP communication function
2.5.1 Send-only messages
2.5.2 Receive-only messages
2.5.3 Sending and receiving messages
2.5.4 Message assembly facility and delivery confirmation facility
2.5.5 Notes on using the TCP/IP communication facility
2.6 Facility for receiving one-way messages from the server
2.6.1 Overview of the facility for receiving one-way messages from the server
2.6.2 Overview of the continuous reception function for one-way messages
2.6.3 Notes on using the continuous reception function for one-way messages
2.7 XATMI interface facility
2.7.1 Interactive service
2.7.2 Interactive service time monitoring
2.7.3 Receiving events
2.7.4 Communication data type
2.7.5 Notes on using the XATMI interface facility
2.8 Character code converter
2.8.1 When not using a code mapping table
2.8.2 When using a code mapping table
2.9 Multi-threading
2.9.1 Overview of a CUP suitable for multi-threading
2.9.2 Execution of functions not suited to multi-threading
2.9.3 Notes on using multi-threading
2.10 Online tester
2.11 Troubleshooting
2.11.1 Error logging
2.11.2 UAP trace collection
2.11.3 Socket trace collection
2.11.4 Module trace collection
2.11.5 TP1/Server performance verification trace
2.11.6 Note on using the troubleshooting facility
2.12 Host name extension
2.12.1 Host name length and host name storage area length that can be specified in the arguments of C functions
2.12.2 COBOL-UAP creation programs when the host name extension function is used
2.12.3 Number of characters that can be specified in an operand in the client environment definition
2.12.4 Notes on using the host name extension function
2.13 Send-host specification facility
2.14 Fixed receive-port facility

3. User Application Program Interface (C Language)
3.1 Function interface
3.1.1 Table of functions
3.1.2 Format of function descriptions
3.2 Compiling and linking user application programs
3.2.1 Compiling and linking in UNIX environment
3.2.2 Compiling and linking in Windows environments
3.3 Example of user application program development
3.3.1 Creating CUPs and SPPs
3.3.2 Creating a user application program that supports a multi-thread environment

4. TP1/Client Functions (C Language)
4.1 Notes on using functions
4.2 User authentication
4.2.1 dc_clt_cltin_s - client user authentication request
4.2.2 dc_clt_cltout_s - release of client user authentication
4.3 Remote procedure calls
4.3.1 dc_rpc_open_s - UAP startup
4.3.2 dc_rpc_close_s - UAP termination
4.3.3 dc_rpc_call_s - remote service request
4.3.4 dc_rpc_call_to_s - Request a remote service with the communication destination specified
4.3.5 dc_rpc_set_watch_time_s - Updating the wait time for service response
4.3.6 dc_rpc_get_watch_time_s - Referencing the wait time for service response
4.3.7 DCRPC_DIRECT_SCHEDULE - Create a DCRPC_BINDING_TBL structure
4.4 Permanent connection
4.4.1 dc_clt_connect_s - Establish permanent connection
4.4.2 dc_clt_disconnect_s - Release permanent connection
4.4.3 dc_clt_set_raphost_s - Set the destination of a request to establish a permanent connection
4.4.4 dc_clt_get_raphost_s - Acquire the destination of a request to establish a permanent connection
4.4.5 dc_clt_set_connect_inf_s - Set terminal identification information
4.5 Transaction control
4.5.1 dc_trn_begin_s - Transaction startup
4.5.2 dc_trn_chained_commit_s - Commit in chained mode
4.5.3 dc_trn_chained_rollback_s - Rollback in chained mode
4.5.4 dc_trn_unchained_commit_s - Commit in unchained mode
4.5.5 dc_trn_unchained_rollback_s - Rollback in unchained mode
4.5.6 dc_clt_get_trnid_s - Collection of identifiers for current transaction
4.5.7 dc_trn_info_s - Post information about current transaction
4.6 TCP/IP communication function
4.6.1 dc_clt_send_s - Sending messages
4.6.2 dc_clt_receive_s - Receiving messages
4.6.3 dc_clt_receive2_s - Receiving messages (messages receivable even if an error occurs)
4.6.4 dc_clt_assem_send_s - Sending assembled messages
4.6.5 dc_clt_assem_receive_s - Receiving assembled messages
4.7 Facility for receiving one-way messages from the server
4.7.1 dc_clt_accept_notification_s - One-way message reception
4.7.2 dc_clt_cancel_notification_s - Canceling one-way message wait
4.7.3 dc_clt_open_notification_s - Start reception of one-way messages
4.7.4 dc_clt_close_notification_s - Terminate reception of one-way messages
4.7.5 dc_clt_chained_accept_notification_s - Receive a one-way message
4.8 XATMI interface facility
4.8.1 tpalloc - Allocate typed buffer
4.8.2 tpfree - Release typed buffer
4.8.3 tpconnect - Establish connection with interactive service
4.8.4 tpdiscon - Disconnect connection with interactive service
4.8.5 tpsend - Send message to interactive service
4.8.6 tprecv - Receive message from interactive service
4.9 Character code converter (When not using a code mapping table)
4.9.1 dc_clt_code_convert - Converting character codes
4.10 Character code converter (When using a code mapping table)
4.10.1 dc_clt_codeconv_open - Starting character code conversion
4.10.2 dc_clt_codeconv_close - Terminating character code conversion
4.10.3 dc_clt_codeconv_exec - Executing character code conversion

5. User Application Program Interface (COBOL Language)
5.1 COBOL-UAP creation program features
5.1.1 Correspondence between UAPs and facilities
5.1.2 Format of COBOL-UAP creation program descriptions
5.2 Compiling and linking user application programs
5.2.1 Compiling and linking in a UNIX environment
5.2.2 Compiling and linking in a Windows environment
5.3 COBOL language template
5.3.1 COBOL language template files
5.3.2 Using COBOL language template
5.3.3 Notes on using COBOL language template
5.4 Example of user application program development
5.4.1 Creating CUPs and SPPs
5.4.2 Creating a user application program that can run in a multi-thread environment

6. Request Statements Available for TP1/Client (COBOL Language)
6.1 Notes on using request statements
6.2 User authentication
6.2.1 CBLDCCLS('CLTIN ') - Client user authentication request
6.2.2 CBLDCCLS('EXCLTIN ') - Client user authentication request (for an extended host name)
6.2.3 CBLDCCLS('CLTOUT ') - Release of client user authentication
6.3 Remote procedure calls
6.3.1 CBLDCRPS('OPEN ') - UAP startup
6.3.2 CBLDCRPS('CLOSE ') - UAP termination
6.3.3 CBLDCRPS('CALL ') - Remote service request
6.3.4 CBLDCRPS('SETWATCH') - Service response wait time update
6.3.5 CBLDCRPS('GETWATCH') - Service response wait time reference
6.4 Permanent connection
6.4.1 CBLDCCLS ('CONNECT ') - Establish permanent connection
6.4.2 CBLDCCLS ('DISCNCT ') - Release permanent connection
6.4.3 CBLDCCLS('STRAPHST') - Set the destination of a request to establish a permanent connection
6.4.4 CBLDCCLS('GTRAPHST') - Acquire the destination of a request to establish a permanent connection
6.4.5 CBLDCCLS('STCONINF') - Set terminal identification information
6.5 Transaction control
6.5.1 CBLDCTRS('BEGIN ') - Transaction startup
6.5.2 CBLDCTRS('C-COMMIT') - Commit in chained mode
6.5.3 CBLDCTRS('C-ROLL ') - Rollback in chained mode
6.5.4 CBLDCTRS('U-COMMIT') - Commit in unchained mode
6.5.5 CBLDCTRS('U-ROLL ') - Rollback in unchained mode
6.5.6 CBLDCTRS('INFO ') - Post information for current transaction
6.5.7 CBLDCCLS('GETTRNID') - Collection of identifiers for current transaction
6.6 TCP/IP communication function
6.6.1 CBLDCCLS('SEND ') - Sending messages
6.6.2 CBLDCCLS('EXSEND ') - Sending messages (for an extended host name)
6.6.3 CBLDCCLS('RECEIVE ') - Receiving messages
6.6.4 CBLDCCLS('RECEIVE2') - Receiving messages (messages receivable even if an error occurs)
6.6.5 CBLDCCLS('ASMSEND ') - Send assembled messages
6.6.6 CBLDCCLS('ASMRECV ') - Receiving assembled messages
6.7 Facility for receiving one-way messages from the server
6.7.1 CBLDCCLS('NOTIFY ') - Receiving one-way messages
6.7.2 CBLDCCLS('EXNACPT ') - Receiving one-way messages (for an extended host name)
6.7.3 CBLDCCLS('CANCEL ') - Canceling one-way message wait state
6.7.4 CBLDCCLS('EXNCANCL') - Canceling one-way message wait state (for an extended host name)
6.7.5 CBLDCCLS('O-NOTIFY') - Start reception of one-way messages
6.7.6 CBLDCCLS('C-NOTIFY') - Terminate reception of one-way messages
6.7.7 CBLDCCLS('A-NOTIFY') - Receive a one-way message
6.7.8 CBLDCCLS('EXNCACPT') - Receive a one-way message (for an extended host name)
6.8 Character code converter (When a code mapping table is not used)
6.8.1 CBLDCUTL ('CODECNV ') - Converting character codes
6.9 Character code converter (When a code mapping table is used)
6.9.1 CBLDCUTL('CNVOPN ') - Starting character code conversion
6.9.2 CBLDCUTL('CNVCLS ') - Terminating character code conversion
6.9.3 CBLDCUTL('CNVEXEC') - Executing character code conversion

7. Definition
7.1 Overview
7.1.1 List of client environment definition operands
7.1.2 Definition conventions
7.2 Definition details
7.2.1 TP1/Client/W format
7.2.2 TP1/Client/P format
7.2.3 TP1/Client/W
7.2.4 TP1/Client/P
7.2.5 Operands common to TP1/Client/W and TP1/Client/P
7.2.6 TP1/Client/W-specific operands
7.2.7 Operands for TP1/Client/P only
7.2.8 Notes on TP1/Client/W
7.2.9 Notes on TP1/Client/P

8. Operating Commands
8.1 Operating command syntax
8.2 Operating command descriptions
8.2.1 cltdump (edit and output a trace)

9. Error Recovery
9.1 Communication errors
9.2 Client errors
9.3 Errors in a remote operation request to XDM/DCCM3

10. Messages
10.1 Format of output messages
10.2 Format of message descriptions
10.3 List of messages

Appendixes
A. Code Conversion Specifications
A.1 Codes supported by TP1/Client/P
A.2 Conversion of shift-JIS codes and KEIS codes
A.3 Code conversion examples
A.4 Notes on code conversion
B. Version Changes
B.1 Changes made in 07-02
B.2 Changes made in 07-01
B.3 Changes made in 07-00

Index