OpenVMS System Services Reference Manual

The time interval specified cannot be less than 10 milliseconds; if it is, $SCHDWK automatically increases it to 10 milliseconds.

If you do not specify reptim, a default value of 0 is used, which specifies that the wakeup request is not to be repeated.

DESCRIPTION

The Schedule Wakeup service schedules the awakening of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service. A wakeup can be scheduled for a specified absolute time or for a delta time and can be repeated at fixed intervals.
If you specify neither the pidadr nor the prcnam argument, the wakeup request is issued on behalf of the calling process. If the longword value at address pidadr is 0, the PID of the target process is returned.
$SCHDWK uses the system dynamic memory to allocate a timer queue entry.
If you issue one or more scheduled wakeup requests for a process that is not hibernating, a subsequent hibernate request by the target process completes immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.
You can cancel scheduled wakeup requests that have not yet been processed by using the Cancel Wakeup ($CANWAK) service.
If a specified absolute time value has already passed and no repeat time is specified, the timer expires at the next clock cycle (within 10 milliseconds).
Required Access or Privileges

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

GROUP privilege to schedule wakeup requests for a process in the same group unless it has the same UIC
WORLD privilege to schedule wakeup requests for any other process in the system

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 calling process to schedule a wakeup request.
Related Services

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

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The expiration time, repeat time, process name string, or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller.

SS$_EXQUOTA The process has exceeded its AST limit quota.

SS$_INCOMPAT The remote node is running an incompatible version of the operating system.

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

SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters.

SS$_IVTIME The specified delta repeat time is a positive value, or an absolute time plus delta repeat time is less than the current time.

SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_NOPRIV The process does not have the privilege to schedule a wakeup request for the specified process.

SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the OpenVMS Cluster 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.)

$SCHED

Affects process scheduling. This service is intended for use by a class scheduler process.

Format

SYS$SCHED func ,p1 ,p2 ,p3

C Prototype

int sys$sched (unsigned int func, unsigned int *p1, unsigned int *p2, unsigned int *p3);

ARGUMENTS

func

OpenVMS usage: function_code

type: longword (unsigned)

access: write only

mechanism: by value

Function code specifying the action $SCHED is to perform. The func argument is a longword containing this code.
See the Function Codes section for a list of valid function codes for $SCHED.
p1, p2, p3

OpenVMS usage: longword

type: longword (unsigned)

access: varies

mechanism: varies

The meaning of the p1, p2, and p3 arguments depends on the function code specified in the func argument, and is defined in the Function Codes section.

Function Codes This section defines each of the $SCHED function codes and describes the values of the p1 argument, p2 argument, and p3 argument for each function.

CSH$_READ_ALL
When you specify CSH$_READ_ALL, $SCHED returns a buffer containing information, including an index, EPID, and priority, for all processes.
The format of the buffer is defined in the $CSHDEF macro and consists of a series of CSHP fields.
The following table shows the p1 argument, p2 argument, and p3 argument values for the CSH$_READ_ALL function code.

Argument Access Description

p1 Read Address of the buffer.

p2 Read Address of the longword size of the buffer.

p3 Write Address of the longword size of the per-process entry.

CSH$_READ_NEW
When you specify CSH$_READ_NEW, $SCHED returns a buffer containing information, including an index, EPID, and priority, for all processes for which a class assignment has not been made.
The format of the buffer is defined in the $CSHDEF macro and consists of a series of CSHP fields.
The following table shows the p1 argument, p2 argument, and p3 argument values for the CSH$_READ_NEW function code.

Argument Access Description

p1 Read Address of the buffer.

p2 Read Address of the longword size of the buffer.

p3 Write Address of the longword size of the per-process entry.

The following table describes the information returned in the buffer fields for both CSH$_READ_ALL and CSH$_READ_NEW.

Buffer Field Definition

CSHP$T_ACCOUNT Account string from the user authorization file (first eight characters).

CSHP$L_CPUTIM Process CPU time used, in 10-millisecond ticks.

CSHP$L_EPID Process ID (PID). If CSHP information is insufficient to determine the right class for a process, the PID can be used with the $GETJPI(W) system service to obtain additional detail.

CSHP$W_PIX A unique integer assigned to the process for its duration. Applications might want to use this value to index arrays.

CSHP$B_PRI Current process priority.

CSHP$B_PRIB Base process priority.

