OpenVMS System Services Reference Manual

Document revision date: 30 March 2001

OpenVMS System Services Reference Manual

Contents

Index

0 ::10

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

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:
-- 12:00:00.00
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

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

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.

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.

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

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.

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.

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.

Previous Next Contents Index

privacy and legal statement

4527PRO_006.HTML

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.

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)

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)

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value