Document revision date: 15 July 2002

DECdtm is a distributed transaction manager that coordinates the activity of resource managers used by an application. DECdtm services are embedded in the OpenVMS operating system and fully support distributed databases using a two-phase commit protocol. The DECdtm services provide the technology and features for distributed processing, ensuring both transaction and database integrity across multiple Compaq resource managers.

DECdtm V2.0 implements the XA standard interface from the X/Open distributed transaction model. The XA interface provides transaction processing interoperability across OpenVMS Oracle/Rdb, OpenVMS Oracle 8i/9i, RMS Journaling, and ACMS. DECdtm V2.0 can interface with XA compliant transaction managers, such as BEA Tuxedo and Compaq's Reliable Transaction Router (RTR).

DECdtm with XA provides:

• Distributed transaction coordination between applications and Oracle 9i, Oracle RDB, and RMS databases.
• ACMS access to the Oracle 9i databases, in addition to Oracle RDB and RMS.
• Transaction and data integrity, allowing for greater transaction interoperability.

This chapter describes new features relating to application and system programming on this version of the Compaq OpenVMS operating system.

5.1 Taking Advantage of Performance-Enhancing Features of Alpha Processors

Each generation of Alpha processors has different characteristics. Applications built to run on one generation of processors continue to run on newer generations. However, newer generations of processors are usually more capable and perform better than previous generations. By rebuilding applications for newer processors, you can take advantage of their new performance-enhancing capabilities and features.

A white paper tells image-providers---ISVs or product developers---how they can take advantage of some of the performance-enhancing features of newer Alpha processors. The HTML and PDF versions of the paper are at the following web site:

The /SHADOW_MEMBER qualifier in the Alpha System Analysis tool ANALYZE Usage Summary specifies which member of a shadow set contains the system dump to be analyzed, or allows the user to determine what system dumps have been written to the member of the shadow set. For more information, refer to the OpenVMS Alpha System Analysis Tools Manual.

5.3 Compaq C Run-Time Library Enhancements

The following sections describe the Compaq C RTL enhancements included in OpenVMS Version 7.3--1. These enhancements provide improved UNIX compatibility and the flexibility of user-controlled feature selections. For more details, refer to the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

5.3.1 Files Larger Than 2 Gigabytes

Support has been added for compiling applications to use file sizes and offsets that are 2 gigabytes or larger. This is accomplished by allowing file offsets of 64-bit integers. Two new functions have been added:

fseeko ftello

These are identical to fseek and ftell , but they accept or return values of type off_t , which allows for a 64-bit variant of off_t to be used.

Modifications to accommodate a 64-bit file offset have been made to the following existing C RTL functions:

fstat ftruncate ftw lseek mmap stat truncate

The new 64-bit interfaces can be selected at compile time by defining the _LARGEFILE feature macro:

$ CC /DEFINE=_LARGEFILE

5.3.2 Enabling C RTL Features at Compile/Link Time

The C RTL now provides an extensive list of feature switches that affect an application's behavior. They can be used to enable new behaviors or preserve previous, depreciated behaviors. You can enable or disable these features at run time using DECC$ logical names. For more information, see Section 4.10.4.5 and refer to the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

A programmable interface is also available to sense or set feature switches within an application. By using this interface in a function referenced by the global symbol LIB$INITIALIZE, you can enable or disable features before the C RTL is initialized.

In many instances, you can enable new behaviors by using feature switches. This will preserve existing behavior as the default. If an application needs to select a different default behavior, a user can then modify the run-time behavior using a logical name.

For some applications, some feature-switch settings may be necessary. In this case, they can be set in a way that a logical name cannot override the value.

There are four functions provided to do this:

int decc$feature_get_index(char *name);
char *decc$feature_get_name(int index);
int decc$feature_get_value(int index, int mode);
int decc$feature_set_value(int index, int mode, int value);

The Compaq C RTL can be instructed to accept UNIX style file and directory path names that contain the extended ASCII character set supported by OpenVMS Extended File Specifications (EFS) on ODS-5 devices.

To enable this feature, define the DECC$FILENAME_UNIX_ONLY logical name to ENABLE before program execution:

$ DEFINE DECC$FILENAME_UNIX_ONLY ENABLE

