The XATMI interface definition for the client UAP (SUP or SPP) is in the format explained below.

Format

called_servers={"server-definition-file-name" [,"server-definition-file-name"]...};

Description

Specify all XATMI interface definition file names defined in the server UAP. When a server UAP definition file is specified, the typed record defined in the server definition file can be used by the client UAP process.

Parameters

• server-definition-file-name
  Specify the file name of the XATMI interface definition file of the server UAP. The definition file name must have a suffix.def.
  Multiple definition files names can be specified in braces {} in one called_servers statement. It is also possible to write multiple called_servers statements in one XATMI interface definition file.
  

Example

Defining a client UAP which communicates with server UAP1 and server UAP2 through the XATMI interface (assuming that the server UAP1 definition file name is serv1.def and the server UAP2 definition file name is serv2.def).

Format 1:

called_servers = {"serv1.def" ,"serv2.def"};

Format 2:

called_servers = {"serv1.def" }; called_servers = {"serv2.def" };

For the XATMI interface definition of a server UAP, the following items must be specified in any order:

• Definition of the typed record to be used
• Definition of service function name and argument information
• called_servers statement (if the server UAP is to call another server UAP)

(a) Definition of the typed record to be used

Format

type-name subtype-name{ data-type data-name; [data-type data-name;] : : } ;

Description

Define the type, subtype, and structure of the typed record to be used with the server UAP. If the server UAP is to call service from another server UAP process, the typed record which can be used by the calling process can also be used by any local process. Therefore, define here only the typed record to be used for I/O by the service function within the local process. However, X_OCTET will always be recognized. If X_OCTET is defined, the execution of the stub creation command (stbmake or tpstbmk) will encounter an error.

X_C_TYPE cannot be used for COBOL APIs. If X_C_TYPE is defined, the execution of the stub creation command (stbmake or tpstbmk) with the -b option specified results in an error.

Parameters

• type-name
  Specify the type name of the typed record to be used with the server UAP.
  
• subtype-name
  Specify the subtype name of the typed record to be used with the server UAP.
  
• data-type
  Specify the data type of the data contained in the structure of the typed record to be used with the server UAP.
  
• data-name
  Specify the data name of the data contained in the structure of the typed record to be used with the server UAP.
  

Data types that can be used for type arguments

Table 1-6 lists the data types that can be used as types. The Identifier column indicates the data type to be specified in the XATMI interface definition. The COBOL data column indicates the typed record to be actually defined for the stub. When converting the data type for communication with a non-OpenTP1 system, include the identifier to be converted in the XATMI interface definition.

Table 1-6 Data types that can be used for type arguments

Legend:

Y: Available with the communication protocol

N: Unavailable with the communication protocol

--: Always treated as an identifier not to be converted

#1: X_OCTET will always be recognized, regardless of whether it is defined. If X_OCTET is specified in the XATMI interface definition, the execution of a stub creation command will encounter an error.

#2: This identifier is available. However, the following identifier should be used for new stub creation:

octet or tchar for X_COMMON

str or tstr for X_C_TYPE

#3: X_C_TYPE cannot be used for COBOL APIs. If X_C_TYPE is defined, the execution of a stub creation command (stbmake or tpstbmk) with the -b option specified results in an error.

Example

X_COMMON subtype1 { char name[8]; long data[10]; long flags; };

(b) Definition of service function name and argument information

Format

service service-program-name { (type-name [subtype-name])(ALL)( [void] )};

Description

Specify the program name of the service program in the server UAP and the type name and subtype name of the typed record to be passed as the arguments. The argument is the data member of the svc_info structure which is the actual argument to the service program.

For the X_OCTET type, specify only the type name because there is no subtype. If intended processing does not involve reference to the data member of the svc_info structure in the service program, assign nothing or void to the argument.

The TPCALL, TPACALL, and TPCONNECT can call a service program without sending the typed record. If data indicated by a member of the svcinfo structure with a service program is not to be referenced explicitly, assign nothing or void to the argument.

To call a specified service program, set NULL for the pointer to the typed record sent with the TPCALL, TPACALL, or TPCONNECT functions at the client side. For the X_OCTET type, a specified service program can be called even if NULL is not set for the pointer or the length of the sent data is zero.

If specification is not to limit the typed record to be received as an argument, assign ALL to the argument. The service program defined with argument ALL can receive any type of typed records as long as they are recognizable in the local process.

Parameters

• service-program-name
  Specify the program name in the server UAP.
  
• type-name
  Specify the type name given to the argument to the function.
  
• subtype-name
  Specify the subtype name given to the argument to the function.
  

Examples

Example 1:

service svc_func1(X_COMMON subtype1);

Example 2 (argument type is X_OCTET):

service svc_func2(X_OCTET);

Example 3 (service program without argument reception):

service svc_func3(void); or service svc_func3();

Example 4 (service program without argument limitation):

service svc_func4(ALL);

(c) If the server UAP is to call another server UAP:

Specify the XATMI interface definition (called_servers statement) of the client UAP.

The name of an XATMI interface definition file must be appended with a suffix.def which indicates that the file is an XATMI interface definition file. The XATMI interface definition file may be placed under any directory that the stub creation command (stbmake or tpstbmk) can search.

The name of an XATMI interface definition file is up to 255 characters long. Note, however, that a lower upper limit is used under some OSs.

After the stub creation command (stbmake or tpstbmk) is executed, stub source files are created under names different from those in the XATMI interface definition file. Therefore, the XATMI interface definition file will not be used when the OpenTP1 is active.

If the same typed record is to be used by different processes, the user can create a definition file for the shared typed record and include it in the definition file for each process.

The statement for including the definition file is in the same format as in the C language as follows:

#include <file-name> or #include "file-name"

The include file will be read through the search path specified by the -i option to the stub creation command (stbmake or tpstbmk command). If the appropriate file is not found in the search path, the current directory will finally be searched.

The file to be included may be given any name (the suffix need not be .h). However, if the file is directly specified in the stub creation command (stbmake or tpstbmk) as the XATMI interface definition file, observe the definition naming convention.

The contents of the file to be included are the same as those of the XATMI interface definition file. However, the file should not contain the definition of a service function within the local process in order to avoid name duplication.

1. Service programs and subtypes must be named according to the OpenTP1 rules as follows:
   
   • Any name cannot begin with dc, DC, CBLDC, tx, TX, tp, or TP.
   • Service program names must be 20 characters or less long.
   • The maximum subtype name length is 32 characters. Of these characters, the first 16 characters are valid. These 16 characters are checked for duplication.
   • Up to 32 characters can be used for the data names of data used in the structures of typed records.
2. Service program names must be unique within the same process.
3. Subtype names may be duplicate in the same process only if the types and structures are identical. Otherwise, the stub creation command (stbmake or tpstbmk) returns with an error.
4. Identical service program names or subtype names may be used in different processes. However, processes treated as different servers will be regarded as the same process by the client if they are called from one client.