Class TP1Client

setDccltinquiretime

public void setDccltinquiretime(int sec)
                         throws ErrInvalidArgsException

Sets the maximum time from one inquiry to another that is issued by a CUP to the server. This is the timer value that is monitored by the RAP-processing server. If there is no inquiry within the specified time, the RAP-processing server forcibly releases the permanent connection. You can call this method while an instance of the TP1Client class exists.

Parameter

sec: Specifies the maximum time of the inquiry interval that is to be monitored by the RAP-processing server, expressed in the range from 0 to 1048575 (seconds). If you specify 0, the RAP-processing server waits indefinitely for an inquiry from the CUP.

Return value: None.

Exception

ErrInvalidArgsException: The value specified in the sec argument is not within the range from 0 to 1048575.

setDccltdelay

public void setDccltdelay(int sec)
                   throws ErrInvalidArgsException

Sets the delay time for communication between the RAP-processing server and the CUP. By specifying this method, you can end monitoring of the maximum time to wait for a response in the RAP-processing server system early by the specified amount of time and avoid missing a message that may arrive after a timeout occurs in the CUP system.

If you specify 0 in the setDcwatchtim method as the maximum time to wait for a response, the communication delay time specified in this method is ignored. If the maximum time to wait for a response minus the RAP-processing server's communication time is 0 or a negative value, the RAP-processing server assumes 1 as the maximum time value for waiting for a response in the RAP-processing server system.

To use the value specified in this method, specify either dcwatchtiminherit=Y in the TP1/Client/J environment definition or the DRPC_WATCHTIMINHERIT argument in the setRpcextend method.

Parameter

sec: Specifies the delay time for communication between the RAP-processing server and the CUP, expressed in the range from 0 to 65535 (seconds).

Return value: None.

Exception

ErrInvalidArgsException: The value specified in the sec argument is not within the range from 0 to 65535.

setDcwatchtim

public void setDcwatchtim(int sec)
                   throws ErrInvalidArgsException

For synchronous-response RPCs, this method sets the maximum time to wait for a response from the service since a service request was sent from the CUP to the SPP. The value specified with this method is also used as the maximum time to wait for a response for internal communications of TP1/Client/J.

Parameter

sec: Specifies the maximum time to wait for a response, expressed in the range from 0 to 65535 (seconds). If you specify 0, the CUP waits for a response indefinitely. Depending on the Java environment in use, release of a TCP/IP connection may not be detected even if the server is shut down. If this value were set to 0 in such a case, the CUP would wait indefinitely for a response from the nonexistent server; for this reason, you should specify an appropriate wait time.

Return value: None.

Exception

ErrInvalidArgsException: The value specified in the sec argument is not within the range from 0 to 65535.

setDcselint

public void setDcselint(int msec)
                 throws ErrInvalidArgsException

Use of this method is not recommended. It is retained only to provide compatibility with the source of the previous version. This method serves no purpose.

setDccltextend

public void setDccltextend(int flags)

Specifies the extension level of TP1/Client/J facilities. To specify multiple extension levels, specify the disjunction of each value.

Parameter

flags: Specifies the extension level of the following facility:; 0x00000000: Does not extend the TP1/Client/J facility.; 0x00000001: Extends the TP1/Client/J facility. When the rpcCall method is called, the IP address of the local CUP is reported to the service. Specify this value if you need to obtain the address of the CUP by using the called service to execute the dc_rpc_get_callers_address() function.

Return value: None.

setRpcextend

public void setRpcextend(int extendoption)
                  throws ErrInvalidArgsException

Specifies functional extension options of RPCs that are issued from TP1/Client/J. To specify multiple extension levels of the RPC facility, specify the disjunction of each value.

Parameter

extendoption: Specifies the following extension level of the RPC facility:; DCRPC_SCD_LOAD_PRIORITY: Specifies whether or not a TP1/Server that is the gateway that accepts a service request has priority for load balancing. If this option is true, the operation is the same as when dcscdloadpriority=Y is specified in the TP1/Client/J environment definition. If this option is false, the operation is the same as when dcscdloadpriority=N is specified in the TP1/Client/J environment definition.; DCRPC_WATCHTIMINHERIT: Specifies whether or not the RAP-processing server is to inherit the CUP's maximum time to wait for a response when an RPC is issued using the remote API facility. If this option is true, the operation is the same as when dcwatchtiminherit=Y is specified in the TP1/Client/J environment definition. If this option is false, the operation is the same as when dcwatchtiminherit=N is specified in the TP1/Client/J environment definition.; DCRPC_RAP_AUTOCONNECT: Specifies whether or not TP1/Client/J is to establish connection automatically when an RPC is issued using the remote API facility. If this option is true, the operation is the same as when dcrapautoconnect=Y is specified in the TP1/Client/J environment definition. If this option is false, the operation is the same as when dcrapautoconnect=N is specified in the TP1/Client/J environment definition. This option is ignored if connection has already been established by calling the openConnection method in the non-auto connect mode.; DCRPC_WATCHTIMRPCINHERIT: Specifies whether or not the server is to inherit the CUP's maximum time to wait for a response. If this option is true, the operation is the same as when dcwatchtimrpcinherit=Y is specified in the TP1/Client/J environment definition. If this option is false, the operation is the same as when dcwatchtimrpcinherit=N is specified in the TP1/Client/J environment definition.

Return value: None.

Exception

ErrInvalidArgsException: The specified extendoption argument is invalid.

setDchost

public void setDchost(String host, int port)
               throws ErrHostUndefException,
                      ErrInvalidPortException,
                      ErrProtoException

Sets the host name and port of the TP1/Server as a gateway.

Parameters

host: Specifies the host name of the TP1/Server as a gateway. If you are issuing RPCs that use the remote API facility, specify the host name of the communication-target RAP-processing listener. If there is a firewall between the CUP and the TP1/Server, specify the host name of the firewall.

port: Specifies the port number of the scheduler server running on the TP1/Server as a gateway and the port number of the name server. If you are issuing RPCs that use the remote API facility, specify the port number of the communication-target RAP-processing listener. Express the port number in the range from 5001 to 65535.

Return value: None.

Exceptions

ErrHostUndefException: The specified host argument is invalid.

ErrInvalidPortException: The specified port argument is invalid.

ErrProtoException: The method issuance order is invalid. This method was called when an RPC was issued using the remote API facility and a permanent connection had already been established with the RAP-processing server.

setTraceArray

public void setTraceArray(String[] array)

Specifies whether or not an error trace is to be acquired in the array specified in the argument. You can call this method whether the CUP is a Java applet, application, or servlet.

Parameter

array: Specifies the String array for storing an error trace. If you specify null, error trace is not acquired.

Return value: None.

setUapTraceMode

public void setUapTraceMode(String TrcPath,
                            int size,
                            boolean flag)
                     throws ErrInvalidArgsException

Specifies whether or not a UAP trace is to be acquired when the CUP is a Java application or servlet. If the CUP is a Java applet, do not call this method.

Parameters

TrcPath: Specifies the directory in which the UAP trace is to be output. This parameter is ignored if false is specified in the flag argument.

size: Specifies the size of the UAP trace file that is to be output, in the range from 4096 to 1048576. This parameter is ignored if false is specified in the flag argument.

flag: Specifies whether or not a UAP trace is to be acquired:; true: Acquire UAP trace.; false: Do not acquire UAP trace.

Return value: None.

Exception

ErrInvalidArgsException: The specified argument is invalid.

Note: You cannot use this method with a Java applet. If used, operations cannot be guaranteed.

setMethodTraceMode

public void setMethodTraceMode(String TrcPath,
                               int size,
                               boolean flag)
                        throws ErrInvalidArgsException

Specifies whether or not a method trace is to be acquired when the CUP is a Java application or servlet. If the CUP is a Java applet, do not call this method.

Parameters

TrcPath: Specifies the directory in which the method trace is to be output. This parameter is ignored if false is specified in the flag argument.

size: Specifies the size of the method trace file that is to be output, in the range from 4096 to 1048576. This parameter is ignored if false is specified in the flag argument.

flag: Specifies whether or not a method trace is to be acquired:; true: Acquire method trace.; false: Do not acquire method trace.

Return value: None.

Exception

ErrInvalidArgsException: The specified argument is invalid.

Note: You cannot use this method with a Java applet. If used, operations cannot be guaranteed.

setDataTraceMode

public void setDataTraceMode(String TrcPath,
                             int size,
                             int DataSize,
                             boolean flag)
                      throws ErrInvalidArgsException

Specifies whether or not a data trace is to be acquired when the CUP is a Java application or servlet. If the CUP is a Java applet, do not call this method.

Parameters

TrcPath: Specifies the directory in which the data trace is to be output. This parameter is ignored if false is specified in the flag argument.

size: Specifies the size of the data trace file that is to be output, in the range from 4096 to 1048576. This parameter is ignored if false is specified in the flag argument.

DataSize: Specifies the size of the data that is to be output, in the range from 16 to 1048576. This parameter is ignored if false is specified in the flag argument.

flag: Specifies whether or not a data trace is to be acquired:; true: Acquire data trace.; false: Do not acquire data trace.

Return value: None.

Exception

ErrInvalidArgsException: The specified argument is invalid.

Note

You cannot use this method with a Java applet. If used, operations cannot be guaranteed.

setErrorTraceMode

public void setErrorTraceMode(String TrcPath,
                              int size,
                              boolean flag)
                       throws ErrInvalidArgsException

Specifies whether or not an error trace is to be acquired when the CUP is a Java application or servlet. If the CUP is a Java applet, do not call this method.

Parameters

TrcPath: Specifies the directory in which the error trace is to be output. This parameter is ignored if false is specified in the flag argument.