CSHP$L_STATUS Undefined; reserved to Digital.

CSH$_READ_QUANT
When you specify CSH$_READ_QUANT, $SCHED returns a buffer containing information about how many ticks are left for each class. Data is returned in a series of longwords, one longword per class, starting with class number 0.
The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_READ_QUANT function code.

Argument Access Description

p1 Read Address of the buffer.

p2 Read Address of the longword size of the buffer.

p3 --- Unused.

CSH$_SET_ATTN_AST
Enables attention asynchronous system traps (ASTs).
The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_ATTN_AST function code.

Argument Access Description

p1 Read Address of an AST routine.

p2 Read Access mode to deliver AST.

p3 --- Unused.

CSH$_SET_CLASS
Places processes in classes with or without windfall capability. The caller supplies a buffer consisting of CSHC blocks.
The format of the buffer is defined in the $CSHDEF macro. The following table describes the information contained in the buffer.

Buffer Field Definition

CSHC$L_EPID Process ID (PID) of the process to affect.

CSHC$W_CLASS Class into which to place the process. Class 65535 (hexadecimal FFFF) has a special interpretation: the associated process is not to be class scheduled and will, therefore, never run out of class quantum. The largest class number is 8191.

CSHC$W_WINDFALL Determines whether the process is to share windfall. A value of 1 permits the process to share windfall; a value of 0 prevents the process from sharing windfall. Values other than 0 and 1 are undefined and can cause unpredictable behavior in future releases of the operating system.

The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_CLASS function code.

Argument Access Description

p1 Read Address of the buffer.

p2 Read Address of the longword size of the buffer.

p3 Read Address of the longword size of the entry used. Should be CSHC$K_LENGTH or equivalent.

CSH$_SET_NEW
Indicates to the class scheduler that the next READ_NEW will return information about the calling process. This function should be used only in executive or kernel mode.
The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_NEW function code.

Argument Access Description

p1 --- Unused.

p2 Read PID (by value).

p3 --- Unused.

CSH$_SET_QUANT
Establishes class quantum and enables class scheduling. The caller supplies a buffer that allocates CPU ticks to classes, one longword per class, starting with class number 0. Class-scheduled processes will have their quantum deducted from the appropriate longword, and will be removed from execution if class quantum is decremented to 0.
The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_QUANT function code.

Argument Access Description

p1 Read Address of the buffer.

p2 Read Address of the longword size of buffer.

p3 --- Unused.

CSH$_SET_TIMEOUT
Establishes a nonstandard timeout. If the application does not issue a CSH$_SET_QUANT within the timeout period, all class scheduling is stopped and processes are returned to normal scheduling. The default value, 30 seconds, should be suitable for most circumstances.
The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_TIMEOUT function code.

Argument Access Description

p1 --- Unused.

p2 Read Time in seconds (by value).

p3 --- Unused.

Argument	Access	Description
p1	Read	Address of the buffer.
p2	Read	Address of the longword size of the buffer.
p3	Write	Address of the longword size of the per-process entry.

Argument	Access	Description
p1	Read	Address of the buffer.
p2	Read	Address of the longword size of the buffer.
p3	Write	Address of the longword size of the per-process entry.

Buffer Field	Definition
CSHP$T_ACCOUNT	Account string from the user authorization file (first eight characters).
CSHP$L_CPUTIM	Process CPU time used, in 10-millisecond ticks.
CSHP$L_EPID	Process ID (PID). If CSHP information is insufficient to determine the right class for a process, the PID can be used with the $GETJPI(W) system service to obtain additional detail.
CSHP$W_PIX	A unique integer assigned to the process for its duration. Applications might want to use this value to index arrays.
CSHP$B_PRI	Current process priority.
CSHP$B_PRIB	Base process priority.
CSHP$L_STATUS	Undefined; reserved to Digital.

Argument	Access	Description
p1	Read	Address of the buffer.
p2	Read	Address of the longword size of the buffer.
p3	---	Unused.

Argument	Access	Description
p1	Read	Address of an AST routine.
p2	Read	Access mode to deliver AST.
p3	---	Unused.

