Preface

This manual is intended for programmers who create application programs used with TP1/Server Base or TP1/LiNK.

Readers of this manual are assumed to have knowledge about operating systems, online systems, handling of the machine to be used, and the syntax of the high-level language (C, C++, or COBOL) used for coding application programs.

This manual assumes that the reader has read the OpenTP1 Description manual or TP1/LiNK User's Guide manual.

This manual is organized into the following chapters and appendixes:

1. OpenTP1 Application Programs

This chapter outlines application programs used with OpenTP1.

2. Basic OpenTP1 Facilities (TP1/Server Base, TP1/LiNK)

This chapter explains the facilities available with application programs which run at nodes comprising only the base product of OpenTP1 system, TP1/Server Base or TP1/LiNK.

3. Facilities Provided by TP1/Message Control

This chapter explains the facilities available with application programs which run at nodes where the product for message exchanging mode communication, TP1/Message Control, is installed in the system.

4. Facilities for User Data

This chapter explains how to use various user files with OpenTP1 application programs.

5. X/Open-compliant Application Programming Interface

This chapter explains the X/Open specification which is useful for OpenTP1 application programs.

6. X/Open-compliant Inter-application Communication (TxRPC)

This chapter explains the X/Open specification which can be created as an OpenTP1 application program (TxRPC interface).

7. Facilities Provided by TP1/Multi

This chapter explains the facilities available with application programs which run at nodes where the product TP1/Multi for a cluster/parallel mode OpenTP1 system is installed in the system.

8. OpenTP1 Samples

This chapter explains how to use samples given by the OpenTP1 for easy setup of the system.

A. Output Format of Undecided Transaction Information

This appendix explains the output format of undecided transaction information to be used for analyzing the conditions of transactions which have not been processed successfully.

B. Output Format of Deadlock Information

This appendix explains the output format of deadlock and timeout information which will be output by OpenTP1 when a deadlock between application programs occurs.

C. Examples of System Configurations Requiring Consideration of the Multi-Scheduler Facility

This appendix explains the examples of system configurations for which you should consider the multi-scheduler facility and examples of resolutions. As systems become larger and machines and networks boast increasingly better performances, conventional scheduler may experience difficulty scheduling messages efficiently.

This manual is part of a related set of manuals. The manuals in the set are listed below (with the manual numbers):

OpenTP1 products

• OpenTP1 Version 7 Description (3000-3-D50(E))
• OpenTP1 Version 7 Programming Guide (3000-3-D51(E))
• OpenTP1 Version 7 System Definition (3000-3-D52(E))
• OpenTP1 Version 7 Operation (3000-3-D53(E))
• OpenTP1 Version 7 Programming Reference C Language (3000-3-D54(E))
• OpenTP1 Version 7 Programming Reference COBOL Language (3000-3-D55(E))
• OpenTP1 Version 7 Messages (3000-3-D56(E))
• OpenTP1 Version 7 Tester and UAP Trace User's Guide (3000-3-D57(E))
• OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/W, TP1/Client/P (3000-3-D58(E))
• OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/J (3000-3-D59(E))
• OpenTP1 Version 7 TP1/LiNK User's Guide (3000-3-D60(E))^#
• OpenTP1 Version 7 Protocol TP1/NET/TCP/IP (3000-3-D70(E))
• OpenTP1 Version 7 TP1/Message Queue User's Guide (3000-3-D90(E))^#
• OpenTP1 Version 7 TP1/Message Queue Messages (3000-3-D91(E))^#
• OpenTP1 Version 7 TP1/Message Queue Application Programming Guide (3000-3-D92(E))^#
• OpenTP1 Version 7 TP1/Message Queue Application Programming Reference (3000-3-D93(E))^#

Other OpenTP1 products

• TP1/Web User's Guide and Reference (3000-3-D62(E))^#

Other related products

• Indexed Sequential Access Method ISAM (3000-3-046(E))
• XP/W (3000-3-047(E))
• Extended Mapping Service 2/Workstation XMAP2/W DESCRIPTION/USER'S GUIDE (3000-7-421(E))
• SEWB 3 General Information (3000-7-450(E))
• Job Management Partner 1/Base User's Guide (3020-3-K06(E))
• Job Management Partner 1/Base Messages (3020-3-K07(E))
• Job Management Partner 1/Base Software Developer's Guide (3020-3-K08(E))