size: Specifies the size of the error trace file that is to be output, in the range from 4096 to 1048576. This parameter is ignored if false is specified in the flag argument.

flag: Specifies whether or not an error trace is to be acquired:; true: Acquire error trace.; false: Do not acquire error trace.

Return value: None.

Exception

ErrInvalidArgsException: The specified argument is invalid.

Note

You cannot use this method with a Java applet. If used, operations cannot be guaranteed.

rpcOpen

public void rpcOpen()
             throws ErrIOErrException,
                    ErrProtoException,
                    ErrFatalException,
                    ErrSecurityException,
                    ErrSyserrException

Initializes the environment required to call TP1/Server's SPP. To execute a CUP, you must call this method first.

Parameter: None.

Return value: None.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrProtoException: The method issuance order was invalid. The rpcOpen method was called again before the rpcClose method was called.

ErrFatalException: There is an error in a TP1/Client/J environment definition specification, or initialization of the environment for communication with TP1/Server failed.

ErrSyserrException: A system error occurred.

ErrSecurityException: A security exception occurred.

Notes

To use this method with a Java application or servlet, acquire the TP1/Client/J environment definition from the system properties.
To use this method with a Java applet, acquire the TP1/Client/J environment definition from the applet's param tag.
To use this method with a Java applet, use TP1Client(Applet app) in the constructor that instantiates the TP1Client class.

rpcOpen

public void rpcOpen(String deffilename)
             throws ErrIOErrException,
                    ErrProtoException,
                    ErrFatalException,
                    ErrSyserrException,
                    ErrInvalidArgsException,
                    ErrSecurityException

Initializes the environment for calling TP1/Server's SPP. To execute a CUP, you must call this method first.

Parameter

deffilename: Specifies the complete path name of the file that contains the TP1/Client/J environment definition.

Return value: None.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrProtoException: The method issuance order was invalid. The rpcOpen method was called again before the rpcClose method was called.

ErrFatalException: There is an error in the TP1/Client/J environment definition, or initialization of the environment for communication with TP1/Server failed.

ErrSyserrException: A system error occurred.

ErrInvalidArgsException: A specified argument is invalid.

ErrSecurityException: A security exception occurred.

Note: You cannot use this method with a Java applet. When using a Java applet, use the rpcOpen method described before this method.

rpcClose

public void rpcClose()
              throws ErrIOErrException,
                     ErrSyserrException,
                     ErrNetDownException

Releases the environment for calling TP1/Server's SPP. To call the service again for TP1/Server's SPP, call the rpcOpen method. Call this method at the end of CUP execution.

Parameter: None.

Return value: None.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrSyserrException: A system error occurred.

ErrNetDownException: A network error occurred.

openConnection

public void openConnection()
                    throws ErrIOErrException,
                           ErrHostUndefException,
                           ErrTimedOutException,
                           ErrNetDownException,
                           ErrNoBufsException,
                           ErrNotUpException,
                           ErrSyserrException,
                           ErrProtoException,
                           ErrInvalidArgsException

Establishes a permanent connection with the RAP-processing server specified by the dchost operand and dcrapport operand in the TP1/Client/J environment definition, or connects to the server (TP1/Web) that uses the OpenTP1 Web session management facility specified by the dcweburl operand, and starts a virtual session.

You cannot establish multiple concurrent permanent connections from a single CUP.

Note, also, if a firewall is located between the CUP and the RAP-processing listener to which the connection request is directed, you must specify to the target RAP-processing listener the host name and the port number of the firewall.

Parameter: None.

Return value: None. If the method does not return an exception, it has terminated normally or a permanent connection had already been established.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrHostUndefException: The host name of a RAP-processing listener is not specified in the dchost operand of the TP1/Client/J environment definition.; Another possibility is that the URL (information such as the protocol, Web server, CGI name of the prompter, or TP1/Web service name) specified in the dcweburl operand of the TP1/Client/J environment definition is invalid.

ErrTimedOutException: A timeout occurred while a connection with a RAP-processing listener was being established.; Another possibility is that a timeout occurred while a virtual session with TP1/Web was being started.

ErrNetDownException: A network error occurred during communication with a RAP-processing listener or TP1/Web.; Another possibility is that the communication target TP1/Server is not running.

ErrNoBufsException: A memory shortage occurred on the RAP-processing listener or RAP-processing server.; Another possibility is that a memory shortage occurred on TP1/Web.

ErrNotUpException: The RAP-processing listener or RAP-processing server is not running.; Another possibility is that TP1/Web is not running.

ErrSyserrException: A system error occurred.

ErrProtoException: The method issuance order was invalid. Connection had already been established, but the openConnection method was called again.

ErrInvalidArgsException: A parameter is invalid.

Note: If the connection-target RAP-processing listener is inactive, ErrIOErrException or ErrNetDownException is returned.; When this method returns an exception, the permanent connection has not been established.

openConnection

public void openConnection(String host,
                           int port)
                    throws ErrIOErrException,
                           ErrHostUndefException,
                           ErrTimedOutException,
                           ErrNoBufsException,
                           ErrNotUpException,
                           ErrSyserrException,
                           ErrInvalidPortException,
                           ErrProtoException,
                           ErrInvalidArgsException,
                           ErrNetDownException

Establishes a permanent connection between a CUP and a RAP-processing listener or server in order to issue an RPC that uses the remote API facility. The method determines the target with which permanent connection is to be established from the specified parameter values.

Parameters

host: Specifies the host name of the RAP-processing listener or firewall.

port: Specifies the port number of the RAP-processing listener or firewall, expressed in the range from 5001 to 65535.

Return value: None. If the method returns no exception, it has terminated normally or a permanent connection had already been established.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrHostUndefException: The specified host argument is invalid.

ErrTimedOutException: A timeout occurred while connection with the RAP-processing listener was being established.

ErrNoBufsException: A memory shortage occurred in the RAP-processing listener or server.

ErrNotUpException: The RAP-processing listener or server is not running.

ErrSyserrException: A system error occurred.

ErrInvalidPortException: The specified port argument is invalid.

ErrProtoException: The method issuance order was invalid. Connection had already been established, but the openConnection method was called again.

ErrInvalidArgsException: A specified argument is invalid.

ErrNetDownException: A network error occurred during communication with the RAP-processing listener, or the communication-target TP1/Server is not active.

Note: If the connection-target RAP-processing listener is inactive, ErrIOErrException or ErrNetDownException is returned. If this method returns an exception, the permanent connection has not been established.

openConnection

public void openConnection(String url,
                           short flags)
                    throws ErrIOErrException,
                           ErrHostUndefException,
                           ErrTimedOutException,
                           ErrNetDownException,
                           ErrNoBufsException,
                           ErrNotUpException,
                           ErrSyserrException,
                           ErrProtoException,
                           ErrInvalidArgsException

Connects to a server (TP1/Web) that uses the OpenTP1 Web session management facility, and starts a virtual session. Subsequently, communication services based on the HTTP protocol can be performed.

Parameters

url: Specifies the protocol, Web server, CGI name of the prompter, TP1/Web service name, and other information in the syntax of a URL.

flags: Specifies DCSESSION.

Return value: None

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrHostUndefException: The URL (protocol, Web server, CGI name of the prompter, TP1/Web service name, and other information) specified by the url parameter is invalid.

ErrTimedOutException: A timeout occurred while the virtual session with TP1/Web was starting.

ErrNetDownException: A network error occurred.

ErrNoBufsException: A memory shortage occurred on TP1/Web.

ErrNotUpException: TP1/Web is not running.

ErrSyserrException: A system error occurred.

ErrProtoException: The issuing sequence of the method is invalid.; dcrapautoconnect=Y or dcrapdirect=N was specified in the TP1/Client/J environment definition when a permanent connection had already been established with a RAP-processing server.

ErrInvalidArgsException: A parameter specification is invalid.

closeConnection

public void closeConnection()
                     throws ErrIOErrException,
                            ErrSyserrException,
                            ErrProtoException,
                            ErrTimedOutException,
                            ErrNetDownException

Releases the permanent connection between the CUP and the RAP-processing listener or server.

Parameter: None.

Return value: None.

Exceptions

ErrIOErrException: An I/O exception occurred.

ErrSyserrException: A system error occurred.

ErrProtoException: The method issuance order was invalid. The connection had already been released, but the closeConnection method was called again.

ErrTimedOutException: A timeout occurred while a virtual session with TP1/Web or a connection with the RAP-processing listener or RAP-processing server was being released.

ErrNetDownException: A network error occurred during communication with the RAP-processing listener.

Note: Even if this method returns an exception, the permanent connection has been released.

rpcCall

public void rpcCall(String group,
                    String service,
                    byte[] in_data,
                    int[] in_len,
                    byte[] out_data,
                    int[] out_len,
                    int flags)
             throws ErrInvalidArgsException,
                    ErrProtoException,
                    ErrNoBufsException,
                    ErrNetDownException,
                    ErrTimedOutException,
                    ErrMessageTooBigException,
                    ErrReplyTooBigException,
                    ErrNoSuchServiceGroupException,
                    ErrNoSuchServiceException,
                    ErrServiceClosedException,
                    ErrServiceTerminatingException,
                    ErrServiceNotUpException,
                    ErrNotUpException,
                    ErrSyserrAtServerException,
                    ErrSyserrException,
                    ErrNoBufsAtServerException,
                    ErrInvalidReplyException,
                    ErrInitializingException,
                    ErrTrnchkException,
                    ErrServerBusyException,
                    ErrSecchkException,
                    ErrServiceTerminatedException,
                    ErrIOErrException,
                    ErrTestmodeException,
                    ErrConnfreeException,
                    ErrHostUndefException,
                    ErrInvalidPortException

