OpenTP1 Version 7 Programming Reference COBOL Language

[Contents][Index][Back][Next]

CBLDCRPC('CALL ') - Request a remote service

Format

PROCEDURE DIVISION specification

CALL  'CBLDCRPC'  USING  unique-name-1 unique-name-2
                         unique-name-3

DATA DIVISION specification

01  unique-name-1.
    02  data-name-A    PIC X(8) VALUE 'CALL    '.
    02  data-name-B    PIC X(5).
    02  FILLER        PIC X(3).
    02  data-name-C    PIC S9(9) COMP VALUE ZERO.
    02  data-name-D    PIC S9(9) COMP.
    02  data-name-E    PIC X(32).
    02  data-name-F    PIC X(n).
01  unique-name-2.
    02  data-name-G    PIC S9(9) COMP.
    02  data-name-H    PIC X(n).
01  unique-name-3.
    02  data-name-I    PIC S9(9) COMP.
    02  data-name-J    PIC X(n).

Description

CBLDCRPC('CALL ') requests an SPP service. This function can be called without consideration of the node containing the requesting service.

Specify a service group name and service name for a data area of CBLDCRPC('CALL ') to request a service. A service request is addressed to the service program corresponding to the specified names.

A UAP which calls CBLDCRPC('CALL ') can be used regardless of whether it has been executed as a transaction. When a service is requested by CBLDCRPC('CALL ') from the process which has been executed as a transaction, the requested service process runs as a transaction branch.

Before this function can be used, the OpenTP1 at the node containing the server UAP to which the service request is addressed must be active.

Receiving a signal while waiting for a response after execution of CBLDCRPC('CALL ') does not cause CBLDCRPC('CALL ') to be returned.

The following items are described after the list of status codes. See each description for details on CBLDCRPC('CALL ').

(1) Data areas of CBLDCRPC('CALL ')

(2) Error cases of CBLDCRPC('CALL ')

(3) Timing when CBLDCRPC('CALL ') results in error

(4) Specification for reexecuting the service request if CBLDCRPC('CALL ') results in error

(5) When a priority is given to a service request

(6) Difference between status codes 00310 and 00306

(7) Specification for the return of status code 00378

(8) Relationship between status codes and synchronization point processing

(9) Notes on requesting a service

(10) When a service is requested with domain qualification

Data areas whose values are set in the UAP

data-name-A

Specify VALUE 'CALL[Figure]' for the request code indicating that a remote service is requested.

data-name-C

Specify the RPC mode and option with a value:

0: Synchronous response-type RPC

2: Asynchronous response-type RPC

1: Nonresponse-type RPC

4: Chained RPC

Add 32 to the value indicating the RPC mode to avoid having the requested processing handled as a transaction. When 32 is added, the processing of the service function is not handled as a transaction even if the service request is issued from the transaction.

Add 256 to the value indicating the RPC mode when the service group name is specified with domain qualification. An RPC with domain qualification cannot be a transaction branch. Therefore, add (256 + 32) to the value indicating the RPC mode whenever CBLDCRPC('CALL ') is used from the transaction.

Example 1:
When a nontransaction service is requested by using a synchronous response-type RPC, specify 32 (0 + 32) for data-name-C.

Example 2:
When a service is requested by using a synchronous response-type RPC with domain qualification from the transaction, specify 290 (2 + 256 + 32) for data-name-C.

data-name-E

Specify the SPP service name with an ASCII character string of up to 31 bytes. End the character string with space. The space is not counted in the length of the character string.

data-name-F

Specify the SPP service group name with an ASCII character string of up to 31 bytes. End the character string with space. The space is not counted in the length of the character string.

When requesting a service with domain qualification, specify the service group name suffixed by an at mark (@) and the DNS domain name, and end the character string with space.

data-name-G

Specify the input parameter length of the service (the length of data-name-H) within the range from 1 to DCRPC_MAX_MESSAGE_SIZE#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

data-name-H

Specify the input parameter of the service.

data-name-I

Specify the length of the response (the length of data-name-J) within the range from 1 to DCRPC_MAX_MESSAGE_SIZE#. DCRPC_MAX_MESSAGE_SIZE is defined in dcrpc.h.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Data areas to which values are returned from server UAP

