OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

$AUDIT_EVENT takes the event message, checks the auditing database to determine whether a class of event is being audited, and, if the event class is enabled, creates an alarm or audit record.

$AUDIT_EVENT completes asynchronously; that is, it does not wait for final status. For synchronous completion, use the $AUDIT_EVENTW service.

Required Access or Privileges

AUDIT

Required Quota

None

Related Services

$CHECK_ACCESS, $CHECK_PRIVILEGE, $CHKPRO

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO A parameter is not accessible.

SS$_BADBUFADR The buffer address is invalid or not readable.

SS$_BADBUFLEN The specified buffer length is invalid or out of range.

SS$_BADCHAIN The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.

SS$_BADITMCOD The specified item code is invalid or out of range.

SS$_EVTNOTENAB The event is not enabled.

SS$_INSFARG A required item code or parameter is missing.

SS$_INVAJLNAM The alarm or audit journal name is invalid.

SS$_IVSTSFLG The specified system service flags are invalid.

SS$_NOAUDIT The caller does not have the required privilege to perform the audit.

SS$_OVRMAXAUD There is insufficient memory to perform the audit.

SS$_SYNCH An audit was not required.

$AUDIT_EVENTW

Determines whether a security-related event should be reported. If the event should be reported, the service sends the event report to the audit server.
The $AUDIT_EVENTW service completes synchronously; that is, it returns only after receiving an explicit confirmation from the audit server that the associated audit, if enabled, has been performed.

Format

SYS$AUDIT_EVENTW efn ,[flags] ,itmlst ,audsts ,[astadr] ,[astprm]

C Prototype

int sys$audit_eventw (unsigned int efn, unsigned int flags, void *itmlst, unsigned int *audsts, void (*astadr)(__unknown_params), int astprm);

$AVOID_PREEMPT

Requests that the EXEC avoid preempting the calling process or thread.

Format

SYS$AVOID_PREEMPT enable

C Prototype

int sys$avoid_preempt (int enable);

Arguments

enable

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by value

Enables or disables preemption avoidance. If the enable argument is set to 1, preemption avoidance is enabled; if 0, preemption avoidance is disabled.

Description

The Avoid Process Preemption service is a caller's mode service that sets a thread-specific bit that informs the scheduler that this thread desires to avoid preemption. Before setting the bit, it checks if the process or thread has already benefited from preemption avoidance during this time on the processor, and if it has, calls the $RESCHED system service to give up the processor.
If quantum end is reached when this bit is set, the scheduler will "borrow" the next quantum for this process or thread. It will give the process or thread another quantum immediately and allow it to resume execution. The next time that the process or thread is eligible for scheduling, it will be placed at the end of the scheduling queue without any execution time, skipping its next quantum.
If another process or thread of the same base priority attempts to preempt a process or thread that has this bit set, this preemption can be avoided if the process had the ALTPRI privilege when the $SETUP_AVOID_PREEMPT service was called. In this case, the priority of the current thread is boosted to the same level as the thread attempting preemption, denying the attempted preemption.
Required Access or Privileges

ALTPRI
Required Quota

None
Related Services

$RESCHED, $SETUP_AVOID_PREEMPT

Condition Values Returned

SS$_NORMAL The service completed successfully.

$BINTIM

Converts an ASCII string to an absolute or delta time value in the system 64-bit time format suitable for input to the Set Timer ($SETIMR) or Schedule Wakeup ($SCHDWK) service.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$BINTIM timbuf ,timadr

C Prototype

int sys$bintim (void *timbuf, struct _generic_64 *timadr);

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 the time string. The time string specifies the absolute or delta time to be converted by $BINTIM. The data type table describes the time string.
timadr

OpenVMS usage: date_time

type: quadword

access: write only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Time value that $BINTIM has converted. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of the quadword system time, which receives the converted time.

Description

The Convert ASCII String to Binary Time service converts an ASCII string to an absolute or delta time value in the system 64-bit time format suitable for input to the Set Timer ($SETIMR) or Schedule Wakeup ($SCHDWK) service. 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.
The required ASCII input strings have the following format:

Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
Delta Time: dddd hh:mm:ss.cc

The following table lists the length (in bytes), contents, and range of values for each field in the absolute time and delta time formats.

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

dddd 4 Number of days (in 24-hour units) 000--9999

Month abbreviations must be uppercase.
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. Also, 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 $BINTIM 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 delta time values, the $BINTIM service uses a default value of 0 for unspecified hours, minutes, and seconds fields. Trailing fields can be truncated. If you omit leading fields from the time value, you must specify the punctuation (blanks, colons, periods). If the number of days in the delta time is 0, you must specify a 0. For example, the following string results in a delta time of 10 seconds:
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

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
dddd	4	Number of days (in 24-hour units)	000--9999

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.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

4527PRO_005.HTML

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	A parameter is not accessible.
SS$_BADBUFADR	The buffer address is invalid or not readable.
SS$_BADBUFLEN	The specified buffer length is invalid or out of range.
SS$_BADCHAIN	The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.
SS$_BADITMCOD	The specified item code is invalid or out of range.
SS$_EVTNOTENAB	The event is not enabled.
SS$_INSFARG	A required item code or parameter is missing.
SS$_INVAJLNAM	The alarm or audit journal name is invalid.
SS$_IVSTSFLG	The specified system service flags are invalid.
SS$_NOAUDIT	The caller does not have the required privilege to perform the audit.
SS$_OVRMAXAUD	There is insufficient memory to perform the audit.
SS$_SYNCH	An audit was not required.

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

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:	date_time
type:	quadword
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

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:	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

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.

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