OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/J
(1) Specifying the remote server
To use an RPC to communicate with a DCCM3 server, use a service group name and a service name to specify the remote server. This specification method is the same as that used when issuing an RPC to an OpenTP1 server.
- Service group name
For the service group name, specify a valid dummy character string. Specify an identifier consisting of between 1 and 31 characters.
- Service name
Specify the transaction name of the DCCM3 server. The characters that can be used are letters (A-Z and a-z) and numbers (0-9). The total number of characters must be between 1 and 8.
(2) Defining an address of the remote server
When an RPC is used to communicate with a DCCM3 server, a server not managed by the OpenTP1 name service must be called. Therefore, TP1/Client/J must define server addresses separately for individual service names. To define a server address, specify the host name and port number of the RPC-accepting gateway in the dchost operand of the TP1/Client/J environment definition.
(3) Executing the RPC
After defining the address of the remote server, execute the RPC. The procedure for executing the RPC differs depending on the specification content of the TP1/Client/J environment definition as shown below.
(a) When Y is specified for the dcrapautoconnect operand
- Execute the rpcOpen method and load the definition.
- Execute the rpcCall method.
Connection is established at the RPC-accepting gateway specified in the dchost operand of the TP1/Client/J environment definition. After the connection is established, the RPC is issued.
(b) When N is specified for the dcrapautoconnect operand or when the specification is omitted
- Execute the rpcOpen method and load the definition.
- Execute the openConnection method without any arguments.
Connection is established at the RPC-accepting gateway specified in the dchost operand of the TP1/Client/J environment definition.
- After the connection is established, execute the rpcCall method to issue the RPC.
(c) To communicate with a server not specified in the dchost operand
- Execute the rpcOpen method and load the definition.
This step may be omitted. Even if it is omitted, steps 2 and 3 can be executed.
- Execute the openConnection method with the RPC-accepting gateway (host name and port number) specified in its arguments.
- After the connection is established, execute the rpcCall method to issue the RPC.
(4) Load distribution when issuing an RPC to a DCCM3 logical terminal
When TP1/Client/J uses permanent connection to issue an RPC to DCCM3 logical terminals, the connection targets can be allocated to multiple DCCM3 servers during connection establishment to distribute load. From the host names and port numbers of the multiple DCCM3 logical terminals specified in the dchost operand of the TP1/Client/J environment definition, TP1/Client/J randomly selects a connection target and attempts a connection. If TP1/Client/J fails to connect to a DCCM3 logical terminal, it randomly selects another DCCM3 logical terminal and attempts a connection. This process is repeated, and only after all attempts to connect to the DCCM3 logical terminals specified in the dchost operand of the TP1/Client/J environment definition have failed, is an error detected.
One of the following two API execution procedures can be used to establish communication between TP1/Client/J and a DCCM3 logical terminal:
- Specify the host name and port number of the DCCM3 logical terminal in the dchost operand of the TP1/Client/J environment definition and execute the openConnection method without any arguments.
In this case, a permanent connection is used.
- Specify the host name and port number of the DCCM3 logical terminal in the dchost operand of the TP1/Client/J environment definition and specify Y in the dchostselect operand.
If Y is specified for the dcrapautoconnect operand of the TP1/Client/J environment definition, execute the rpcCall method. Executing the rpcCall method automatically establishes a connection if none has been established.
If N is specified for the dcrapautoconnect operand of the TP1/Client/J environment definition or if specification is omitted, execute the openConnection method without any arguments. Executing the openConnection method without any arguments establishes a connection.
(5) TP1/Client/J environment definition example
The following figure shows an example of TP1/Client/J environment definition used for connecting to a DCCM3 server:
Figure 2-30 Issuing an RPC to a DCCM3 server
- In the TP1/Client/J environment definition, define in separate definition files the addresses (RPC-accepting gateways) of the servers that process transactions in the dchost operand.
- When an RPC is to be issued, the address of an RPC-accepting gateway is determined from the definition file and an RPC message is sent.
- The RPC message is interpreted and the requested service is executed.
- For a synchronous-response RPC, a response message from the server is received.
- Example of the definition file tran1.ini:
dcrapdirect=Y
dcwatchtim=180
dcrapautoconnect=Y
dchostselect=Y
#Defines the address of the server that can process the "TRAN1" transaction.
dchost=xxx.xxx.xxx.xxx:10020,zzz.zzz.zzz.zzz:10022
- Example of the definition file tran2.ini:
dcrapdirect=Y
dcwatchtim=180
dcrapautoconnect=Y
dchostselect=Y
#Defines the address of the server that can process the "TRAN2" transaction.
dchost=yyy.yyy.yyy.yyy:10021,zzz.zzz.zzz.zzz:10022
A program example that uses the above TP1/Client/J environment definition follows.
- Program example
import JP.co.Hitachi.soft.OpenTP1.*;
public class DCCM3Caller
{
...
public void Function1(){
TP1Client clt = new TP1Client();
// RPC that calls the TRAN1 transaction
clt.rpcOpen("tran1.ini");
...
// Synchronous-response RPC
clt.rpcCall("dummysvg", "TRAN1", ..., TP1Client.DCNOFLAGS);
...
clt.rpcClose();
// RPC that calls the TRAN2 transaction
// Reloads the definition for acquiring the request target server address.
clt.rpcOpen("tran2.ini");
...
// Non-response type RPC
clt.rpcCall("dummysvg", "TRAN2", ..., TP1Client.DCRPC_NOREPLY);
...
clt.rpcClose();
}
}
(6) Notes about issuing an RPC to a DCCM3 logical terminal
- Only RPCs that use the remote API facility can be used.
- Chained RPCs cannot be used.
- The transaction control facility cannot be used.
- Before sending or receiving a message containing character string data, the character code to be used inside the message must be agreed upon with the communication-target system, and character conversion must be carried out by a UAP if necessary. In Java, Unicode is used as the internal expression of character strings inside memory.
- Specification of the dccltinquiretime operand of the TP1/Client/J environment definition is ignored. To specify a maximum time interval from CUP to server, use DCCM3's Unattended terminal monitoring time.
- For details about notes on DCCM3 servers, see the manuals VOS3 Data Management System XDM E2 System Description and VOS1 Data Communication Management System DCCM3 Description.
All Rights Reserved. Copyright (C) 2006, 2009, Hitachi, Ltd.