OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

$SETDFPROT

Allows you to read and write the default file protection for the process.

Format

SYS$SETDFPROT [new-def-prot-addr] ,[cur-def-prot-addr]

C Prototype

int sys$setdfprot (unsigned short int *newdefprotaddr, unsigned short int *curdefprotaddr);

Arguments

new-def-prot-addr

OpenVMS usage: file_protection

type: word (unsigned)

access: read only

mechanism: by reference

A word that specifies the new default file protection specification. The new-def-prot-addr argument is the address of the word that specifies the desired protection. If you do not want the process-default file protection to be changed, specify the value 0.
cur-def-prot-addr

OpenVMS usage: file_protection

type: word (unsigned)

access: write only

mechanism: by reference

A word that is to receive the current default file protection specification. The cur-def-prot-addr argument is the address of the word that receives the current process-default protection. If you do not want the current default file protection, specify the value 0.

Description

The Set Default File Protection service allows you to read and write the default file protection for the process. You should restore the old default file protection specification unless you want the changed default to last beyond the exit of your image.
There is no predefined macro of the form $SETDEFPROT_G or $SETDEFPROT_S to call this service.
Required Access or Privileges

None
Required Quota

None
Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $GET_SECURITY, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SET_SECURITY, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

RMS$_NORMAL The service completed successfully.

RMS$_IAL The argument list is invalid.

$SETEF

Sets an event flag in a local or common event flag cluster. The condition value returned by $SETEF indicates whether the specified flag was previously set or clear. After the event flag is set, processes waiting for the event flag to be set resume execution.

Format

SYS$SETEF efn

C Prototype

int sys$setef (unsigned int efn);

Argument

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be set. The efn argument is a longword containing this number; however, $SETEF uses only the low-order byte.
Two local event flag clusters are local to the process: cluster 0 and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1 contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127.

Condition Values Returned

SS$_WASCLR The service completed successfully. The specified event flag was previously 0.

SS$_WASSET The service completed successfully. The specified event flag was previously 1.

SS$_ILLEFC You specified an illegal event flag number.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$SETEXV

Assigns a condition handler address to the primary, secondary, or last chance exception vectors, or removes a previously assigned handler address from any of these three vectors.

Format

SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]

C Prototype

int sys$setexv (unsigned int vector, int (*addres)(__unknown_params), unsigned int acmode, void *(*(prvhnd)));

Arguments

vector

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by value

Vector for which a condition handler is to be established or removed. The vector argument is a longword value. The value 0 (the default) specifies the primary exception vector; the value 1, the secondary vector; and the value 2, the last chance exception vector.
addres

OpenVMS usage: procedure

type: procedure value

access: call without stack unwinding

mechanism: by reference

Condition handler address to be established for the exception vector specified by the vector argument. The addres argument is a longword value containing the address of the condition handler routine.
If you do not specify addres or specify it as the value 0, the condition handler address already established for the specified vector is removed; that is, the contents of the longword vector is set to 0.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode for which the exception vector is to be modified. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.
The most privileged access mode used is the access mode of the caller. Exception vectors for access modes more privileged than the caller's access mode cannot be modified.

prvhnd

OpenVMS usage: procedure value

type: longword (unsigned)

access: write only

mechanism: by reference

Previous condition handler address contained by the specified exception vector. The prvhnd argument is the address of a longword into which $SETEXV writes the handler's procedure value.

Description

The Set Exception Vector service (1) assigns a condition handler address to the primary, secondary, or last chance exception vectors or (2) removes a previously assigned handler address from any of these three vectors. A process cannot modify a vector associated with a more privileged access mode.
The operating system provides two different methods for establishing condition handlers:

Using the call stack associated with each access mode. Each call frame includes a longword to contain the address of a condition handler associated with that frame.
On VAX systems, the RTL routine LIB$ESTABLISH establishes a condition handler; the RTL routine LIB$REVERT removes a handler.
Using the software exception vectors (by using $SETEXV) associated with each access mode. These vectors are set aside in the control region (P1 space) of the process.

The modular properties associated with the first method do not apply to the second. The software exception vectors are intended primarily for performance monitors and debuggers. For example, the primary exception vector and the last chance exception vector are used by the OpenVMS Debugger for user mode access, and DCL uses the last chance exception vector for supervisor mode access.
User mode exception vectors are canceled at image exit.
Required Access or Privileges

None
Required Quota

None
Related Services

$DCLCMH, $SETSFM, $UNWIND

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The longword to receive the previous contents of the vector cannot be written by the caller.

$SETIME

Changes the value of, or recalibrates, the system time.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$SETIME [timadr]

C Prototype

int sys$setime (struct _generic_64 *timadr);

Argument

timadr

OpenVMS usage: date_time

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

New absolute time value for the system time, specifying the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a quadword containing the new system time value. A negative (delta) time value is invalid.
If you do not specify the value of timadr or specify it as 0, $SETIME recalibrates the system time using the time-of-year clock.

Description

The Set System Time service (1) changes the value of or (2) recalibrates the system time which is defined by a quadword value that specifies the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858.
System time is the reference used for nearly all timer-related software activities in the operating system. After changing or recalibrating the system clock, $SETIME updates the timer queue by adjusting each element in the timer queue by the difference between the previous system time and the new system time.
The $SETIME service saves the new time (for future bootstrap operations) in the system image SYS$SYSTEM:SYS.EXE on VAX systems or SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE on Alpha systems. To save the time, the service assigns a channel to the system boot device and calls $QIOW. You need the LOG_IO user privilege to perform this operation.
Required Access or Privileges