Issues an SPP service request. This method calls the service function that is identified by the service group name and service name and receives its response. If the specified service group is shut down when this method is called, the method returns ErrServiceClosedException.

By specifying DCRPC_TPNOTRAN in the flags argument, you can treat an RPC from transaction processing as a service request that is not transaction processing.

If the specified service group is under termination processing by a command such as dcsvstop or has already been terminated when this method is called, ErrServiceTerminatingException, ErrServiceClosedException, or ErrNoSuchServiceGroupException is returned. The actual exception that is returned depends on the timing of this method call.

The server that receives requests from a socket uses the values of the max_socket_msg and max_socket_msglen operands in the user service definition to execute congestion control on messages. Therefore, the server may not be able to receive service requests. In such a case, calling the method returns ErrServerBusyException. When this exception is returned, you may be able to issue a service request by calling this method again after waiting a while.

Parameters

group: Specifies the service group name, expressed as an identifier of a maximum of 31 characters.

service: Specifies the service name, expressed as an identifier of a maximum of 31 characters.

in_data: Specifies input parameters for the service.

in_len: Specifies the length of the input parameter for the service, in the range from 1 to the value of DCRPC_MAX_MESSAGE_SIZE.^# Store the length of the input parameter in in_len[0].; #; When the dccltrpcmaxmsgsize operand is used, the size of the input parameter response area is the value specified by the dccltrpcmaxmsgsize operand rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

out_data: Specifies the area in which the response specified in the service function is to be returned.; For a non-response type RPC, specify null. Even if a non-null value is specified for a non-response type RPC, nothing will be stored.

out_len: Specifies the length of the service's response, expressed in the range from 1 to the value of DCRPC_MAX_MESSAGE_SIZE^#. Store the length of the response in out_len[0].; When the service request is terminated, the length of the response specified in the service function of the SPP is set in out_len[0].; For a non-response type RPC, the length of response is ignored, if specified, in which case nothing is set in out_len[0] when the service request is terminated.; #; When the dccltrpcmaxmsgsize operand is used, the length of the service's response is the value specified by the dccltrpcmaxmsgsize operand rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

flags

Specifies one of the following flags as the RPC mode:

DCNOFLAGS: Synchronous-response RPC

DCRPC_NOREPLY: Non-response type RPC

DCRPC_CHAINED: Chained RPC

DCRPC_TPNOTRAN: RPC that does not inherit transactions

If you specify DCNOFLAGS or DCRPC_CHAINED, the method does not return control until the server returns a response, or the maximum time to wait for a response specified in the dcwatchtim operand of the TP1/Client/J environment definition is reached and a timeout occurs. If the SPP to which the service request was issued terminates abnormally, the method returns an exception immediately. In this case, the exception returned by the method depends on the value of the dcwatchtim operand specified in the TP1/Client/J environment definition:

When a value in the range from 1 to 65535 is specified
ErrTimedOutException
When 0 is specified
ErrServiceNotUpException

If DCRPC_NOREPLY is specified, the method assumes that the requested service does not return a response. In such a case, the method returns control immediately without waiting for the service to end its execution. When you specify this flag, you cannot reference the response (value specified in the out_data argument) or the length of the response (value specified in the out_len argument). Additionally, the CUP cannot determine whether or not the service function was executed.

If DCRPC_CHAINED is specified and a service belonging to the same service group is requested more than once, the same process as for the first request is used for execution.

When a chained RPC is used, the following limitations apply:

The second or subsequent call to this method cannot detect a shutdown of the user server or service.
If an error occurs in service function processing during the second or subsequent call to this method, the entire user server is shut down, not just the applicable service.
If you use the remote API facility, you can specify DCRPC_CHAINED in the flags parameter.
In the case of a chained RPC, use one of the following methods to terminate it:
Execute the rpcCall method specifying DCNOFLAGS in the flags parameter (synchronous-response RPC) on the service group that is executing the chained RPC.^#
Complete the global transaction executing the chained RPC by synchronization point processing (commit or rollback).
#
If you call the closeConnection or rpcClose method without executing a synchronous-response RPC, the API of TP1/Client/J terminates normally, but the following status results:
Outside the global transaction range
The process executing the service is locked until a chained RPC timeout occurs.
Within the global transaction range
Implicit commit occurs and the chained RPC is terminated.

By specifying DCRPC_TPNOTRAN, you can treat an RPC from transaction processing as a service request that is not transaction processing. You can specify DCRPC_TPNOTRAN only from transaction processing. You can specify DCRPC_TPNOTRAN with DCNOFLAGS, DCRPC_NOREPLY, or DCRPC_CHAINED.

Example: flags = TP1Client.DCNOFLAGS|TP1Client.DCRPC_TPNOTRAN;

Return value: None.

Exceptions

ErrInvalidArgsException: A specified argument is invalid. In this case, the invalid argument name is set in the detail message.

ErrProtoException: The method issuance order was invalid. The openConnection method has not been called.

ErrNoBufsException: A memory shortage occurred.

ErrNetDownException: A network error occurred, or the communication-target TP1/Server is not active.

ErrTimedOutException: A timeout occurred in this method processing, or the SPP whose service was requested terminated abnormally before completing the processing.

ErrMessageTooBigException: The length of input parameters specified in the in_len argument exceeds the maximum value.

ErrReplyTooBigException: The response returned form the server is larger than the area provided by the CUP (value specified for the out_data argument).

ErrNoSuchServiceGroupException: The service group name specified in the group argument is undefined.

ErrNoSuchServiceException: The service name specified in the service argument is undefined.

ErrServiceClosedException: The service group containing the service name specified in the service argument is shut down.

ErrServiceTerminatingException: The service specified in the service argument is under termination processing.

ErrServiceNotUpException: The SPP specified in the service request has not started, or the SPP specified in the service request terminated abnormally before completing its processing. This exception is returned when dcwatchtim=0 is specified (to wait for a response indefinitely) in the TP1/Client/J environment definition.

ErrNotUpException: The TP1/Server is not active at the node that contains the specified service. In this case, the TP1/Server may have terminated abnormally, may have been shut down, may be under termination processing, or a network error may have occurred.

ErrSyserrAtServerException: A system error occurred in the specified service.

ErrSyserrException: A system error occurred.

ErrNoBufsAtServerException: A memory shortage occurred in the specified service.

ErrInvalidReplyException: The length of the response returned from the service function is not within the range from 1 to the value specified for DCRPC_MAX_MESSAGE_SIZE^#.; #; When the dccltrpcmaxmsgsize operand is used, the value specified in the dccltrpcmaxmsgsize operand is used rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

ErrInitializingException: The TP1/Server at the node specified in the service request is under start processing.

ErrTrnchkException: In the environment using the inter-node load-balancing facility, the transaction attributes of multiple SPPs do not match. Alternatively, the inter-node load-balancing facility cannot be executed because the version of the TP1/Server at the target node is older than the TP1/Client/J version. This exception is returned only when a service request is issued to the SPP using the inter-node load-balancing facility.

ErrServerBusyException: The target server that receives requests from a socket cannot receive service requests.

ErrSecchkException: The SPP to which the service request was issued is protected by the security facility. The CUP that called the rpcCall method does not have access authority to the SSP.

ErrServiceTerminatedException: The SPP specified in the service request terminated abnormally before completing the processing. This exception is returned only when 00000001 is specified in the rpc_extend_function operand of the RAP-processing listener service definition. If you specified 00000000 in the rpc_extend_function operand or omitted the operand, ErrTimedOutException or ErrServiceNotUpException is returned.

ErrIOErrException: An I/O exception occurred. The RAP-processing server may have timed out while monitoring the inquiry interval and released the connection.

ErrTestmodeException: A service request was issued to an SPP in the test mode.

ErrConnfreeException: The permanent connection with the RAP-processing server was released. Another possibility is that the virtual session with TP1/Web ended.

ErrHostUndefException

Possible causes are as follows:

Either the host name of the communication target TP1/Server is not specified in the dchost operand of the TP1/Client/J environment definition, or the specification is invalid.
The URL (protocol, Web server, CGI name of the prompter, TP1/Web service name, and other information) specified in the dcweburl operand of the TP1/Client environment definition is invalid.

ErrInvalidPortException

Possible causes are as follows:

An RPC was issued using the remote API facility, but the dcrapport operand was not specified in the TP1/Client/J environment definition.
An RPC was issued using the scheduler direct facility, but the dcscdport operand was not specified in the TP1/Client/J environment definition.

Notes

Do not specify the same area for the input parameters (value of the in_data argument) and for the service function's response (value of the out_data argument).
If you specify DCRPC_NOREPLY in the flags argument, the following exceptions will not be returned:

Exceptions that will not occur:

ErrReplyTooBigException
ErrInvalidReplyException

Exceptions that cannot be detected, if thrown:

ErrNoSuchServiceException
ErrServiceClosedException
ErrServiceTerminatingException
ErrSyserrAtServerException
ErrNoBufsAtServerException
ErrNotUpException

The possible causes of ErrTimedOutException are as follows:
- The maximum time to wait for a response specified in the TP1/Client/J environment definition or TP1/Server definition is too short.
- The service function issued by the target SPP terminated abnormally.
- An error occurred at the node that contains the target SPP.
- The target SPP terminated abnormally before completing its processing.
- A network error occurred.
If any of these events occurs, the transaction started by the target SPP may have been committed and the database may have been updated. Check to see if the database has been updated.
If an error occurs when this method is called, an exception is returned, but whether or not the permanent connection with the RAP-processing listener or server was released as a result of the error cannot be determined at this point. If the permanent connection with the RAP-processing listener or server has in fact been released, calling this method again returns ErrConnfreeException.
If the permanent connection with the RAP-processing listener or server is released as a result of an error when this method is called, you need to call the openConnection method again to establish permanent connection with the RAP-processing listener or server.
In the case of a permanent connection while the auto connect mode is in effect, if a network error occurs in communication with the RAP-processing server during transmission of the service request, the method retries only once. If the connection is not established by this retry, the method returns ErrNetDownException.
In the case of an RPC that uses the scheduler direct facility or name service, you cannot specify DCRPC_CHAINED in the flags argument. If you use the remote API facility, you can specify DCRPC_CHAINED in the flags parameter.

