HP OpenVMS System Services Reference Manual


Previous Contents Index


$DCLCMH

Specifies the address of a routine to receive control when a Change Mode to User or Change Mode to Supervisor instruction trap occurs.


Format

SYS$DCLCMH addres ,[prvhnd] ,[type]


C Prototype

int sys$dclcmh (int (*addres)(__unknown_params), void *(*(prvhnd)), char type);


Arguments

addres


OpenVMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference

Routine to receive control when a change mode trap or a compatibility mode fault occurs. The addres argument is the exception handling code in the address space of the calling process.

If you specify the addres argument as 0, $DCLCMH clears the previously declared handler.

prvhnd


OpenVMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference

Address of a previously declared handler. The prvhnd argument is the address of a longword containing the address of the previously declared handler.

type


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

Handler type indicator. The type argument is a longword value. The value 0 (the default) indicates that a change mode handler is to be declared for the access mode at which the request is issued; the value 1 specifies that a compatibility mode handler is to be declared.


Description

On Alpha and Integrity server systems, the Declare Change Mode or Compatibility Mode Handler service calls the change mode handler as a normal procedure (that is, with a standard procedure call). The change mode handler must exit by performing a standard procedure return to the change mode dispatcher.

Arguments (for example, the change mode code) passed between the routine that issued the change mode instruction and the change mode handler are strictly by agreement between the two procedures.

The following MACRO code example shows a subroutine calling Change Mode to User. The example is written for Alpha and Integrity servers users porting from VAX systems.


CHG_MD:  .CALL_ENTRY 
         CHMU 
         RET 

Call this subroutine from any program that requires a Change Mode to User instruction to be invoked.

A change mode handler provides users with a dispatching mechanism similar to that used for system service calls. It allows a routine that executes in supervisor mode to be called from user mode. You declare the change mode handler from supervisor mode; then when the process executing in user mode issues a Change Mode to Supervisor instruction, the change mode handler receives control and executes in supervisor mode.

The top longword of the stack contains the zero-extended change mode code. The change mode handler must exit by removing the change mode code from the stack and issuing an REI instruction.

The operating system uses compatibility mode handlers to bypass normal condition handling procedures when an image executing in compatibility mode causes a compatibility mode exception. Before transferring control to the compatibility mode handler, the system saves the compatibility exception code, the registers R0 through R6, and the PC and PSL in a 10-longword array starting at the location CTL$AL_CMCNTX. Before the compatibility mode handler exits, it must restore the saved registers R0 through R6, push the saved PC and PSL onto the stack, and exit by issuing an REI instruction.

Required Access or Privileges

You can declare a change mode or compatibility mode handler only from user or supervisor mode.

Required Quota

None

Related Services

$SETEXV, $UNWIND


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The longword to receive the address of the previous change mode handler cannot be written by the caller.
++SS$_IVSSRQ The call to the service is invalid because it attempted to declare a compatibility mode handler on Alpha and Integrity server systems.

++Alpha and Integrity servers specific


$DCLEXH

Declares an exit handling routine that receives control when an image exits.

Format

SYS$DCLEXH desblk


C Prototype

int sys$dclexh (void *desblk);


Argument

desblk


OpenVMS usage: exit_handler_block
type: longword (unsigned)
access: write
mechanism: by reference

Exit handler control block. The desblk argument is the address of this control block. This control block, which describes the exit handler, is depicted in the following diagram:


Description

The Declare Exit Handler service declares an exit handler routine that receives control when an image exits. Image exit normally occurs when the image currently executing in a process returns control to the operating system. Image exit might also occur when you call the Exit ($EXIT) or Force Exit ($FORCEX) service. Process exit handlers are not invoked when a process is deleted (such as using a $DELPRC call, for example).

Exit handlers are described by exit control blocks. The operating system maintains a separate list of these control blocks for user, supervisor, and executive modes, and the $DCLEXH service adds the description of an exit handler to the front of one of these lists. The actual list to which the exit control block is added is determined by the access mode of the $DCLEXH caller.

At image exit, the image context, the image stack pointers, and the validity of any variables allocated on the stack are all indeterminate. Accordingly, the exit handler control block and any variables accessed by each exit handler must all be declared using non-volatile semantics. Examples of such non-volatile declarations include the BASIC and Fortran COMMON construct, and the C static storage class.

