 |
OpenVMS System Services Reference Manual
Note the space between the 0 in the day field and the two colons.
For both absolute and delta time values, there can be any number of
leading blanks, and any number of blanks between fields normally
delimited by blanks; however, there can be no embedded blanks within
either the date or time field.
Required Access or Privileges
None
Required Quota
None
Related Services
$ASCTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_IVTIME
|
The syntax of the specified ASCII string is invalid, or the time
component is out of range.
|
Example
Column 1 of the following table lists legal input strings to the
$BINTIM service; column 2 lists the $BINTIM output of these strings
translated through the Convert Binary Time to ASCII String ($ASCTIM)
system service. The current date is assumed to be 30-DEC-1994
04:15:28.00.
| Input to $BINTIM |
$ASCTIM Output String |
|
-- :50
|
30-DEC-1994 04:50:28.00
|
|
-- 1994 0:0:0.0
|
29-DEC-1994 00:00:00.00
|
|
30-DEC-1994 12:32:1.1161
|
30-DEC-1994 12:32:01.12
|
|
29-DEC-1994 16:35:0.0
|
29-DEC-1994 16:35:00.00
|
|
0 ::.1
|
0 00:00:00.10
|
|
0 ::.06
|
0 00:00:00.06
|
|
5 3:18:32.068
|
5 03:18:32:07
|
|
20 12:
|
20 12:00:00.00
|
|
0 5
|
0 05:00:00.00
|
$BINUTC
Converts an ASCII string to an absolute time value in the 128-bit UTC
format.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$BINUTC timbuf ,utcadr
C Prototype
int sys$binutc (void *timbuf, unsigned int *utcadr [4]);
Arguments
timbuf
| OpenVMS usage: |
time_name |
| 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) |
Buffer that holds the ASCII time to be converted. The
timbuf argument specifies the 32-bit address (on VAX
systems) or the 32- or 64-bit address (on Alpha systems) of a character
string descriptor pointing to a local time string. The time string
specifies the absolute time to be converted by $BINUTC.
utcadr
| OpenVMS usage: |
coordinated universal time |
| type: |
utc_date_time |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Time value that $BINUTC has converted. The utcadr
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha systems) of a 16-byte location to receive the
converted time.
Description
The Convert ASCII String to UTC Binary Time service converts an ASCII
string to an absolute time in the 128-bit UTC format. The service
executes at the access mode of the caller and does not check whether
address arguments are accessible before it executes. Therefore, an
access violation causes an exception condition if the input buffer or
buffer descriptor cannot be read or the output buffer cannot be written.
This service does not check the length of the argument list and
therefore cannot return the SS$_INSFARG (insufficient arguments) error
status code. If the service does not receive enough arguments (for
example, if you omit required commas in the call), errors can result.
$BINUTC uses the time zone differential factor of the local system to
encode the 128-bit UTC.
The required ASCII input strings have the following format:
- Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
The following table lists the length (in bytes), contents, and range of
values for each field in the absolute time format:
| Field |
Length
(Bytes) |
Contents |
Range of Values |
|
dd
|
2
|
Day of month
|
1--31
|
|
--
|
1
|
Hyphen
|
Required syntax
|
|
mmm
|
3
|
Month
|
JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
|
|
--
|
1
|
Hyphen
|
Required syntax
|
|
yyyy
|
4
|
Year
|
1858--9999
|
|
blank
|
n
|
Blank
|
Required syntax
|
|
hh
|
2
|
Hour
|
00--23
|
|
:
|
1
|
Colon
|
Required syntax
|
|
mm
|
2
|
Minutes
|
00--59
|
|
:
|
1
|
Colon
|
Required syntax
|
|
ss
|
2
|
Seconds
|
00--59
|
|
.
|
1
|
Period
|
Required syntax
|
|
cc
|
2
|
Hundredths of a second
|
00--99
|
Note that month abbreviations must be uppercase and that the
hundredths-of-second field represents a true fraction. For example, the
string .1 represents ten-hundredths of a second (one-tenth of a second)
and the string .01 represents one-hundredth of a second. Note also that
you can add a third digit to the hundredths-of-second field; this
thousandths-of-second digit is used to round the hundredths-of-second
value. Digits beyond the thousandths-of-second digit are ignored.
The following two syntax rules apply to specifying the ASCII input
string:
- You can omit any of the date and time fields.
For absolute time
values, the $BINUTC service supplies the current system date and time
for nonspecified fields. Trailing fields can be truncated. If leading
fields are omitted, you must specify the punctuation (hyphens, blanks,
colons, periods). For example, the following string results in an
absolute time of 12:00 on the current day:
- For absolute time values, there can be any number of leading
blanks, and any number of blanks between fields normally delimited by
blanks; however, there can be no embedded blanks within either the date
or time field.
Required Access or Privileges
None
Required Quota
None
Related Services
$ASCUTC, $GETUTC, $NUMUTC, $TIMCON
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_IVTIME
|
The syntax of the specified ASCII string is invalid, the specified time
is a delta time, or the time component is out of range.
|
$BRKTHRU
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.
For synchronous completion, use the Breakthrough and Wait ($BRKTHRUW)
service. The $BRKTHRUW service is identical to the $BRKTHRU service in
every way except that $BRKTHRUW returns to the caller after the message
is written to the specified terminals.
For additional information about system service completion, refer to
the Synchronize ($SYNCH) service.
The $BRKTHRU service supersedes the Broadcast ($BRDCST) service. When
writing new programs, you should use $BRKTHRU instead of $BRDCST. When
updating old programs, you should change all uses of $BRDCST to
$BRKTHRU.
Format
SYS$BRKTHRU [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb] [,carcon]
[,flags] [,reqid] [,timout] [,astadr] [,astprm]
C Prototype
int sys$brkthru (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);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be set when the message has been written to
the specified terminals. The efn argument is a
longword containing this number; however, $BRKTHRU uses only the
low-order byte.
When the message request is queued, $BRKTHRU clears the specified event
flag (or event flag 0 if efn is not specified). Then,
after the message is sent, $BRKTHRU sets the specified event flag (or
event flag 0).
msgbuf
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Message text to be sent to the specified terminals. The
msgbuf argument is the address of a descriptor
pointing to this message text.
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 space can affect the maximum length of the message
text.
sendto
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of a single device (terminal) or single user name to which the
message is to be sent. The sendto argument is the
address of a descriptor pointing to this name.
The sendto argument is used in conjunction with the
sndtyp argument. When sndtyp
specifies BRK$C_DEVICE or BRK$C_USERNAME, the sendto
argument is required.
If you do not specify sndtyp or if
sndtyp does not specify BRK$C_DEVICE or
BRK$C_USERNAME, you should not specify sendto; if
sendto is specified, $BRKTHRU ignores it.
sndtyp
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Terminal type to which $BRKTHRU is to send the message. The
sndtyp argument is a longword value specifying the
terminal type.
Each terminal type has a symbolic name, which is defined by the $BRKDEF
macro. The following table describes each terminal type:
| Terminal Type |
Description |
|
BRK$C_ALLTERMS
|
When specified, $BRKTHRU sends the message to all terminals at which
users are logged in and to all other terminals that are connected to
the system except those with the AUTOBAUD characteristic set.
|
|
BRK$C_ALLUSERS
|
When specified, $BRKTHRU sends the message to all users who are
currently logged in to the system.
|
|
BRK$C_DEVICE
|
When specified, $BRKTHRU sends the message to a single terminal; you
must specify the name of the terminal by using the
sendto argument.
|
|
BRK$C_USERNAME
|
When specified, $BRKTHRU sends the message to a user with a specified
user name; you must specify the user name by using the
sendto argument.
|
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
I/O status block that is to receive the final completion status. The
iosb argument is the address of this quadword block.
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).
|
carcon
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Carriage control specifier indicating the carriage control sequence to
follow the message that $BRKTHRU sends to the terminals. The
carcon argument is a longword containing the carriage
control specifier.
For a list of the carriage control specifiers that you can use in the
carcon argument, refer to the 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.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag bit mask specifying options for the $BRKTHRU operation. The
flags argument is a longword value that is the logical
OR of each desired flag option.
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.
|
reqid
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Class requester identification, which identifies to $BRKTHRU the
application (or image) that is calling $BRKTHRU. The
reqid argument is this longword identification 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.
|
timout
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Timeout value, which is the number of seconds that must elapse before
an attempted write by $BRKTHRU to a terminal is considered to have
failed. The timout argument is this longword value (in
seconds).
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.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST service routine to be executed after $BRKTHRU has sent the message
to the specified terminals. The astadr argument is the
address of this routine.
If you specify astadr, the AST routine executes at the
same access mode as the caller of $BRKTHRU.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter to be passed to the AST routine specified by the
astadr argument. The astprm argument
specifies this longword parameter.
Description
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.
|
