 |
HP OpenVMS System Services Reference Manual
$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.
For asynchronous completion, use the Audit Event ($AUDIT_EVENT)
service. In all other respects, $AUDIT_EVENTW is identical to
$AUDIT_EVENT. For additional information about $AUDIT_EVENTW, refer to
the $AUDIT_EVENT service.
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 and I64 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 and I64) |
| 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 and I64 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 and I64) |
| 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 and I64 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.
Leaving out any
element, however, including hundredths of a second, results in the
$BINTIM service supplying the current base time for the missing
element.
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 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:
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-2003
04:15:28.00.
| Input to $BINTIM |
$ASCTIM Output String |
|
-- :50
|
30-DEC-2003 04:50:28.00
|
|
-- 2003 0:0:0.0
|
29-DEC-2003 00:00:00.00
|
|
30-DEC-2003 12:32:1.1161
|
30-DEC-2003 12:32:01.12
|
|
29-DEC-2003 16:35:0.0
|
29-DEC-2003 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 and I64 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 and I64) |
| 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 and I64 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 and I64) |
| 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 and I64 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.
|
