On the Part III page, the content in the "Alpha Only" note should be replaced with the following:

This utility runs on OpenVMS Alpha systems only.

On the first page of Chapter 13, the content in the "Alpha Only" note should be replaced with the following:

This utility runs on OpenVMS Alpha systems only.

4.29.39 SET PROCESS/LOG Command

In the format section, ARGS should be replaced with ARGUMENTS.

In description of parameter FLAGS, ARGS should be replaced with ARGUMENTS.

Note that these changes also affect the HP OpenVMS DCL Dictionary: N--Z.

This chapter provides release notes about application and system programming on OpenVMS systems.

5.1 System Service Changes

V8.3

The following sections describe system service changes in this release.

5.1.1 Additions

Additions and changes have been made to the following system services:

• $GETJPI--item codes JPI$_TERMINAL and JPI$_SCHED_CLASS_NAME
• $GETRMI--description changed to: $GETRMI is an asynchronous system service and requires the $SYNCH service or another wait-state synchronous mechanism to guarantee that the required information is available. There is no synchronous wait form for this system service.
• $GETRMI item code change: RMI$_MODES returns the amount of time, in 10-ms units, spent by all currently active CPUs in all processor modes since the system was booted. Each increment in the returned time for a mode represents an additional 10 ms spent by the CPU in that mode. An active CPU is one that is actively participating in the processor scheduling that the OpenVMS instance performs. For additional information, see the $GETRMI system service in the HP OpenVMS System Services Reference Manual.
• $GETSYI--processor codes added for Intel Itanium© 2 and Intel© Itanium 3
• $GETSYI--item code definitions changed:

  SYI$_ACTIVE_CPU_MASK
  SYI$_CPUCONF
  SYI$_IO_PREFER_CPU
  SYI$_POTENTIAL_CPU_MASK
  SYI$_POWERED_CPU_MASK
  SYI$_PRESENT_CPU_MASK

• $INIT_VOL: some item codes now apply to ODS-5 as well as ODS-2

V8.3

In response to customer requests and to allow simpler definition of batch environments, the job limit item codes for two system services are increased in OpenVMS Version 8.3:

• For the $GETQUI system service, the range of the QUI$_JOB_LIMIT item code is now 1 to 65535.
• For the $SNDJBC system service, the range of the SJC$_JOB_LIMIT item code is now 1 to 65535.

V8.2

OpenVMS Alpha Version 8.2 is a major version release in which a number of privileged data structures have changed. It might be necessary to recompile and relink privileged applications linked with /SYSEXE that refer to internal OpenVMS data structures or routines.

If you get a SYSVERDIF error message when you invoke an image or load a device driver, this indicates that the privileged image or driver was compiled and linked under a prior version of the operating system. You must then recompile and relink the image or driver to run on OpenVMS Alpha Version 8.2.

5.4 Privileged Data Structures Updates

V8.2

OpenVMS Version 8.2 contains updates for a number of privileged data structures. These changes apply to both Alpha and I64 systems. The majority of these data structure updates are to support future scaling and performance projects in the operating system. As a result of these changes, any images or drivers that link against the base operating system (that is, those that use /SYSEXE on the LINK command) might need to be recompiled and relinked in order to run on OpenVMS Version 8.2.

The privileged data structure changes do not necessarily affect all privileged images and drivers --- only those linked with one of the specific subsystems that has changed. For these subsystems, the major version identification number associated with the subsystem has been increased. The subsystems that have changed are the following:

SYS$K_IO
SYS$K_MEMORY_MANAGEMENT
SYS$K_CLUSTERS_LOCKMGR
SYS$K_FILES_VOLUMES
SYS$K_CPU
SYS$K_MULTI_PROCESSING
SYS$K_PROCESS_SCHED

Note: On I64 systems, these versions are reported as SYS$K_VERSION_xxxx.

The versions of these subsystems are linked into images based on the usage of various privileged system routines and data cells. You can use the ANALYZE/IMAGE utility to determine with what specific subsystem a privileged image is linked. For example:

$ ANALYZE/IMAGE IMAGE.EXE /OUTPUT=IMAGE.TXT $ SEARCH IMAGE.TXT "SYS$K_"

If any of the versions reported match this list, OpenVMS Version 8.2 will fail to activate the image and issue a SS$_SYSVERDIF (system version mismatch error) for images linked on prior versions of the operating system.

5.4.1 KPB Extensions

V8.2

Prior versions of OpenVMS supported the use of KPBs for kernel mode above IPL 2. To make the transition to I64 easier, usage of KPBs has been expanded for use in outer modes and all IPLs. This Alpha and I64 change allows certain code that previously had private threading packages to make use of KPBs on both Alpha and I64. In order to support these changes to kernel processes, some changes to the KPB structure were required. No source changes should be necessary for existing Alpha code.

