Document revision date: 19 July 1999

Removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment.

Format

SYS$PURGWS inadr

C Prototype

int sys$purgws (struct _va_range *inadr);

Argument

inadr

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

Starting and ending virtual addresses of the range of pages to be purged. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. The addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.

Description

The Purge Working Set service removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment. However, the Adjust Working Set Limit ($ADJWSL) service is the preferred mechanism for controlling a process's use of physical memory resources.

The $PURGWS service locates pages within the specified range and removes them if they are in the working set.

If the starting and ending virtual addresses are the same, only that single page is purged.

To purge the entire working set, specify a range of pages from 0 through 7FFFFFFF; in this case, the image continues to execute and pages are faulted back into the working set as they are needed.

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The input address array cannot be read by the caller.

On Alpha systems, removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment.

This service accepts 64-bit addresses.

Format

SYS$PURGE_WS start_va_64 ,length_64

C Prototype

int sys$purge_ws (void *start_va_64, unsigned __int64 length_64);

Arguments

start_va_64

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

The starting virtual address of the pages to be purged from the working set. The specified virtual address will be rounded down to a CPU-specific page boundary.

length_64

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

Length of the virtual address space to be purged from the working set. The specified length will be rounded up to a CPU-specific page boundary so that it includes all CPU-specific pages in the requested range.

Description

The Purge Working Set service removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment. However, the Adjust Working Set Limit ($ADJWSL) service is the preferred mechanism for controlling a process's use of physical memory resources.

The $PURGE_WS service locates pages within the specified range and removes them if they are in the working set. To purge the entire working set, specify a range of pages from 0 through FFFFFFFF.FFFFFFFF (or to the highest possible process private virtual address, available from $GETJPI); in this case, the image continues to execute, and pages are faulted back into the working set.

Required Privileges

None

Required Quota

None

Related Services

$ADJWSL, $LCKPAG_64, $LKWSET_64, $PURGWS, $ULKPAG_64, $ULWSET_64

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Writes informational and error messages to processes.

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

Format

SYS$PUTMSG msgvec ,[actrtn] ,[facnam] ,[actprm]

C Prototype

int sys$putmsg (void *msgvec, void (*actrtn)(__unknown_params), void *facnam, unsigned __int64 actprm);

Arguments

msgvec

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

Message argument vector specifying the message or messages to be written and options that $PUTMSG is to use in writing the message or messages. The msgvec argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the message vector.

The message vector consists of one longword followed by one or more message descriptors, one descriptor per message. The following diagram depicts the contents of the first longword.

The following table describes the message vector fields.

Descriptor Field	Definition
Argument count	This word-length field specifies the total number of longwords in the message vector, not including the first longword (of which it is a part).
Default message options	This word-length field specifies which message component or components are to be written. The default message options field is a word-length bit vector wherein a bit, when set, specifies that the corresponding message component is to be written. For a description of each of these components, refer to the Description section.

The following table shows the significant bit numbers. Note that the bit numbers shown (0, 1, 2, 3) are the bit positions from the beginning of the word; however, because the word is the second word in the longword, you should add the number 16 to each bit number to specify its exact offset within the longword.

Bit	Value	Description
0	1 0	Include message text Do not include message text
1	1 0	Include mnemonic name for message text Do not include mnemonic name for message text
2	1 0	Include severity level indicator Do not include severity level indicator
3	1 0	Include facility prefix Do not include facility prefix

Bits 4 through 15 must be 0.

You can override the default setting specified by the default message options field for any or all messages by specifying different options in the new message options field of any subsequent message descriptor. When you specify new message options, the options it specifies become the new default settings for all remaining messages until you specify new message options again.

The $PUTMSG service passes the default message options field to the $GETMSG service as the flags argument.

If you specify the default message options field as 0, the default message options for the process are used; you can set the process default message options by using the DCL command SET MESSAGE.

The Description section shows the format that $PUTMSG uses to write these message components.

Message Descriptors

Following the first longword of the message vector are one or more message descriptors. A message descriptor can have one of four possible formats, depending on the type of message it describes. There are four types of messages:

• User-supplied
• System
• OpenVMS RMS
• System exception

The following diagrams depict the message descriptors for each type of message.

Message Descriptor for User-Supplied Messages

Message Descriptor for System Messages

Message Descriptor for OpenVMS RMS Messages

Message Descriptor for System Exception Messages

On Alpha systems, 64-bit message vectors can be used for applications that require them. A 64-bit message vector begins with the same argument count longword as the 32-bit message vector. After the argument count longword is another longword containing the value SS$_SIGNAL64, which signals that a 64-bit message vector follows. Subsequent message vector elements have a layout analogous to 32-bit message vectors but are 64-bits wide.

For example, the following diagram depicts the format of a 32-bit message vector:

The 64-bit version of that same message vector would have the following format:

The $PUTMSG service accepts either the 32-bit or the 64-bit form of the message vector on Alpha systems.

actrtn

Note that the first argument passed to the action routine is the address of a character string descriptor pointing to the message text; the parameter specified by actprm is the second.

The action routine receives control after a message is formatted but before it is actually written to the user.

The completion code in general register R0 from the action routine indicates whether the message should be written. If the low-order bit of R0 is set (1), then the message will be written. If the low-order bit is cleared (0), then the message will not be written.

If you do not specify actrtn or specify it as 0 (the default), no action routine executes.

Because $PUTMSG writes messages only to SYS$ERROR and SYS$OUTPUT, an action routine is useful when output must be directed to, for example, a file.

facnam

If you do not specify facnam, $PUTMSG uses the default facility prefix associated with the message.

actprm

Description

In the operating system, a message is identified by a longword value, which is called the message code. To construct a message code, you specify values for its four fields, using the Message utility. The following diagram depicts the longword message code.

Thus, each message has a unique longword value associated with it: its message code. You can give this longword value a symbolic name using the Message utility. Such a symbolic name is called the message symbol.

The Message utility describes how to construct a message symbol according to the conventions for operating system messages. Basically, the message symbol has two parts: (1) a facility prefix, which is an abbreviation of the name of the facility with which the message is associated, and (2) a mnemonic name for the message text, which serves to hint at the nature of the message. These two parts are separated by an underscore character (_) in the case of a user-constructed message and by a dollar sign/underscore ($_) in the case of system messages.

The message components written by $PUTMSG are derived both from the message code and from the message symbol. For additional information about both the message code and the message symbol, refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

The $PUTMSG service writes the message components in the following format:

%FACILITY-L-IDENT, message text

where:

%	Is the prefix used for the first message written. The hyphen (-) is the prefix used for the remaining messages.
FACILITY	Is the facility prefix taken from the message symbol. This facility prefix can be overridden by a facility prefix specified in the facnam argument in the call to $PUTMSG.
L	Is the severity level indicator. The severity level indicator is taken from the message code.
IDENT	Is a mnemonic name for the message text, taken from the message symbol.
message text	Is the message text specified in the message source file.

The $PUTMSG service does not check the length of the argument list and therefore cannot return the SS$_INSFARG (insufficient arguments) condition value. Be sure you specify the required number of arguments.

If an error occurs while $PUTMSG calls the Formatted ASCII Output ($FAO) service, $FAO parameters specified in the message vector do not appear in the output.

You cannot call the $PUTMSG service from kernel mode.

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, $INIT_VOL, $MOUNT, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Example

#include <ssdef.h> 
#include <rmsdef.h> 
#include <starlet.h> 
 
main() 
{ 
    int msgvec[] = {3,                  /* Arg count and message flags */ 
                    SS$_ABORT,          /* Message code */ 
                    RMS$_FNF,           /* RMS Message code */ 
                    0};                 /* RMS Status value */ 
 
    return (sys$putmsg(msgvec));        /* Generate message */ 
} 
      

Queues an I/O request to a channel associated with a device. This service completes asynchronously; for synchronous completion, use the Queue I/O Request and Wait ($QIOW) service.

For additional information about system service completion, refer to the Synchronize ($SYNCH) service.

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

Format

SYS$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]

C Prototype

int sys$qio (unsigned int efn, unsigned short int chan, unsigned int func, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5, __int64 p6);

Arguments

efn

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

Event flag that $QIO is to set when the I/O operation completes. The efn argument is a longword value containing the number of the event flag; however, $QIO uses only the low-order byte.

If you do not specify efn, event flag 0 is set.

When $QIO begins execution, it clears the specified event flag or event flag 0 if efn was not specified.

The specified event flag is set if the service terminates without queuing an I/O request.

chan

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

I/O channel assigned to the device to which the request is directed. The chan argument is a longword value containing the number of the I/O channel; however, $QIO uses only the low-order word.

Specifying an invalid value for the chan argument will result in either SS$_IVCHAN or SS$_IVIDENT being returned.

func

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

Device-specific function codes and function modifiers specifying the operation to be performed. The func argument is a longword containing the function code.

Each device has its own function codes and function modifiers. For complete information about the function codes and function modifiers that apply to the particular device to which the I/O operation is to be directed, refer to the OpenVMS I/O User's Reference Manual.

iosb

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

I/O status block to receive the final completion status of the I/O operation. The iosb argument is the address of the quadword I/O status block. The following diagram depicts the structure of the I/O status block.

The following table defines the I/O status block fields.

Status Block Field	Definition
Condition value	Word-length condition value that $QIO returns when the I/O operation actually completes.
Transfer count	Number of bytes of data transferred in the I/O operation. For information about how specific devices handle this field of the I/O status block, refer to the OpenVMS I/O User's Reference Manual.
Device-specific information	Contents of this field vary depending on the specific device and on the specified function code. For information on how specific devices handle this field of the I/O status block, refer to the OpenVMS I/O User's Reference Manual.

When $QIO begins execution, it clears the quadword I/O status block if the iosb argument is specified.

Though this argument is optional, Compaq strongly recommends that you specify it, for the following reasons:

• If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
• If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
• The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $QIO service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $QIO, you must first check the condition value returned in R0. If R0 contains a successful value, then you must check the condition value in the I/O status block.

astadr

	privacy and legal statement
4527PRO_074.HTML