HP OpenVMS System Services Reference Manual


Previous Contents Index

If you are creating a new lock, the resnam argument should be specified because the default value for the resnam argument produces an error when it is used to create a lock. The resnam argument is ignored for lock conversions.

parid


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

Lock identification of the parent lock. The parid argument is a longword containing this identification value.

If you do not specify this argument or specify it as 0, $ENQ assumes that the lock does not have a parent lock. This argument is optional for new locks and is ignored for lock conversions.

astadr


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference

AST service routine to be executed when the lock is either granted or converted. The astadr argument is the 32- or 64-bit address of this routine. The AST is also delivered when the lock or conversion request is canceled. Cancellation occurs if you use $DEQ with the cancel modifier or if the waiting request is chosen to break a deadlock.

If you specify the astadr argument, the AST routine executes at the same access mode as the caller of $ENQ.

astprm


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

AST parameter to be passed to the AST routine specified by the astadr argument. The astprm argument specifies this quadword parameter.

blkast


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference

Blocking AST routine to be called whenever this lock is granted and is blocking any other lock requests. The blkast argument is the 32- or 64-bit address of this routine. Locks that are converting to a new mode, but that are not yet granted in the new mode, do not receive blocking ASTs.

You can pass a parameter to this routine by using the astprm argument.

acmode


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

Access mode to be associated with the resource name. The acmode argument indicates the least privileged access mode from which locks can be queued on the resource.

This argument does not affect the access mode associated with the lock or its blocking and completion ASTs. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the following symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User

The $ENQ service associates an access mode with the lock in the following way:

rsdm_id


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

Resource domain identification. The rsdm_id argument is a longword specifying the resource domain association through which a new lock is to be taken. This argument is ignored for lock conversions and sublocks (parid is nonzero). Valid resource domain identifiers are returned from the $SET_RESOURCE_DOMAIN service, or by the constants RSDM$K_SYSTEM_RSDM_ID or RSDM$K_PROCESS_RSDM_ID, which are defined by the $RSDMDEF macro in STARLET.

nullarg


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

Placeholding argument reserved by HP.

Description

The Enqueue Lock Request service queues a new lock or lock conversion on a resource. The $ENQ service completes asynchronously; that is, it returns to the caller after queuing the lock request without waiting for the lock to be either granted or converted. For synchronous completion, use the Enqueue Lock Request and Wait ($ENQW) service. The $ENQW service is identical to the $ENQ service in every way except that $ENQW returns to the caller when the lock is either granted or converted.

The $ENQ service uses system dynamic memory for the creation of the lock and resource blocks.

When $ENQ queues a lock request, it returns the status of the request in R0 and writes the lock identification of the lock in the lock status block. Then, when the lock request is granted, $ENQ writes the final completion status in the lock status block, sets the event flag, and calls the AST routine if this has been requested.

When $ENQW queues a lock request, it returns status in R0 and in the lock status block when the lock has been either granted or converted. Where applicable, it simultaneously sets the event flag and calls the AST routine.

Invalidation of the Lock Value Block

In some situations, the lock value block can become invalid. In these situations, $ENQ warns the caller by returning the condition value SS$_VALNOTVALID in the lock status block, provided the caller has specified the flag LCK$M_VALBLK in the flags argument.

The SS$_VALNOTVALID condition value is a warning message, not an error message; therefore, the $ENQ service grants the requested lock and returns this warning on all subsequent calls to $ENQ until either a new lock value block is written to the lock database or the resource is deleted. Resource deletion occurs when no locks are associated with the resource.

The following events can cause the lock value block to become invalid:

Invalidation of the Extended Lock Value Block

The extended lock value block can be marked invalid in the following situation: If a program updates the lock block specifying only LCK$M_VALBLK without LCK$M_XVALBLK, only the first 16 bytes of the lock value block will be written. The remaining 48 bytes will not be modified. A reader who, in the future, specifies the LCK$M_XVALBLK flag in the $ENQ system service call will be be given all 64 bytes but will receive the warning status SS$_XVALNOTVALID flag.

If the entire lock status block is invalid as described in Invalidation of the Lock Value Block, the SS$_VALNOTVALID status will be returned, overriding the SS$_XVALNOTVALID status.