The declared exit handlers are called from the least-privileged processor mode to the most-privileged mode, and the exit handler(s) for each processor mode are called in the reverse order from which they were originally declared. Each exit handler is executed only once; it must be explicitly redeclared by the application if it is to be executed again.

The exit handler routine is called as a normal procedure with the argument list specified in the third through nth longwords of the exit control block. The first argument is always the address of a user-allocated longword to receive the system status code indicating the reason for the exit; the system always fills in the referenced longword before calling the exit handler. Accordingly, the exit handler routine receives a pointer to the status code as its first argument. Application programmers can append zero or more additional application-specific longword arguments for use within the exit handler routine, with the total number of arguments controlled by the value specified in the argument count field.

You can call this service only from user, supervisor, and executive modes.

Following is a BASIC programming example for this service. To view a C example, see the HP OpenVMS Programming Concepts Manual.


program         DCLEXH_EXAMPLE 
        option type = explicit 
 
        external long EXIT_HANDLER 
        external long function SYS$DCLEXH 
        external long function SYS$EXIT 
        external long function LIB$STOP 
 
        declare long RETURN_STATUS 
 
        record EXIT_DESCRIPTOR 
          long FORWARD_LINK 
          long HANDLER_ADDR 
          long ARG_COUNT 
          long CONDITION_VALUE_PTR 
          long RANDOM_EXAMPLE_VALUE 
          ! borrow part of the record structure for data storage... 
          long CONDITION_VALUE 
        end record EXIT_DESCRIPTOR 
 
        ! declare the exit handler block in non-volatile storage 
        common (SaveBlock) EXIT_DESCRIPTOR EXHBLK 
 
        PRINT 
        PRINT "DCLEXH_EXAMPLE initializing..." 
        PRINT 
 
        EXHBLK::FORWARD_LINK = 0% 
        EXHBLK::HANDLER_ADDR = loc(EXIT_HANDLER) 
        EXHBLK::ARG_COUNT = 2% 
        EXHBLK::CONDITION_VALUE_PTR = loc(EXHBLK::CONDITION_VALUE ) 
        EXHBLK::RANDOM_EXAMPLE_VALUE = 303147% 
 
        PRINT "Calling SYS$DCLEXH..." 
 
        RETURN_STATUS = SYS$DCLEXH (EXHBLK by ref) 
        call LIB$STOP (RETURN_STATUS by value) if (RETURN_STATUS and 1%) = 0% 
 
        PRINT "SYS$DCLEXH called..." 
 
        PRINT "Calling SYS$EXIT..." 
 
        call SYS$EXIT(RETURN_STATUS by value) 
 
end 
 
function LONG EXIT_HANDLER(long CONDITION_VALUE, long RANDOM_VALUE by value) 
 
        ! the exit handler gains control effectively after the main 
        ! program module has exited.  Direct access to (or otherwise 
        ! sharing) variables used by the main routine requires explicit 
        ! storage allocation control. 
 
        option type = explicit 
 
        print "EXIT_HANDLER invoked..." 
        print "CONDITION_VALUE:  ", CONDITION_VALUE 
        print "RANDOM_VALUE:     ", RANDOM_VALUE 
 
        PRINT 
        PRINT "DCLEXH_EXAMPLE done..." 
        PRINT 
 
end function 

Required Access or Privileges

None

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

The Cancel Exit Handler ($CANEXH) service removes an exit control block from the list.


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The first longword of the exit control block cannot be written by the caller.
SS$_IVSSRQ The call to the service is invalid because it was made from kernel mode.
SS$_NOHANDLER The exit handler control block address was not specified or was specified as 0.

$DECLARE_RM

Creates a new Resource Manager instance (RMI) in the calling process.

Format

SYS$DECLARE_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id ,event_handler ,[part_name] [,[rm_context] ,[acmode] ,[tm_log_id] ,[event_mask]]


C Prototype

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

;


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-23. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-23 $DECLARE_RM Option Flags
Flag Name Description
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.
DDTM$M_VOLATILE Set this flag for the new RMI to be volatile. With this flag set, the DECdtm transaction manager will not log information about any RM participants associated with the new RMI. Resource managers that never perform recovery should set this flag.

