HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$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 I64 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.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.


$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.

$ERASE

The Erase service deletes a disk file and removes the file's directory entry specified in the path to the file. If additional directory entries have been created for this file by the Enter service, you must use the Remove service to delete them.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.


$EXIT

Initiates image rundown when the current image in a process completes execution. Control normally returns to the command interpreter.

Format

SYS$EXIT [code]


C Prototype

int sys$exit (unsigned int code);


Argument

code


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

Longword value to be saved in the process header as the completion status of the current image. If you do not specify this argument in a macro call, a value of 1 is passed as the completion code for VAX MACRO and VAX BLISS--32, and a value of 0 is passed for other languages. You can test this value at the command level to provide conditional command execution.

Description

The $EXIT service is unlike all other system services in that it does not return status codes in R0 or anywhere else. The $EXIT service does not return control to the caller; it performs an exit to the command interpreter or causes the process to terminate if no command interpreter is present.

Required Access or Privileges

None

Required Quota

None

Related Services

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


$EXPREG

Adds a specified number of new virtual pages to a process's program region or control region for the execution of the current image. Expansion occurs at the current end of that region's virtual address space.

Format

SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]


C Prototype

int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsigned int acmode, char region);


Arguments

pagcnt


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

Number of pages (on VAX systems) or pagelets (on Alpha and I64 systems) to add to the current end of the program or control region. The pagcnt argument is a longword value containing this number.

On Alpha and I64 systems, the specified value is rounded up to an even multiple of the CPU-specific page size.

retadr


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

Starting and ending process virtual addresses of the pages that $EXPREG has actually added. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.

acmode


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

Access mode to be associated with the newly added pages. The acmode argument is a longword containing the access mode.

The most privileged access mode used is the access mode of the caller.

The newly added pages are given the following protection: (1) read and write access for access modes equal to or more privileged than the access mode used in the call, and (2) no access for access modes less privileged than that used in the call.

region


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

Number specifying which program region is to be expanded. The region argument is a longword value. A value of 0 (the default) specifies that the program region (P0 region) is to be expanded. A value of 1 specifies that the control region (P1 region) is to be expanded.

Description

The Expand Program/Control Region service adds a specified number of new virtual pages to a process's program region or control region for the execution of the current image. Expansion occurs at the current end of that region's virtual address space.

The new pages, which were previously inaccessible to the process, are created as demand-zero pages.

Because the bottom of the user stack is normally located at the end of the control region, expanding the control region is equivalent to expanding the user stack. The effect is to increase the available stack space by the specified amount.

The starting address returned is always the first available page in the designated region; therefore, the ending address is smaller than the starting address when the control region is expanded and is larger than the starting address when the program region is expanded.

If an error occurs while pages are being added, the retadr argument (if specified) indicates the pages that were successfully added before the error occurred. If no pages were added, both longwords of the retadr argument contain the value --1.

Required Access or Privileges

None

Required Quota

The process's paging file quota (PGFLQUOTA) must be sufficient to accommodate the increased size of the virtual address space.

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW

Typically, the information returned in the location addressed by the retadr argument (if specified) can be used as the input range to the Delete Virtual Address Space ($DELTVA) service.


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The return address array cannot be written by the caller.
SS$_EXQUOTA The process exceeded its paging file quota.
SS$_ILLPAGCNT The specified page count was less than 1 or would cause the program or control region to exceed its maximum size.
SS$_INSFWSL The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_VASFULL The process's virtual address space is full. No space is available in the process page table for the requested regions.

$EXPREG_64 (Alpha and I64)

On Alpha and I64 systems, adds a specified number of demand-zero allocation pages to a process's virtual address space for the execution of the current image. Expansion occurs at the next free available address within the specified region.

This service accepts 64-bit addresses.


Format

SYS$EXPREG_64 region_id_64 ,length_64 ,acmode ,flags ,return_va_64 ,return_length_64


C Prototype

int sys$expreg_64 (struct _generic_64 *region_id_64, unsigned __int64 length_64, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64);


Arguments

region_id_64


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

The region ID associated with the virtual address range to be expanded. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each of the three default regions in P0, P1, and P2 space.

The following region IDs are defined:

Symbol Region
VA$C_P0 Program region
VA$C_P1 Control region
VA$C_P2 64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified.

length_64


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

Length of the virtual address space to be created. The length specified must be a multiple of CPU-specific pages.

acmode


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

Access mode associated with the call to $EXPREG_64. The access mode determines the owner mode of the pages as well as the read and write protection on the pages. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.

The $EXPREG_64 service uses whichever of the following two access modes is least privileged:

  • The access mode specified by the acmode argument.
  • The access mode of the caller. The protection of the pages is read/write for the resultant access mode and those more privileged.

Address space cannot be created within a region that has a create mode associated with it that is more privileged than the caller's mode. The condition value SS$_IVACMODE is returned if the caller is less privileged than the create mode for the region.

flags


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

Flag mask controlling the characteristics of the demand-zero pages created. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $VADEF macro and the VADEF.H file define a symbolic name for each flag. You construct the flags argument by performing a logical OR operation on the symbol names for all desired flags.

All bits in the flags argument are reserved for future use by HP and should be specified as 0. The condition value SS$_IVVAFLG is returned if any bits are set.

return_va_64


OpenVMS usage: address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference

The lowest process virtual address of a created virtual address range. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.

return_length_64


OpenVMS usage: byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length in bytes of the virtual address range created.

Description

The Expand Virtual Address Space service is a kernel mode service that can be called from any mode. This service adds a range of demand-zero allocation pages to a process's virtual address space for the execution of the current image. Expansion occurs at the next free available address within the specified region. The new pages, which were previously inaccessible to the process, are created as demand-zero pages.

The returned address is always the lowest virtual address in the range of pages created. The returned length is always an unsigned byte count indicating the length of the range of pages created.

Successful return status from $EXPREG_64 Expand Virtual Address service means that the specified region's virtual address space was expanded by the number of bytes specified in the length_64 argument.

If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64 and return_length_64 arguments. If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully added before the error occurred. If no pages were added, the return_va_64 argument will contain the value --1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

None

Required Quota

The working set quota (WSQUOTA) of the process must be sufficient to accommodate the increased length of the process page table required by the increase in virtual address space.

The process's paging file quota (PGFLQUOTA) must be sufficient to accommodate the increased size of the virtual address space.

Related Services

$CREATE_BUFOBJ_64, $CREATE_REGION_64, $CRETVA_64, $DELETE_REGION_64, $DELTVA_64, $LCKPAG_64, $LKWSET_64, $PURGE_WS, $SETPRT_64, $ULKPAG_64, $ULWSET_64


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The return_va_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_EXPGFLQUOTA The process exceeded its paging file quota.
SS$_INSFWSL The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE The caller's mode is less privileged than the create mode associated with the region.
SS$_IVREGID An invalid region ID was specified.
SS$_IVVAFLG An invalid flag, a reserved flag, or an invalid combination of flags and arguments was specified.
SS$_LEN_NOTPAGMULT The length_64 argument is not a multiple of CPU-specific pages.
SS$_NOSHPTS The region ID of a shared page table region was specified.
SS$_REGISFULL The specified virtual region is full.


Previous Next Contents Index