Required Access or Privileges

To queue a lock on a systemwide resource, the calling process must either have SYSLCK privilege or be executing in executive or kernel mode.

To specify a parent lock when queuing a lock, the access mode of the caller must be equal to, or less privileged than, the access mode associated with the parent lock.

To queue a lock conversion, the access mode associated with the lock being converted must be equal to, or less privileged than, the access mode of the calling process.

Required Quota

Related Services

$DEQ, $ENQW, $GETLKI, $GETLKIW, $SET_RESOURCE_DOMAIN


Condition Values Returned

SS$_NORMAL The service completed successfully; the lock request was successfully queued.
SS$_SYNCH The service completed successfully; the LCK$M_SYNCSTS flag in the flags argument was specified, and $ENQ was able to grant the lock request immediately.
SS$_ACCVIO The lock status block or the resource name cannot be read.
SS$_BADPARAM You specified an invalid lock mode in the lkmode argument.
SS$_CVTUNGRANT You attempted a lock conversion on a lock that is not currently granted.
SS$_EXDEPTH The limit of levels of sublocks has been exceeded.
SS$_EXENQLM The process has exceeded its enqueue limit (ENQLM) quota.
SS$_INSFMEM The system dynamic memory is insufficient for creating the necessary data structures.
SS$_IVBUFLEN The length of the resource name was either 0 or greater than 31.
SS$_IVLOCKID You specified an invalid or nonexistent lock identification, or the lock identified by the lock identification has an associated access mode that is more privileged than the caller's, or the access mode of the parent was less privileged than that of the caller.
SS$_NOLOCKID No lock identification was available for the lock request.
SS$_NOSYSLCK The LCK$M_SYSTEM flag in the flags argument was specified, but the caller lacks the necessary SYSLCK privilege.
SS$_NOTQUEUED The lock request was not queued; the LCK$M_NOQUEUE flag in the flags argument was specified, and $ENQ was not able to grant the lock request immediately.
SS$_PARNOTGRANT The parent lock specified in the parid argument was not granted.

Condition Values Returned in the Lock Status Block

SS$_NORMAL The service completed successfully; the lock was successfully granted or converted.
SS$_ABORT The lock was dequeued (by the $DEQ service) before $ENQ could grant the lock.
SS$_CANCEL The lock conversion request has been canceled and the lock has been regranted at its previous lock mode. This condition value is returned when $ENQ queues a lock conversion request, the request has not been granted yet (it is in the conversion queue), and, in the interim, the $DEQ service is called (with the LCK$M_CANCEL flag specified) to cancel this lock conversion request. If the lock is granted before $DEQ can cancel the conversion request, the call to $DEQ returns the condition value SS$_CANCELGRANT, and the call to $ENQ returns SS$_NORMAL.
SS$_DEADLOCK A deadlock was detected.
SS$_ILLRSDM The operation attempted is not allowed on the resource. Use SHOW SECURITY to verify the access allowed to the specified resource domain.
SS$_NODOMAIN The RSDM_ID argument passed to the $ENQ call either does not correspond to a valid resource domain for your process, or the system is not running the audit server process.
SS$_VALNOTVALID The lock value block is marked invalid. This warning message is returned only if the caller has specified the flag LCK$M_VALBLK in the flags argument. Note that the lock has been successfully granted despite the return of this warning message. For a complete discussion of lock value block invalidation, see the Description section.
SS$_XVALNOTVALID The extended value block has been marked invalid because the previous writer has written the value block without specifying the LCK$M_XVALBLK flag. This warning message is returned only if the caller has specified the LCK$M_XVALBLK flag in the flags argument. Note that the lock is successfully granted despite the return of this warning message.

For a detailed discussion of extended lock value block invalidation, see the section Invalidation of the Extended Lock Value Block.


$ENQW

Queues a lock on a resource. The $ENQW service completes synchronously; that is, it returns to the caller when the lock has been either granted or converted. For asynchronous completion, use the Enqueue Lock Request ($ENQ) service; $ENQ returns to the caller after queuing the lock request, without waiting for the lock to be either granted or converted. In all other respects, $ENQW is identical to $ENQ. See the $ENQ description for all other information about the $ENQW service.

For additional information about system service completion, see the Synchronize ($SYNCH) service documentation.