rpcCall

public void rpcCall(String group,
                    String service,
                    byte[] in_data,
                    byte[] out_data,
                    int flags)
             throws ErrInvalidArgsException,
                    ErrProtoException,
                    ErrNoBufsException,
                    ErrNetDownException,
                    ErrTimedOutException,
                    ErrMessageTooBigException,
                    ErrReplyTooBigException,
                    ErrNoSuchServiceGroupException,
                    ErrNoSuchServiceException,
                    ErrServiceClosedException,
                    ErrServiceTerminatingException,
                    ErrServiceNotUpException,
                    ErrNotUpException,
                    ErrSyserrAtServerException,
                    ErrSyserrException,
                    ErrNoBufsAtServerException,
                    ErrInvalidReplyException,
                    ErrInitializingException,
                    ErrTrnchkException,
                    ErrServerBusyException,
                    ErrSecchkException,
                    ErrServiceTerminatedException,
                    ErrIOErrException,
                    ErrTestmodeException,
                    ErrConnfreeException,
                    ErrHostUndefException,
                    ErrInvalidPortException

By specifying DCRPC_TPNOTRAN in the flags argument, you can treat an RPC from transaction processing as a service request that is not transaction processing.

The server that receives requests from a socket uses the values of the max_socket_msg and max_socket_msglen operands in the user service definition to execute congestion control on messages. Therefore, the server may not be able to receive service requests. In such a case, calling the method returns ErrServerBusyException. If this exception is returned, you may be able to issue a service request by calling this method again after waiting a while.

Parameters

group: Specifies the service group name, expressed as an identifier of a maximum of 31 characters.

service: Specifies the service name, expressed as an identifier of a maximum of 31 characters.

in_data: Specifies input parameters for the service.

out_data: Specifies the area in which the response specified in the service function is to be returned.; For a non-response type RPC, specify null. Even if a non-null value is specified for a non-response type RPC, nothing will be stored.

flags

Specifies one of the following flags as the RPC mode:

DCNOFLAGS: Synchronous-response RPC

DCRPC_NOREPLY: Non-response type RPC

DCRPC_CHAINED: Chained RPC

DCRPC_TPNOTRAN: RPC that does not inherit transactions

If you specify DCNOFLAGS or DCRPC_CHAINED, the method does not return control until the server returns a response, or the maximum time to wait for a response specified in the dcwatchtim operand of the TP1/Client/J environment definition is reached and a timeout occurs. If the SPP to which the service request was issued terminates abnormally, the method returns an exception immediately. In this case, the exception returned by the method depends on the maximum time to wait for a response that was specified in the dcwatchtim operand of the TP1/Client/J environment definition:

When a value in the range from 1 to 65535 is specified
ErrTimedOutException
When 0 is specified
ErrServiceNotUpException

If DCRPC_NOREPLY is specified, the method assumes that the requested service does not return a response. In such a case, the method returns control immediately without waiting for the service to end its execution. When you specify this flag, you cannot reference the response (value specified in the out_data argument) or the response length (value specified in the out_len argument). Additionally, the CUP cannot determine whether or not the service function was executed.

If DCRPC_CHAINED is specified and a service belonging to the same service group is requested more than once, the same process as for the first request is used for execution.

When a chained RPC is used, the following limitations apply:

The second or subsequent call to this method cannot detect a shutdown of the user server or service.
If an error occurs in service function processing during the second or subsequent call to this method, the entire user server is shut down, not just the applicable service.
If you specified DCRPC_CHAINED in the flags argument to call a service, execute an RPC specifying DCNOFLAGS during the last service request. If you call the closeConnection method without specifying DCNOFLAGS during the last service request, the method returns ErrTimedOutException or some other exception. The process executing the service is locked until a timeout occurs in the chained RPCs.
If you use the remote API facility, you can specify DCRPC_CHAINED in the flags parameter.
In the case of a chained RPC, use one of the following methods to terminate it:
Execute the rpcCall method specifying DCNOFLAGS in the flags parameter (synchronous-response RPC) on the service group that is executing the chained RPC.^#
Complete the global transaction executing the chained RPC by synchronization point processing (commit or rollback).
#
If you call the closeConnection or rpcClose method without executing a synchronous-response RPC, the API of TP1/Client/J terminates normally, but the following status results:
Outside the global transaction range
The process executing the service is locked until a chained RPC timeout occurs.
Within the global transaction range
Implicit commit occurs and the chained RPC is terminated.

By specifying DCRPC_TPNOTRAN, you can treat an RPC from transaction processing as a service request that is not transaction processing. You cannot specify DCRPC_TPNOTRAN from processing outside the transaction. You can specify DCRPC_TPNOTRAN with DCNOFLAGS, DCRPC_NOREPLY, or DCRPC_CHAINED.

Example: flags = TP1Client.DCNOFLAGS|TP1Client.DCRPC_TPNOTRAN;

Return value: None.

Exceptions

ErrInvalidArgsException: A specified argument is invalid. In this case, the invalid argument name is set in the detail message.

ErrProtoException: The method issuance order was invalid. The openConnection method has not been called.

ErrNoBufsException: A memory shortage occurred.

ErrNetDownException: A network error occurred, or the communication-target TP1/Server is not active.

ErrTimedOutException: A timeout occurred in this method processing, or the SPP whose service was requested terminated abnormally before completing the processing.

ErrMessageTooBigException: The input parameters length specified in the in_len argument exceeds the maximum value.

ErrReplyTooBigException: The response returned form the server is larger than the area provided by the CUP (value specified for the out_data argument).

ErrNoSuchServiceGroupException: The service group name specified in the group argument is undefined.

ErrNoSuchServiceException: The service name specified in the service argument is undefined.

ErrServiceClosedException: The service group containing the service name specified in the service argument is shut down.

ErrServiceTerminatingException: The service specified in the service argument is under termination processing.

ErrServiceNotUpException: The SPP specified in the service request has not started, or the SPP specified in the service request terminated abnormally before completing its processing. This exception is returned when dcwatchtim=0 is specified (to wait for a response indefinitely) in the TP1/Client/J environment definition.

ErrNotUpException: The TP1/Server is not active at the node that contains the specified service. In this case, the TP1/Server may have terminated abnormally, may have been shut down, may be under termination processing, or a network error may have occurred.

ErrSyserrAtServerException: A system error occurred in the specified service.

ErrSyserrException: A system error occurred.

ErrNoBufsAtServerException: A memory shortage occurred in the specified service.

ErrInvalidReplyException: The length of the response returned from the service function is not within the range from 1 to the value specified for DCRPC_MAX_MESSAGE_SIZE^#.; #; When the dccltrpcmaxmsgsize operand is used, the value specified in the dccltrpcmaxmsgsize operand is used rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

ErrInitializingException: The TP1/Server at the node specified in the service request is under start processing.

ErrTrnchkException: In the environment using the inter-node load-balancing facility, the transaction attributes of multiple SPPs do not match, or the inter-node load-balancing facility cannot be executed because the version of the TP1/Server at the target node is older than the TP1/Client/J version. This exception is returned only when a service request is issued to the SPP using the inter-node load-balancing facility.

ErrServerBusyException: The target server that receives requests from a socket cannot receive service requests.

ErrSecchkException: The SPP to which the service request was issued is protected by the security facility. The CUP that called the rpcCall method does not have access authority to the SSP.

ErrServiceTerminatedException: The SPP specified in the service request terminated abnormally before completing the processing. This exception is returned only when 00000001 is specified in the rpc_extend_function operand of the RAP-processing listener service definition. If you specified 00000000 in the rpc_extend_function operand or omitted the operand, ErrTimedOutException or ErrServiceNotUpException is returned.

ErrIOErrException: An I/O exception occurred. The RAP-processing server may have timed out while monitoring the inquiry interval and released the connection.

ErrTestmodeException: A service request was issued to an SPP in the test mode.

ErrConnfreeException: The permanent connection with the RAP-processing server was released. Another possibility is that the virtual session with TP1/Web ended.

ErrHostUndefException

Possible causes are as follows:

Either the host name of the communication target TP1/Server is not specified in the dchost operand of the TP1/Client/J environment definition, or the specification is invalid.
The URL (protocol, Web server, CGI name of the prompter, TP1/Web service name, and other information) specified in the dcweburl operand of the TP1/Client/J environment definition is invalid.

ErrInvalidPortException

Possible causes are as follows:

An RPC was issued using the remote API facility, but the dcrapport operand was not specified in the TP1/Client/J environment definition.
An RPC was issued using the scheduler direct facility, but the dcscdport operand was not specified in the TP1/Client/J environment definition.

Notes

Do not specify the same area for the input parameters (value of the in_data argument) and for the response of the service function (value of the out_data argument).
If you specify DCRPC_NOREPLY in the flags argument, the following exceptions will not be returned:

Exceptions that will not occur:

ErrReplyTooBigException
ErrInvalidReplyException

Exceptions that cannot be detected, if thrown:

ErrNoSuchServiceException
ErrServiceClosedException
ErrServiceTerminatingException
ErrSyserrAtServerException
ErrNoBufsAtServerException
ErrNotUpException

