![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 30 March 2001 | |
|
|
|
|
|
|
| Previous | Contents | Index |
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.
SYS$DCLAST astadr ,[astprm] ,[acmode]
int sys$dclast (void (*astadr)(__unknown_params), unsigned __int64 astprm, unsigned int acmode);
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.
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.
None
The $DCLAST service requires system dynamic memory and uses the AST limit (ASTLM) quota of the process.
$SETAST, $SETPRA
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.
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.
SYS$DCLCMH addres ,[prvhnd] ,[type]
int sys$dclcmh (int (*addres)(__unknown_params), void *(*(prvhnd)), char type);
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.
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 RETCall 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.
You can declare a change mode or compatibility mode handler only from user or supervisor mode.
None
$SETEXV, $UNWIND
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.
Declares an exit handling routine that receives control when an image exits.
SYS$DCLEXH desblk
int sys$dclexh (void *desblk);
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:
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 functionNone
None
$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.
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.
On Alpha systems, deletes a buffer object previously created by the $CREATE_BUFOBJ_64 system service.This service accepts 64-bit addresses.
SYS$DELETE_BUFOBJ buffer_handle_64
int sys$delete_bufobj (struct _generic_64 *buffer_handle_64);
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.
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.
None
None
$CREATE_BUFOBJ_64
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.
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.
SYS$DELETE_GALAXY_LOCK handle
int sys$delete_galaxy_lock (unsigned __int64 lock_handle);
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.
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.CMKRNL, SHMEM
None
$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
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.
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.
SYS$DELETE_GALAXY_LOCK_TABLE handle
int sys$delete_galaxy_lock_table (unsigned int *lcktbl_handle);
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.
This service deletes an OpenVMS Galaxy lock table. If there are no longer any mappers of the locktable section, the table is deleted.CMKRNL, SHMEM
None
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK
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.
Searches for and deletes all records in the intrusion database matching the caller's specifications.
SYS$DELETE_INTRUSION user_criteria ,[flags]
int sys$delete_intrusion (void *user_criteria, unsigned int flags);
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.
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.
Previous Next Contents Index
privacy and legal statement 4527PRO_028.HTML