HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$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.


Previous Next Contents Index