HP OpenVMS System Services Reference Manual

$IO_PERFORMW (Alpha and Integrity servers)

On Alpha and Integrity server systems, starts a Fast I/O operation. The $IO_PERFORMW service completes synchronously; that is, it returns to the caller after performing the Fast I/O operation.
In all other respects, $IO_PERFORMW is identical to $IO_PERFORM. For all other information about the IO_PERFORMW service, see the description of $IO_PERFORM in this manual.

Format

SYS$IO_PERFORMW fandle ,chan ,iosadr ,bufadr ,buflen ,devdata

C Prototype

int sys$io_performw (unsigned __int64 fandl, unsigned short int chan, struct _iosa *iosadr, void *bufadr, unsigned __int64 buflen, unsigned __int64 devdata);

$IO_SETUP (Alpha and Integrity servers)

On Alpha and Integrity server systems, allocates resources for Fast I/O.
This service accepts 64-bit addresses.

Format

SYS$IO_SETUP func ,bufobj ,iosobj ,astadr ,flags ,return_fandle

C Prototype

int sys$io_setup (unsigned int func, struct _generic_64 *bufobj, struct _generic_64 *iosobj, void (*astadr)(struct _iosa *), unsigned int flags, unsigned __int64 *return_fandle);

Arguments

func

OpenVMS usage: function_code

type: longword

access: read only

mechanism: by value

I/O function code. Must be one of the following:

IO$_READVBLK
IO$_WRITEVBLK
IO$_READLBLK
IO$_WRITELBLK

Various function modifiers are supported, depending on the device and driver. Disk drivers support IO$M_NOVCACHE and IO$M_DATACHECK. Some tape devices support IO$M_REVERSE. Illegal modifiers are detected by the $IO_PERFORM(W) service.
bufobj

OpenVMS usage: buffer object

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Handle describing the buffer object that contains the user's buffer. This identifier cannot be 0.
iosobj

OpenVMS usage: object handle

type: vector longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Buffer object handle describing the buffer object that contains the I/O Status Area (IOSA). This might or might not be the same identifier as the bufobj argument. This identifier cannot be 0.
astadr

OpenVMS usage: ast_procedure

type: procedure value

access: read only

mechanism: by 32- or 64-bit reference

Completion AST routine address (0, if none). There is no AST parameter argument. When the AST routine is called, the AST parameter will be the address of the IOSA for the operation. Applications can store data in the IOSA at offset IOSA$IH_CONTEXT.
flags

OpenVMS usage: mask_longword

type: 64-bit integer (unsigned)

access: read only

mechanism: by value

Flag mask. The flags argument is a bit vector in which each bit corresponds to a flag. Flags are defined in the module IOSADEF.
The following table describes the flags that are valid for the $IO_SETUP service:

Flag Description

FIO$M_EXPEDITE This is a high priority I/O; that is, it is to be given preferential treatment by the I/O subsystem. Use of this bit requires ALTPRI or PHY_IO privilege.

FIO$M_AST_NOFLOAT The AST procedure does not use, or call any procedure that uses, any floating-point registers. This is a performance option. If set, AST delivery will neither save nor restore floating-point registers. Caution: Use of floating-point registers when FIO$M_AST_NOFLOAT has been specified can cause unpredictable, difficult to detect, error conditions.

All other bits in the flags argument are reserved for future use by HP and should be specified as 0.
return_fandle

OpenVMS usage: fandle