If this flag is clear, the new RMI is not volatile. The DECdtm transaction manager will log the following information about each RM participant associated with the new RMI:

  • The name of the RM participant.
  • The identifier (TID) of the transaction in which it is participating.

If this flag is clear and a recoverable failure occurs, such as a system crash, the resource manager can use the $GETDTI system service to query the transaction log to determine the outcome of the transactions in which it was participating before the failure occurred.

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:


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 $DECLARE_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: write only
mechanism: by reference

Longword in which the identifier (RM_ID) of the new RMI is returned. This identifier is unique within the calling process at any time.

event_handler


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

The new RMI's event handler. This routine is called to report an event to the new RMI or one of its RM participants. The event_handler argument is the address of the entry mask of this routine. An event handler must be specified.

This routine is called as an AST delivered by the DECdtm transaction manager.

The AST is executed in the access mode specified by the acmode argument. The AST parameter is the address of a DECdtm event report block that contains an event report.

The DECdtm transaction manager reports events to an RMI and the RM participants associated with it using ASTs executed in the access mode specified in the call to $DECLARE_RM that created that RMI.

The DECdtm transaction manager creates an event report block, and passes its address to the AST routine in the parameter of the AST. Each event report block contains:

Table SYS-24 describes the fields in an event report block, in alphabetical order:

Table SYS-24 Fields in an Event Report Block
Symbol Description
DDTM$A_TID_PTR Address of the identifier (TID) of the transaction.
DDTM$L_ABORT_REASON Abort reason code (longword).

See the $ACK_EVENT service for a list of possible values. Present only in abort event reports.

DDTM$L_EVENT_TYPE A code that identifies the event (longword). The following table lists the possible values:
Symbol Event
DDTM$K_ABORT Abort
DDTM$K_COMMIT Commit
DDTM$K_PREPARE Prepare
DDTM$K_ONE_PHASE_COMMIT One-phase commit
DDTM$K_STARTED_DEFAULT Default transaction started
DDTM$K_STARTED_NONDEFAULT Nondefault transaction started
DDTM$L_REPORT_ID Event report identifier (unsigned longword).
DDTM$L_RM_CONTEXT The context of the RM participant or RMI to which the event report is being delivered (unsigned longword).
DDTM$Q_PART_NAME The name of the RM participant or RMI to which the event report is being delivered (descriptor).
DDTM$Q_TX_CLASS The transaction class of the transaction (descriptor).

Each event report must be acknowledged by calling $ACK_EVENT, specifying the identifier of the report. This acknowledgment need not come from AST context.

The DECdtm transaction manager delivers only one event report at a time to each RM participant. For example, if a prepare event report has been delivered to an RM participant, and the transaction is aborted while the RM participant is doing its prepare processing, then the DECdtm transaction manager does not deliver an abort event report to that RM participant until it has acknowledged the prepare event report by a call to $ACK_EVENT. Note that the DECdtm transaction manager may deliver multiple reports to an RMI.

After acknowledging the event report, the RMI or RM participant should no longer access the event report block.

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 RMI. This is:

This string must be no longer than 32 characters.

If this argument is omitted, the name of the new RMI is the null string.

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 of the new RMI. This is:

If this argument is omitted, the context of the new RMI is 0.

acmode


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

The access mode of the new RMI. This is:

The access mode of the new RMI is the least privileged of:

If this argument is omitted, the access mode of the new RMI is the same as the access mode of the caller.

tm_log_id


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

The globally unique identifier of the transaction log for the local node. This identifier is used during resource manager recovery to check that the correct DECdtm transaction manager log is used. See $GETDTI for more information.

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.

event_mask


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

Requests the types of event to be reported to the new RMI and to its RM participants. The only type of event that can be reported to the new RMI is a Transaction Started event (a default or non-default transaction started event). The following types of event can be reported to its RM participants:

The event_mask argument is a longword bit mask that is the logical OR of each bit set, where each bit corresponds to an event. The $DDTMDEF module defines a symbolic name for each flag bit. Table SYS-25 describes the flags. All undefined bits must be 0.


Previous Next Contents Index