| Previous | Contents | Index |
When the iosb argument is specified, $BRKTHRU sets the quadword to 0 when it queues the message request. Then, after the message is sent to the specified terminals, $BRKTHRU returns four informational items, one item per word, in the quadword I/O status block.
These informational items indicate the status of the messages sent only to terminals and mailboxes on the local node; these items do not include the status of messages sent to terminals and mailboxes on other nodes in an OpenVMS Cluster system.
The following table shows each word of the quadword block and the informational item it contains:
| Word | Informational Item |
|---|---|
| 1 | A condition value describing the final completion status. |
| 2 | A decimal number indicating the number of terminals and mailboxes to which $BRKTHRU successfully sent the message. |
| 3 | A decimal number indicating the number of terminals to which $BRKTHRU failed to send the message because the write to the terminals timed out. |
| 4 | A decimal number indicating the number of terminals to which $BRKTHRU failed to send the message because the terminals were set to the NOBROADCAST characteristic (by using the DCL command SET TERMINAL/NOBROADCAST). |
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
For a list of the carriage control specifiers that you can use in the carcon argument, see the HP OpenVMS I/O User's Reference Manual.
If you do not specify the carcon argument, $BRKTHRU uses a default value of 32, which represents a space in the ASCII character set. The message format resulting from this default value is a line feed, the message text, and a carriage return.
The carcon argument has no effect on message formatting specified by the BRK$M_SCREEN flag in the flags argument. See the description of the flags argument.
| OpenVMS usage: | mask_longword |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
Each flag option has a symbolic name. The $BRKDEF macro defines the following symbolic names:
| Symbolic Name | Description |
|---|---|
| BRK$V_ERASE_LINES |
When specified with the BRK$M_SCREEN flag, BRK$V_ERASE_LINES causes a
specified number of lines to be cleared from the screen before the
message is displayed. When BRK$M_SCREEN is not also specified,
BRK$V_ERASE_LINES is ignored.
Unlike the other Boolean flags, BRK$V_ERASE_LINES specifies a 1-byte integer in the range 0 to 24. It occupies the first byte in the longword flag mask. In coding the call to $BRKTHRU, specify the desired integer value in the OR operation with any other desired flags. |
| BRK$M_SCREEN |
When specified, $BRKTHRU sends screen-formatted messages as well as
messages formatted through the use of the
carcon argument. $BRKTHRU sends screen-formatted
messages to terminals with the DEC_CRT characteristic, and it sends
messages formatted by
carcon to those without the DEC_CRT characteristic.
You set the DEC_CRT characteristic for the terminal by using the DCL
command SET TERMINAL/DEC_CRT.
A screen-formatted message is displayed at the top of the terminal screen, and the cursor is repositioned at the point it was prior to the broadcast message. However, the BRK$V_ERASE_LINES and BRK$M_BOTTOM flags also affect the display. |
| BRK$M_BOTTOM | When BRK$M_BOTTOM is specified and BRK$M_SCREEN is also specified, $BRKTHRU writes the message to the bottom of the terminal screen instead of the top. BRK$M_BOTTOM is ignored if the BRK$M_SCREEN flag is not set. |
| BRK$M_NOREFRESH | When BRK$M_NOREFRESH is specified, $BRKTHRU, after writing the message to the screen, does not redisplay the last line of a read operation that was interrupted by the broadcast message. This flag is useful only when the BRK$M_SCREEN flag is not specified, because BRK$M_NOREFRESH is the default for screen-formatted messages. |
| BRK$M_CLUSTER | Specifying BRK$M_CLUSTER enables $BRKTHRU to send the message to terminals or mailboxes on other nodes in an OpenVMS Cluster system. If BRK$M_CLUSTER is not specified, $BRKTHRU sends messages only to terminals or mailboxes on the local node. |
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
The reqid argument is used by several images that send messages to terminals and can be used by as many as 16 different user images as well.
When such an image calls $BRKTHRU, specifying reqid, $BRKTHRU notifies the terminal that this image wants to write to the terminal. This makes it possible for you to allow the image to write or prevent it from writing to the terminal.
To prevent a particular image from writing to your terminal, you use the image's name in the DCL command SET TERMINAL/NOBROADCAST=image-name. Note that image-name in this DCL command is the same as the value of the reqid argument that the image passed to $BRKTHRU.
For example, you can prevent the Mail utility (which is an image) from writing to the terminal by entering the DCL command SET BROADCAST=NOMAIL.
The $BRKDEF macro defines class names that are used by several OpenVMS components. These components specify their class names by using the reqid argument in calls to $BRKTHRU. The $BRKDEF macro also defines 16 class names (BRK$C_USER1 through BRK$C_USER16) for the use of user images that call $BRKTHRU. The class names and the components to which they correspond are as follows:
| Class Name | Component |
|---|---|
| BRK$C_GENERAL | This class name is used by the image invoked by the DCL command REPLY and the callers of the $BRKTHRU service. This is the default if the reqid argument is not specified. |
| BRK$C_PHONE | This class name is used by the OpenVMS Phone utility. |
| BRK$C_MAIL | This class name is used by the OpenVMS Mail utility. |
| BRK$C_DCL | This class name is used by the DIGITAL Command Language (DCL) interpreter for the Ctrl/T command, which displays the process status. |
| BRK$C_QUEUE | This class name is used by the queue manager, which manages print and batch jobs. |
| BRK$C_SHUTDOWN | This class name is used by the system shutdown image, which is invoked by the DCL command REPLY/ID=SHUTDOWN. |
| BRK$C_URGENT | This class name is used by the image invoked by the DCL command REPLY/ID=URGENT. |
|
BRK$C_USER1
through BRK$C_USER16 |
These class names can be used by user-written images. |
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
Because $BRKTHRU calls the $QIO service to perform write operations to the terminal, the timeout value specifies the number of seconds allotted to $QIO to perform a single write operation to the terminal.
If you do not specify the timout argument, $BRKTHRU uses a default value of 0 seconds, which specifies infinite time (no timeout occurs).
The value specified by timout can be 0 or any number greater than 4; the numbers 1, 2, 3, and 4 are illegal.
When you press Ctrl/S or the No Scroll key, $BRKTHRU cannot send a message to the terminal. In such a case, the value of timout is usually exceeded and the attempted write to the terminal fails.
| OpenVMS usage: | ast_procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by reference |
If you specify astadr, the AST routine executes at the same access mode as the caller of $BRKTHRU.
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
The Breakthrough service sends a message to one or more terminals. The $BRKTHRU service completes asynchronously; that is, it returns to the caller after queuing the message request without waiting for the message to be written to the specified terminals.The $BRKTHRU service operates by assigning a channel (by using the $ASSIGN service) to the terminal and then writing to the terminal (by using the $QIO service). When calling $QIO, $BRKTHRU specifies the IO$_WRITEVBLK function code, together with the IO$M_BREAKTHRU, IO$M_CANCTRLO, and (optionally) IO$M_REFRESH function modifiers.
The current state of the terminal determines if and when the broadcast message is displayed on the screen. For example:
- If the terminal is performing a read operation when $BRKTHRU sends the message, the read operation is suspended, the message is displayed, and then the line that was being read when the read operation was suspended is redisplayed (equivalent to the action produced by Ctrl/R).
- If the terminal is performing a write operation when $BRKTHRU sends the message, the message is displayed after the current write operation has completed.
- If the terminal has the NOBROADCAST characteristic set for all images, or if you have disabled the receiving of messages from the image that is issuing the $BRKTHRU call (see the description of the reqid argument), the message is not displayed.
After the message is displayed, the terminal is returned to the state it was in prior to receiving the message.
The calling process must have OPER privilege for the following conditions:
- To send a message to more than one terminal
- To send a message to a terminal that is allocated to another user
- To send a message to a specific user that has a different user name than the current process
To send a message to a specific user that is the same as your process requires no privileges.
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.
$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
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.
Any condition values returned by the $ASSIGN, $FAO, $GETDVI, $GETJPI, or $QIO service.
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, see the description of $BRKTHRU.
For additional information about system service completion, see 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.
SYS$BRKTHRUW [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb] [,carcon] [,flags] [,reqid] [,timout] [,astadr] [,astprm]
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);
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.
SYS$CANCEL chan
int sys$cancel (unsigned short int chan);
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.
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 ancillary 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.
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.
The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota.
$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
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.
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.
SYS$CANEXH [desblk]
int sys$canexh (void *desblk);
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.
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.
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.
SYS$CANTIM [reqidt] ,[acmode]
int sys$cantim (unsigned __int64 reqidt, unsigned int acmode);
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.
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.
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.
Canceled timer requests are restored to the process's quota for timer queue entries (TQELM quota).
$ASCTIM, $BINTIM, $CANWAK, $GETTIM, $GETTIM_PREC, $NUMTIM, $SCHDWK, $SETIME, $SETIMR
SS$_NORMAL The service completed successfully.
| Previous | Next | Contents | Index |