Communication data belongs to a type and a subtype. The type and subtype of communication data to be used by a UAP are specified in the stub source file (XATMI interface definition) which is used for creating the UAP. For XATMI interface definitions, see the applicable OpenTP1 Programming Reference manual.

(a) Type

A type identifies a kind of communication data as defined in the XATMI interface. Each type is characterized by the following:

• X_OCTET
  Data of this type is an octet array (byte string). The X_OCTET type has no subtype.
  
• X_COMMON
  Data of this type is a structure or record that is not nested. A subtype identifies the construction.
  
• X_C_TYPE
  Data of this type is a structure or record that is not nested. A subtype identifies the construction.
  

(b) Subtype

A subtype identifies a structure or record whose elements are populated with data in a range compatible with the type.

For the data types that can be used as communication data types, see (3) in 5.1.6 Communication data types.

The use of typed buffers or typed records allows structures in C or records in COBOL to be transferred. If function flags are specified appropriately, it is possible to receive data of a type or subtype of a different data type or of a different size from that specified for reception. However, before a communication data type can be handled by a UAP, it must match the value specified for the UAP in advance in the XATMI interface definition.

If you want to use a typed buffer, define its type, subtype, and data type in the XATMI interface definition (for the server UAP). When a stub is created from the XATMI interface definition file and the stub object file is linked to the server UAP, the typed buffer can be used. For XATMI interface definitions, see the applicable OpenTP1 Programming Reference manual.

Even when OSI TP is used as the protocol for communication with a non-OpenTP1 system, a typed buffer or type record can be sent to the remote system after it is converted so that it will be recognized by the remote system.

The table below lists the data types that can be used with each communication data type. The identifier indicates the data type that must be specified in the XATMI interface definition. The data type in C and the data in COBOL indicates the typed buffer or typed record that is actually defined in the stub. To convert a data type as preparation for communication with a non-OpenTP1 system, specify the identifier requiring conversion in the XATMI interface definition.

Table 5-4 Data types that can be used with each communication data type

Type	Identifier	Data type in C	Data in COBOL	Communication protocol		Remarks
				TCP/IP	OSI TP
X_OCTET	--#1	--#1	--#1	Y	Y	None
X_COMMON	short a	short a	PIC S9(9) COMP-5	Y	Y	None
	short a[n]	short a[n]	PIC S9(9) COMP-5 OCCURS n TIMES	Y	Y	None
	long a	long a	PIC S9(9) COMP-5	Y	Y	None
	long a[n]	long a[n]	PIC S9(9) COMP-5 OCCURS n TIMES	Y	Y	None
	char a#2	char a	PIC X	Y	Y	Array not to be converted
	octet a	char a	PIC X	Y	Y	Array not to be converted
	tchar a	char a	PIC X	-	Y	Array to be converted
	char a[n]#2	char a[n]	PIC X(n)	Y	Y	Array not to be converted
	octet a[n]	char a[n]	PIC X(n)	Y	Y	Array not to be converted
	tchar a[n]	char a[n]	PIC X(n)	-	Y	Array to be converted
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 under this communication protocol.

N: Cannot be used under this 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 can be used, but the following identifier should be used if you are in process of creation.

octet or tchar for X_COMMON

str or tstr for X_C_TYPE

Explained below is how to use XATMI interface functions for manipulating communication data. The API that can manipulate communication data can be used only via the C language. There is no COBOL API for manipulating communication data.

(a) Allocation of typed buffer

To allocate a typed buffer, issue the function tpalloc() with a type and a subtype values from the UAP. The area allocated by the function tpalloc() is cleared to NULL.

(b) Reallocation of typed buffer

To expand a typed buffer, use the function tprealloc(). The typed buffer available with the function tprealloc() is only X_OCTET. If another typed buffer is specified, the function returns with an error. If the new buffer length is shorter than the data, the data is truncated. If the new buffer length is longer than the data, the extra area is cleared to NULL.

If reallocation fails, the old typed buffer is also invalidated.

(c) Deallocation of typed buffer

To deallocate the allocated area, call the function tpfree() having a pointer to the typed buffer as its argument. A value which is not a typed buffer pointer is ignored even if it is specified.

(d) Acquisition of typed buffer information

To acquire the type or other information about a buffer, call the function tptypes().

(e) Notes on typed buffer operation

Do not use functions for typed buffer operation in combination with the functions malloc(), realloc(), or free() in the C library. For example, the buffer allocated by the function tpalloc() cannot be deallocated by the function free(). If the function free() is called for the allocated typed buffer, the result is unpredictable.

The typed buffer of the X_OCTET type is partially different from other typed buffers. Notes on using the typed buffer of the X_OCTET type are given below.

1. The typed buffer of the X_OCTET type has no subtype (structure) (no subtype-specific information is needed).
2. Data is send without conversion (data is treated only as a bit array).
3. A parameter indicating the length must be specified.