The possible causes of ErrTimedOutException are as follows:
- The maximum time to wait for a response specified in the TP1/Client/J environment definition or TP1/Server definition is too short.
- The service function issued by the target SPP terminated abnormally.
- An error occurred at the node that contains the target SPP.
- The target SPP terminated abnormally before completing its processing.
- A network error occurred.
If any of these events occurs, the transaction started by the target SPP may have been committed and the database may have been updated. Check to see whether or not the database has been updated.
If an error occurs when this method is called, an exception is returned, but whether or not the permanent connection with the RAP-processing listener or server was released as a result of the error cannot be determined at this point. If the permanent connection with the RAP-processing listener or server has in fact been released, calling this method again returns ErrConnfreeException.
If the permanent connection with the RAP-processing listener or server is released as a result of an error when this method is called, you need to call the openConnection method again to establish permanent connection with the RAP-processing listener or server.
In the case of a permanent connection when the auto connect mode is being used, if a network error occurs in communication with the RAP-processing server during transmission of the service request, the method retries only once. If the connection is not established by this retry, the method returns ErrNetDownException.
In the case of an RPC that uses the scheduler direct facility or name service, you cannot specify DCRPC_CHAINED in the flags argument. If you use the remote API facility, you can specify DCRPC_CHAINED in the flags parameter.

rpcCallTo

public void rpcCallTo(DCRpcBindTbl direction,
                    String group,
                    String service,
                    byte[] in_data,
                    int[] in_len,
                    byte[] out_data,
                    int[] out_len,
                    int flags)
             throws ErrInvalidArgsException,
                    ErrProtoException,
                    ErrNoBufsException,
                    ErrNetDownException,
                    ErrTimedOutException,
                    ErrMessageTooBigException,
                    ErrReplyTooBigException,
                    ErrNoSuchServiceGroupException,
                    ErrNoSuchServiceException,
                    ErrServiceClosedException,
                    ErrServiceTerminatingException,
                    ErrServiceNotUpException,
                    ErrNotUpException,
                    ErrSyserrAtServerException,
                    ErrSyserrException,
                    ErrNoBufsAtServerException,
                    ErrInvalidReplyException,
                    ErrInitializingException,
                    ErrTrnchkException,
                    ErrServerBusyException,
                    ErrSecchkException,
                    ErrServiceTerminatedException,
                    ErrIOErrException,
                    ErrTestmodeException,
                    ErrConnfreeException,
                    ErrHostUndefException,
                    ErrInvalidPortException

Similarly to the rpcCall method, this method issues an SPP service request. The rpcCallTo method uses a host name in addition to a service group name and service name as the search key for determining the target service function.

Before calling this method, you need to call the setScdDirectObject method and create a DCRpcBindTbl instance. The other interfaces are the same as for the rpcCall method.

Parameters

direction: Specifies the DCRpcBindTbl object. Before calling this method, call the setScdDirectObject method to set the communication-target information.

group: Specifies the service group name, expressed as an identifier of a maximum of 31 characters.

service: Specifies the service name, expressed as an identifier of a maximum of 31 characters.

in_data: Specifies input parameters for the service.

in_len: Specifies the length of the input parameter for the service, in the range from 1 to the value of DCRPC_MAX_MESSAGE_SIZE.^# Store the length of the input parameter in in_len[0].; #; When the dccltrpcmaxmsgsize operand is used, the size of the input parameter response area is the value specified by the dccltrpcmaxmsgsize operand rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

out_data: Specifies the area in which the response specified in the service function is to be returned.; For a non-response type RPC, specify null. Even if a non-null value is specified for a non-response type RPC, nothing will be stored.

out_len: Specifies the length of the service's response, expressed in the range from 1 to the value of DCRPC_MAX_MESSAGE_SIZE^#. Store the length of the response in out_len[0].; #; When the dccltrpcmaxmsgsize operand is used, the length of the service's response is the value specified by the dccltrpcmaxmsgsize operand rather than the value specified in DCRPC_MAX_MESSAGE_SIZE.

flags: Specifies one of the following flags as the RPC mode:; DCNOFLAGS: Synchronous-response RPC; DCRPC_NOREPLY: Non-response type RPC

Return value: None.

Exception: Exceptions are the same as for the rpcCall method.

Notes

If you issue a service request to a user server that receives requests from a socket, this method returns ErrServiceNotUpException.
The version of the target TP1/Server whose service is requested must be 03-03 or later. If a service request is issued to an earlier version of TP1/Server, operations cannot be guaranteed.
This method is not applicable to an RPC that uses the remote API facility. If this method is issued when the remote API facility is used, the method returns ErrProtoException.
This method is not applicable to a chained RPC. If you specify DCRPC_CHAINED in the flags argument, this method returns ErrInvalidArgsException.
During a call to the rpcCallTo method, the following operands in the TP1/Client/J environment definition are not referenced:
- dchost
- dcscdport
- dcnamport
- dcscdloadpriority
Neither the host name nor the port number specified in the setDchost method is referenced. The specified values take effect the next time the rpcCall method is called.
If the specified target host name is invalid, this method returns ErrHostUndefException.
If the specified target port number is invalid, this method returns ErrInvalidPortException.

setScdDirectObject

public DCRpcBindTbl setScdDirectObject(String scdhost,
                                      int scdport,
                                      int flags)

Sets the host name and port number of the communication-target scheduler.

Parameters

scdhost: Specifies the host name of the communication-target schedule server. If the specified host name is invalid or NULL is specified, the rpcCallTo method that is called after this method returns ErrHostUndefException.

scdport: Specifies the port number of the communication-target schedule server. Express the port number in the range from 5001 to 65535. If the specified port number is invalid, the rpcCallTo method that is called after this method returns ErrInvalidPortException.

flags: Specifies DCNOFLAGS.

Return value: DCRpcBindTbl object

trnBegin

public void trnBegin()
             throws ErrProtoException,
                    ErrTMException,
                    ErrRMException,
                    ErrNoBufsException,
                    ErrNotUpException,
                    ErrTimedOutException,
                    ErrIOErrException,
                    ErrConnfreeException,
                    ErrSyserrException,
                    ErrNetDownException,
                    ErrHostUndefException,
                    ErrInvalidPortException

Starts a global transaction from the TP1Client object that calls the trnBegin method.

This method is applicable only when the remote API facility is used and the version of the target TP1/Server Base is 05-00 or later.

Parameter: None.

Return value: None.

Exceptions

ErrProtoException: The trnBegin method was called from an invalid context.

ErrTMException: The method was unable to start the transaction because an error occurred in the transaction service. When this exception is returned, calling this method again after waiting a while may start the transaction successfully.

ErrRMException: An error occurred in the resource manager. The transaction was not started.

ErrNoBufsException: A memory shortage occurred.

ErrNotUpException: TP1/Server is not active.

ErrTimedOutException: A timeout occurred.

ErrIOErrException: An I/O exception occurred.

ErrConnfreeException: The permanent connection was released from the CUP executing process.

ErrSyserrException: A system error occurred.

ErrNetDownException: A network error occurred.

ErrHostUndefException: Either the host name of the communication target TP1/Server is not specified in the dchost operand of the TP1/Client/J environment definition, or the specification is invalid.

ErrInvalidPortException: The communication-target port is invalid or has not been set.

trnChainedCommit

public void trnChainedCommit()
             throws ErrProtoException,
                    ErrRollbackException,
                    ErrHeuristicException,
                    ErrHazardException,
                    ErrNoBeginException,
                    ErrRollbackNoBeginException,
                    ErrHeuristicNoBeginException,
                    ErrHazardNoBeginException,
                    ErrNoBufsException,
                    ErrNotUpException,
                    ErrTimedOutException,
                    ErrIOErrException,
                    ErrConnfreeException,
                    ErrNetDownException,
                    ErrSyserrException

Acquires a transaction synchronization point.

When the trnChainedCommit method terminates normally, a new global transaction occurs and the subsequent methods that are executed belong to the range of the new global transaction.

Parameter: None.

Return value: None.

Exceptions

ErrProtoException: The trnChainedCommit method was called from an invalid context.

ErrRollbackException: The current transaction was rolled back without being committed. Even after this exception is returned, this process is still under the transaction and within the range of the global transaction.

ErrHeuristicException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_chained_commit function were committed and some were rolled back. This exception is returned when the result of heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Even after this exception is returned, this process is still under the transaction and within the range of the global transaction.

ErrHazardException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Even after this exception is returned, this process is still under the transaction and within the range of the global transaction.

ErrNoBeginException: Commit or rollback processing terminated normally, but the method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrRollbackNoBeginException: The transaction that was to be committed was rolled back without being committed. The method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrHeuristicNoBeginException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_chained_commit function were committed and some were rolled back. This exception is returned when the result of the heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. The method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrHazardNoBeginException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. The method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrNoBufsException: A memory shortage occurred.

ErrNotUpException: TP1/Server is not active.

ErrTimedOutException: A timeout occurred.

ErrIOErrException: An I/O exception occurred.

ErrConnfreeException: The permanent connection was released from the CUP executing process.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

trnChainedRollback

public void trnChainedRollback()
             throws ErrProtoException,
                    ErrHeuristicException,
                    ErrHazardException,
                    ErrNoBeginException,
                    ErrHeuristicNoBeginException,
                    ErrHazardNoBeginException,
                    ErrNoBufsException,
                    ErrNotUpException,
                    ErrTimedOutException,
                    ErrIOErrException,
                    ErrConnfreeException,
                    ErrNetDownException,
                    ErrSyserrException

Rolls back a transaction.

When the trnChainedRollback method terminates normally, a new global transaction occurs and the subsequent methods that are called belong to the range of the new global transaction.

Parameter: None.

Return value: None.

Exceptions

ErrProtoException: The trnChainedRollback method was called from an invalid context.