data-name-B

A status code of 5 digits is returned.

data-name-D

The descriptor is returned when asynchronous response-type RPCs are used.

data-name-I

The length of the response set by the service program is returned.

data-name-J

The response set by the service program is returned.

Status codes

The following status codes are returned from OpenTP1, not from the service program.

Status code Explanation
00000 Normal termination. In the case of asynchronous response-type RPC, the descriptor was set in data-name-D.
00301 The value specified for the data-name is invalid. This error also occurs if the request code (data-name-A) is invalid.
00302 CBLDCRPC('OPEN ') was not called.
00304 A memory shortage occurred. Or, a service request was not accepted because a space shortage occurred in the message storage buffer pool (message_store_buflen operand) of the SPP to which the service was requested.
If necessary, revise the message_store_buflen operand in the user service default definition or in the user service definition of the SPP to which the service was requested.
00306 A communication failure occurred.
Check if a network failure has occurred.
00307 The response wait time in CBLDCRPC('CALL ') has elapsed.
If necessary, revise the response wait time specified in CBLDCRPC('CALL ') (watch_time operand and arguments in CBLDCRPC('SETWATCH')).
The SPP to which the service was requested terminated abnormally during execution of a service program.
Check the cause of abnormal termination of the SPP to which the service was requested.
00308 The input parameter length specified in data-name-G exceeded the maximum.
If necessary, revise the data-name-G setting.
00309 The length of the response (data-name-D of the service program) set in the service program of the SPP to which the service was requested exceeded the response length (data-name-I of the service program) in CBLDCRPC('CALL ').
If necessary, revise the response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested.
00310 The service group name set in data-name-F is invalid, or the SPP to which the service was requested with the service group set in data-name-F was not running.
If necessary, revise the data-name-F setting, or start the SPP to which the service was requested with the service group set in data-name-F.
00311 The service name set in data-name-E is invalid, or the service name set in data-name-E by the SPP to which the service was requested has not been specified in the service operand in the user service definition file.
If necessary, revise the data-name-E setting, or specify the service name set in data-name-E also in the service operand for the SPP to which the service was requested.
00312 The SPP to which the service was requested with the service group set in data-name-F is under server shutdown or service shutdown status.
Check the cause of the shutdown, and then release the SPP from shutdown status.
00313 The SPP to which the service was requested is under termination processing.
00314 The SPP to which the service was requested with the service group set in data-name-F is not running, or a communication failure might have occurred during the service request send processing.
Start the SPP to which the service was requested with the service group set in data-name-F. If the SPP is already running, check to see if a network failure has occurred.
While 0 was specified for the service request response time (watch_time operand and an argument in CBLDCRPC('SETWATCH')), the SPP to which the service was requested terminated abnormally during execution of a service program.
Check the cause of abnormal termination of the SPP to which the service was requested.
00315 OpenTP1 for the SPP to which the service was requested is not running. OpenTP1 might be under termination processing or a communication failure might have occurred during the service request send processing.
Start OpenTP1 for the SPP to which the service was requested, or check for a network failure.
00316 A system error (internal conflict) occurred in the SPP to which the service was requested.
00317 A memory shortage occurred in the SPP to which the service was requested.
00318 A system error (internal conflict) occurred in the UAP that requested the service.
00319 The response length (data-name-D of the service program) set by a service program of the SPP to which the service was requested is outside the range from 1 to the value defined in DCRPC_MAX_MESSAGE_SIZE.#
If necessary, revise the response length (data-name-D of the service program) in the service program of the SPP to which the service was requested.
00320 OpenTP1 for the SPP to which the service was requested is under start processing.
00323 A memory shortage occurred in the UAP that is requesting the service or the SPP to which the service was requested. When this value is returned, the transaction branch rolls back.
Check if unneeded memory is allocated by the UAP that is requesting the service or the SPP to which the service was requested.
00324 A system error (internal conflict) occurred in the UAP that requested the service. When this value is returned, the transaction branch rolls back.
00325 A system error (internal conflict) occurred in the SPP to which the service was requested. When this value is returned, the transaction branch rolls back.
00326 The response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested exceeded the response length (data-name-I of the service program) in CBLDCRPC('CALL '). When this value is returned, the transaction branch rolls back.
If necessary, revise the response length (data-name-D of the service program) set in the service program of the SPP to which the service was requested.
00327 When the inter-node load-balancing facility and the extended internode load-balancing facility are used, the transaction attributes (atomic_update operand) do not match among the SPPs with the same service group name to which the service was requested. Another possibility is that the inter-node load-balancing facility and the extended internode load-balancing facility cannot be used because the version of OpenTP1 at the node to which loads are to be distributed is earlier than that of the OpenTP1 for the UAP that is requesting the service.
This value is returned only when the service request is issued to an SPP that uses the inter-node load-balancing facility and the extended internode load-balancing facility.
If necessary, revise the transaction attribute (atomic_update operand) of the SPP that uses the inter-node load-balancing facility and the extended internode load-balancing facility, or revise if necessary the version of OpenTP1.
The dcsvgdef definition command was used to issue a service request to a user server with the non-transaction attribute (atomic_update is N in the user service definition or jnl_fileless_option is Y in the system common definition). However, 32 was not added to data-name-C for CBLDCRPC('CALL ').
00328 The domain name of the service group name with the domain qualification in data-name-F is invalid.
If necessary, revise the domain name.
00329 A service was requested with a domain qualification in data-name-F, but the port number of the domain representative schedule service was not found.
If necessary, revise the domain_masters_port operand setting in the system common definition and the port number setting for the domain representative schedule service in /etc/services.
00356 The SPP to which the service was requested (the server that receives requests from socket) cannot receive the service request.
If necessary, revise the max_socket_msg and max_socket_msglen operands in the user service definition or the user service default definition for the SPP to which the service was requested.
00366 When the online tester was being used, a service request was issued from a UAP in the test mode to an SPP in the nontest mode or from a UAP in the nontest mode to an SPP in the test mode.
If necessary, revise the UAP's test mode setting.
00367 CBLDCRPC('CALL ') with nontransaction setting specified for data-name-C was called to request a service after a chained RPC with the transaction attribute was executed.
00370 The SPP to which the service was requested is protected by the security facility.
The UAP that requested the service by executing CBLDCRPC('CALL ') does not have permission to access the SPP to which the service was requested. If necessary, revise the access permissions for the SPP to which the service was requested.
00372 The transaction branch cannot be started because it exceeds the maximum number of transaction branches that can be activated concurrently in the OpenTP1 for the SPP to which the service was requested.
If necessary, revise the setting in the trn_tran_process_count operand in the transaction service definition.
The transaction branch cannot be started because it exceeds the maximum number of child transaction branches that can be activated from one transaction branch by the UAP that is requesting the service.
If necessary, revise the setting in the trn_max_subordinate_count operand in the transaction service definition.
32 is not added to the value specified for data-name-C when a service with domain qualification specified in a transaction is requested.
Transaction branching cannot start because the SPP to which the service was requested encountered a resource manager (RM) error.
Eliminate the cause of the resource manager (RM) error and then re-execute the function.
In the System Environment window of TP1/LiNK, the Transaction Facility item is not set to Yes.
If necessary, revise the Transaction Facility setting in the System Environment window of TP1/LiNK.
00378 The SPP that received the service request terminated abnormally during execution of the service program.
If necessary, revise the service program processing of the SPP that received the service request. This status code is returned only when "00000001" is specified in the pc_extend_function operand in the user service definition of the UAP that requested the service. When "00000000" is specified in the rpc_extend_function operand or when this operand is omitted, status code 00307 or 00314 is returned, instead of 00378.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