The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the user interface to the Lock Management facility.

On Alpha and Integrity server systems, this service accepts 64-bit addresses.


Format

SYS$ENQW [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]


C Prototype

int sys$enqw (unsigned int efn, unsigned int lkmode, struct _lksb *lksb, unsigned int flags, void *resnam, unsigned int parid, void (*astadr)(__unknown_params), unsigned __int64 astprm, void (*blkast)(__unknown_params), unsigned int acmode, unsigned int rsdm_id,...);


$ENTER

The Enter service inserts a file name in a directory.

For additional information about this service, see to the OpenVMS Record Management Services Reference Manual.


$ERAPAT

Generates a security erase pattern.

Format

SYS$ERAPAT [type] ,[count] ,[patadr]


C Prototype

int sys$erapat (int type, unsigned int count, unsigned int *patadr);


Arguments

type


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

Type of storage to be written over with the erase pattern. The type argument is a longword containing the type of storage.

The three storage types, together with their symbolic names, are defined by the $ERADEF macro and are listed in the following table:
Storage Type Symbolic Name
Main memory ERA$K_MEMORY
Disk ERA$K_DISK
Tape ERA$K_TAPE

count


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

Number of times that $ERAPAT has been called in a single security erase operation. The count argument is a longword containing the iteration count.

You should call the $ERAPAT service initially with the count argument set to 1, the second time with the count argument set to 2, and so on, until the status code SS$_NOTRAN is returned.

patadr


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

Security erase pattern to be written. The patadr argument is the address of a longword into which the security erase pattern is to be written.

Description

The Get Security Erase Pattern service generates a security erase pattern that can be written into memory areas containing outdated but sensitive data to make it unreadable. This service is used primarily by the operating system, but it can also be used by users who want to perform security erase operations on foreign disks.

You should call the $ERAPAT service iteratively until the completion status SS$_NOTRAN is returned.

The following example demonstrates how to use the $ERAPAT service to perform a security erase to a disk. Note that, after each call to $ERAPAT, a test for the status SS$_NOTRAN is made. If SS$_NOTRAN has not been returned, $QIO is called to write the pattern returned by $ERAPAT onto the disk. After this write, $ERAPAT is called again and the cycle is repeated until the code SS$_NOTRAN is returned, at which point the security erase procedure is complete.


; Code fragment that erases 20 blocks (blocks 15 through 34) on a disk 
; 
PATTERN: 
        .LONG   0                       ; Cell to contain output from $ERAPAT 
CHANNEL: 
        .WORD   0                       ; Channel assigned to disk device 
DEVICE: .ASCID  /DISK:/                 ; Disk device name 
                . 
                . 
                . 
        $ASSIGN_S DEVNAM=DISK,-         ; Assign a channel to the device 
                CHAN=CHANNEL 
        BLBC    RO, EXIT                ; Branch if error 
                . 
                . 
                .                                         
        MOVL    #1, R2                  ; Set initial count 
 
        $ERADEF                         ; Macro to define names 
                                        ; used by $ERAPAT 
 
10$:    $ERAPAT_S -                     ; Call the $ERAPAT service 
                COUNT=R2,-               
                TYPE=#ERA$K_DISK,- 
                PATADR=PATTERN 
        BLBC    R0, EXIT                ; Branch if error 
        CMPL    #SS$_NOTRAN, R0         ; Are we done? 
        BEQL    EXIT                    ; Branch if so 
        $QIO_S  CHAN=CHANNEL,- 
                FUNC=#I0$_WRITELBLK!IO$M_ERASE,-        ; Call 
                P1=PATTERN,-            ; to the $QIO service 
                P2=#<20*512>,-          ; to write the erase 
                P3=#15                  ; pattern 
 
        INCL    R2                      ; Increase count 
 
        BRB     10$ 
 
EXIT:           . 
                . 
                . 

Required Access or Privileges

None.

Required Quota

None.

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY


Condition Values Returned

SS$_NORMAL The service completed successfully; proceed with the next erase step.
SS$_NOTRAN The service completed successfully; security erase completed.
SS$_ACCVIO The patadr argument cannot be written by the caller.
SS$_BADPARAM The type argument or count argument is invalid.


Previous Next Contents Index