Buffer Field	Definition
CSHC$L_EPID	Process ID (PID) of the process to affect.
CSHC$W_CLASS	Class into which to place the process. Class 65535 (hexadecimal FFFF) has a special interpretation: the associated process is not to be class scheduled and will, therefore, never run out of class quantum. The largest class number is 8191.
CSHC$W_WINDFALL	Determines whether the process is to share windfall. A value of 1 permits the process to share windfall; a value of 0 prevents the process from sharing windfall. Values other than 0 and 1 are undefined and can cause unpredictable behavior in future releases of the operating system.

Argument	Access	Description
p1	Read	Address of the buffer.
p2	Read	Address of the longword size of the buffer.
p3	Read	Address of the longword size of the entry used. Should be CSHC$K_LENGTH or equivalent.

Argument	Access	Description
p1	---	Unused.
p2	Read	PID (by value).
p3	---	Unused.

Argument	Access	Description
p1	Read	Address of the buffer.
p2	Read	Address of the longword size of buffer.
p3	---	Unused.

Argument	Access	Description
p1	---	Unused.
p2	Read	Time in seconds (by value).
p3	---	Unused.

DESCRIPTION

The Affect Process Scheduling service is used by class scheduler processes to affect scheduling.
Use the func argument to specify which action $SCHED is to perform.
Required Access or Privileges

ALTPRI is required to affect processes. Group access is required to affect processes in the same UIC group. World access is required to affect processes in different UIC groups. SYSPRV is required to set the timeout value.
Required Quota

None
Related Services

$GETJPI, $GETJPIW, $SETPRI

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADPARAM The function code is invalid.

SS$_ILLSER The loadable image CLASS_SCHEDULER has not been loaded. Refer to the SYSMAN command SYS_LOADABLE in the OpenVMS System Management Utilities Reference Manual for instructions.

$SETAST

Enables or disables the delivery of asynchronous system traps (ASTs) for the access mode from which the service call was issued.

Format

SYS$SETAST enbflg

C Prototype

int sys$setast (char enbflg);

ARGUMENT

enbflg

OpenVMS usage: boolean

type: byte (unsigned)

access: read only

mechanism: by value

Value specifying whether ASTs are to be enabled. The enbflg argument is a byte containing this value. The value 1 enables AST delivery for the calling access mode; the value 0 disables AST delivery.

DESCRIPTION

The Set AST Enable service enables or disables the delivery of ASTs for the access mode from which the service call was issued.
Required Access or Privileges

When an image is executing in user mode, ASTs are always enabled for more privileged access modes. If ASTs are disabled for a more privileged access mode, the operating system cannot deliver ASTs for less privileged access modes until ASTs are enabled once again for the more privileged access mode. Therefore, a process that has disabled ASTs for a more privileged access mode must reenable ASTs for that mode before returning to a less privileged access mode.
Required Quota

None
Related Services

$DCLAST, $SETPRA

Condition Values Returned

SS$_WASCLR The service completed successfully. AST delivery was previously disabled for the calling access mode.

SS$_WASSET The service completed successfully. AST delivery was previously enabled for the calling access mode.

$SETCLUEVT (Alpha Only)

On Alpha systems, establishes a request for notification when an OpenVMS Cluster configuration event occurs.

Format

SYS$SETCLUEVT event ,astadr ,[astprm] ,[acmode] ,[handle]

C Prototype

int sys$setcluevt (unsigned int event, void (*astadr)(__unknown_params), int astprm, unsigned int acmode, struct _generic_64 *handle);

ARGUMENTS

event

OpenVMS usage: event_code

type: longword (unsigned)

access: read only

mechanism: by value

Event code indicating the type of cluster configuration event for which an AST is to be delivered. The event argument is a value indicating which type of event is of interest.
Each event type has a symbolic name. The $CLUEVTDEF macro defines the following symbolic names.

Symbolic Name Description

CLUEVT$C_ADD One or more OpenVMS nodes have been added to the OpenVMS Cluster system.

CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.

astadr

OpenVMS usage: ast_procedure

type: procedure value

access: call without stack unwinding

mechanism: by reference

Notification AST routine to receive control after a change in OpenVMS Cluster configuration occurs.
astprm

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by value

Optional AST parameter to be passed to the AST service routine. The astprm argument is a longword value containing the AST parameter.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Optional access mode at which the configuration event AST is to execute. The acmode argument is a longword containing the access mode.
Each access mode has a symbolic name. 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 value of the access mode must not be more privileged than the access mode of the caller.
handle

OpenVMS usage: identifier

type: quadword (unsigned)

access: write only

mechanism: by reference

