 |
HP OpenVMS System Services Reference Manual
$NUMUTC
Converts an absolute 128-bit binary time into its numeric components.
The numeric components are returned in local time.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$NUMUTC timbuf ,[utcadr]
C Prototype
int sys$numutc (unsigned short int timbuf [13], unsigned int *utcadr
[4]);
Arguments
timbuf
| OpenVMS usage: |
vector_word_unsigned |
| type: |
word |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
Buffer into which $NUMUTC writes the converted date and time. The
timbuf argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) of a 13-word
structure containing time, inaccuracy of time, and time differential
factor. The time differential factor encoded in the 128-bit buffer is
used to convert the UTC to its numerical components. Negative values in
the inaccuracy field indicate an infinite inaccuracy.
The following diagram depicts the fields in this structure:
utcadr
| OpenVMS usage: |
coordinated universal time |
| type: |
utc_date_time |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
The 128-bit UTC time value to be converted.
The utcadr argument is optional; if it is not used,
$NUMUTC will use the current time.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_INVTIME
|
The 128-bit UTC time is not valid.
|
$NXTVOL
The Next Volume service allows you to process the next tape volume in a
multiple volume set. This service applies only to files on magnetic
tape volumes.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$OPEN
The Open service makes an existing file available for processing by
your program. The Open service specifies the type of record access to
be used and determines whether the file can be shared. The Open service
also performs an implicit Display service.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$PARSE
The Parse service analyzes the file specification string and fills in
various NAM block fields.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$PARSE_ACL
Parses the specified text string and converts it to the binary
representation for an access control entry (ACE).
Format
SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]
C Prototype
int sys$parse_acl (void *aclstr, void *aclent, unsigned short int
*errpos, void *accnam, int (*routin)(void));
Arguments
aclstr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Formatted ACE that is parsed when $PARSE_ACL completes execution. The
aclstr argument is the address of a string descriptor
pointing to the text string to be parsed.
aclent
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Description of the ACE that is parsed when $PARSE_ACL completes
execution. The aclent argument is the address of a
descriptor pointing to the buffer in which the ACE is written. The
first byte of the buffer contains the length of the ACE; the second
byte contains a value that identifies the type of ACE, which in turn
defines the format of the ACE.
For information about the ACE types and their associated formats, see
$FORMAT_ACL system service documentation.
errpos
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters from aclstr processed by
$PARSE_ACL. The errpos argument is the address of a
word that receives the number of characters actually processed by the
service. If the service fails, this count points to the failing point
in the string.
accnam
| OpenVMS usage: |
access_bit_names |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Names of the bits in the access mask when $PARSE_ACL is executing. The
accnam argument is the address of an array of 32
quadword descriptors that define the names of the bits in the access
mask. Each element points to the name of a bit. The first element names
bit 0, the second element names bit 1, and so on.
You can call LIB$GET_ACCNAM to retrieve the access name table for the
class of object whose ACL is to be formatted. If you omit
accnam, the following names are used:
| Bit |
Name |
|
Bit 0
|
READ
|
|
Bit 1
|
WRITE
|
|
Bit 2
|
EXECUTE
|
|
Bit 3
|
DELETE
|
|
Bit 4
|
CONTROL
|
|
Bit 5
|
BIT_5
|
|
Bit 6
|
BIT_6
|
.
.
.
|
|
|
Bit 31
|
BIT_31
|
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to HP.
Description
The Parse Access Control List Entry service parses the specified text
string and converts it to the binary representation for an access
control entry (ACE).
Required Access or Privileges
None
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,
$ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL,
$FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC,
$MOD_HOLDER, $MOD_IDENT, $MTACCESS, $REM_HOLDER, $REM_IDENT, $REVOKID,
$SET_SECURITY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The string or its descriptor cannot be read by the caller; the buffer
descriptor cannot be read by the caller; the buffer cannot be written
by the caller; or the buffer is too small to hold the ACL entry.
|
|
SS$_IVACL
|
The format of the access control list entry is not valid.
|
|
SS$_NOSUCHID
|
The specified identifier does not exist in the rights database.
|
$PERM_DIS_ALIGN_FAULT_REPORT (Alpha and I64)
On Alpha and I64 systems, disables user process alignment fault
reporting.
Format
SYS$PERM_DIS_ALIGN_FAULT_REPORT
C Prototype
int sys$perm_dis_align_fault_report (void);
Arguments
None.
Description
The Disable Alignment Fault Reporting service disables user process
alignment fault reporting.
See the description of the $PERM_REPORT_ALIGN_FAULT service for an
example of a program that can be used to enable and disable user
process alignment fault reporting.
Required Access or Privileges
None
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,
$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT,
$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,
$STOP_SYS_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
$PERM_REPORT_ALIGN_FAULT (Alpha and I64)
On Alpha and I64 systems, initializes user process alignment fault
reporting.
Format
SYS$PERM_REPORT_ALIGN_FAULT
C Prototype
int sys$perm_report_align_fault (void);
Arguments
None.
Description
The Report Alignment Fault service allows the user to permanently
enable user process alignment fault reporting for all subsequent images.
This service reports alignment faults only in exception mode. For more
information about reporting modes, see the $START_ALIGN_FAULT_REPORT
service.
Image alignment fault reporting takes precedence over process alignment
fault reporting; that is, if both image and process alignment fault
reporting are enabled, faults are reported to the image first.
Required Access or Privileges
None
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,
$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,
$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,
$STOP_SYS_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
Example
|
/**********************************************************************/
/* */
/* SET_ALIGN_REPORT.C */
/* */
/* This program can be used to permanently turn on and off */
/* alignment fault reporting for a process. After creating the */
/* executable, do: */
/* */
/* $ align :== $dir:set_align_report.exe */
/* $ align on */
/* $ run program ! will generate align faults on screen */
/* $ align off */
/* $ run program ! will not generate align faults */
/* */
/**********************************************************************/
#include <stdio>
#include <ctype>
#include <ssdef>
/* alignment fault reporting system services */
extern sys$perm_report_align_fault(),
sys$perm_dis_align_fault_report();
main(argc, argv)
int argc;
char *argv[];
{
int status;
/* check arguments */
if (argc < 2) {
printf ("Insufficient arguments\n");
return (40);
}
/* check if the argument is on or off */
if ((strcmp ("ON", argv[1]) == 0) || (strcmp ("on", argv[1]) == 0))
/* on, turn alignment fault reporting on for this process */
status = sys$perm_report_align_fault ();
else if ((strcmp ("OFF", argv[1]) == 0) || (strcmp ("off", argv[1]) == 0))
/* off, turn alignment fault reporting off for this process */
status = sys$perm_dis_align_fault_report ();
else
return (SS$_BADPARAM);
/* return status */
return (status);
}
|
This example shows a program that can be used to enable and disable
alignment fault reporting for a process.
$PERSONA_ASSUME (VAX Only)
Modifies the context of the current process to match the context of a
given persona. The $PERSONA_ASSUME service allows an OpenVMS process to
assume the identity of another user or to discard a persona to return
the process to its original state.
Format
SYS$PERSONA_ASSUME persona ,[flags]
C Prototype
int sys$persona_assume (unsigned int *persona, unsigned int flags);
Arguments
persona
| OpenVMS usage: |
integer |
| type: |
longword (unsigned) |
| access: |
read |
| mechanism: |
by reference |
Address of a longword in which the persona identification handle is
expected.
If the value of the context passed is 1, then the current persona is
discarded, and the state of the calling process is returned to the
state that existed prior to the first call to $PERSONA_CREATE.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying which Persona services options are to be employed
when the persona is assumed. This argument is ignored when a persona is
being discarded.
The following table describes each flag:
| Flag |
Description |
|
IMP$M_ASSUME_SECURITY
|
Assume access rights, UIC, authorized privileges, user name, and
security audit flag.
|
|
IMP$M_ASSUME_ACCOUNT
|
Assume OpenVMS account.
|
|
IMP$M_ASSUME_JOB_WIDE
|
Assume the new persona, even in a multiprocess job.
|
Description
When assuming a persona using the IMP$M_ASSUME_SECURITY option, any
previously enabled image privileges will be disabled. The caller's
process will have only the privileges of the impersonated user enabled.
These privileges are enabled in the Current, Process, and Authorized
privilege masks.
When using IMP$M_ASSUME_SECURITY, access to the job logical name table
might no longer be possible because the table is protected by the UIC
of the user on whose behalf the current process was created. Also, a
new access to the process' controlling terminal might fail, and the
process might be in a different default resource domain for locking.
Any persona is automatically discarded and deleted upon image exit.
Hence, it is not possible to permanently change the persona of a
process using $PERSONA_ASSUME.
The arguments are read in caller's mode, so an invalid argument can
cause an access violation to be signaled.
Required Access or Privileges
None
Required Quota
None
Related Services
$PERSONA_CREATE, $PERSONA_DELETE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the desired access is granted.
|
|
IMP$_NOCHJIB
|
The Job Information Block cannot be modified.
|
|
IMP$_PERSONANONGRATA
|
Invalid persona argument.
|
$PERSONA_ASSUME (Alpha and I64)
On Alpha and I64 systems, allows an OpenVMS thread to assume the
identity of another persona.
Format
SYS$PERSONA_ASSUME persona ,[flags], [previous], [acmode]
C Prototype
int sys$persona_assume (unsigned int *persona, unsigned int flags,
unsigned int *previous, unsigned int acmode);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword in which the persona identification handle is
expected.
If the value passed is ISS$C_ID_NATURAL, then the state of the calling
thread is returned to the natural persona.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Ignored.
previous
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification handle of
the currently active persona being replaced is written.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be considered when assuming a persona. The
acmode argument is a longword containing the access
mode.
The most privileged access mode used is the access mode of the caller.
Only equal or more privileged access modes can use this persona.
Description
This service establishes the specified persona as the active security
profile and returns the persona identification handle of the persona
that was active at the point in which the call to this service was made.
On image exit, the natural persona is assumed and all nonpermanent
personae are deleted.
The arguments are validated against the caller's mode, so an invalid
argument can cause an access violation to be signaled.
Required Access or Privileges
None
Required Quota
None
Related Services
$PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the desired access is granted.
|
|
SS$_ACCVIO
|
Access violation.
|
|
SS$_INSFARG
|
Certain required arguments were not specified.
|
|
SS$_IVMODE
|
The caller cannot create a persona that is more privileged than the
caller.
|
|
SS$_NOPRIV
|
The operation requires IMPERSONATE privilege.
|
|
SS$_PERSONANONGRATA
|
Invalid persona argument.
|
$PERSONA_CLONE (Alpha and I64)
On Alpha and I64 systems, creates a copy of an existing persona within
the context of the current process. The service returns the assigned
persona identification for the new persona in the
persona argument. This persona can be assumed using
the $PERSONA_ASSUME service.
Format
SYS$PERSONA_CLONE persona ,[input]
C Prototype
int sys$persona_clone (unsigned int *persona, unsigned int *input);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification handle is
written.
input
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword containing the persona identification of the
persona to be cloned. If this argument is 0, null, or absent, the
currently active persona is cloned.
Description
The Clone Persona service creates a copy of an existing persona within
the context of the current process. The service returns the assigned
persona identification for the new persona in the
persona argument. This persona can be assumed using
the $PERSONA_ASSUME service.
On image exit, the natural persona is assumed and all nonpermanent
personae are deleted.
Required Access or Privileges
None
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
Access violation.
|
|
SS$_EXQUOTA
|
The caller lacks sufficient quota to allocate a new persona.
|
|
SS$_INSFMEM
|
Insufficient memory.
|
|
SS$_IVMODE
|
The caller cannot create a persona that is more privileged than the
caller.
|
|
SS$_PERSONANONGRATA
|
The persona ID supplied was invalid.
|
|
