Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $WAITFR

> Tests a specific event flag and returns immediately if the flag is set; otherwise, the process is placed in a wait state until the event flag is set.

### Format

> SYS$WAITFR efn

### C Prototype

> int sys$waitfr (unsigned int efn);

### Argument

> #### efn

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

> Number of the event flag for which to wait. The efn argument is a longword containing this number; however, $WAITFR uses only the low-order byte.

### Description

> The Wait for Single Event Flag service tests a specific event flag and returns immediately if the flag is set. Otherwise, the process is placed in a wait state until the event flag is set. The wait state caused by this service can be interrupted by an asynchronous system trap (AST) if (1) the access mode at which the AST executes is equal to or more privileged than the access mode from which the $WAITFR service was issued and (2) the process is enabled for ASTs at that access mode.

> When a wait state is interrupted by an AST and after the AST service routine completes execution, the operating system repeats the $WAITFR request on behalf of the process. At this point, if the event flag has been set, the process resumes execution.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WFLAND, $WFLOR

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ILLEFC | You specified an illegal event flag number.
> SS$_UNASEFC | The process is not associated with the cluster containing the specified event flag.

## $WAKE

> Activates a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service.

> This service accepts 64-bit addresses.

### Format

> SYS$WAKE [pidadr] ,[prcnam]

### C Prototype

> int sys$wake (unsigned int *pidadr, void *prcnam);

### Arguments

> #### pidadr

> OpenVMS usage: | process_id
> type: | longword (unsigned)
> access: | modify
> mechanism: | by 32- or 64-bit reference

> Process identification (PID) of the process to be activated. The pidadr argument is the 32- or 64-bit address of a longword that contains the PID. The pidadr argument can refer to a process running on the local node or a process running on another node in the cluster.

> #### prcnam

> OpenVMS usage: | process_name
> type: | character-coded text string
> access: | read only
> mechanism: | by 32- or 64-bit descriptor--fixed-length string descriptor

> Process name of the process to be activated. The prcnam argument is the 32- or 64-bit address of a 32- or 64-bit character string descriptor pointing to the process name. A process running on the local node can be identified with a 1 to 15 character string.

> To identify a process on a particular node in a cluster, specify the full process name, which includes the node name as well as the process name. The full process name can contain up to 23 characters.

> The process name is implicitly qualified by the UIC group number of the calling process. For this reason, you can use the prcnam argument only if the process to be activated is in the same UIC group as the calling process. To activate a process in another UIC group, you must specify the pidadr argument.

### Description

> The Wake Process from Hibernation service activates a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service. If you specify neither the pidadr nor the prcnam argument, the wake request is issued for the calling process.

> If the longword at address pidadr is the value 0, the PID of the target process is returned.

> If one or more wake requests are issued for a process not currently hibernating, a subsequent hibernate request completes immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.

> You can also activate a hibernating process with the Schedule Wakeup ($SCHDWK) service.

> Required Access or Privileges

> Depending on the operation, the calling process might need one of the following privileges to use $WAKE:

> - GROUP privilege to wake another process in the same group, unless the process has the same UIC as the calling process
> - WORLD privilege to wake any other process in the system

> Required Quota

> None

> Related Services

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

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The process name string or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller.
> SS$_INCOMPAT | The remote node is running an incompatible version of the operating system.
> SS$_IVLOGNAM | The specified process name string has a length of 0 or has more than 15 characters.
> SS$_NONEXPR | The specified process does not exist, or you specified an invalid process identification.
> SS$_NOPRIV | The process does not have the privilege to wake the specified process.
> SS$_NOSUCHNODE | The process name refers to a node that is not currently recognized as part of the VSMcluster system.
> SS$_REMRSRC | The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)
> SS$_UNREACHABLE | The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)

## $WFLAND

> Allows a process to specify a set of event flags for which it wants to wait.

### Format

> SYS$WFLAND efn ,mask

### C Prototype

> int sys$wfland (unsigned int efn, unsigned int mask);

### Arguments

> #### efn

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

> Number of any event flag within the event flag cluster to be used. The efn argument is a longword containing this number; however, $WFLAND uses only the low-order byte. Specifying the number of an event flag within the cluster serves to identify the event flag cluster.

> There are two local event flag clusters: 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.

> #### mask

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

> Event flags for which the process is to wait. The mask argument is a longword bit vector wherein a bit, when set, selects the corresponding event flag for which to wait.

### Description

> The Wait for Logical AND of Event Flags service allows a process to specify a set of event flags for which it wants to wait. The process is put in a wait state until all specified event flags are set, at which time $WFLAND returns to the caller and execution resumes.

> The wait state caused by this service can be interrupted by an asynchronous system trap (AST) if (1) the access mode at which the AST executes is equal to or more privileged than the access mode from which the $WAITFR service was issued and (2) the process is enabled for ASTs at that access mode.

> When a wait state is interrupted by an AST and after the AST service routine completes execution, the operating system repeats the $WFLAND request on behalf of the process. At this point, if all the specified event flags have been set, the process resumes execution.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLOR

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ILLEFC | You specified an illegal event flag number.
> SS$_UNASEFC | The process is not associated with the cluster containing the specified event flag.

## $WFLOR

> Allows a process to specify a set of event flags for which it wants to wait.

### Format

> SYS$WFLOR efn ,mask

### C Prototype

> int sys$wflor (unsigned int efn, unsigned int mask);

### Arguments

> #### efn

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

> Number of any event flag within the event flag cluster to be used. The efn argument is a longword containing this number; however, $WFLOR uses only the low-order byte. Specifying the number of an event flag within the cluster serves to identify the event flag cluster.

> There are two local event flag clusters: 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.

> #### mask

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

> Event flags for which the process is to wait. The mask argument is a longword bit vector wherein a bit, when set, selects the corresponding event flag for which to wait.

### Description

> The Wait for Logical OR of Event Flags service allows a process to specify a set of event flags for which it wants to wait. The process is put in a wait state until any one of the specified event flags is set, at which time $WFLOR returns to the caller and execution resumes.

> The wait state caused by this service can be interrupted by an asynchronous system trap (AST) if (1) the access mode at which the AST executes is equal to or more privileged than the access mode from which the $WFLOR service was issued and (2) the process is enabled for ASTs at that access mode.

> When a wait state is interrupted by an AST and after the AST service routine completes execution, the operating system repeats the $WFLOR request on behalf of the process. At this point, if any of the specified event flags has been set, the process resumes execution.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> $ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ILLEFC | You specified an illegal event flag number.
> SS$_UNASEFC | The process is not associated with the cluster containing the specified event flag.

## Appendix A
Obsolete Services

The following table lists the obsolete system services and the current services that have replaced them.

Obsolete Service | Current Service
--- | ---
$BRDCST | $BRKTHRU, $BRKTHRUW
$CHANGE_ACL | $GET_SECURITY, $SET_SECURITY
$CNTREG | $DELTVA
$CRELOG | $CRELNM
$DELLOG | $DELLNM
$GETCHN | $GETDVI, $GETDVIW
$GETDEV | $GETDVI, $GETDVIW
$INPUT | $QIO, $QIOW
$OUTPUT | $QIO, $QIOW
$SETSFM | This service is still supported but its use is discouraged.
$SETSSF | This service is still supported but its use is discouraged.
$SNDACC | $SNDJBC, $SNDJBCW
$SNDSMB | $SNDJBC, $SNDJBCW
$TRNLOG | $TRNLNM

Index | Contents

| privacy and legal statement |
4527PRO_104.HTML