(1) Data areas of CBLDCRPC('CALL ')

Data areas of CBLDCRPC('CALL ') are explained below.

Values passed to server UAP

Allocate an area (data-name-J) for the response from the service program before requesting a service. The client UAP sets the following values in CBLDCRPC('CALL ').

The input parameter, input parameter length, and response length values which are set in CBLDCRPC('CALL ') of the client UAP are passed to the service program as is. Change the notation of character codes or digits in the processing of the client UAP or requested service program if required. If a service request is addressed to a service program which does not return any response, the specified response length is ignored.

The maximum values of input parameter length and response length are declared as DCRPC_MAX_MESSAGE_SIZE# in the header file dcrpc.h. See the contents of dcrpc.h to confirm the maximum values.

#: If you used the rpc_max_message_size operand, the value of this data area is the value specified in the rpc_max_message_size operand and not the value of DCRPC_MAX_MESSAGE_SIZE (1 megabyte).

Values returned from server UAP

When the service program terminates and response is returned, the following values can be referenced:

The value of data-name-I is the length of the response which is actually returned from the service program. The values of data-name-J and data-name-I can be referenced in the following cases depending on the RPC mode:

If CBLDCRPC('CALL ') or CBLDCRPC('POLLANYR') returns with an error, the values of data-name-J and data-name-I cannot be referenced.

If the returned response is larger than the response area acquired by the client UAP (data-name-I), CBLDCRPC('CALL ') returns with an error, giving the status code 00309.

Value specified for data-name-C

The value specified for data-name-C and the execution result of CBLDCRPC('CALL ') are explained below.

When an asynchronous response-type RPC is used in a transaction, receive responses by using CBLDCRPC('POLLANYR') before performing the synchronization point processing (commitment or rollback). No response can be received by CBLDCRPC('POLLANYR') after the synchronization point processing. To designate a specific response received by CBLDCRPC('POLLANYR'), specify the positive integer (descriptor), which is returned by CBLDCRPC('CALL '), as the argument of CBLDCRPC('POLLANYR'). Thus, hold the value of data-name-D of CBLDCRPC('CALL ') to designate a specific response received.

To receive responses after the synchronization point processing in non-transaction processing, specify the corresponding option in rpc_extend_function of the system service definition. For details about rpc_extend_function, see the manual OpenTP1 System Definition.

(2) Error cases of CBLDCRPC('CALL ')

Reasons why CBLDCRPC('CALL ') returns with an error are explained below.

If the OpenTP1 at the node containing the server UAP is not active

If the OpenTP1 to which the service is requested is not running, CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:

00306

00314

00315

00320

If the server UAP is not active

When the server UAP is a multiserver, the service request is dealt with a new process which is activated by the OpenTP1 even if the server UAP is being terminated abnormally or being partially recovered. However,CBLDCRPC('CALL ') returns with an error in the following cases:

  1. No service request can be addressed to the SPP in shutdown state. If the service group is shut down, CBLDCRPC('CALL ') returns with an error, giving the status code 00312.
  2. If the SPP is being terminated or has been terminated by the stop command for the user server (dcsvstop command) or for OpenTP1 (dcstop command), CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:
    00310
    00312
    00313
    Which status code returns depends on the timing when CBLDCRPC('CALL ') was called.
  3. If the OpenTP1 is being started, CBLDCRPC('CALL ') returns with an error, giving the status code 00320. In this case, a service may be requested normally after activation of the server UAP or OpenTP1 is completed. Since activation of the OpenTP1 is completed when a message log with the message ID KFCA01809-I is output, request a service again after this message appears.

When a service request is issued in an environment where internode load-balancing and extended internode load-balancing are in use:

If a service request is issued in an environment where internode load- balancing and extended internode load-balancing are in use and the requested service at the addressed node is unavailable because of a closed schedule, the OpenTP1 automatically transfers that service request to another node. If one of the following events occurs, however, CBLDCRPC('CALL ') returns with an error, giving the status code 00327:

  1. The service was requested from a transaction process and the transaction attribute of the service at the transfer destination node disagrees with that of the closed service.
  2. The version of the OpenTP1 residing in the transfer destination node is earlier than the version of the OpenTP1 residing in the node that requested the service.

If the above error return occurs, take actions to reach consistency among:

  1. Transaction attributes of SPPs that participate in internode load-balancing and extended internode load-balancing.
  2. Versions of OpenTP1 that participate in internode load-balancing and extended internode load-balancing.

When a service request is addressed to the server that receives requests from a socket