With this feature enabled, all file and path specifications input to the Compaq C RTL are assumed to be UNIX style and therefore can consist of the full, printable ASCII character set (20-7E hexadecimal), with the following exceptions:

* (asterisk)
? (quotation mark)
/ (forward slash)
" (double quotation mark)

The Compaq C RTL provides any necessary enclosing quotation marks for special characters when presenting the file specification to the OpenVMS file system. OpenVMS file and path specifications that are output by the Compaq C RTL are converted to UNIX style where appropriate, and any special characters quoted by the OpenVMS file system are unquoted before being returned to the Compaq C RTL caller. In addition, the OpenVMS version number field is stripped from the file name on output.

For example, assume the following UNIX style path name is input:

./abc.d/data.dat.dat

The Compaq C RTL converts it to the following before passing it on to the OpenVMS file system:

[.abc^.d]data^.dat.dat

The caret (^) character is the EFS quote or escape character. (For more information about escape characters and name and type delimiters, refer to the OpenVMS User's Manual.) When this file name is retrieved, it is output to the Compaq C RTL caller just as it was input, with quoted characters unquoted.

Note that, under normal Compaq C RTL parsing rules, an OpenVMS version field in a UNIX style input file name is passed directly to the file system. Therefore, the following example accesses version number 3 of the file with name data and type dat :

data.dat;3

With the new feature, this file name is passed to the OpenVMS file system as the following (a file with name data and type dat;3 ):

data.dat^;3

The OpenVMS version number associated with the file is not returned on output.

The scope of this feature applies to allowable characters in both the directory and file-name fields of a UNIX style specification. Enabling this feature does not affect other features of the Compaq C RTL UNIX-to-OpenVMS and OpenVMS-to-UNIX path conversion. If logical-name expansion of the first element in the UNIX specification is enabled, the Compaq C RTL does not quote any special characters that appear in the logical-name equivalence string before presentation to the file system.

5.3.4 POSIX Root Support

Support has been added to provide OpenVMS with a UNIX style root that behaves like a real directory. This allows such actions as the following:

% cd / % mkdir /dirname % tar -xvf tarfile.tar /dirname % ls /

Previously, the C RTL did not recognize the slash (/) character as a directory name. The normal processing for a file path starting with the slash character was to interpret the first element as a logical name or device name. If this failed, there was special processing for the name /dev/null and names starting with /bin and /tmp :

/dev/null NLA0: /bin SYS$SYSTEM: /tmp SYS$SCRATCH:

These behaviors are retained for compatibility purposes. In addition, support has been added to the C RTL for the logical name SYS$POSIX_ROOT as an equivalent to the slash character.

To enable this feature for use by the C RTL, define SYS$POSIX_ROOT as a concealed logical name. For example:

$ DEFINE/TRANSLATION=(CONCEALED,TERMINAL) SYS$POSIX_ROOT "$1$DKA0:[SYS0.abc.]"

To disable this feature, enter the following command:

$ DEFINE DECC$DISABLE_POSIX_ROOT {1, ENABLE 0, DISABLE}

Enabling SYS$POSIX_ROOT results in the following behavior:

• If the existing translation of a UNIX path starting with the slash (/) character fails and SYS$POSIX_ROOT is defined, the name is interpreted as if it starts with /sys$posix_root .
• When converting from an OpenVMS to a UNIX style file name, and the OpenVMS name starts with SYS$POSIX_ROOT:, then the SYS$POSIX_ROOT: portion is removed. For example, SYS$POSIX_ROOT:[dirname] becomes /dirname . If the resulting name could be interpreted as a logical name or as one of the special cases listed, the result is /./dirname instead of /dirname .

The C RTL supports 32-bit user identification (UID) and group identification (GID). 32-bit UID and GID support was added to some versions of the OpenVMS operating system to provide support for POSIX style identifiers.

Although OpenVMS 7.3-1 does not support POSIX style IDs, it does support 32-bit UID and GID. When an application is compiled to use 32-bit UID/GID, the UID and GID are derived from the UIC, as in previous versions of the operating system. In some cases, such as with the getgroups function, more information might be returned when the application supports 32-bit GIDs.

To compile an application for 32-bit UID or GID support, define the macro __USE_LONG_GID_T. To compile an application for 16-bit UID or GID support, define the macro _DECC_SHORT_GID_T.

In addition, although you cannot compile with POSIX style IDs enabled on OpenVMS Version 7.3-1, you can run programs that were compiled with POSIX style IDs enabled on OpenVMS systems that do provide that support.

5.3.6 New and Changed C RTL Functions

The Compaq C RTL includes the following new or modified functions for OpenVMS Version 7.3--1:

• New feature switch-setting functions:

  decc$feature_get_index decc$feature_get_name decc$feature_get_value decc$feature_set_value

• New scanf functions:

  vfscanf vfwscanf vscanf vwscanf vsscanf vswscanf

• New functions to support 64-bit file sizes and offsets:

  fseeko ftello

• Functions modified to support 64-bit file sizes and offsets:

  fstat ftruncate ftw lseek mmap stat truncate

DECdtm provides basic infrastructure for a distributed transaction processing system. Several DECdtm system services are now documented. For information about the XA capability with DECdtm, see Section 4.24.

Table 5-1 lists all newly documented DECdtm system services.

Table 5-1 DECdtm System Services

System Service	System Service with Wait	Description
$ABORT_TRANS	$ABORT_TRANSW	Aborts a transaction.
$ACK_EVENT		Acknowledges an event reported to an RM participant or an RMI.
$ADD_BRANCH	$ADD_BRANCHW	Authorizes a new branch to be added to a transaction.
$CREATE_UID		Generates a universally unique identifier.
$DECLARE_RM	$DECLARE_RMW	Creates a new resource manager instance (RMI).
$END_BRANCH	$END_BRANCHW	Removes a branch from a transaction and returns the transaction outcome.
$END_TRANS	$ENDTRANSW	Ends a transaction.
$FORGET_RM	$FORGETRMW	Deletes an RMI from the calling process.
$GET_DEFAULT_TRANS		Returns the default transaction of the calling process.
$GETDTI	$GETDTIW	Returns information about the state of individual transactions.
$JOIN_RM	$JOIN_RMW	Adds a new RM participant to a transaction.
$SET_DEFAULT_TRANS	$SET_DEFAULT_TRANSW	Sets or clears the default transaction of the calling process.
$SETDTI	$SETDTIW	Sets process current transaction and removes resource managers from transactions.
$START_BRANCH	$START_BRANCHW	Adds a new branch to a transaction.
$START_TRANS	$START_TRANSW	Starts a transaction.
$TRANS_EVENT	$TRANS_EVENTW	Forces certain transaction state changes.

For More Information On	See
DECdtm system services	OpenVMS System Services Reference Manual
Managing DECdtm and XA transactions	OpenVMS System Manager's Manual
XGCP Utility used with DECdtm/XA	OpenVMS System Management Utilities Reference Manual
Programming with DECdtm and XA	OpenVMS Programming Concepts Manual, Volume II

5.5 Open Source Security for OpenVMS---CDSA and SSL

Common Data Security Architecture (CDSA) is a multiplatform, industry-standard security infrastructure. It provides a standards-based, stable programming interface that applications can use to access operating system security services, allowing developers to create cross-platform, security-enabled applications. Applications request security services, such as cryptography and other public key operations, through a dynamically extensible application programming interface (API). These requests are serviced by a set of plug-in security service provider interfaces (SPIs), which can be supplemented or changed as business needs and technologies evolve.

Compaq SSL (Secure Sockets Layer) for OpenVMS Alpha provides industry standard tools that enable secure and accurate network communications with OpenVMS systems in the enterprise. Using strong cryptography and sophisticated hashing algorithms, messages are encrypted for secure transmission and the integrity of the data is validated, ensuring that all data arrived intact and unmodified.

Secure Sockets Layer (SSL) is the open standard security protocol for the secure transfer of sensitive information over the Internet. SSL provides three major capabilities:

• Privacy through encryption
• Server authentication
• Message integrity

Client authentication is available as an optional function.

Compaq SSL V1.0 for OpenVMS Alpha ports the SSL 0.9.6B toolkit and cryptography library to OpenVMS Alpha Version 7.3--1. Compaq SSL for OpenVMS Alpha provides a certificate tool that is a simple interface for viewing and creating SSL certificates. The SSL Certificate Tool enables you to perform the most important certification functions with ease:

• View certificates and certificate requests
• Create certificate requests
• Sign your own certificate
• Create your own certificate authority
• Sign client certificate requests

Additional hash functions are included.

For more detailed information, refer to the Open Source Security for OpenVMS Alpha, Volume 1: Common Data Security Architecture or Open Source Security for OpenVMS Alpha, Volume 2: Compaq SSL (Secure Sockets Layer) for OpenVMS Alpha.

5.6 Using LDAP with Compaq SSL for OpenVMS

Customers who need added security protection for their enterprise information stored in an LDAP directory can now use Compaq SSL for OpenVMS Alpha in an LDAP session. SSL uses X.509 public key technology to provide the following security functions:

• Integrity and confidentiality of the LDAP dialogue
• Authentication of the client
• Authentication of the server

When you connect to an LDAP directory, you need to log in to use certain services. This involves sending a bind() request to the server. The username/password in a simple bind is sent in clear text. SSL is important because, with Compaq SSL, this bind request is encrypted making the password unreadable except to the server.

For details, refer to the LDAP chapter in the OpenVMS Utility Routines Manual.

5.7 New Alpha Floating-Point Registers and Execution Data Block (FRED)

A new structure, the floating-point registers and execution data block (FRED), is a combined structure that contains the HWPCB, the floating-point register save area, and the per-kernel thread data. Prior to Version 7.2, OpenVMS supported 16 kernel threads per process. With Version 7.2 and later, OpenVMS supported 256 kernel threads per process. Also, prior to Version 7.3--1, OpenVMS allocated the maximum number of FRED blocks for a given process when that process was created, even if the process did not become multithreaded. With Version 7.3--1, OpenVMS allocates all FRED blocks on an as-needed basis. This results in improved scaling and performance for applications using kernel threads.

For more information, refer to the OpenVMS Programming Concepts Manual, Volume I.

5.8 Future Architecture-Specific Code Changes

With the upcoming port of the OpenVMS operating system to the Intel Itanium processor architecture, customers should be aware of conflicts arising from the use of the SYI$_HW_MODEL system service to determine the processor architecture. Previously, HW_MODEL 1024 and greater indicated an Alpha system. With the Itanium-based systems, this will no longer be true.

Compaq recommends that customers determine the system achitecture by using either the SYI$_ARCH_TYPE or SYI$_ARCH_NAME system services on all platforms.

The following table lists the specific system services and their current return values or working suggestions:

Processor	Value Returned
System Marketing Model (SMM), SYI$_HW_MODEL, word field1
VAX	1:1023	VAX$K_name highest issued: 541
Alpha	1024:4095	ALPHA$K_name highest issued: 2006
Itanium Processor	4096:8191	IPF$K_name
CPQ Reserved	8191:32767
ISV Reserved	32768:65535
SYI$_ARCH_NAME, fifteen characters
VAX	"VAX"
Alpha	"Alpha"
Itanium Processor	"IA-64"
OTHER	"OTHER"
SYI$_ARCH_TYPE, longword
OTHER	0
VAX	1
Alpha	2
Itanium Processor	3
SYI$_NODE_SWTYPE, longword
All	"VMS"
SYI$_CPU, longword
VAX	CPU code
Others	SS$_NOTAVAX
SYI$_CPUTYPE (and SYI$_REAL_CPUTYPE), longword
Alpha	Alpha microprocessor core code
Others	SS$_NOTALPHA (new)
SYI$_CPULID (new) (and SYI$_REAL_CPULID), longword
Itanium Processor	Itanium Processor LID value
Others	SS$_NOTIA64 (new)
SYI$_SID, longword
VAX	CPU code
Others	256
SYI$_CPULID (new) (and SYI$_REAL_CPULID), longword
Itanium Processor	Itanium Processor LID value
Others	SS$_NOTIA64 (new)
SYI$_SID, longword
VAX	CPU code
Others	256
SYI$_SYSTYPE, longword
VAX	Not implemented on VAX
Alpha	Alpha platform family code 1:63	highest issued: 40
Itanium Processor	Itanium Processor platform family code (64:255)
256:32767	Compaq reserved
32768:~0	ISV reserved
SYI$_XCPU, longword
All	Implementation-specific
SYI$_XSID, longword
All	Implementation-specific

	privacy and legal statement
6657PRO_006.HTML