To set system time, the calling process must have OPER, LOG_IO, and SYSPRV privileges.
Required Quota

None
Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIMR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The quadword that contains the new system time value cannot be read by the caller.

SS$_IVTIME The caller specified no time value or a negative time value and an invalid processor clock was found.

SS$_NOIOCHAN No I/O channel is available for assignment.

SS$_NOPRIV The process does not have the privileges to set the system time.

$SETIMR

Sets the timer to expire at a specified time.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]

C Prototype

int sys$setimr (unsigned int efn, struct _generic_64 *daytim, void (*astadr)(__unknown_params), unsigned __int64 reqidt, unsigned int flags);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Event flag to be set when the timer expires. The efn argument is a longword value containing the number of the event flag; however, $SETIMR uses only the low-order byte. If you do not specify efn, event flag 0 is set.
When $SETIMR first executes, it clears the specified event flag or event flag 0.
daytim

OpenVMS usage: date_time

type: quadword

access: read only

mechanism: by 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Time at which the timer expires. The daytim argument is the 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a quadword time value. A positive time value specifies an absolute time at which the timer expires; a negative time value specifies an offset (delta time) from the current time.
astadr

OpenVMS usage: ast_procedure

type: procedure value

access: call without stack unwinding

mechanism: by 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

AST service routine that is to execute when the timer expires. The astadr argument is the 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the procedure value of this routine. If you do not specify the value of astadr or specify it as 0 (the default), no AST routine executes.
The AST routine, if specified, executes at the access mode of the caller.
reqidt

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by value

Identification of the timer request. The reqidt argument is a longword value containing a number that uniquely identifies the timer request. If you do not specify reqidt, the value 0 is used.
To cancel a timer request, the identification of the timer request (as specified by reqidt in $SETIMR) is passed to the Cancel Timer ($CANTIM) service (as the reqidt argument).
If you want to cancel specific timer requests but not all timer requests, be sure to specify a nonzero value for reqidt in the $SETIMR call; $CANTIM interprets an identification value of 0 as a request to cancel all timer requests.
You can specify unique values for reqidt for each timer request or give the same value to related timer requests. This permits selective canceling of a single timer request, a group of related timer requests, or all timer requests.
If you specify the astadr argument in the $SETIMR call, the value specified by the reqidt argument is passed as a parameter to the AST routine. If the AST routine requires more than one parameter, specify an address for the value of reqidt; the AST routine can then interpret that address as the beginning of a list of parameters.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Longword of bit flags for the set timer operation. Currently, only bit 0 is used for the flags argument. When the low bit (bit 0) is set, it indicates that this timer request should be in units of CPU time, rather than elapsed time. When bit 0 is clear (the default), the timer request is in units of elapsed time. The flags argument is optional.

Description

The Set Timer service sets the timer to expire at a specified time. When the timer expires, an event flag is set and (optionally) an AST routine executes. This service requires dynamic memory and executes at the access mode of the caller, as does the AST routine if one is specified.
Required Access or Privileges

None
Required Quota

This service uses the process's timer queue entries (TQELM) quota. If you specify an AST routine, the service uses the AST limit (ASTLM) quota of the process.
Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The expiration time cannot be read by the caller.

SS$_EXQUOTA The process exceeded its quota for timer entries or its AST limit quota; or the system dynamic memory is insufficient for completing the request.

SS$_ILLEFC You specified an illegal event flag number.

SS$_INSFMEM The dynamic memory is insufficient for allocating a timer queue entry.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$SETPRA

Establishes a routine to receive control after a power recovery is detected.

Format

SYS$SETPRA astadr ,[acmode]

C Prototype

int sys$setpra (int (*astadr)(__unknown_params), unsigned int acmode);

Arguments

astadr

OpenVMS usage: ast_procedure

type: procedure value

access: call without stack unwinding

mechanism: by reference

Power recovery AST routine to receive control when a power recovery is detected. The astadr argument is the address of this routine.
If you specify astadr as the value 0, an AST is not delivered to the process when a power recovery is detected.
The system passes one parameter to the specified AST routine. This parameter is a longword value containing the length of time that the power was off, expressed as the number of 1/100th-of-a-second intervals that have elapsed.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode at which the power recovery AST routine is to execute. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.
The most privileged access mode used is the access mode of the caller.

Description

The Set Power Recovery AST service establishes a routine to receive control after a power recovery is detected.
You can specify only one power recovery AST routine for a process. The AST entry point address is cleared at image exit.
The entry and exit conventions for the power recovery AST routine are the same as for all AST service routines.
Required Access or Privileges

None
Required Quota

One unit of quota is deducted from the process's ASTLM.
Related Services

$DCLAST, $SETAST
For more information, see the chapter on AST services in the OpenVMS Programming Concepts Manual.

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_EXQUOTA The process exceeded its quota for outstanding AST requests.

Contents

Index

Legal

 
4527PRO_079.HTML

OpenVMS usage:	file_protection
type:	word (unsigned)
access:	read only
mechanism:	by reference

RMS$_NORMAL	The service completed successfully.
RMS$_IAL	The argument list is invalid.

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

SS$_WASCLR	The service completed successfully. The specified event flag was previously 0.
SS$_WASSET	The service completed successfully. The specified event flag was previously 1.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

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

OpenVMS usage:	procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

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

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The longword to receive the previous contents of the vector cannot be written by the caller.

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

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

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

SS$_NORMAL	The service completed successfully.
SS$_EXQUOTA	The process exceeded its quota for outstanding AST requests.