OpenVMS System Services Reference Manual
$DCLAST
Queues an asynchronous system trap (AST) for the calling access mode or
for a less privileged access mode.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$DCLAST astadr ,[astprm] ,[acmode]
C Prototype
int sys$dclast (void (*astadr)(__unknown_params), unsigned __int64
astprm, unsigned int acmode);
Arguments
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
AST service routine to be executed. On Alpha systems, the
astadr argument is the 32- or 64-bit address of this
routine. On VAX systems, the astadr argument is the
32-bit address of this routine.
astprm
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 64-bit value (Alpha) |
| mechanism: |
by 32-bit value (VAX) |
AST parameter to be passed to the AST routine specified by the
astadr argument. On Alpha sytems, the
astprm argument is a quadword value containing this
parameter. On VAX systems, the astprm argument is a
longword value containing this parameter.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode for which the AST is to be declared. The most privileged
access mode used is the access mode of the caller. The resultant mode
is the access mode for which the AST is declared.
Description
The Declare AST service queues an AST for the calling access mode or
for a less privileged access mode. For example, a routine executing in
supervisor mode can declare an AST for either supervisor or user mode.
The service does not validate the address of the AST service routine.
If you specify an illegal address (such as 0), an access violation
occurs when the AST service routine is given control.
Required Access or Privileges
None
Required Quota
The $DCLAST service requires system dynamic memory and uses the AST
limit (ASTLM) quota of the process.
Related Services
$SETAST, $SETPRA
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_EXQUOTA
|
The process has exceeded its AST limit (ASTLM) quota.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for completing the service.
|
$DCLCMH
On Alpha systems, specifies the address of a routine to receive control
when a Change Mode to User or Change Mode to Supervisor instruction
trap occurs.
On VAX systems, specifies the address of a routine to receive control
when a Change Mode to User or Change Mode to Supervisor instruction
trap occurs, or when a compatibility mode fault 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 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 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.
On VAX systems, the $DCLCMH service specifies the address of a routine
to receive control when (1) a Change Mode to User or Change Mode to
Supervisor instruction trap occurs, or (2) a compatibility mode fault
occurs. 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 systems.
|
++Alpha 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, refer to the 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.
|
$DELETE_BUFOBJ (Alpha Only)
On Alpha systems, deletes a buffer object previously created by the
$CREATE_BUFOBJ_64 system service.
This service accepts 64-bit addresses.
Format
SYS$DELETE_BUFOBJ buffer_handle_64
C Prototype
int sys$delete_bufobj (struct _generic_64 *buffer_handle_64);
Arguments
buffer_handle_64
| OpenVMS usage: |
handle |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The buffer object to be deleted. The buffer_handle_64
argument is the 32- or 64-bit address of a 2-longword array previously
returned by a $CREATE_BUFOBJ_64 call.
Description
The Delete Buffer Object system service deletes the buffer object
identified by the buffer_handle_64 argument. The
associated memory is made free to be paged, swapped, or deleted.
Buffer objects are also automatically deleted at image rundown.
Required Privileges
None
Required Quota
None
Related Services
$CREATE_BUFOBJ_64
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
buffer_handle_64 argument cannot be read by the caller.
|
|
SS$_BADPARAM
|
The
buffer_handle_64 argument is not a valid buffer handle.
|
|
SS$_NOPRIV
|
The buffer object was created by a more privileged access mode than the
caller's access mode.
|
$DELETE_GALAXY_LOCK (Alpha Only)
Invalidates an OpenVMS Galaxy lock and deletes it.
Note that this system service is supported only in an OpenVMS Alpha
Galaxy environment.
For more information about programming with OpenVMS Galaxy system
services, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
Format
SYS$DELETE_GALAXY_LOCK handle
C Prototype
int sys$delete_galaxy_lock (unsigned __int64 lock_handle);
Arguments
handle
| OpenVMS usage: |
galaxy lock handle |
| type: |
quadword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The 64-bit lock handle that identifies the lock to be deleted. This
value is returned by SYS$CREATE_GALAXY_LOCK.
Description
This service invalidates the OpenVMS Galaxy lock and deletes it. The
memory for the lock is not truly deleted; however, it is put on a free
list for later use.
Required Access or Privileges
CMKRNL, SHMEM
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE,
$DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO,
$GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_BADLCKTBL
|
Galaxy lock table is corrupt.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_LOCKINUSE
|
Invalid operation; lock is in use.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEN
|
Operation requires SHMEM privilege.
|
$DELETE_GALAXY_LOCK_TABLE (Alpha Only)
Deletes an OpenVMS Galaxy locktable.
Note that this system service is supported only in an OpenVMS Alpha
Galaxy environment. For more information about programming with OpenVMS
Galaxy system services, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
Format
SYS$DELETE_GALAXY_LOCK_TABLE handle
C Prototype
int sys$delete_galaxy_lock_table (unsigned int *lcktbl_handle);
Arguments
lcktbl_handle
| OpenVMS usage: |
lock table handle |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
input by value |
The 32-bit lock table handle that identifies the table to be deleted.
This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.
Description
This service deletes an OpenVMS Galaxy lock table. If there are no
longer any mappers of the locktable section, the table is deleted.
Required Access or Privileges
CMKRNL, SHMEM
Required Quota
None
Related Services
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK,
$DELETE_GALAXY_LOCK, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE,
$RELEASE_GALAXY_LOCK
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_IVLOCKID
|
Invalid lock id.
|
|
SS$_IVLOCKTBL
|
Invalid lock table.
|
|
SS$_NOCMKRNL
|
Operation requires CMKRNL privilege.
|
|
SS$_NOSHMEM
|
Operation requires SHMEM privilege.
|
$DELETE_INTRUSION
Searches for and deletes all records in the intrusion database matching
the caller's specifications.
Format
SYS$DELETE_INTRUSION user_criteria ,[flags]
C Prototype
int sys$delete_intrusion (void *user_criteria, unsigned int flags);
Arguments
user_criteria
| OpenVMS usage: |
char_string or item_list_3 |
| type: |
character-coded text string or longword
(unsigned) |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor or by
reference |
If the CIA$M_ITEMLIST flag is FALSE:
The user_criteria argument is the description of
intruder or suspect. This argument is the address of a character-string
descriptor pointing to a buffer containing the user criteria to match
an intrusion record's user specification in the intrusion database.
The user_criteria argument is a character string of 1
to 1058 bytes containing characters to match the user specification on
records in the intrusion database.
A user specification is any combination of the suspect's or intruder's
source node name, source user name, source DECnet-Plus address, local
failed user name, or local terminal. The user specification for an
intrusion record is based on the input to the $SCAN_INTRUSION service
and the settings of the LGI system parameter. For more information,
refer to the OpenVMS Guide to System Security.
Wildcards are allowed for the user_criteria argument.
For example, if you specify an asterisk (*) for the
user_criteria argument, the service deletes all
records in the intrusion database.
If the CIA$M_ITEMLIST flag is TRUE:
The user_criteria argument is now the address of a
32-bit item list. If the item list is used, one item, the
CIA$_USER_CRITERIAL item, must be present in the item list. The
ITM$L_BUFADR should point to a buffer containing the specified user
criteria.
The following table lists the valid item descriptions for the
user_criteria argument:
| Item |
Description |
|
CIA$_SCSNODE_LIST
|
Address of a list of 8-character null-padded SCS nodenames for which
intrusions are to be deleted.
|
|
CIA$_USER_CRITERIAL
|
Address of a buffer, 1-1058 bytes long, containing the intruder or
suspect.
|
If the CIA$_SCSNODE_LIST item is present, it is the address of a list
of 8-character null-padded SCS nodenames for which intrusions are to be
deleted. If this item is absent, the service deletes the specified
intrusion records for all nodes in the cluster. Multiple
CIA$_SCSNODE_LIST items are permitted.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Functional specification for the service. The flags
argument is a longword bit mask wherein each bit corresponds to an
option.
Each flag option has a symbolic name. The $CIADEF macro defines the
following valid names for the $DELETE_INTRUSION service:
| Symbolic Name |
Description |
|
CIA$M_IGNORE_RETURN
|
The service should not wait for the return status from the security
server. No return status from the server's function will be returned to
the caller.
|
|
CIA$M_ITEMLIST
|
If FALSE, the
user_criteria argument is a character string. If TRUE,
this argument is a 32-bit item list.
|
Description
The Delete Intrusion Records service deletes from the intrusion
database a set of records matching the criteria you specify in the
user_criteria argument. All records matching the
criteria you specify are deleted. You do not have to call the service
more than once to delete a set of records.
For example, if you specify an asterisk (*) for the
user_criteria argument, the service deletes all
records in the intrusion database with one call.
|