The server that receives requests from a socket controls message congestion according to the specified values for max_socket_msg and max_socket_msglen in the user service definition. It is probable that service requests cannot be accepted if a message reaches the defined value. In this case, CBLDCRPC('CALL ') returns with an error, giving the status code 00356. If this status code is returned, the client UAP can sometimes reissue the service request successfully after waiting for a while.

When a chained RPC is used

If CBLDCRPC('CALL ') which is not a transaction is called from the UAP using a chained RPC which is processed as a transaction to the same server UAP, CBLDCRPC('CALL ') returns with an error, giving the status code 00367.

When the online tester is used

If the online tester is in use and CBLDCRPC('CALL ') is called from a UAP in test mode to a UAP in nontest mode or vice versa, CBLDCRPC('CALL ') returns with an error, giving the status code 00366.

When the security facility is used

If the desired service is protected with the security facility and the client UAP which called CBLDCRPC('CALL ') does not have the access permission for the SPP, CBLDCRPC('CALL ') returns with an error, giving the status code 00370.

(3) Timing when CBLDCRPC('CALL ') results in error

The following explains the timing when an error is returned to the client UAP if the SPP to which the service request is addressed terminates abnormally.

When CBLDCRPC('CALL ') results in error due to time monitoring of the client UAP

In the following cases, CBLDCRPC('CALL ') returns with an error, giving the status code 00307, after the time specified in the watch_time operand in the user service definition of the client UAP has elapsed:

(4) Specification for reexecuting the service request if CBLDCRPC('CALL ') results in error

Even if the OpenTP1 to which the service request is issued is not active because it is being started or is engaged in system switching, you can have the OpenTP1 re-execute the requested search and service request transmission without treating CBLDCRPC('CALL ') processing as an error.

To re-execute the requested search and service request transmission, specify Y in the rpc_retry operand in the system common definition. You use the rpc_retry_count and rpc_retry_interval operands to specify the re-executions count and re-execution interval, respectively, for a requested search and service request transmission. If this count value exceeds the re-executions count value specified in the system common definition, CBLDCRPC('CALL ') returns with an error and sets one of the following status code values:

00301

00306

00310

00314

00315

00320

(5) When a priority is given to a service request

To specify a schedule priority for a service request, call CBLDCRPC('SETSVPRI') immediately before CBLDCRPC('CALL '). If no schedule priority is specified, the priority of the service request is determined according to the default interpretation of the schedule service.

(6) Difference between status codes 00310 and 00306

These status codes are returned if the user server corresponding to the service group name is not found.

(7) Specification for the return of status code 00378

You can use the status code 00378 instead of 00307 or 00314 to check whether the SPP that was asked to offer its service abnormally terminated before processing was completed. For this purpose, assign 00000001 to the rpc_extend_function operand in the user service definition. With this specification, the status code 00378 will return if the above error occurs. If nothing or 00000000 is assigned to the rpc_extend_function operand, the status code 00307 or 00314 will be returned, instead of 00378.

(8) Relationship between status codes and synchronization point processing

The relationship between status codes of CBLDCRPC('CALL ') and synchronization point processing (commitment and rollback) is explained below. The description applies to the service request which is a transaction, rather than the service request which is not a transaction (including the case when 32 is added to the value of data-name-C indicating the RPC mode).

When commitment is performed even though CBLDCRPC('CALL ') returns with an error

The status code 00307 may be returned due to abnormal termination of the service program which the service request is addressed, a node error, or network error. However, when the client UAP is not a transaction, the service program to which the service request is addressed may terminate normally and database may be updated.

Status codes which require rollback processing

If CBLDCRPC('CALL ') called from a transaction returns with an error, some status codes always require rollback processing for the transaction (the server UAP enters rollback_only state). In this case, rollback processing is always performed even if either of the COBOL-UAP creation programs for commitment and rollback is used. The following status codes of CBLDCRPC('CALL ') always require rollback processing for the transaction:

00311

00317

00319

00326

