 |
HP OpenVMS System Services Reference Manual
$PURGE_WS (Alpha and I64)
On Alpha and I64 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.
|
$PUT
The Put service inserts a record into a file.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$PUTMSG
Writes informational and error messages to processes.
On Alpha and I64 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 and I64); 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 and I64 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 Field |
Definition |
|
Message code
|
Longword value that uniquely identifies the message. The Description
section discusses the message code; the OpenVMS Command Definition, Librarian, and Message Utilities Manual explains how to
create message codes.
|
|
FAO parameter count
|
Word-length value specifying the number of longword $FAO parameters
that follow in the message descriptor. The number of $FAO parameters
needed depends on the $FAO directives used in the message text; some
$FAO directives require one or more parameters, while some directives
require none.
|
|
New message options
|
Word-length bit vector specifying new message options for the current
message. The contents and format of this field are identical to that of
the default message options field.
|
|
FAO parameter
|
Longword value used by an $FAO directive appearing in the message text.
The $FAO parameters listed in the message descriptor must appear in the
order in which they will be used by the $FAO directives in the message
text.
|
Message Descriptor for System Messages
| Message Descriptor Field |
Definition |
|
Message code
|
Longword value that uniquely identifies the message. The facility
number field in the message code identifies the facility associated
with the message. A system message has a facility number of 0. You
cannot specify the FAO parameter count, new message options, and FAO
parameter fields. Each longword following the message identification
field in the message vector will be interpreted as another message
identification.
|
Message Descriptor for OpenVMS RMS Messages
| Message Descriptor Field |
Definition |
|
Message code
|
Longword value that uniquely identifies the message. The facility
number field in the message code identifies the facility associated
with the message. An OpenVMS RMS message has a facility number of 1.
You cannot specify the FAO parameter count, new message options, and
FAO parameter fields. The longword following the message identification
field in the message vector will be interpreted as a standard value
field (STV).
|
|
RMS status value
|
Longword containing an STV for use by an RMS message that has an
associated STV value. The $PUTMSG service uses the STV value as an $FAO
parameter or as another message identification, depending on the RMS
message identified by the message identification field. If the RMS
message does not have an associated STV, $PUTMSG ignores the STV
longword in the message descriptor.
|
Message Descriptor for System Exception Messages
| Message Descriptor Field |
Definition |
|
Message code
|
Longword value that uniquely identifies the message. The facility
number field in the message code identifies the facility associated
with the message. A system exception message has a facility number of 0.
You cannot specify the FAO parameter count and new message options
fields. The longword or longwords following the message code field in
the message vector will be interpreted as $FAO parameters.
|
On Alpha and I64 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 and I64 systems.
actrtn
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
User-supplied action routine to be executed during message processing.
The actrtn argument is the 32- or 64-bit address (on
Alpha and I64 systems) or the 32-bit address (on VAX systems) of this
routine.
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
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor: fixed-length string descriptor
(Alpha and I64); by 32-bit descriptor: fixed-length string descriptor
(VAX) |
Facility prefix to be used in the first or only message written by
$PUTMSG. The facnam argument is the 32- or 64-bit
address (on Alpha and I64 systems) or the 32-bit address (on VAX
systems) of a character string descriptor pointing to this facility
prefix.
If you do not specify facnam, $PUTMSG uses the default
facility prefix associated with the message.
actprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Parameter to be passed to the action routine. The
actprm argument is a longword value containing this
parameter. If you do not specify actprm, no parameter
is passed.
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 */
}
|
$QIO
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 and I64 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 used.
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 HP 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 and I64); 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 HP 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 HP 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, HP 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
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
AST service routine to be executed when the I/O completes. The
astadr argument is the address of the AST routine.
The AST routine executes at the access mode of the caller of $QIO.
astprm
| OpenVMS usage: |
user_arg |
| type: |
quadword unsigned (Alpha and I64); longword unsigned
(VAX) |
| access: |
read only |
| mechanism: |
by 64-bit value (Alpha and I64); by 32-bit value
(VAX) |
AST parameter to be passed to the AST service routine. On Alpha and I64
systems, the astprm argument is a quadword value
containing the AST parameter. On VAX systems, the
astprm argument is a longword value containing the AST
parameter.
p1 to p6
| OpenVMS usage: |
varying_arg |
| type: |
quadword (unsigned) (Alpha and I64); longword unsigned
(VAX) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference or by 64-bit value, depending on
the I/O function (Alpha and I64); by 32-bit reference or by 32-bit
value, depending on the I/O function (VAX) |
Optional device-specific and function-specific I/O request parameters.
For example, the p1 parameter usually specifies a
buffer by reference. Other parameters, such as the buffer size, disk
block number, or carriage control are often passed by value.
For more information about these parameters, refer to the HP OpenVMS I/O User's Reference Manual.
Description
The Queue I/O Request service operates only on assigned I/O channels
and only from access modes that are equal to or more privileged than
the access mode from which the original channel assignment was made.
|