ErrHeuristicException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_chained_rollback function were committed and some were rolled back. This exception is returned when the result of the heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Even after this exception is returned, this process is still under the transaction and within the range of the global transaction.

ErrHazardException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Even after this exception is returned, this process is still under the transaction and within the range of the global transaction.

ErrNoBeginException: Commit or rollback processing terminated normally, but the method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrHeuristicNoBeginException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_chained_rollback function were committed and some were rolled back. This exception is returned when the result of the heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. The method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrHazardNoBeginException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. The method was unable to start a new transaction. Once this exception has been returned, this process is no longer under the transaction.

ErrNoBufsException: A memory shortage occurred.

ErrNotUpException: TP1/Server is not active.

ErrTimedOutException: A timeout occurred.

ErrIOErrException: An I/O exception occurred.

ErrConnfreeException: The permanent connection was released from the CUP executing process.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

trnUnchainedCommit

public void trnUnchainedCommit()
             throws ErrProtoException,
                    ErrRollbackException,
                    ErrHeuristicException,
                    ErrHazardException,
                    ErrNoBufsException,
                    ErrNotUpException,
                    ErrTimedOutException,
                    ErrIOErrException,
                    ErrConnfreeException,
                    ErrNetDownException,
                    ErrSyserrException

Acquires a transaction synchronization point.

When the trnUnchainedCommit method terminates normally, the global transaction ends. You cannot execute an SPP as a transaction from outside the range of the global transaction.

Parameter: None.

Return value: None.

Exceptions

ErrProtoException: The trnUnchainedCommit method was called from an invalid context.

ErrRollbackException: The current transaction was rolled back without being committed. The process is outside the range of the transaction.

ErrHeuristicException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_unchained_commit function were committed and some were rolled back. This exception is returned when the result of the heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Once this exception has been returned, this process is no longer under the transaction. The process is outside the range of the global transaction.

ErrHazardException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Once this exception has been returned, this process is no longer under the transaction. The process is outside the range of the global transaction.

ErrNoBufsException: A memory shortage occurred.

ErrNotUpException: TP1/Server is not active.

ErrTimedOutException: A timeout occurred.

ErrIOErrException: An I/O exception occurred.

ErrConnfreeException: The permanent connection was released from the CUP executing process.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

trnUnchainedRollback

public void trnUnchainedRollback()
             throws ErrProtoException,
                    ErrHeuristicException,
                    ErrHazardException,
                    ErrNoBufsException,
                    ErrNotUpException,
                    ErrTimedOutException,
                    ErrIOErrException,
                    ErrConnfreeException,
                    ErrNetDownException,
                    ErrSyserrException

Rolls back a transaction.

When the trnUnchainedRollback method is called, the global transaction ends. You cannot execute an SPP as a transaction from outside the range of the global transaction.

Parameter: None.

Return value: None.

Exceptions

ErrProtoException: The trnUnchainedRollback method was called from an invalid context.

ErrHeuristicException: For heuristic determination purposes, some of the transaction branches in the global transaction that executed the dc_trn_unchained_rollback function were committed and some were rolled back. This exception is returned when the result of the heuristic determination does not match the result of the synchronization point of the global transaction. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Once this exception has been returned, this process is no longer under the transaction. The process is outside the range of the global transaction.

ErrHazardException: A transaction branch of the global transaction was completed heuristically. However, the result of the synchronization point of the transaction branch that was completed heuristically was unknown due to an error. For the result of the synchronization point of the global transaction, resource manager, and UAP that caused this exception, see TP1/Server's message log file. Once this exception has been returned, this process is no longer under the transaction. The process is outside the range of the global transaction.

ErrNoBufsException: A memory shortage occurred.

ErrNotUpException: TP1/Server is not active.

ErrTimedOutException: A timeout occurred.

ErrIOErrException: An I/O exception occurred.

ErrConnfreeException: The permanent connection was released from the CUP executing process.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

trnInfo

public boolean trnInfo()

Reports whether or not the TP1Client object that called the trnInfo method is currently running as a transaction. This method only references internal variables; it does not communicate with the RAP-processing server.

Parameter: None.

Return value

true: The TP1Client object that called the trnInfo method is within the range of a transaction.

false: The TP1Client object that called the trnInfo method is outside the range of a transaction.

Exception: None.

getTrnID

public void getTrnID(byte[] gid,byte[] bid)
             throws ErrInvalidArgsException,
                    ErrProtoException

Acquires the current transaction global identifier and transaction branch identifier. This method only references internal variables; it does not communicate with the RAP-processing server.

The current transaction global identifier and transaction branch identifier were assigned by TP1/Server when the following methods were called and a transaction was started:

trnBegin method
trnChainedCommit method
trnChainedRollback method

Parameter

gid: Specifies a minimum of 16 bytes of the byte type array that stores the transaction global identifier.

bid: Specifies a minimum of 16 bytes of the byte type array that stores the transaction branch identifier.

Return value: None.

Exceptions

ErrInvalidArgsException: A specified argument is invalid.

ErrProtoException: The getTrnID method was called from an invalid context.

cltReceive

public void cltReceive(byte[]  buff,
                       int[]   recvleng,
                       int     timeout,
                       int     flags)
                throws ErrInvalidArgsException,
                       ErrProtoException,
                       ErrNetDownException,
                       ErrTimedOutException,
                       ErrSyserrException,
                       ErrInvalidPortException,
                       ErrConnfreeException

Receives a message sent from an MHP.

Before executing the cltReceive method, you must have specified either DCCLT_ONEWAY_RCV or DCCLT_SNDRCV in the dcsndrcvtype operand of the TP1/Client/J environment definition, and executed the rpcOpen method.

Parameters

buff: Specifies the area in which to store the received message. Make sure to specify an area that is at least the size specified in recvleng. The received message is returned after the method finishes executing.

recvleng: Specifies the length of the message to be received in recvleng[0]. The length of the received message is returned after the method finishes executing.

timeout: Specifies the maximum wait time when a message is being received, expressed as an integer from -1 to 65535 in units of seconds.; If you specify -1, cltReceive waits until the message is received without any timeout limitations.; If you specify 0, cltReceive does not wait for the message to be received. If there is no message to be received, it returns an ErrTimedOutException.; If you specify an integer between 1 and 65535, cltReceive waits for the specified number of seconds for the message to be received. If the specified number of seconds is exceeded before the message can be received, cltReceive returns an ErrTimedOutException.

flags: Specifies whether or not to release the connection after the message is received.; DCNOFLAGS: Does not release the connection after the message is received.; If DCNOFLAGS is specified, unless there is an error, the connection is not released until the rpcClose method is executed.; DCCLT_RCV_CLOSE: Releases the connection after the message is received.

Return value: None

Exceptions

ErrInvalidArgsException: The parameter specification is invalid.

ErrProtoException: The rpcOpen method did not execute. Another possibility is that, although the rpcOpen method did execute, neither DCCLT_ONEWAY_RCV nor DCCLT_SNDRCV is specified in the dcsndrcvtype operand of the TP1/Client/J environment definition.

ErrNetDownException: A network error occurred.

ErrTimedOutException: A timeout occurred while the message was being received.

ErrSyserrException: A system error occurred.

ErrInvalidPortException: This exception occurs when Y is specified in the dcsockopenatrcv operand of the TP1/Client/J environment definition, and the port specified in the dcrcvport operand is already in use. If N is specified in the dcsockopenatrcv operand, the rpcOpen method returns ErrFatalException.

ErrConnfreeException: The connection was released from the MHP.

Notes

The cltReceive method returns control to the CUP at the following times:

When a message of the length specified by the recvleng parameter is received from the MHP
When a timeout occurs while a message is being received from the MHP
When the connection is released from the MHP
When a network error occurs

If the MHP drops the connection when a cltReceive method is issued, an ErrConnfreeException error is returned.

cltSend

public void cltSend(byte[]  buff,
                    int     sendleng,
                    String  hostname,
                    int     portnum,
                    int     flags)
             throws ErrInvalidArgsException,
                    ErrProtoException,
                    ErrNetDownException,
                    ErrSyserrException,
                    ErrHostUndefException,
                    ErrInvalidPortException,
                    ErrConnRefusedException

Sends a message to an MHP.

Before executing the cltSend method, you must have specified either DCCLT_ONEWAY_SND or DCCLT_SNDRCV in the dcsndrcvtype operand of the TP1/Client/J environment definition, and executed the rpcOpen method.

Parameters

buff: Specifies the area in which to store the message to be sent. Make sure to specify an area that is at least the size specified in sendleng.

sendleng: Specifies the length of the message to be sent.

hostname: Specifies the host name of the node on which the MHP to be connected exists, in case the connection cannot be established.; If you specify null, cltSend references the dcsndhost operand of the TP1/Client/J environment definition that is obtained when the rpcOpen method is executed.; You can also specify an IP address, following the decimal-plus-dot convention, as the host name.; This parameter is ignored if the connection is established.

portnum: Specifies an integer for the port number of the MHP to be connected of between 0 and 65535, if the connection is not established.; If you specify 0, cltSend references the dcsndport operand of the TP1/Client/J environment definition that is obtained when the rpcOpen method is executed.; This parameter is ignored if the connection is established.

flags: Specifies whether or not to release the connection after the message is sent.; DCNOFLAGS: Does not release the connection after the message is sent.; If DCNOFLAGS is specified, unless there is an error, the connection is not released until the rpcClose method is executed.; DCCLT_SND_CLOSE: Releases the connection after the message is sent.

Return value: None

Exceptions

ErrInvalidArgsException: The parameter specification is invalid.

ErrProtoException: The rpcOpen method did not execute. Another possibility is that, although the rpcOpen method did execute, neither DCCLT_ONEWAY_SND nor DCCLT_SNDRCV is specified in the dcsndrcvtype operand of the TP1/Client/J environment definition.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