(9) Notes on requesting a service

  1. Define the service group name and service name at server UAP environment setup. These names are set in CBLDCRPC('CALL '). If a service is requested while invalid service group name or service name is set in CBLDCRPC('CALL '), the function returns with an error, giving the status code 00310 or 00311. If the service program does not return response, CBLDCRPC('CALL ') does not return with an error, giving the status code 00310.
  2. The process of the server UAP is different from that of the client UAP. Therefore, the following matters are different from ordinary procedure calls:
    • Attributes which are given to the process of the client UAP by the OS (environment variables, schedule priority (nice value), etc.) are not passed on to the server UAP.
    • Environment settings of the OpenTP1 specified at the node of the client UAP (existence of specification of transaction attribute, time limit of transaction branch, schedule priority, etc.) are not passed on to the OpenTP1 of the server UAP.
  3. Do not specify the same buffer area for the input parameter and the response from the service program.
  4. If 1 is specified for data-name-C, the following status codes will not return:
    • Errors which never occur
      00309
      00319
    • Errors which cannot be detected even though they could occur
      00311
      00312
      00313
      00316
      00318
      00320
      00370
    In addition, OpenTP1 does not output a message when an error occurs. If errors must be detected, consider specifying 0 to data-name-C (synchronous-response-type RPC).
  5. When a service group is requested by CBLDCRPC('CALL ') from a transaction, an SPP is occupied until the transaction terminates. When the same service is requested more than once by CBLDCRPC('CALL ') from the same transaction, perform the following:
    • Re-estimate the values specified for the balance_count operand and parallel_count operand in the user service definition according to the number of usages.
    • Request a service by using chained RPCs so that the number of processes will not increase.
    If the values specified for the balance_count operand and parallel_count operand are incorrect, the transaction will shut down abnormally and a deadlock may occur.
  6. When an asynchronous response-type RPC is used, the server UAP may be occupied until CBLDCRPC('POLLANYR') receives all asynchronous responses or CBLDCRPC('DISCARDF') rejects the receiving of asynchronous responses. This may occur regardless of whether it is a transaction or not. Increase the number of resident processes according to how many times an asynchronous response-type RPC is used.
    An asynchronous response-type RPC requires many resources in addition to occupying the server UAP. To prevent responses from degrading performance of UAP processing and activation of unnecessary SPPs, ensure that responses are received or the receiving of responses is rejected after CBLDCRPC('CALL ') of an asynchronous response-type RPC is used.
  7. To receive a response after using the service request in asynchronous-response-type RPC for more than one time continuously, specify a different response storage area as shown below for each service request when requesting an asynchronous-response-type RPC service. If the same area is specified, the response that comes in later will be overwritten and an accurate response cannot be received.
    01 unique-name-3-1.
       02 data-name-I1 PIC S9(9) COMP.
       02 data-name-J1 PIC X(n).
    01 unique-name-3-2.
       02 data-name-I2 PIC S9(9) COMP.
       02 data-name-J2 PIC X(n).
    01 unique-name-3-3.
       02 data-name-I3 PIC S9(9) COMP.
       02 data-name-J3 PIC X(n).
  8. The server UAP (SPP) that requested a service using an asynchronous response-type RPC sends a response soon after the service function is executed, regardless of whether the process that executed the asynchronous response-type RPC issued the CBLDCRPC('POLLANYR'). If the same asynchronous response-type RPC is executed numerous times simultaneously without the CBLDCRPC('POLLANYR') being issued, the response sent by the SPP may stay in the TCP/IP buffer and the SPP may fail to send a response. If the SPP fails to send a response, no response can be received from the SPP even if the source of the asynchronous response-type RPC issues the CBLDCRPC('POLLANYR').
  9. If a large number of asynchronous response-type RPCs or non-response type RPCs having the transaction attribute are executed, messages about transactions sent by the SPP can no longer be received. In this case, the transactions may roll back.

(10) When a service is requested with domain qualification

Specifying a service group name with domain qualification enables requesting an OpenTP1 service in the DNS domain. Specify the service group name suffixed by an at mark (@) and the DNS domain name for domain qualification.