For OpenTP1 protocol manuals, please check whether English versions are available.

#

If you want to use this manual, confirm that it has been published. (Some of these manuals might not have been published yet.)

Reference manuals for using TP1/Message Control (message exchanging facility)

The OpenTP1 Version 6 Programming Reference manual does not contain information about syntax which, when TP1/Message Control is in use, is specific to products supporting the communication protocol. For the syntax of the following APIs, see the OpenTP1 Protocol manual in the version for the pertinent protocol:

• Receive a message (dc_mcf_receive(), CBLDCMCF('RECEIVE '))
• Receive a synchronous message (dc_mcf_recvsync(), CBLDCMCF('RECVSYNC'))
• Send a response message (dc_mcf_reply(), CBLDCMCF('REPLY '))
• Resend a message (dc_mcf_resend(), CBLDCMCF('RESEND '))
• Send a message (dc_mcf_send(), CBLDCMCF('SEND '))
• Exchange a synchronous message (dc_mcf_sendrecv(), CBLDCMCF('SENDRECV'))
• Send a synchronous message (dc_mcf_sendsync(), CBLDCMCF('SENDSYNC'))

This manual uses the following abbreviations for product names:

Abbreviation			Full name or meaning
AIX			AIX 5L V5.1
			AIX 5L V5.2
			AIX 5L V5.3
			AIX V6.1
Client .NET		TP1/Client for .NET Framework	uCosminexus TP1/Client for .NET Framework
Connector .NET		TP1/Connector for .NET Framework	uCosminexus TP1/Connector for .NET Framework
DPM			JP1/ServerConductor/Deployment Manager
HI-UX/WE2			HI-UX/workstation Extended Version 2
HP-UX	HP-UX (IPF)		HP-UX 11i V2 (IPF)
			HP-UX 11i V3 (IPF)
	HP-UX (PA-RISC)		HP-UX 11i V1 (PA-RISC)
			HP-UX 11i V2 (PA-RISC)
IPF			Itanium(R) Processor Family
Java			JavaTM
JP1	JP1/AJS2	JP1/AJS2 - Agent	JP1/Automatic Job Management System 2 - Agent
		JP1/AJS2 - Manager	JP1/Automatic Job Management System 2 - Manager
		JP1/AJS2 - View	JP1/Automatic Job Management System 2 - View
	JP1/AJS2 - Scenario Operation	JP1/AJS2 - Scenario Operation Manager	JP1/Automatic Job Management System 2 - Scenario Operation Manager
		JP1/AJS2 - Scenario Operation View	JP1/Automatic Job Management System 2 - Scenario Operation View
		JP1/NETM/Audit	JP1/NETM/Audit - Manager
Linux			Linux(R)
Linux (AMD64/Intel EM64T/x86)			Red Hat Enterprise Linux AS 4 (AMD64 & Intel EM64T)
			Red Hat Enterprise Linux AS 4 (x86)
			Red Hat Enterprise Linux ES 4 (AMD64 & Intel EM64T)
			Red Hat Enterprise Linux ES 4 (x86)
			Red Hat Enterprise Linux 5 (AMD/Intel 64)
			Red Hat Enterprise Linux 5 (x86)
			Red Hat Enterprise Linux 5 Advanced Platform (AMD/Intel 64)
			Red Hat Enterprise Linux 5 Advanced Platform (x86)
Linux (IPF)			Red Hat Enterprise Linux AS 4 (IPF)
			Red Hat Enterprise Linux 5 (Intel Itanium)
			Red Hat Enterprise Linux 5 Advanced Platform (Intel Itanium)
MS-DOS			Microsoft(R) MS-DOS(R)
NETM/DM			JP1/NETM/DM Client
			JP1/NETM/DM Manager
			JP1/NETM/DM SubManager
Oracle			Oracle 10g
			Oracle9i
Solaris			Solaris 8
			Solaris 9
			Solaris 10
TP1/Client		TP1/Client/J	uCosminexus TP1/Client/J
		TP1/Client/P	uCosminexus TP1/Client/P
		TP1/Client/W	uCosminexus TP1/Client/W
			uCosminexus TP1/Client/W(64)
