 |
OpenVMS System Services Reference Manual
After the message is displayed, the terminal is returned to the state
it was in prior to receiving the message.
Required Access or Privileges
The calling process must have OPER privilege to send a message to more
than one terminal or to a terminal that is allocated to another user.
The calling process must have WORLD privilege to send a message to a
specific user by specifying the BRK$C_USERNAME symbolic code for the
sndtyp argument.
Required Quota
The $BRKTHRU service allows the message text to be as long as 16,350
bytes; however, both the system parameter MAXBUF and the caller's
available process buffered I/O byte count limit (BYTLM) quota must be
sufficient to handle the message.
Related Services
$ALLOC, $ASSIGN, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN,
$DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI,
$GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC,
$SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The message buffer, message buffer descriptor, device name string, or
device name string descriptor cannot be read by the caller.
|
|
SS$_BADPARAM
|
The message length exceeds 16,350 bytes; the process's buffered I/O
byte count limit (BYTLM) quota is insufficient; the message length
exceeds the value specified by the system parameter MAXBUF; the value
of the TIMOUT parameter is nonzero and less than 4 seconds; the value
of the REQID is outside the range 0 to 63; or the value of the SNDTYP
is not one of the legal ones listed.
|
|
SS$_EXQUOTA
|
The process has exceeded its buffer space quota and has disabled
resource wait mode with the Set Resource Wait Mode ($SETRWM) service.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for completing the request
and the process has disabled resource wait mode with the Set Resource
Wait Mode ($SETRWM) service.
|
|
SS$_NONLOCAL
|
The device is on a remote node.
|
|
SS$_NOOPER
|
The process does not have the necessary OPER privilege.
|
|
SS$_NOSUCHDEV
|
The specified terminal does not exist, or it cannot receive the message.
|
Condition Values Returned in the I/O Status Block1
Any condition values returned by the $ASSIGN, $FAO, $GETDVI, $GETJPI,
or $QIO service.
$BRKTHRUW
Sends a message to one or more terminals. The $BRKTHRUW service
operates synchronously; that is, it returns to the caller after the
message has been sent to the specified terminals.
For asynchronous operations, use the Breakthrough ($BRKTHRU) service;
$BRKTHRU returns to the caller after queuing the message request,
without waiting for the message to be delivered.
Aside from the preceding, $BRKTHRUW is identical to $BRKTHRU. For all
other information about the $BRKTHRUW service, refer to the description
of $BRKTHRU.
For additional information about system service completion, refer to
the documentation of the Synchronize ($SYNCH) service.
The $BRKTHRU and $BRKTHRUW services supersede the Broadcast ($BRDCST)
service. When writing new programs, you should use $BRKTHRU or
$BRKTHRUW instead of $BRDCST. When updating old programs, you should
change all uses of $BRDCST to $BRKTHRU or $BRKTHRUW. $BRDCST is now an
obsolete system service and is no longer being enhanced.
Format
SYS$BRKTHRUW [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb] [,carcon]
[,flags] [,reqid] [,timout] [,astadr] [,astprm]
C Prototype
int sys$brkthruw (unsigned int efn, void *msgbuf, void *sendto,
unsigned int sndtyp, struct _iosb *iosb, unsigned int carcon, unsigned
int flags, unsigned int reqid, unsigned int timout, void
(*astadr)(__unknown_params),int astprm);
$CANCEL
Cancels all pending I/O requests on a specified channel. In general,
this includes all I/O requests that are queued, as well as the request
currently in progress.
Format
SYS$CANCEL chan
C Prototype
int sys$cancel (unsigned short int chan);
Argument
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
I/O channel on which I/O is to be canceled. The chan
argument is a word containing the channel number.
Description
The Cancel I/O on Channel service cancels all pending I/O requests on a
specified channel. In general, this includes all I/O requests that are
queued, as well as the request currently in progress.
When you cancel a request currently in progress, the driver is notified
immediately. The actual cancellation might occur immediately, depending
on the logical state of the driver. When cancellation does occur, the
following action for I/O in progress, similar to that for queued
requests, takes place:
- The specified event flag is set.
- The first word of the I/O status block, if specified, is set to
SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if the I/O is
in progress.
- The AST, if specified, is queued.
Proper synchronization between this service and the actual canceling of
I/O requests requires the issuing process to wait for I/O completion in
the normal manner and then note that the I/O has been canceled.
If the I/O operation is a virtual I/O operation involving a disk or
tape ancilliary control process (ACP), the I/O cannot be canceled. In
the case of a magnetic tape, however, cancellation might occur if the
device driver is hung.
Outstanding I/O requests are automatically canceled at image exit.
Required Access or Privileges
To cancel I/O on a channel, the access mode of the calling process must
be equal to or more privileged than the access mode that the process
had when it originally made the channel assignment.
Required Quota
The $CANCEL service requires system dynamic memory and uses the
process's buffered I/O limit (BIOLM) quota.
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CREMBX, $DALLOC, $DASSGN,
$DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI,
$GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC,
$SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_EXQUOTA
|
The process has exceeded its buffered I/O limit (BIOLM) quota.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for canceling the I/O.
|
|
SS$_IVCHAN
|
You specified an invalid channel, that is, a channel number of 0 or a
number larger than the number of channels available.
|
|
SS$_NOPRIV
|
The specified channel is not assigned or was assigned from a more
privileged access mode.
|
$CANEXH
Deletes an exit control block from the list of control blocks for the
calling access mode. Exit control blocks are declared by the Declare
Exit Handler ($DCLEXH) service and are queued according to access mode
in a last-in first-out order.
Format
SYS$CANEXH [desblk]
C Prototype
int sys$canexh (void *desblk);
Argument
desblk
| OpenVMS usage: |
exit_handler_block |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Control block describing the exit handler to be canceled. If you do not
specify the desblk argument or specify it as 0, all
exit control blocks are canceled for the current access mode. The
desblk argument is the address of this control block.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The first longword of the exit control block or the first longword of a
previous exit control block in the list cannot be read by the caller,
or the first longword of the preceding control block cannot be written
by the caller.
|
|
SS$_IVSSRQ
|
The call to the service is invalid because it was made from kernel mode.
|
|
SS$_NOHANDLER
|
The specified exit handler does not exist.
|
$CANTIM
Cancels all or a selected subset of the Set Timer requests previously
issued by the current image executing in a process. Cancellation is
based on the request identification specified in the Set Timer
($SETIMR) service. If you give the same request identification to more
than one timer request, all requests with that request identification
are canceled.
Format
SYS$CANTIM [reqidt] ,[acmode]
C Prototype
int sys$cantim (unsigned __int64 reqidt, unsigned int acmode);
Arguments
reqidt
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Request identification of the timer requests to be canceled. If you
specify it as 0 (the default), all timer requests are canceled. The
reqidt argument is a longword containing this
identification.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode of the requests to be canceled. The acmode
argument is a longword containing the access mode.
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 most privileged access mode used is the access mode of the caller.
Description
The Cancel Timer service cancels all or a selected subset of the Set
Timer requests previously issued by the current image executing in a
process. Cancellation is based on the request identification specified
in the Set Timer ($SETIMR) service. If you give the same request
identification to more than one timer request, all requests with that
request identification are canceled.
Outstanding timer requests are automatically canceled at image exit.
Required Access or Privileges
The calling process can cancel only timer requests that are issued by a
process whose access mode is equal to or less privileged than that of
the calling process.
Required Quota
Canceled timer requests are restored to the process's quota for timer
queue entries (TQELM quota).
Related Services
$ASCTIM, $BINTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
$CANWAK
Removes all scheduled wakeup requests for a process from the timer
queue, including those made by the caller or by other processes. The
Schedule Wakeup ($SCHDWK) service makes scheduled wakeup requests.
Format
SYS$CANWAK [pidadr] ,[prcnam]
C Prototype
int sys$canwak (unsigned int *pidadr, void *prcnam);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process for which wakeups are to be
canceled. The pidadr argument is the address of a
longword specifying the PID. The pidadr argument can
refer to a process running on the local node or a process running on
another node in the OpenVMS Cluster system.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the process for which wakeups are to be canceled. The
prcnam argument is the address of a character string
descriptor pointing to the process name string.
A process running on the local node can be identified with a 1- to
15-character string. To identify a process on a specific node in a
cluster, specify the full process name, which includes the node name as
well as the process name. The full process name can contain up to 23
characters.
The operating system interprets the UIC group number of the calling
process as part of the process name; the names of processes are unique
to UIC groups. Because of this, you can use the prcnam
argument only on behalf of processes in the same group as the calling
process.
Description
The Cancel Wakeup service removes from the timer queue all scheduled
wakeup requests for a process, including those made by the caller or by
other processes. The Schedule Wakeup ($SCHDWK) service makes scheduled
wakeup requests.
If the longword at address pidadr is 0, the PID of the
target process is returned.
If you specify neither the pidadr nor the
prcnam argument, scheduled wakeup requests for the
calling process are canceled.
Pending wakeup requests issued by the current image are automatically
canceled at image exit.
This service cancels only wakeup requests that have been scheduled; it
does not cancel wakeup requests made with the Wake Process from
Hibernation ($WAKE) service.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
listed privileges to use $CANWAK:
- You need GROUP privilege to cancel wakeups for processes in the
same group that do not have the same UIC.
- You need WORLD privilege to cancel wakeups for any process in the
system.
Required Quota
Canceled wakeup requests are restored to the process's AST limit
(ASTLM) quota.
Related Services
$ASCTIM, $BINTIM, $CANTIM, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification cannot be written by the caller.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_IVLOGNAM
|
The process name string has a length of 0 or has more than 15
characters.
|
|
SS$_NONEXPR
|
The specified process does not exist, or you specified an invalid
process identification.
|
|
SS$_NOPRIV
|
The process does not have the privilege to cancel wakeups for the
specified process.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the cluster.
|
|
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.)
|
$CHECK_ACCESS
Determines on behalf of a third-party user whether a named user can
access the object specified.
Format
SYS$CHECK_ACCESS [objtyp], [objnam], [usrnam], itmlst, [contxt],
[clsnam], [objpro], [usrpro]
C Prototype
int sys$check_access (unsigned int *objtyp, void *objnam, void *usrnam,
void *itmlst, unsigned int *contxt, void *clsnam, void *objpro, void
*usrpro);
Arguments
objtyp
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Type of object being accessed. The objtyp argument is
the address of a longword containing a value specifying the type of
object.
The appropriate symbols are listed in the following table and are
defined in the system macro $ACLDEF library:
| Symbol |
Meaning |
|
ACL$C_CAPABILITY
|
Object is a restricted resource; use the reserved name VECTOR.
|
|
ACL$C_DEVICE
|
Object is a device.
|
|
ACL$C_FILE
|
Object is a Files-11 On-Disk Structure Level 2 file.
|
|
ACL$C_GROUP_GLOBAL_SECTION
|
Object is a group global section.
|
|
ACL$C_JOBCTL_QUEUE
|
Object is a batch, print, or server queue.
|
|
ACL$C_LOGICAL_NAME_TABLE
|
Object is a logical name table.
|
|
ACL$C_SYSTEM_GLOBAL_SECTION
|
Object is a system global section.
|
For further information about these symbols, see the description of the
clsnam argument.
objnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the object being accessed. The objnam argument
is the address of a character-string descriptor pointing to the object
name.
usrnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the user attempting access. The usrnam
argument is the address of a descriptor that points to a character
string that contains the name of the user attempting to gain access to
the specified object. The user name string can contain a maximum of 12
alphanumeric characters.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Attributes describing how the object is to be accessed and information
returned after $CHECK_ACCESS performs the protection check (for
instance, security alarm information).
For each item code, you must include a set of four elements and end the
list with a longword containing the value 0 (CHP$_END). This is shown
in the following diagram:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word containing a user-supplied integer specifying the length (in
bytes) of the associated buffer. The length of the buffer needed
depends on the item code specified in the item code field of the item
descriptor. If the value of buffer length is too small, the service
truncates the data.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the item of
information in the associated buffer.
|
|
Buffer address
|
A longword containing the user-supplied address of the buffer.
|
|
Return length address
|
A longword containing the address of a word in which $CHECK_ACCESS
writes the number of bytes written to the buffer pointed to by
bufadr. If the buffer pointed to by
bufadr is used to pass information to $CHECK_ACCESS,
retlenadr is ignored but must be included.
|
contxt
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read-write |
| mechanism: |
by reference |
Longword used to maintain the user authorization file (UAF) context.
The contxt argument is the address of a longword to
receive a UAI context longword. On the initial call, this longword
should contain the value --1. On subsequent calls, the value of the
contxt argument from the previous call should be
passed back in.
Using the contxt argument keeps the UAF open across
all calls, thereby improving the performance of the system on
subsequent calls. To close the UAF, you must run down the image.
The resulting contxt value from a $CHECK_ACCESS call
can also be used as the input contxt argument to the
$GETUAI system service, and vice versa.
clsnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor |
Object class name associated with the protected object. The
clsnam argument is the address of a descriptor
pointing to the name of the object class associated with the object
specified by either the objnam or the
objpro argument. The clsnam and
objtyp arguments are mutually exclusive. The
clsnam argument is the preferred argument to
$CHECK_ACCESS. The following object class names are valid:
|
CAPABILITY
|
QUEUE
|
|
COMMON_EVENT_CLUSTER
|
RESOURCE_DOMAIN
|
|
DEVICE
|
SECURITY_CLASS
|
|
FILE
|
SYSTEM_GLOBAL_SECTION
|
|
GROUP_GLOBAL_SECTION
|
VOLUME
|
|
LOGICAL_NAME_TABLE
|
|
objpro
| OpenVMS usage: |
char_string |
| type: |
opaque byte stream or object handle |
| access: |
read only |
| mechanism: |
by descriptor |
Buffer containing an object security profile or object handle. The
objpro argument is the address of a descriptor
pointing to a buffer that contains an encoded object security profile
or the address of a descriptor pointing to an object handle.
|