5.4.2 CPU Name Space

V8.2

OpenVMS currently has an architectural limit of a maximum CPU ID of 31. Various internal data structures and data cells have allocated 32 bits for CPU masks. We are increasing the amount of space allocated for these masks to 64 bits for Alpha and 1024 bits on I64 to allow supporting larger CPU IDs in a future release. The existing longword CPU mask symbols and data cells will still be maintained.

There should be no initial impact to privileged images and drivers. However, at some time in the future, HP will document how privileged products that refer to CPU masks must change their code to support systems with CPU IDs greater than 31.

5.4.3 64-Bit Logical Block Number (LBN)

V8.2

OpenVMS today supports LBNs of only 31 bits. This limits our support of a disk volume to 1 terabyte. The amount of space allocated for internal LBN fields is being increased to 64 bits to allow support for larger disk volumes in the future. The existing longword LBN symbols will still be maintained and will be overlaid with a quadwords symbol.

5.4.4 Forking to a Dynamic Spinlock

V8.2

In order to scale the OpenVMS operating system on large SMP systems, a number of areas in the operating system have been using dynamic spinlocks as opposed to the very limited number of static spinlocks. The ability to FORK and have the fork dispatcher obtain synchronization with a dynamic spinlock is desirable. We are adding this capability to OpenVMS Version 8.2 by extending the size of the FKB structure and by adding a FKB$L_SPINLOCK field to the end of this structure. This spinlock field is referenced only if FKB$B_FLCK contains the value SPL$C_DYNAMIC. The FKB structure is embedded in many other system data structures, and this change impacts the size and layout of a large number of privileged data structures

Applications that copy the FKB$B_FLCK field from an OpenVMS created structure to another FKB should also consider copying the data in the FKB$L_SPINLOCK field.

HP recommends that privileged code check for cases of allocating FKB structures and using a hard-coded value for the size of 32. Code should use the symbol FKB$C_LENGTH for the size of a FKB.

5.4.5 UCB/DDB Updates

V8.2

A number of updates have been made to the UCB and DDB structures.

The list of UCBs associated with a DDB is currently a singularly linked list. When creating and deleting a UCB, this list must be walked until the appropriate location is found. For OpenVMS Version 8.2, UCBs are now linked to the DDB with a double linked list. In addition, the DDB maintains a seed pointer to where the search should start when creating a new unit to allow for faster device creation. Drivers that manipulate their unit seed pointer in a template UCB will not be able to take advantage of the faster device creation.

Any code that manipulates the DDB list of UCBs will no longer work correctly. HP highly recommends that you use the provided internal routines for linking and unlinking UCBs. Code-walking the list of UCB forward continues to work correctly.

The UCB$W_UNIT field is currently a 16-bit word field. There are now 32 bits allocated for this field. The UCB$W_UNIT field will still be maintained, so no source code changes are necessary. In a future release, OpenVMS might support larger unit numbers. This would be done only for drivers that indicate they can support this feature.

Byte and Word fields in the terminal driver's UCB extension are now aligned on longword boundaries.

5.4.6 PCB$T_TERMINAL Size Increase

V8.2

The Process Control Block (PCB) structure contains a field PCB$T_TERMINAL, which is 8 bytes to hold the device name for an interactive process (such as LTA123:, RTA7:, NVA456: and so forth). This field is a counted ASCII string, with the first byte being the length of the string and the remaining 7 bytes holding the device name. With a 3-letter device name, only four digits can be used to hold the unit number, and the colon would be stripped off for unit numbers greater than 999. For OpenVMS Version 8.2, this field has been increased to 16 bytes to hold device names with larger unit numbers.

If you fetch this field using a call to $GETJPI with the JPI$_TERMINAL item code, you are not impacted, but you might want to increase the buffer passed to the system service to hold up to 16 bytes.

5.4.7 Per-Thread Security Impacts Privileged Code and Device Drivers

Permanent Change

The method used for attaching a security profile to an I/O Request Packet (IRP) changed with Version 7.2.

In versions of OpenVMS prior to Version 7.2, the IRP structure contained the address of the processwide Access Rights Block (ARB) security structure of the requestor. Beginning with OpenVMS Alpha Version 7.2, the address of the new security profile structure (Persona Security Block, or PSB) was added to the IRP as a functional replacement of the ARB address.

The I/O subsystem maintains its access to the PSB through a reference counter within the PSB. The I/O subsystem increments this reference counter at the time of IRP creation and decrements the counter at I/O postprocessing of that IRP. When this counter reaches zero, the PSB structure is deallocated.

Device drivers that create or clone copies of IRPs to facilitate multiple I/O operations per request, and subsequently pass the copies to the I/O subsystem for postprocessing, must make code changes to account for the extra references to the PSB in these additional IRPs. This is done by passing the PSB address located in the copied IRP to the NSA_STD$REFERENCE_PSB routine. The include file and routine call for NSA_STD$REFERENCE_PSB is as follows:

#include <security-macros.h> /* Increment REFCNT of PSB that is now shared by both IRPs */ nsa_std$reference_psb( irp->irp$ar_psb );

Device drivers need to make this change under the following conditions:

• If a device driver creates a new IRP by duplicating an existing IRP and submits both the original and the duplicate IRPs for I/O postprocessing by calling IOC_STD$SIMREQCOM or IOC_STD$DIRPOST1, the device driver must call NSA_STD$REFERENCE_PSB sometime after duplicating the IRP, but before submitting it for I/O postprocessing.
• If a device driver creates a new IRP by duplicating an existing IRP and does not put the address of some procedure descriptor into the IRP$L_PID cell in either the copy or the original IRP, and the device driver submits both the original and the duplicate IRPs for I/O postprocessing by calling IOC_STD$REQCOM, COM_STD$POST, COM_STD$POST_NOCNT, or IOC_STD$POST_IRP, the device driver must call NSA_STD$REFERENCE_PSB sometime after duplicating the IRP but before submitting it for I/O postprocessing.
  Device drivers that perform these steps are also likely to put the address of some procedure descriptor into IRP$L_PID. Therefore, most device drivers that duplicate IRPs should be able to function correctly on OpenVMS Version 7.2 or higher without making source changes, relinking, or recompiling.

Failure to call NSA_STD$REFERENCE_PSB in these circumstances will result in corrupt tracking information within the PSB, which can result in system failures.

If you make code changes in a device driver to call NSA_STD$REFERENCE_PSB, you must recompile and relink the driver to run on OpenVMS Version 7.2 or higher.

Several routines are used by privileged code to create OpenVMS fork execution threads. These routines run in system context independent of any process. There are four variations of these routines, depending on whether an immediate or queued fork is required and on which language interface is being used:

• EXE$QUEUE_FORK
• EXE_STD$QUEUE_FORK
• EXE$PRIMITIVE_FORK
• EXE_STD$PRIMITIVE_FORK

These routines must be called at or above IPL$_RESCHED, to prevent accidental rescheduling to a different CPU during their execution. Such a reschedule could cause the system to hang.

In OpenVMS V7.3-1, if SYSTEM_CHECK is set to 1, these routines check the system IPL at entry. If the IPL is below IPL$_RESCHED, the system will fail with an SPLINVIPL bugcheck.

For performance reasons, the IPL is not verified if SYSTEM_CHECK is set to zero (the default). Incorrect code may cause the system to hang if a reschedule to another CPU occurs during execution of these routines from process context (for example, below IPL$_RESCHED).

5.5 Applications Using Floating-Point Data

V8.2

The Itanium® architecture implements floating-point arithmetic in hardware using the IEEE floating-point formats, including IEEE single and IEEE double.

The Alpha hardware supports both IEEE and VAX floating-point formats. On OpenVMS Alpha, the compilers generate code to use the VAX formats by default with options to use the IEEE formats.

On OpenVMS I64, the compilers generate code to use the IEEE formats by default with options to use the VAX formats. HP recommends the use of IEEE formats on Integrity servers unless applications need to process VAX floating-point binary data that has been generated on VAX or Alpha systems. For details about using VAX formats on OpenVMS I64, refer to the OpenVMS Floating-Point White Paper on the following website:

5.5.1 IEEE Floating-Point Filter (I64 Only)

V8.3

In order to allow floating point exceptions to conform completely with IEEE-Std 754-1985, Intel provides a function called an IEEE filter. An application developer who wants to use this function can place a call to this function code within a normal OpenVMS exception handler. When an exception occurs, the filter can decode the floating point instructions that caused the exception, as well as decoding the IEEE rounding modes and precision, and determining the operands that caused the exception

To obtain a copy of this filter, access the following Intel Web site and look for the OpenVMS header:

The application note available at this site explains the filter in more detail. The example source code and the filter object library are supplied as an OpenVMS backup save set.

Note that this filter is required only to make certain details of floating point exceptions conform to the IEEE standard. It is not required for normal floating point operation.

5.5.2 Limitation When Using Ctrl/C and STOP Button (OpenVMS Alpha)

V8.3

Condition: Pressing Ctrl/C to interrupt a program running under debugger control works only once. Thereafter, the Crtl/C interrupt is ignored. The same is true when using the DECwindows STOP button; the action is acknowledged only the first time the button is pressed.

Workaround: None.

5.5.3 Ada Event Support (I64 Only)

V8.3

Ada event support (SET BREAK/EVENT=ada_event, where ada_event is one of the events described by SHOW EVENT) is enabled on OpenVMS I64. However, this support is incomplete.

If you encounter problems with event breakpoints, switch to pthread events (SET EVENT_FACILITY pthread) as a workaround. Note that not all Ada events have an equivalent in the pthreads facility.