ErrHostUndefException: The hostname parameter specification is invalid. Another possibility is that the host name is not specified in either the hostname parameter or in the dcsndhost operand in the TP1/Client/J environment definition.

ErrInvalidPortException: The portnum parameter specification is invalid.

ErrConnRefusedException: The connection establishment request to the MHP was denied (an attempt was made to establish a connection through a port that is not waiting for a connection).

Notes: If the MHP drops the connection after the cltSend method is executed and a message is being sent, the cltSend method next executed ends normally or abnormally. If the cltSend method next executed ends normally, the cltSend method following that one ends abnormally. We recommend that you take the above into consideration when creating a CUP.

cltAssemSend

public void cltAssemSend(byte[] buff,
                         int sendleng,
                         String hostname,
                         int portnum,
                         int timeout,
                         int flags)
                  throws ErrInvalidArgsException,
                         ErrProtoException,
                         ErrNetDownException,
                         ErrSyserrException,
                         ErrHostUndefException,
                         ErrInvalidPortException,
                         ErrConnRefusedException,
                         ErrTimedOutException,
                         ErrConnfreeException,
                         ErrInvalidMessageException,
                         ErrCollisionMessageException

Uses the receive message assembly facility to send a message.

To execute the cltAssemSend method, you must first specify DCCLT_ONEWAY_SND or DCCLT_SNDRCV in the dcsndrcvtype operand of the TP1/Client/J environment definition and execute the rpcOpen method.

When the receive message assembly facility is used, message length (4 + specification value of the sendleng argument) is added to the first 4 bytes of the message, and a message having a length of between buff[0] and buff[sendleng - 1] is sent.

If the connection with the remote system is not established, connection is established according to the values specified in the hostname and portnum arguments, and a message is sent.

Parameters

buff: Specifies the area where the message to be sent is stored. Specify an area that is longer than the value specified by the sendleng argument.

sendleng: Specifies the length of the message to be sent.

hostname: Specifies the host name of the remote system to be connected if no connection has been established.; If null is specified, the content of the dcsndhost operand of the TP1/Client/J environment definition acquired by executing the rpcOpen method is referenced.; For the host name, you can also specify an IP address expressed in the decimal dot method. If connection has been established, this argument is ignored.

portnum: Specifies the port number of the remote system to be connected, expressed as an integer of between 0 and 65535, if no connection has been established.; If 0 is specified, the content of the dcsndport operand of the TP1/Client/J environment definition acquired by executing the rpcOpen method is referenced. If connection has been established, this argument is ignored.

timeout: A reserved argument. Specify 0.

flags: Specifies whether to release the connection after the message is sent.; DCNOFLAGS: Does not release the connection after the message is sent.; If DCNOFLAGS is specified, the connection is not released until the rpcClose method is executed, except when an error occurs.; DCCLT_SND_CLOSE: Releases the connection after the message is sent.

Return value

None

Exceptions

ErrInvalidArgsException: The specified argument is invalid.

ErrProtoException: The rpcOpen method has not been executed. Another possibility is that, although the rpcOpen method has been executed, DCCLT_ONEWAY_SND or DCCLT_SNDRCV has not been specified in the dcsndrcvtype operand of the TP1/Client/J environment definition.

ErrNetDownException: A network error occurred.

ErrSyserrException: A system error occurred.

ErrHostUndefException: The name of the remote host to be connected is invalid. Another possibility is that no host name is specified in either the hostname argument or the dcsndhost operand of the TP1/Client/J environment definition.

ErrInvalidPortException: The specified portnum argument is invalid.

ErrConnRefusedException: The request to establish connection to the remote system was denied (an attempt was made to establish a connection through a port that is not waiting for a connection).

ErrTimedOutException: A timeout occurred while receiving a response message. The connection is released.

ErrConnfreeException: The connection was released by the remote system.

ErrInvalidMessageException: An invalid message was received.

ErrCollisionMessageException: A send/receive message collision occurred.

Note: If the remote system releases the connection when you are sending a message by executing the cltAssemSend method, the cltAssemSend method that is executed next is terminated either normally or abnormally. If it is terminated normally, abnormal termination occurs with the cltAssemSend method that is executed next. Therefore, take note of this fact when creating a CUP.

cltAssemReceive

public void cltAssemReceive(byte[] buff,
                            int[] recvleng,
                            int timeout,
                            int flags)
                     throws ErrInvalidArgsException,
                            ErrProtoException,
                            ErrNetDownException,
                            ErrTimedOutException,
                            ErrSyserrException,
                            ErrInvalidPortException,
                            ErrConnfreeException,
                            ErrInvalidMessageException,
                            ErrBufferOverflowException

Uses the receive message assembly facility to receive a message.

To execute the cltAssemReceive method, you must first specify DCCLT_ONEWAY_RCV or DCCLT_SNDRCV in the dcsndrcvtype operand of the TP1/Client/J environment definition and execute the rpcOpen method.

When the receive message assembly facility is used, the first 4 bytes of the message are not stored in the buffer specified by the buff argument.

When this method terminates normally, a message containing user data having the length of recvleng[0] is received, and the user data is stored in buff[0] through buff[recvleng[0]-1].

Parameters

buff: Specifies the area in which to store the received message. Specify an area that is longer than the message to be received.

recvleng: After the method is executed, the length of the received message is returned to recvleng[0].

timeout: Specifies the maximum amount of time to wait to receive a message, expressed as an integer of between -1 and 65535 (seconds).; If -1 is specified, the system waits indefinitely until a message is received.; If 0 is specified, the system does not wait to receive a message. If there is no message to be received, ErrTimedOutException is returned.; If a value between 1 and 65535 is specified, the system waits to receive a message for the number of seconds specified. If a message cannot be received within the specified period, ErrTimedOutException is returned.

flags: Specifies whether to release the connection after the message is received.; DCNOFLAGS: Does not release the connection after the message is received.; If DCNOFLAGS is specified, the connection is not released until the rpcClose method is executed, except when an error occurs.; DCCLT_RCV_CLOSE: Releases the connection after the message is received.

Return value

None

Exceptions

ErrInvalidArgsException: The specified argument is invalid.

ErrProtoException: The rpcOpen method has not been executed. Another possibility is that, although the rpcOpen method has been executed, DCCLT_ONEWAY_RCV or DCCLT_SNDRCV has not been specified in the dcsndrcvtype operand of the TP1/Client/J environment definition.

ErrNetDownException: A network error occurred.

ErrTimedOutException: A timeout occurred while receiving a message.

ErrSyserrException: A system error occurred.

ErrInvalidPortException: This exception occurs when Y is specified in the dcsockopenatrcv operand of the TP1/Client/J environment definition, and the port specified in the dcrcvport operand is already in use. If N is specified for the dcsockopenatrcv operand, the rpcOpen method returns ErrFatalException.

ErrConnfreeException: The connection was released by the remote system.

ErrInvalidMessageException: An invalid message was received.

ErrBufferOverflowException: A message whose length exceeds the value specified in the buff argument was received.

Notes

The cltAssemReceive method returns control to the CUP in the following cases:

Message receiving is completed.
A message whose length exceeds the value specified in the buff argument is received.
A network error occurred.
A timeout occurred while receiving a message.
The connection is released by the remote system.
A message with an invalid message length is received.
A message with invalid segment information is received.

If the remote system releases the connection when the cltAssemReceive method is issued, the method returns the ErrConnfreeException error.

setConnectInformation

public void setConnectInformation(byte[] inf,
                                  short inf_len)
                           throws ErrInvalidArgsException

Sets the terminal identification information.

The terminal identification information specified in this method takes effect when you specify the host name of a DCCM3 logical terminal in the dchost operand and the port number of the DCCM3 logical terminal in the dchost or dcrapport operand in the TP1/Client/J environment definition, and when you use one of the following methods to establish a permanent connection with the DCCM3 logical terminal:

Call the openConnection method. If the openConnection method has parameters, specify DCCM3 logical terminal host name in the host parameter and the port number of the DCCM3 logical terminal in the port parameter.
Specify Y in the dcrapautoconnect operand in the TP1/Client/J environment definition and then call the rpcCall method.

When this method is called, the terminal identification information specified in the dccltconnectinf operand in the TP1/Client/J environment definition is ignored until the rpcOpen method is called again.

The terminal identification information specified in this method is recognized when a permanent connection is established with the DCCM3 logical terminal. If this method is called more than once, the terminal identification information specified immediately before the permanent connection was established with the DCCM3 logical terminal takes effect.

The terminal identification information specified by this method is ignored for an RPC using the name service or scheduler direct facility.

Parameters

inf: Specifies the logical terminal name of the DCCM3 logical terminal as terminal identification information consisting of up to 64 bytes of EBCDIK codes. Note that DCCM3 uses only the first 8 bytes and ignores the rest.

inf_len: Specifies the length of the terminal identification information, in the range from 1 to 64 bytes.

Return value: None.

Exception

ErrInvalidArgsException: A specified parameter is invalid.

acceptNotification

public void acceptNotification(
                               byte[] inf,
                               int[] inf_len,
                               int port,
                               int timeout,
                               byte[] hostname,
                               byte[] nodeid)
                       throws  ErrInvalidArgsException,
                               ErrProtoException,
                               ErrIOErrException,
                               ErrSecurityException,
                               ErrInvalidPortException,
                               ErrTimedOutException,
                               ErrNetDownException,
                               ErrInvalidMessageException,
                               ErrAcceptCanceledException,
                               ErrReplyTooBigException,
                               ErrVersionException,
                               ErrSyserrException