TP1/EE			uCosminexus TP1/Server Base Enterprise Option
			uCosminexus TP1/Server Base Enterprise Option(64)
TP1/Extension 1			uCosminexus TP1/Extension 1
			uCosminexus TP1/Extension 1(64)
TP1/FS/Direct Access			uCosminexus TP1/FS/Direct Access
			uCosminexus TP1/FS/Direct Access(64)
TP1/FS/Table Access			uCosminexus TP1/FS/Table Access
			uCosminexus TP1/FS/Table Access(64)
TP1/High Availability			uCosminexus TP1/High Availability
			uCosminexus TP1/High Availability(64)
TP1/LiNK			uCosminexus TP1/LiNK
TP1/Message Control			uCosminexus TP1/Message Control
			uCosminexus TP1/Message Control(64)
TP1/Message Control/Tester			uCosminexus TP1/Message Control/Tester
TP1/Message Queue			uCosminexus TP1/Message Queue
			uCosminexus TP1/Message Queue(64)
TP1/Message Queue - Access			uCosminexus TP1/Message Queue - Access
			uCosminexus TP1/Message Queue - Access(64)
TP1/Messaging			uCosminexus TP1/Messaging
TP1/Multi			uCosminexus TP1/Multi
TP1/NET/HDLC			uCosminexus TP1/NET/HDLC
TP1/NET/High Availability			uCosminexus TP1/NET/High Availability
			uCosminexus TP1/NET/High Availability(64)
TP1/NET/HSC			uCosminexus TP1/NET/HSC
TP1/NET/Library			uCosminexus TP1/NET/Library
			uCosminexus TP1/NET/Library(64)
TP1/NET/NCSB			uCosminexus TP1/NET/NCSB
TP1/NET/OSAS-NIF			uCosminexus TP1/NET/OSAS-NIF
TP1/NET/OSI-TP			uCosminexus TP1/NET/OSI-TP
TP1/NET/SLU - TypeP2		TP1/NET/Secondary Logical Unit - TypeP2	uCosminexus TP1/NET/Secondary Logical Unit - TypeP2
TP1/NET/TCP/IP			uCosminexus TP1/NET/TCP/IP
			uCosminexus TP1/NET/TCP/IP(64)
TP1/NET/UDP			uCosminexus TP1/NET/User Datagram Protocol
TP1/NET/User Agent			uCosminexus TP1/NET/User Agent
TP1/NET/X25			uCosminexus TP1/NET/X25
TP1/NET/X25-Extended			uCosminexus TP1/NET/X25-Extended
TP1/NET/XMAP3			uCosminexus TP1/NET/XMAP3
TP1/Offline Tester			uCosminexus TP1/Offline Tester
TP1/Online Tester			uCosminexus TP1/Online Tester
TP1/Resource Manager Monitor			uCosminexus TP1/Resource Manager Monitor
TP1/Server Base			uCosminexus TP1/Server Base
			uCosminexus TP1/Server Base(64)
TP1/Shared Table Access			uCosminexus TP1/Shared Table Access
TP1/Web			uCosminexus TP1/Web
Windows 2000			Microsoft(R) Windows(R) 2000 Advanced Server Operating System
			Microsoft(R) Windows(R) 2000 Datacenter Server Operating System
			Microsoft(R) Windows(R) 2000 Professional Operating System
			Microsoft(R) Windows(R) 2000 Server Operating System
Windows Server 2003			Microsoft(R) Windows Server(R) 2003, Datacenter Edition
			Microsoft(R) Windows Server(R) 2003, Enterprise Edition
			Microsoft(R) Windows Server(R) 2003, Standard Edition
Windows Server 2003 R2			Microsoft(R) Windows Server(R) 2003 R2, Enterprise Edition
			Microsoft(R) Windows Server(R) 2003 R2, Standard Edition
Windows Server 2003 x64 Editions			Microsoft(R) Windows Server(R) 2003, Datacenter x64 Edition
			Microsoft(R) Windows Server(R) 2003, Enterprise x64 Edition
			Microsoft(R) Windows Server(R) 2003, Standard x64 Edition
Windows Server 2003 R2 x64 Editions			Microsoft(R) Windows Server(R) 2003 R2, Enterprise x64 Edition
			Microsoft(R) Windows Server(R) 2003 R2, Standard x64 Edition