5.5.4 SHOW SYMBOL/TYPE Now Reports Correct Array Size (Alpha and I64)

V8.3

The SHOW SYMBOL command now reports the correct overall size of an array type. The previous behavior of SHOW SYMBOL/TYPE erroneously reported an incorrect size, for example:

DBG> sho sym/type z data MATINV\Z noncontiguous array descriptor type, 2 dimensions, bounds: [0:10,0:10], size: 4 bytes cell type: atomic type, IEEE single precision floating point, size: 4 bytes DBG>

The corrected behavior is:

DBG> sho symbol/type z data MATINV\MATINV\Z noncontiguous array descriptor type, 2 dimensions, bounds: [0:10,0:10], size: 484 bytes cell type: atomic type, IEEE single precision floating point, size: 4 bytes DBG>

5.5.5 EXAMINE/INSTRUCTION %PREVLOC Command Is Fixed (I64 Only)

V8.3

The EXAMINE/INSTRUCTION %PREVLOC command (and the EXAMINE/INSTRUCTION ^ alternative command) now works as expected. Previously, the debugger would not decrement the PC so that the same instruction was displayed.

5.5.6 SHOW MODULE Command Now Computes Module Size (I64 only)

V8.3

The SHOW MODULE command now reports a nonzero value for the size of a module. The value is an estimate, so you should use it only as a guide to compare the relative sizes of modules.

5.5.7 C++ Language Issues (I64 Only)

V8.2

Condition: The SHOW CALLS command sometimes displays C++ mangled names, rather than demangled names.

Workaround: None.

V8.3

Condition: The debugger does note support debugging C++ programs compiled with /OPTIMIZE.

Workaround: Compile C++ programs with /NOOPTIMIZE.

5.6 Ada Compiler(I64 Only)

V8.2

GNAT Pro (Ada 95) is available from AdaCore. Contact AdaCore at www.adacore.com or sales@adacore.com for more information.

5.7 Backup API: Journaling Callback Events Restriction

Permanent Restriction

If an application registers a callback routine for any of the journaling events, it must register a callback routine for all the journaling callback events. The following is a list of the journaling callback events:

BCK_EVENT_K_JOURNAL_OPEN
BCK_EVENT_K_JOURNAL_WRITE
BCK_EVENT_K_JOURNAL_CLOSE

Refer to the Backup API chapter in the HP OpenVMS Utility Routines Manual for more information about registering callback routines.

5.8 C Programs: Compiling with CASE_LOOKUP=SENSITIVE Settings

Permanent Restriction

If you are compiling C programs in a process where the characteristics were set to CASE_LOOKUP=CASE=SENSITIVE, any #include files in your C program specified with the .h file type (lowercase h) will not be seen and executed. In addition, if a system #include file specifies another #include file with a .h file type, the second #include file will not be seen and an error will be generated.

To avoid this behavior, compile with case set to blind. If it is necessary to use case=sensitive , specify any #include files in your C programs either with no file type (for example, #include <stdio> ) or with an uppercase H file type (for example, #include <stdio.H> ).

Note that this does not correct the scenario where system #include files, such as stdlib.h, in turn specify #include files with a .h file type and cause an error to be generated.

5.9 C Run-Time Library

The following sections describe changes and corrections to the C Run-Time Library (RTL).

5.9.1 C RTL TCP/IP Header File Updates

V8.3

The C RTL ships header files for users to call TCP/IP. These headers have had numerous problems, making some of them unusable for anything beyond trivial TCP/IP programming.

Corrected headers shipped previously with several releases of TCP/IP and are located in their examples area. For OpenVMS Version 8.3, C RTL places those corrected headers into the C RTL header library (DECC$RTLDEF.TLB).

The following are examples of changes in the files:

• Member alignment is corrected. This returns the structures defined in the headers to the required packed alignment.
• Some constant macro definitions are changed to correctly match the constants with which TCP/IP is built.
• SOCKET.H changed MSG_DONTWAIT and MSG_DONTROUTE, swapping the values to be correct. To avoid hangs with the change, users might need to make changes if they coded workarounds for this.
• Previously, compatibility with older programs that were compiled with older headers was not possible because the older programs were not correctly passing data with TCP/IP. Data structure changes were made so users can communicate with TCP/IP. Without these changes, the header files were not usable. Users must recompile for these new definitions.
• The standards TCP/IP follows required header changes.
• New types, macros, and header files are added, as appropriate for new features in TCP/IP.
  C RTL header files changed:

  BITYPES.H IN.H NAMESER_COMPAT.H RESOLV.H IF.H IN6.H NETDB.H SOCKET.H IF_ARP.H INET.H PCAP-BPF.H STROPTS.H IF_TYPES.H NAMESER.H PCAP.H TCP.H