Waits for a message sent by the server's function (dc_rpc_cltsend) for up to the amount of time specified in the timeout parameter. When the method receives the message, it returns control to the CUP and returns the notification message, length of the notification message, and the host name and node identifier of the server that sent the message.

Parameters

inf: Specifies the area for storing the notification message from the server.; When the method terminates normally, the notification message from the server is stored.

inf_len: Specifies the length of the area for storing the notification message from the server (length of the area in the inf parameter). The value must be in the range from 0 to DCRPC_MAX_MESSAGE_SIZE.; If the dccltrpcmaxmsgsize value specified in the TP1/Client/J environment definition is 2 or greater, the permitted maximum value is that dccltrpcmaxmsgsize value, not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).; When the method terminates normally, the length of the notification message from the server is stored.

port: Specifies the port number that is to be used to receive notification messages from the server. Specify a value in the range from 5001 to 65535. If you execute multiple processes or threads concurrently on the same machine, specify different port numbers in the port parameters. This port number must be unique from port numbers used by the OS or other programs. If a port number that is already in use is specified, response data may not be received correctly. For details about the port numbers used by the OS, see the OS-related documentation.

timeout: Specifies the timeout value, in the range from 0 to 65535 (seconds). If 0 is specified, the method waits indefinitely.

hostname: Specifies the area for storing the host name of the notifying server. This size of this area must at least 256 bytes.; When the method terminates normally, the host name of the notifying server is stored in this area. TP1/Client/J acquires the host name from the IP address of the notifying server using the getHostName method of the java.net.InetAddress class and then converts the acquired host name to a byte array using the platform's default character set. TP1/Client/J then stores the result in hostname. If the conversion from IP address to host name fails, TP1/Client/J stores the IP address in hostname in decimal dot notation (example: 10.209.15.124).; If null is specified, the method does not store the host name of the notifying server.

nodeid: Specifies the area for storing the node identifier of the notifying server. The size of this area must be at least 8 bytes.; When the method terminates normally, the node identifier of the notifying server is stored in this area. The format of a node identifier is as follows:

Return value: None.

Exception

ErrInvalidArgsException: A parameter specified in the method is invalid.

ErrProtoException: The rpcOpen method has not been executed.

ErrIOErrException: An I/O exception occurred.

ErrSecurityException: A security exception occurred.

ErrInvalidPortException: The port number specified in the port parameter is in use.

ErrClientTimedOutException: A timeout occurred on TP1/Client/J.

ErrNetDownAtClientException: A network error occurred between TP1/Server and CUP.

ErrInvalidMessageException: An invalid message was received.

ErrAcceptCanceledException: The unidirectional message reception wait status was released by the cancelNotification method. In this case, values have already been set in the inf, inf_len, and hostname parameters. In the nodeid parameter, a value whose leading 8 bytes are initialized to 0 is set.

ErrReplyTooBigException: The received message cannot fit in the area provided by the CUP. The excess portion of the message was discarded. In this case, values have already been set in the hostname and nodeid parameters.

ErrVersionException: The version of the notifying server is invalid.

ErrSyserrException: A system error occurred.

cancelNotification

public void cancelNotification(
                               byte[] inf,
                               int inf_len,
                               String hostname,
                               int port)
                       throws  ErrInvalidArgsException,
                               ErrProtoException,
                               ErrIOErrException,
                               ErrInvalidPortException,
                               ErrTimedOutException,
                               ErrNetDownException,
                               ErrHostUndefException,
                               ErrSyserrException

Releases the unidirectional server message reception wait status (issuance of the acceptNotification or acceptNotificationChained method). Once this wait status is released, you can send messages specified in the inf parameter to the CUP in the unidirectional message reception wait status.

Parameters

inf: Specifies the message to be sent to the CUP.

inf_len: Specifies the length of the message that is sent to the CUP (length of message set in the inf parameter). The value must be in the range from 0 to DCRPC_MAX_MESSAGE_SIZE. If 0 is specified, no message is sent to the CUP.; If the dccltrpcmaxmsgsize value specified in the TP1/Client/J environment definition is 2 or greater, the permitted maximum value is that dccltrpcmaxmsgsize value, not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

hostname: Specifies the name of the host where the CUP in the unidirectional message reception wait status is located. For the host name, you can also specify the IP address in decimal dot notation (example: 10.209.15.124).

port: Specifies the port number, in the range from 5001 to 65535, of the CUP that is in the unidirectional message reception wait status.

Return value: None.

Exception

ErrInvalidArgsException: A parameter specified in the method is invalid.

ErrProtoException: The rpcOpen method has not been executed.

ErrIOErrException: An I/O exception occurred.

ErrInvalidPortException: The port number specified in the port parameter is invalid.

ErrClientTimedOutException: A timeout occurred on TP1/Client/J.

ErrNetDownAtClientException: A network error occurred between CUPs.

ErrHostUndefException: The host name specified in the hostname parameter is invalid.

ErrSyserrException: A system error occurred.

openNotification

public void openNotification(int port)
                     throws  ErrInvalidArgsException,
                             ErrProtoException,
                             ErrInvalidPortException,
                             ErrNetDownException,
                             ErrSyserrException

Creates an environment for using the unidirectional message consecutive reception facility. Issue this method as a pair with the closeNotification method. Once this method terminates normally, make sure that you issue the closeNotification method.

Parameters

port: Specifies the port number, in the range from 5001 to 65535, that is to be used to receive notification messages from the server.; If you execute multiple processes or threads concurrently on the same machine, specify different port numbers in the port parameters. This port number must be unique from port numbers used by the OS or other programs. If a port number that is already in use is specified, response data may not be received correctly. For details about the port numbers used by the OS, see the OS-related documentation.

Return value: None.

Exception

ErrInvalidArgsException: A parameter specified in the method is invalid.

ErrProtoException: The rpcOpen method has not been executed or the openNotification method has already been executed.

ErrInvalidPortException: The port number specified in the port parameter is already in use.

ErrNetDownAtClientException: A network error occurred between TP1/Server and CUP.

ErrSyserrException: A system error occurred.

acceptNotificationChained

public void acceptNotificationChained(
                                      byte[] inf,
                                      int[] inf_len,
                                      int timeout,
                                      byte[] hostname,
                                      byte[] nodeid)
                              throws  ErrInvalidArgsException,
                                      ErrProtoException,
                                      ErrIOErrException,
                                      ErrSecurityException,
                                      ErrTimedOutException,
                                      ErrNetDownException,
                                      ErrInvalidMessageException,
                                      ErrAcceptCanceledException,
                                      ErrReplyTooBigException,
                                      ErrVersionException,
                                      ErrSyserrException

Waits for a message sent by the server's function (dc_rpc_cltsend) until the amount of time specified in the timeout parameter is reached. When the method receives the message, it returns control to the CUP and returns the notification message, the length of the notification message, and the host name and node identifier of the server that sent the message. In order to issue this method, you must have already issued the openNotification method. You must issue this method after the openNotification method has been issued but before the closeNotification method is issued.

Parameters

inf: Specifies the area for storing the notification message from the server.; When the method terminates normally, the notification message from the server is stored.

inf_len: Specifies the length of the area for storing the notification message from the server (length of the area in the inf parameter). The value must be in the range from 0 to DCRPC_MAX_MESSAGE_SIZE.; If the dccltrpcmaxmsgsize value specified in the TP1/Client/J environment definition is 2 or greater, the permitted maximum value is that dccltrpcmaxmsgsize value, not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).; When the method terminates normally, the length of the notification message from the server is stored.

timeout: Specifies the timeout value, in the range from 0 to 65535 (seconds). If 0 is specified, the method waits indefinitely.

hostname: Specifies the area for storing the host name of the notifying server. This size of this area must be at least 256 bytes.; When the method terminates normally, the host name of the notifying server is stored in this area.; TP1/Client/J acquires the host name from the IP address of the notifying server using the getHostName method of the java.net.InetAddress class and then converts the acquired host name to a byte array using the platform's default character set. TP1/Client/J then stores the result in hostname. If the conversion from IP address to host name fails, TP1/Client/J stores the IP address in hostname in decimal dot notation (example: 10.209.15.124).; If null is specified, the method does not store the host name of the notifying server.

nodeid: Specifies the area for storing the node identifier of the notifying server. The size of this area must be at least 8 bytes.; When the method terminates normally, the node identifier of the notifying server is stored in this area. The format of a node identifier is as follows:

Return value: None.

Exception

ErrInvalidArgsException: A parameter specified in the method is invalid.

ErrProtoException: The openNotification method has not been executed.

ErrIOErrException: An I/O exception occurred.

ErrSecurityException: A security exception occurred.

ErrClientTimedOutException: A timeout occurred on TP1/Client/J.

ErrNetDownAtClientException: A network error occurred between TP1/Server and CUP.

ErrInvalidMessageException: An invalid message was received.

ErrAcceptCanceledException: The unidirectional message reception wait status was released by the cancelNotification method. In this case, values have already been set in the inf, inf_len, and hostname parameters. In the nodeid parameter, a value whose leading 8 bytes are initialized to 0 is set.

ErrReplyTooBigException: The received message cannot fit in the area provided by the CUP. The excess portion of the message was discarded. In this case, values have already been set in the hostname and nodeid parameters.

ErrVersionException: The version of the notifying server is invalid.

ErrSyserrException: A system error occurred.

closeNotification

public void closeNotification()
                      throws  ErrNetDownException,
                              ErrSyserrException

Deletes the environment for using the unidirectional message consecutive reception facility. Issue this method as a pair with the openNotification method. Once the openNotification method has terminated normally, make sure that you issue this method.

Parameters: None.

Return value: None.

Exception

ErrNetDownAtClientException: A network error occurred between TP1/Server and CUP.

ErrSyserrException: A system error occurred.