Windows Server 2008			Microsoft(R) Windows Server(R) 2008 Datacenter (x86)
			Microsoft(R) Windows Server(R) 2008 Enterprise (x86)
			Microsoft(R) Windows Server(R) 2008 Standard (x86)
Windows Server 2008 x64 Editions			Microsoft(R) Windows Server(R) 2008 Datacenter (x64)
			Microsoft(R) Windows Server(R) 2008 Enterprise (x64)
			Microsoft(R) Windows Server(R) 2008 Standard (x64)
Windows Vista			Microsoft(R) Windows Vista(R) Business (x86)
			Microsoft(R) Windows Vista(R) Enterprise (x86)
			Microsoft(R) Windows Vista(R) Ultimate (x86)
Windows Vista x64 Editions			Microsoft(R) Windows Vista(R) Business (x64)
			Microsoft(R) Windows Vista(R) Enterprise (x64)
			Microsoft(R) Windows Vista(R) Ultimate (x64)
Windows XP			Microsoft(R) Windows(R) XP Professional Operating System

• If there is no difference in OS functionality, the term Windows is used to indicate Windows 2000, Windows Server 2003, Windows Server 2008, Windows XP, and Windows Vista.
• The term UNIX is used to indicate AIX, HP-UX, Linux, and Solaris.

This manual also uses the following acronyms:

Acronym	Full name or meaning
ANSI	American National Standards Institute
AP	Application Program
API	Application Programming Interface
CPU	Central Processing Unit
CRM	Communication Resource Manager
CUP	Client User Program
DAM	Direct Access Method
DBMS	Database Management System
DCE	Distributed Computing Environment
DML	Data Manipulation Language
DNS	Domain Name System
GUI	Graphical User Interface
HA	High Availability
I/O	Input/Output
ID	Identifier
IDL	Interface Definition Language
ISAM	Indexed Sequential Access Method
IST	Internode Shared Table
LAN	Local Area Network
MCF	Message Control Facility
MHP	Message Handling Program
MQI	Message Queue Interface
OS	Operating System
OSI	Open Systems Interconnection
OSI TP	Open Systems Interconnection Transaction Processing
PC	Personal Computer
PRF	Performance
RM	Resource Manager
RPC	Remote Procedure Call
RTS	Real Time Statistic
SPP	Service Providing Program
SUP	Service Using Program
TAM	Table Access Method
TCP/IP	Transmission Control Protocol/Internet Protocol
UAP	User Application Program
UOC	User Own Coding
VM	Virtual Machine
WAN	Wide Area Network
WS	Workstation
XA	Extended Architecture
XAR	Extended Architecture Resource

This manual uses the following conventions in diagrams:

The JIS code and ASCII code keyboards are different in the input characters represented by the following codes. In this manual, the use of a JIS keyboard is assumed for these characters.

Code	JIS keyboard	ASCII keyboard
(5c)16	(yen symbol)	\ (backslash)
(7e)16	(overline)	~ (tilde)

This manual uses the notation /BeTRAN to indicate the OpenTP1 installation directory. The actual installation directory differs depending on the operating system. Use the following table to determine the actual installation directory for your OS.

As written in this manual	Actual directory for each OS
	AIX, HP-UX, and Solaris	Linux	Windows
/BeTRAN	/BeTRAN	/opt/OpenTP1	The directory in which OpenTP1 was installed

The following table explains the fonts used in this manual:

Font	Convention
Bold	Bold type indicates text on a window, other than the window title. Such text includes menus, menu options, buttons, radio box options, or explanatory labels. For example: From the File menu, choose Open. Click the Cancel button. In the Enter name entry box, type your name.
Italics	Italics are used to indicate a placeholder for some actual text to be provided by the user or system. For example: Write the command as follows: copy source-file target-file The following message appears: A file was not found. (file = file-name) Italics are also used for emphasis. For example: Do not delete the configuration file.
Code font	A code font indicates text that the user enters without change, or text (such as messages) output by the system. For example: At the prompt, enter dir. Use the send command to send mail. The following message is displayed: The password is incorrect.

The following table explains the symbols used in this manual:

Symbol	Convention
|	In syntax explanations, a vertical bar separates multiple items, and has the meaning of OR. For example: A|B|C means A, or B, or C.
{ }	In syntax explanations, curly brackets indicate that only one of the enclosed items is to be selected. For example: {A|B|C} means only one of A, or B, or C.
[ ]	In syntax explanations, square brackets indicate that the enclosed item or items are optional. For example: [A] means that you can specify A or nothing. [B|C] means that you can specify B, or C, or nothing.
...	In coding, an ellipsis (...) indicates that one or more lines of coding are not shown for purposes of brevity. In syntax explanations, an ellipsis indicates that the immediately preceding item can be repeated as many times as necessary. For example: A, B, B, ... means that, after you specify A, B, you can specify B as many times as necessary.

This manual uses the following conventions:

• 1 KB (kilobyte) is 1,024 bytes.
• 1 MB (megabyte) is 1,024² bytes.
• 1 GB (gigabyte) is 1,024³ bytes.
• 1 TB (terabyte) is 1,024⁴ bytes.

For the Windows version of OpenTP1, there are some notational differences from the description in the manual. The following table describes these differences.

Item	Description in the manual	Change to:
Environment variable	$aaaaaa Example: $DCDIR	%aaaaaa% Example: %DCDIR%
Path name separator	Colon (:)	Semicolon (;)
Directory name separator	Slash (/)	Backslash (\)
Absolute path name	A path from the root directory Example: /tmp	A path name from a drive letter and the root directory Example: C:\tmp
Executable file name	File name only (without an extension) Example: mcfmngrd	File name with an extension Example: mcfmngrd.exe
make command	make	nmake

The version numbers of Hitachi program products are usually written as two sets of two digits each, separated by a hyphen. For example:

• Version 1.00 (or 1.0) is written as 01-00.
• Version 2.05 is written as 02-05.
• Version 2.50 (or 2.5) is written as 02-50.
• Version 12.25 is written as 12-25.

The version number might be shown on the spine of a manual as Ver. 2.00, but the same version number would be written in the program as 02-00.

Quotations from X/Open CAE Specification Distributed Transaction Processing: The XATMI Specification published by X/Open Company Limited

The specification as interpreted in the above document is quoted in the following section of this manual to give information about the usage with OpenTP1:

Chapter 5. X/Open-Compliant Application Programming Interface

5.1 XATMI Interface (Client/Server Mode Communication)

Quotations from X/Open CAE Specification Distributed Transaction Processing: The TX (Transaction Demarcation) Specification published by X/Open Company Limited

The specification as interpreted in the above document is quoted in the following section of this manual to give information about the usage with OpenTP1:

Chapter 5. X/Open-Compliant Application Programming Interface

5.2 TX Interface (Transaction Control)

Quotation from X/Open Preliminary Specification Distributed Transaction Processing: The TxRPC Specification published by X/Open Company Limited

The specification as interpreted in the above document is quoted in the following section of this manual to give information about the usage with OpenTP1:

Chapter 6. X/Open-Compliant Inter-Application Communication (TxRPC)

COBOL

COBOL was developed by CODASYL (the Conference on Data Systems Languages). Of the OpenTP1 application programming interface specifications, the data manipulation language (DML) specification was developed by relying on the communication section in CODASYL COBOL (1981) as well as the RECEIVE, SEND, COMMIT, and ROLLBACK statements and adding original specifications and interpretations made by Hitachi, Ltd. The publisher of this manual expresses acknowledgment to the original developer and presents the following acknowledgment statement as requested by CODASYL. This statement is quoted from the acknowledgment in the original CODASYL COBOL specification titled COBOL Journal of Development 1984.

Any organization interested in reproducing the COBOL report and specifications in whole or in part, using ideas from this report as the basis for an instruction manual or for any other purpose, is free to do so. However, all such organizations are requested to reproduce the following acknowledgement paragraphs in their entirety as part of the preface to any such publication. Any organization using a short passage from this document, such as in a book review, is requested to mention "COBOL" in acknowledgement of the source, but need not quote the acknowledgement.

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection therewith.

The authors and copyright holders of the copyrighted material used herein

FLOW-MATIC (trademark of Sperry Rand Corporation), Programming for the Univac (R) I and II, Data Automation Systems copyrighted 1958, 1959, by Sperry Rand Corporation; IBM Commercial Translator Form No. F 28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell

have specifically authorized the use of this material in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications.