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 buffer 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 buffer 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 buffer 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 buffer to be used with the server UAP. If the server UAP is to call service from another server UAP process, the typed buffer which can be used by the calling process can also be used by any local process. Therefore, define here only the typed buffer 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 a stub creation command (stbmake or tpstbmk command) will encounter an error.

Parameters

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

List of the data types that can be used as types

Table 1-6 lists the data types that can be used as types. Identifier means a data type to be written in the XATMI interface definition. Data type in C means data type of a typed buffer actually defined in a stub. To convert a data type in order to communicate with a system other than OpenTP1, specify the identifier to be converted in the XATMI interface definition.

For OpenTP1, a value of type int has four bytes. Therefore, int4 is written in the definition file so that the fact is explicitly indicated.

Table 1-6 Data types that can be used as types

Type	Identifier	Data type in C	Communication protocol		Remarks
			TCP/IP	OSI TP
X_OCTET	O#1	O#1	Y	Y	None
X_COMMON	short a	short a	Y	Y	None
	short a[n]	short a[n]	Y	Y	None
	long a	long a	Y	Y	None
	long a[n]	long a[n]	Y	Y	None
	char a#2	char a	Y	Y	Unconverted array
	octet a	char a	Y	Y	Unconverted array
	tchar a	char a	O	Y	Converted array
	char a[n]#2	char a[n]	Y	Y	Unconverted array
	octet a[n]	char a[n]	Y	Y	Unconverted array
	tchar a[n]	char a[n]	O	Y	Converted array
X_C_TYPE	short a	short a	Y	N	None
	short a[n]	short a[n]	Y	N	None
	long a	DCLONG a	Y	N	None
	long a[n]	DCLONG a[n]	Y	N	None
	int4 a	DCLONG a	Y	N	None
	int4 a[n]	DCLONG a[n]	Y	N	None
	char a#2	char a	Y	N	None
	octet a	char a	Y	N	None
	tchar a	char a	Y	N	None
	char a[n]#2	char a[n]	Y	N	None
	octet a[n]	char a[n]	Y	N	None
	tchar a[n]	char a[n]	Y	N	None
	float a	float a	Y	N	None
	float a[n]	float a[n]	Y	N	None
	double a	double a	Y	N	None
	double a[n]	double a[n]	Y	N	None
	octet a[n][n]	char a[n][n]	Y	N	None
	tchar a[n][n]	char a[n][n]	Y	N	None
	str a[n]	char a[n]	Y	N	None
	str a[n][n]	char a[n][n]	Y	N	None
	tstr a[n]	char a[n]	Y	N	None
	tstr a[n][n]	char a[n][n]	Y	N	None

Legend:

Y: Can be used for the applicable communication protocol.

N: Cannot be used for the applicable communication protocol.

O: Even an identifier to be converted is treated as it is without conversion.

#1

X_OCTET is automatically recognized if it is not defined. If X_OCTET is specified in the XATMI interface definition, an error occurs when a command that creates a stub is executed.

#2

This identifier can also be used. However, to create a new program, use one of the following identifiers:

For X_COMMON: octet or tchar

For X_C_TYPE: str or tstr

Example

X_C_TYPE subtype1 { char name[8]; int4 data[10]; int4 flags; };

(b) Definition of service function name and argument information

Format

service service-function-name (type-name [subtype-name])|(ALL)|( [void] )};

Description

Specify the function name of the service function in the server UAP and the type name and subtype name of the typed buffer 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 function.

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 function, assign nothing or void to the argument.

The tpcall(), tpacall(), and tpconnect() functions can call a service function without sending the typed buffer. If data indicated by a member of the svcinfo structure with a service function is not to be referenced explicitly, assign nothing or void to the argument.

To call a specified function, set NULL for the pointer to the typed buffer sent with the tpcall(), tpacall(), or tpconnect() functions at the client side. For the X_OCTET type, a specified function 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 buffer to be received as an argument, assign ALL to the argument. The service function defined with argument ALL can receive any type of typed buffers as long as they are recognizable in the local process.

Parameters

• service-function-name
  Specify the function 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_C_TYPE subtype1);

Example 2 (argument type is X_OCTET):

service svc_func2(X_OCTET);

Example 3 (service function without argument reception):

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

Example 4 (service function 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 file name must end with the suffix .def indicating an XATMI interface definition file. The directory to contain the file must be in a path that a stub creation command (stbmake or tpstbmk command) can search. No other restrictions are placed on it.

The name of an XATMI interface definition file can have up to 255 characters. However, the name that can be specified may be shorter than 255 characters due to OS restrictions.

After a command that creates a stub (stbmake or tpstbmk command) is executed, a stub source file is created under a name different from that of the XATMI interface definition file. Therefore, the XATMI interface definition file is not used while OpenTP1 running.

If the same typed buffer is to be used by different processes, the user can create a definition file for the shared typed buffer 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 a 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 a stub creation command (stbmake or tpstbmk command) 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 functions 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 function 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 buffers.
2. Service function 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, a stub creation command (stbmake or tpstbmk command) returns with an error.
4. Identical service function 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.