type: 64-bit integer (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

Address of an aligned quadword to receive the fandle for this I/O operation.

Flag	Description
FIO$M_EXPEDITE	This is a high priority I/O; that is, it is to be given preferential treatment by the I/O subsystem. Use of this bit requires ALTPRI or PHY_IO privilege.
FIO$M_AST_NOFLOAT	The AST procedure does not use, or call any procedure that uses, any floating-point registers. This is a performance option. If set, AST delivery will neither save nor restore floating-point registers. Caution: Use of floating-point registers when FIO$M_AST_NOFLOAT has been specified can cause unpredictable, difficult to detect, error conditions.

Description

The Set Up Fast I/O system service allocates and initializes a number of internal objects based on the parameters supplied. Because these objects are then ready for use when a subsequent $IO_PERFORM or $IO_PERFORMW is issued, the I/O operation will require less CPU time and fewer multiprocessor steps.
Required Privileges

If you use the flags argument FIO$M_EXPEDITE, a process must have ALTPRI or PHY_IO privilege.
Required Quota

Byte count
Related Services

$IO_CLEANUP, $IO_PERFORM(W)

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The fandle does not have 8 bytes of writability, or the two buffer objects do not have 8 bytes of readability each.

SS$_BADPARAM Invalid flags options specified.

SS$_EXBUFOBJLM Buffer object cannot be created because it would bring the total number of buffer object pages above the systemwide limit MAXBOBMEM.

SS$_ILLBUFOBJ The buffer object is not valid.

SS$_ILLIOFUNC The function code is not valid.

SS$_ILLMODIFIER The I/O function modifier is not permitted.

SS$_INSFMEM There is no pool available from which to create a fandle vector, or the fandle vector is already full and an attempted expansion failed.

SS$_INSFSPTS Insufficient system page table entries.

SS$_IVSTSFLG The specified status flag is invalid.

SS$_NOBUFOBJID The process attempted to create a buffer object from user mode but was not holding required rights identifier VMS$BUFFER_OBJECT_USER.

SS$_NOPRIV Valid flag options were specified but from user mode.

SS$_PAGNOTWRITE A page within the address range is not writable.

SS$_PAGOWNVIO Page owner violation. The pages could not be put into the buffer object because the access mode associated with the call to $IO_SETUP was less privileged than the access mode associated with the pages. See $CREATE_BUFOBJ_64 for additional information.

SS$_UNALIGNED The I/O Status Area (IOSA) or data buffer is not aligned on a quadword boundary.

$JOIN_RM

Adds a new Resource Manager (RM) participant to a transaction.

Format

SYS$JOIN_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id [,[tid] ,[part_name] ,[rm_context] ,[timout] ,[bid]]

C Prototype

int sys$join_rm (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int rm_id,...);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flags specifying options for the service. The flags argument is a longword bit mask in which each bit corresponds to an option flag. The $DDTMDEF macro defines symbolic names for these option flags described in Table SYS-47. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-47 $JOIN_RM Option Flags
Flag Name Description

DDTM$M_COORDINATOR Set this flag to specify that the new RM participant is to be a coordinator of the transaction on this node.

DDTM$M_SYNC Specifies successful synchronous completion by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in.

iosb

OpenVMS usage: io_status_block

type: quadword (unsigned)

access: write only

mechanism: by reference

The I/O status block in which the completion status of the service is returned as a condition value. See the Condition Values Returned section.
The following diagram shows the structure of the I/O status block:

**Table SYS-47 $JOIN_RM Option Flags**
Flag Name	Description
DDTM$M_COORDINATOR	Set this flag to specify that the new RM participant is to be a coordinator of the transaction on this node.
DDTM$M_SYNC	Specifies successful synchronous completion by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in.

astadr

OpenVMS usage:	ast_procedure
type:	procedure entry mask
access:	call without stack unwinding
mechanism:	by reference

The AST routine that is executed when the service completes, if SS$_NORMAL is returned in R0. The astadr argument is the address of the entry mask of this routine. The routine is executed in the same access mode as that of the caller of the $JOIN_RM service.

astprm

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

The AST parameter that is passed to the AST routine specified by the astadr argument.

rm_id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by value

The identifier of the RMI with which the new RM participant is associated. This identifies:

Types of event that are to be reported to the new RM participant.
Event handler to which these event reports are to be delivered, and the access mode in which its ASTs are to be fired.
Minimum access mode that the new RM participant must be in to acknowledge one of these event reports by calling $ACK_EVENT.
Whether or not the DECdtm transaction manager may log information about the new RM participant.

tid

OpenVMS usage:	trans_id
type:	octaword (unsigned)
access:	read only
mechanism:	by reference

The identifier (TID) of the transaction to which the new RM participant is to be added.

If this argument is omitted (the default) or its value is zero, $JOIN_RM adds an RM participant to the default transaction of the calling process.

part_name

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

The name of the new RM participant.

Used by recoverable resource managers to specify the RM participant to use in a subsequent call to $GETDTI or $SETDTI during recovery.

This argument has no effect if the RMI is volatile. If this argument is omitted (the default) or its value is zero, the name of the new RM participant is the same as that of the RMI with which it is associated.

The string passed in this argument can be no longer than 32 characters.

To ensure smooth operation in a mixed-network environment, refer to the chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for information on defining node names.

rm_context

OpenVMS usage:	userarg
type:	longword (unsigned)
access:	read only
mechanism:	by value

The context associated with the new RM participant. This is passed in the event reports subsequently delivered to the new RM participant.

If this argument is omitted (the default) or is zero, the context associated with the new RM participant is the same as that of the RMI with which it is associated.

timout

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Reserved to HP.

bid

OpenVMS usage:	branch_id
type:	octaword (unsigned)
access:	write only
mechanism:	by reference

The identifier of an authorized branch (BID) that may be added to the transaction by a subsequent call to $START_BRANCH on the same node as that of the RMI. This argument is ignored if the DDTM$M_COORDINATOR flag is clear in the flags argument. The call to $START_BRANCH should specify the node of the RMI for the tm_name argument.

Description

The $JOIN_RM system service:

Adds a new RM participant to the specified transaction. The new RM participant is associated with the RMI whose identifier is passed in the rm_id argument.
Introduces a new transaction to DECdtm if the new RM participant is a coordinator and the specified transaction is unknown to DECdtm.
Authorizes a new branch of the transaction if the new RM participant is a coordinator.

Preconditions for the successful completion of $JOIN_RM are:

Unless the DDTM$M_COORDINATOR flag is set, the calling process must contain at least one branch of the specified transaction.
The calling process must contain the specified RMI.
The caller must not be in a less privileged mode than the access mode of the specified RMI.
If the DDTM$M_COORDINATOR flag is set, either the calling process must have the SYSPRV privilege, or the caller must be in executive or kernel mode.
If the DDTM$M_COORDINATOR flag is set, the specified RMI must not be volatile. That is, the DDTM$M_VOLATILE flag must not have been set on the call to the $DECLARE_RM that created it.
The access mode of the specified RMI must not be less privileged than that of the specified transaction in this process.

$JOIN_RM can fail for various reasons, including:

Preconditions were not met.
The DDTM$M_COORDINATOR flag was set, but no bid argument was supplied.

When $JOIN_RM completes successfully, a new RM participant running in the calling process is added to the transaction. This RM participant is associated with the specified RMI.
The DECdtm transaction manager will report to the new RM participant the types of event specified in the call to $DECLARE_RM that created the RMI with which it is associated. Note however that events of type prepare, one-phase commit, and commit are never reported to RM participants that set the DDTM$M_COORDINATOR flag on the call to $JOIN_RM.
If the call to $DECLARE_RM requested prepare and one-phase commit events, and the $JOIN_RM call does not set the DDTM$M_COORDINATOR flag, the new RM participant is entitled to a vote on the outcome of the transaction.
If the $JOIN_RM call sets the DDTM$M_COORDINATOR flag, then the new RM participant is expected to initiate commit or abort processing by a call to $TRANS_EVENT. No events of type prepare, one-phase commit, or commit are delivered to the RM participant.
Events of type abort are reported to the RM participant.
The new RM participant is removed from the transaction when the first of the following conditions is met:

On successful completion of a call to $ACK_EVENT that acknowledges an event report delivered to that RM participant, if the event and its acknowledgment were one of those listed in the following table:

Event Acknowledgment (report_reply)

Abort SS$_FORGET

Commit SS$_FORGET or SS$_REMEMBER

Prepare SS$_FORGET

One-phase commit SS$_NORMAL or SS$_VETO

On completion of a successful call to $TRANS_EVENT that specifies a commit or abort event, if the DDTM$M_COORDINATOR flag is set.
When a commit or abort event occurs, and no associated event report is delivered to the RM participant.
On successful completion of a call to $FORGET_RM that deletes the RMI with which it is associated.
When the current process terminates (normally or abnormally).
When the current image terminates (normally or abnormally).

If the DDTM$M_COORDINATOR flag is set:

A new branch is authorized for the transaction and its identifier is returned in the octaword that the bid argument points to. $JOIN_RM uses the $CREATE_UID system service to generate the BID. No other call to $ADD_BRANCH, $JOIN_RM, or $CREATE_UID on any other node ever returns the same BID value.
The transaction cannot commit until the new branch has been started by a matching call to $START_BRANCH. (See the description of $START_BRANCH for the definition of a matching call to $START_BRANCH.)
If the transaction is not already known to this process, then the transaction is introduced to this process with an access mode equal to the access mode of the caller. (See the description of $START_TRANS for a definition of the access mode of a transaction.)

There is also a wait form of the service, $JOIN_RMW.

Event	Acknowledgment (report_reply)
Abort	SS$_FORGET
Commit	SS$_FORGET or SS$_REMEMBER
Prepare	SS$_FORGET
One-phase commit	SS$_NORMAL or SS$_VETO

Required Privileges

If the DDTM$M_COORDINATOR flag is set, then either the calling process must have the SYSPRV privilege or the caller must be in executive or kernel mode.

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.

SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).