Optional identifier to receive a value that uniquely identifies this AST request. $SETCLUEVT sets this handle to a unique value so that it can later be used to identify the request in the $CLRCLUEVT and $TSTCLUEVT services.

Symbolic Name	Description
CLUEVT$C_ADD	One or more OpenVMS nodes have been added to the OpenVMS Cluster system.
CLUEVT$C_REMOVE	One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

DESCRIPTION

The Set Cluster Event service establishes a request for notification when a cluster configuration event occurs. The service establishes only one AST notification for a configuration event. To receive AST notification for all cluster configuration events, the $SETCLUEVT service must be reissued within the notification AST routine. The service will verify that the input parameters specify a valid request, allocate appropriate data structures to hold the request, and enqueue the request for notification.
You must specify an event type and an AST address. You can specify an AST parameter, the access mode, and an address into which to place the handle of this request.
Errors will be returned in the following cases:

If quotas are exceeded, an error identifying the specific quota will be returned. It is important to note that this routine will return an error and will not retry an attempt to get quota if quota is exhausted on the first attempt. See the Condition Values Returned section for types of errors that can be returned.
If the astadr argument is omitted, SS$_BADPARAM will be returned.
If the event argument is omitted or incorrectly specified, SS$_BADPARAM will be returned.
If the access mode parameter is more privileged than the mode of the caller, the mode of the caller will be used.
If specified, the handle argument must be readable and writable from the mode of the caller. SS$_ACCVIO is returned if this is not the case.

Required Access or Privileges

None
Required Quota

None
Related Services

$CLRCLUEVT, $TSTCLUEVT

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO Unable to process parameters for improper use.

SS$_BADPARAM The event was improperly specified.

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

SS$_INSFMEM The system dynamic memory is insufficient to complete the service.

$SETDDIR

Allows you to read and change the default directory string for the process.

Format

SYS$SETDDIR [new-dir-addr] ,[length-addr] ,[cur-dir-addr]

C Prototype

int sys$setddir (void *newdiraddr, unsigned short int *lengthaddr, void *curdiraddr);

ARGUMENTS

new-dir-addr

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor---fixed-length string descriptor

A descriptor of the new default directory. The new-dir-addr argument is the address of the descriptor that points to the buffer containing the new directory specification that RMS will use to set the new process-default directory. If the default directory is not to be changed, the value of the new-dir-addr argument should be 0.
length-addr

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

A word that is to receive the length of the current default directory. The length-addr argument is the address of the word that will receive the length. If you do not want this value returned, specify the value 0.
cur-dir-addr

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor---fixed-length string descriptor

A descriptor of a buffer that is to receive the current default directory string. The cur-dir-addr argument is the address of the descriptor that points to the buffer area that is to receive the current directory string.

DESCRIPTION

The Set Default Directory service allows you to read and change the default directory string for the process. You should restore the old default directory string to its original status unless you want the changed default directory string to last beyond the exit of your image. The new directory name string is checked for correct syntax.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P064.HTM
  OSSG Documentation
  22-NOV-1996 13:00:27.14
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The expiration time, repeat time, process name string, or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller.
SS$_EXQUOTA	The process has exceeded its AST limit quota.
SS$_INCOMPAT	The remote node is running an incompatible version of the operating system.
SS$_INSFMEM	The system dynamic memory is insufficient for allocating a timer queue entry.
SS$_IVLOGNAM	The process name string has a length of 0 or has more than 15 characters.
SS$_IVTIME	The specified delta repeat time is a positive value, or an absolute time plus delta repeat time is less than the current time.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_NOPRIV	The process does not have the privilege to schedule a wakeup request for the specified process.
SS$_NOSUCHNODE	The process name refers to a node that is not currently recognized as part of the OpenVMS Cluster 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.)

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

OpenVMS usage:	longword
type:	longword (unsigned)
access:	varies
mechanism:	varies

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	The function code is invalid.
SS$_ILLSER	The loadable image CLASS_SCHEDULER has not been loaded. Refer to the SYSMAN command SYS_LOADABLE in the OpenVMS System Management Utilities Reference Manual for instructions.

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

SS$_WASCLR	The service completed successfully. AST delivery was previously disabled for the calling access mode.
SS$_WASSET	The service completed successfully. AST delivery was previously enabled for the calling access mode.

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

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

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

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

OpenVMS usage:	identifier
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference