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 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 $PUTMSG service accepts either the 32-bit or the 64-bit form of the message vector on Alpha systems.
OpenVMS usage: | procedure |
type: | procedure value |
access: | call without stack unwinding |
mechanism: | by 32- or 64-bit reference (Alpha) |
mechanism: | by 32-bit reference (VAX) |
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.
OpenVMS usage: | char_string |
type: | character-coded text string |
access: | read only |
mechanism: | by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha) |
mechanism: | by 32-bit descriptor--fixed-length string descriptor (VAX) |
If you do not specify facnam, $PUTMSG uses the default facility prefix associated with the message.
OpenVMS usage: | user_arg |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
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 textwhere:
% 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
Required Quota
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
SS$_NORMAL The service completed successfully.
#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.
SYS$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
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);
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, Digital 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) mechanism: 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); longword unsigned (VAX) access: read only mechanism: by 64-bit value (Alpha) mechanism: by 32-bit value (VAX)
AST parameter to be passed to the AST service routine. On Alpha 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); 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) mechanism: 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, see the OpenVMS I/O User's Reference Manual.
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.The $QIO service uses system dynamic memory to construct a database to queue the I/O request and might require additional memory depending on the queued device.
For $QIO, you can synchronize completion (1) by specifying the astadr argument to have an AST routine execute when the I/O completes or (2) by calling the Synchronize ($SYNCH) service to await completion of the I/O operation. The $QIOW service completes synchronously, and it is the best choice when synchronous completion is required.
For information about how to use the $QIO service for network operations, refer to the DECnet for OpenVMS Networking Manual.
Required Access or Privileges
LOG_IO or PHY_IO is required, depending upon the device type and the requested operation. DIAGNOSE is required to issue a $QIO with an associated diagnostic buffer. In addition, read or write access is generally required for the device. For more information, see the Security Guide.
Required Quota
The $QIO service uses the following quotas:
- The process's quota for buffered I/O limit (BIOLM) or direct I/O limit (DIOLM)
- The process's buffered I/O byte count (BYTLM) quota
- The process's AST limit (ASTLM) quota, if an AST service routine is specified
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR, $IO_CLEANUP, $IO_PERFORM, $IO_SETUP
SS$_NORMAL The service completed successfully. The I/O request was successfully queued. SS$_ABORT A network logical link was broken. SS$_ACCVIO Either the I/O status block cannot be written by the caller, or the parameters for device-dependent function codes are specified incorrectly. SS$_CONNECFAIL The connection to a network object timed out or failed. SS$_DEVOFFLINE The specified device is off line and not currently available for use. SS$_EXQUOTA The process has (1) exceeded its AST limit (ASTLM) quota, (2) exceeded its buffered I/O byte count (BYTLM) quota, (3) exceeded its buffered I/O limit (BIOLM) quota, (4) exceeded its direct I/O limit (DIOLM) quota, or (5) requested a buffered I/O transfer smaller than the buffered byte count quota limit (BYTLM), but when added to other current buffer requests, the buffered I/O byte count quota was exceeded. SS$_FILALRACC A logical link is already accessed on the channel (that is, a previous connect on the channel). SS$_ILLEFC You specified an illegal event flag number. SS$_INSFMEM The system dynamic memory is insufficient for completing the service. SS$_INVLOGIN The access control information was invalid at the remote node. SS$_IVCHAN You specified an invalid channel number, that is, a channel number of 0, or you failed to specify a channel number. SS$_IVIDENT You specified a channel number greater than the number of channels assigned for the process. SS$_IVDEVNAM The NCB has an invalid format or content. SS$_LINKABORT The network partner task aborted the logical link. SS$_LINKDISCON The network partner task disconnected the logical link. SS$_LINKEXIT The network partner task was started, but exited before confirming the logical link (that is, $ASSIGN to SYS$NET). SS$_NOLINKS No logical links are available. The maximum number of logical links as set for the executor MAXIMUM LINKS parameter was exceeded. SS$_NOPRIV The specified channel does not exist or was assigned from a more privileged access mode, or the process does not have the necessary privileges to perform the specified functions on the device associated with the specified channel. SS$_NOSUCHNODE The specified node is unknown. SS$_NOSUCHOBJ The network object number is unknown at the remote node; or for a TASK= connect, the named DCL command procedure file cannot be found at the remote node. SS$_NOSUCHUSER The remote node could not recognize the login information supplied with the connection request. SS$_NOT64DEVFUNC On Alpha systems, this fatal condition value is returned under the following circumstances: (1) The caller has specified a 64-bit virtual address in the P1 device dependent parameter but the device driver does not support 64-bit addresses with the requested I/O function. (2) The caller has specified a 64-bit address for a diagnostic buffer but the device driver does not support 64-bit addresses for diagnostic buffers. (3) Some device drivers might also return this condition value when 64-bit buffer addresses are passed using the P2 through P6 parameters and the driver does not support a 64-bit address with the requested I/O function. SS$_PATHLOST The path to the network partner task node was lost. SS$_PROTOCOL A network protocol error occurred. This error is most likely due to a network software error. SS$_REJECT The network object rejected the connection. SS$_REMRSRC The link could not be established because system resources at the remote node were insufficient. SS$_SHUT The local or remote node is no longer accepting connections. SS$_THIRDPARTY The logical link was terminated by a third party (for example, the system manager). SS$_TOOMUCHDATA The task specified too much optional or interrupt data. SS$_UNASEFC The process is not associated with the cluster containing the specified event flag. SS$_UNREACHABLE The remote node is currently unreachable.
Device-specific condition values; the OpenVMS I/O User's Reference Manual lists these condition values for each device.
The Queue I/O Request and Wait service queues an I/O request to a channel associated with a device.The $QIOW service completes synchronously; however, Digital recommends that you use an IOSB with this service to avoid premature completion.
For asynchronous completion, use the Queue I/O Request ($QIO) service.
In all other respects, $QIOW is identical to $QIO. For more information about $QIOW, refer to the description of $QIO.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.
On Alpha systems, this service accepts 64-bit addresses.
SYS$QIOW [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
int sys$qiow (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);
Returns the current status of all 32 event flags in a local or common event flag cluster and indicates whether the specified event flag is set or clear.
Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
![]()
4527P061.HTM OSSG Documentation 22-NOV-1996 13:00:22.35Copyright © Digital Equipment Corporation 1996. All Rights Reserved.