Notes on requesting a service with domain qualification

  1. To request a service with domain qualification, add (256 + 32) to the value of data-name-C of CBLDCRPC('CALL ') indicating the RPC mode. If the service group name with domain qualification is specified without addition, CBLDCRPC('CALL ') returns with an error, giving the status code 00310.
  2. If an RPC with domain qualification is used, a transaction cannot be extended even if the process which called CBLDCRPC('CALL ') is a transaction. Therefore, to request a service with domain qualification from a transaction, add (256 + 32) to the value of data-name-C of CBLDCRPC('CALL ') indicating the RPC mode in order not to have the transaction extended. When the local domain is specified for the domain name, the transaction also cannot be extended.
  3. When an RPC with domain qualification is used, a service request can be addressed only to a server that receives requests from a queue, rather than a server that receives requests from a socket.
  4. A service request with domain qualification is sent to the domain-alternate schedule service which is activated on the host registered with the namdomainsetup command. Obtain the port number of the domain-alternate schedule service from /etc/services. If an error occurs while transferring the service request and multiple host names are registered with the namdomainsetup command, the service request is transferred to other hosts sequentially. Even if the RPC with domain qualification terminates normally, an error may occur during transfer to the domain-alternate schedule service.

Preparation for requesting a service with domain qualification

Perform the following environment setup for an RPC with domain qualification:

  1. Register the name of the host on which the domain-alternate schedule service is activated by using the namdomainsetup command.
  2. Define as follows the port number of the domain-alternate schedule service in /etc/services of the host on which the OpenTP1 which requests a service with domain qualification is activated:
    OpenTP1scd port-number/tcp
  3. Specify the well-known port of the domain-alternate schedule service for the scd_port operand in the schedule service definition for the OpenTP1 which activates the domain-alternate schedule service.

Example

Client UAP which executes the service ADD
01  unique-name-1.
    02  data-name-A     PIC X(8) VALUE 'CALL    '.
    02  STATUS-CODE    PIC X(5) VALUE SPACES.
    02  FILLER         PIC X(3).
    02  FLAGS          PIC S9(9) COMP VALUE ZERO.
    02  DESCRIPTOR     PIC S9(9) COMP VALUE ZERO.
    02  SERVICE-NAME   PIC X(32) VALUE SPACES.
    02  GROUP-NAME     PIC X(32) VALUE SPACES.
01  unique-name-2.
    02  NAME-LENG      PIC S9(9) COMP.
    02  NAME           PIC X(32) VALUE SPACES.
01  unique-name-3.
    02  RESULT-LENG    PIC S9(9) COMP.
    02  RESULT         PIC X(20).
*
MOVE 'ADDRESS-BOOK' TO GROUP-NAME.
MOVE 'ADD' TO SERVICE-NAME.
MOVE 'SATO' TO NAME.
MOVE 4 TO NAME-LENG.
MOVE 20 TO RESULT-LENG.
CALL 'CBLDCRPC' USING  unique-name-1  unique-name-2
                       unique-name-3.
IF STATUS-CODE NOT = '00000' THEN
   DISPLAY 'FAILED'
END-IF.
STOP RUN.

Server UAP which executes the service ADD
PROGRAM-ID. ADD.
DATA DIVISION.
LINKAGE SECTION.
01  unique-name-1.
    02  ADD-NAME    PIC X(20).
01  unique-name-2.
    02  NAME-LENG   PIC S9(9) COMP.
01  unique-name-3.
    02  RESULT      PIC X(20).
01  unique-name-4.
    02  RESULT-LENG PIC S9(9) COMP.
         :
         :
PROCEDURE DIVISION USING unique-name-1 unique-name-2
                          unique-name-3 unique-name-4.
         :
* Processes the contents of the received unique-name-1
         :
MOVE 'ADD-COMPLETE' TO RESULT.
MOVE 12 TO RESULT-LENG.
EXIT PROGRAM.

Note

Assume that you want to perform a transactional RPC on an OpenTP1 system other than the domain specified in the all_node clause of the system common definition. In this case, you must ensure that the node identifiers (node_id clause of the system common definition) of all OpenTP1 systems in the local domain and remote domain are unique. In addition, all the OpenTP1 systems must be version 03-02 or later. If these conditions are not met, the transaction may not recover properly.