SS$_ACCVIO An argument was not accessible to the caller.

SS$_BADPARAM The options flags were invalid, the specified tid was invalid, or DTM$M_COORDINATOR set but no bid supplied.

SS$_EXASTLM The process AST limit (ASTLM) was exceeded.

SS$_EXQUOTA The job buffered I/O byte limit quota (BYTLM) was exceeded.

SS$_ILLEFC The event flag number was invalid.

SS$_INSFARGS A required argument was missing.

SS$_INSFMEM There was insufficient system dynamic memory for the operation.

SS$_INVBUFLEN The string passed in the part_name argument was too long.

SS$_NOSYSPRIV The DDTM$M_COORDINATOR flag was set and the caller was in user or supervisor mode but the calling process did not have the SYSPRV privilege.

SS$_NOCURTID An attempt was made to add a new participant to the default transaction (the tid argument was zero or omitted) but the calling process did not have a default transaction.

SS$_NOSUCHTID The DDTM$M_COORDINATOR flag was clear and the calling process did not contain any branches in the transaction.

SS$_NOSUCHRM The calling process did not contain the specified RMI.

SS$_WRONGACMODE The caller was in a less privileged access mode than that of the RMI.

SS$_WRONGSTATE The transaction was in the wrong state for the attempted operation because either:

An abort event had occurred for the transaction.
A call to $END_TRANS to end the transaction was in progress and it is too late to add a new RM participant to the transaction.

Contents

Index

OpenVMS usage:	function_code
type:	longword
access:	read only
mechanism:	by value

OpenVMS usage:	buffer object
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	object handle
type:	vector longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	mask_longword
type:	64-bit integer (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	fandle
type:	64-bit integer (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The fandle does not have 8 bytes of writability, or the two buffer objects do not have 8 bytes of readability each.
SS$_BADPARAM	Invalid flags options specified.
SS$_EXBUFOBJLM	Buffer object cannot be created because it would bring the total number of buffer object pages above the systemwide limit MAXBOBMEM.
SS$_ILLBUFOBJ	The buffer object is not valid.
SS$_ILLIOFUNC	The function code is not valid.
SS$_ILLMODIFIER	The I/O function modifier is not permitted.
SS$_INSFMEM	There is no pool available from which to create a fandle vector, or the fandle vector is already full and an attempted expansion failed.
SS$_INSFSPTS	Insufficient system page table entries.
SS$_IVSTSFLG	The specified status flag is invalid.
SS$_NOBUFOBJID	The process attempted to create a buffer object from user mode but was not holding required rights identifier VMS$BUFFER_OBJECT_USER.
SS$_NOPRIV	Valid flag options were specified but from user mode.
SS$_PAGNOTWRITE	A page within the address range is not writable.
SS$_PAGOWNVIO	Page owner violation. The pages could not be put into the buffer object because the access mode associated with the call to $IO_SETUP was less privileged than the access mode associated with the pages. See $CREATE_BUFOBJ_64 for additional information.
SS$_UNALIGNED	The I/O Status Area (IOSA) or data buffer is not aligned on a quadword boundary.

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

SS$_NORMAL	If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH	The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	The options flags were invalid, the specified tid was invalid, or DTM$M_COORDINATOR set but no bid supplied.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA	The job buffered I/O byte limit quota (BYTLM) was exceeded.
SS$_ILLEFC	The event flag number was invalid.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_INVBUFLEN	The string passed in the part_name argument was too long.
SS$_NOSYSPRIV	The DDTM$M_COORDINATOR flag was set and the caller was in user or supervisor mode but the calling process did not have the SYSPRV privilege.
SS$_NOCURTID	An attempt was made to add a new participant to the default transaction (the tid argument was zero or omitted) but the calling process did not have a default transaction.
SS$_NOSUCHTID	The DDTM$M_COORDINATOR flag was clear and the calling process did not contain any branches in the transaction.
SS$_NOSUCHRM	The calling process did not contain the specified RMI.
SS$_WRONGACMODE	The caller was in a less privileged access mode than that of the RMI.
SS$_WRONGSTATE	The transaction was in the wrong state for the attempted operation because either: An abort event had occurred for the transaction. A call to $END_TRANS to end the transaction was in progress and it is too late to add a new RM participant to the transaction.