 |
OpenVMS System Services Reference Manual
$START_TRANSW
Starts a new transaction.
$START_TRANSW always waits for the request to complete before returning
to the caller. Other than this, it is identical to $START_TRANS.
Format
SYS$START_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]
,[timout] ,[acmode]]
C Prototype
int sys$start_transw (unsigned int efn, unsigned int flags, struct
_iosb *iosb,...);
$STOP_ALIGN_FAULT_REPORT (Alpha Only)
On Alpha systems, disables user image alignment fault reporting.
Format
SYS$STOP_ALIGN_FAULT_REPORT
C Prototype
int sys$stop_align_fault_report (void);
Arguments
None.
Description
The Stop Alignment Fault Reporting service disables user image
alignment fault reporting.
The service returns SS$_AFR_NOT_ENABLED if user image alignment fault
reporting is not enabled; otherwise, it returns success.
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,
$PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT,
$STOP_SYS_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_AFR_NOT_ENABLED
|
The $START_ALIGN_FAULT_REPORT service has not been called.
|
$STOP_SYS_ALIGN_FAULT_REPORT (Alpha Only)
On Alpha systems, disables systemwide alignment fault reporting.
Format
SYS$STOP_SYS_ALIGN_FAULT_REPORT
C Prototype
int sys$stop_sys_align_fault_report (void);
Arguments
None.
Description
The Stop System Alignment Fault Reporting service disables systemwide
alignment fault reporting.
The service returns SS$_AFR_NOT_ENABLED if systemwide alignment fault
reporting is not enabled; otherwise, it returns success.
Required Access or Privileges
CMKRNL privilege is required.
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,
$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,
$PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_NOPRIV
|
The caller lacks sufficient privilege.
|
|
SS$_AFR_NOT_ENABLED
|
The $START_ALIGN_FAULT_REPORT service has not been called.
|
$SUBSYSTEM
Saves or restores the process image rights for the current protected
subsystem.
Format
SYS$SUBSYSTEM enbflg
C Prototype
int sys$subsystem (unsigned int enbflg);
Argument
enbflg
| OpenVMS usage: |
boolean |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Value specifying whether the protected subsystem identifiers are to be
saved or restored. If the enbflg argument is set to 0,
the active subsystem is saved. If it is set to 1, the subsystem is
restored.
Description
A protected subsystem image is a main image that has in its access
control list a special type of ACE that names a set of identifiers and
their attributes. Whenever the operating system activates a main image
that has protected subsystem identifiers associated with it, these
identifiers are automatically granted to the process for the duration
of the image.
In essence, a protected subsystem provides the same behavior as if the
image had been installed with the identifiers. Subsystem identifiers
are sometimes referred to as image rights, in contrast to process
rights and system rights.
The Subsystem service provides an easy way for a protected subsystem
image to dynamically save and restore its subsystem identifiers. A
protected subsystem might choose to turn off its subsystem identifiers
at certain times to temporarily revoke the user's access to the objects
comprising the protected subsystem. For example, DCL uses the
$SUBSYSTEM service to temporarily remove any image identifiers from the
process during Ctrl/Y interrupt processing.
The image rights are saved in the process control region and
automatically deleted on image rundown ($RMSRUNDWN).
For more information about protected subsystems, refer to the
OpenVMS Guide to System Security.
Required Access or Privileges
None
Required Quota
None
Related Services
None
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully; protected subsystem had no
identifiers associated with it.
|
|
SS$_WASSET
|
The service completed successfully; protected subsystem had identifiers
associated with it.
|
$SUSPND
Allows a process to suspend itself or another process.
Format
SYS$SUSPND [pidadr] ,[prcnam] ,[flags]
C Prototype
int sys$suspnd (unsigned int *pidadr, void *prcnam, unsigned int flags);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process to be suspended. The
pidadr argument is the address of the longword PID.
The pidadr argument can refer to a process running on
the local node or a process running on another node in the OpenVMS
Cluster system.
You must specify the pidadr argument to suspend a
process whose UIC group number is different from that of the calling
process.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the process to be suspended. The prcnam
argument is the address of a character string descriptor pointing to
the process name. A process running on the local node can be identified
with a 1- to 15-character string.
To identify a process on a particular node on a cluster, specify the
full process name, which includes the node name as well as the process
name. The full process name can contain up to 23 characters.
A process name is implicitly qualified by its UIC group number. Because
of this, you can use the prcnam argument only to
suspend processes in the same UIC group as the calling process.
To suspend processes in other groups, you must specify the
pidadr argument.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Longword of bit flags specifying options for the suspend operation.
Currently, only bit 0 is used for the flags argument.
When bit 0 is set, the process is suspended at kernel mode and ASTs are
not deliverable to the process.
To request a kernel mode suspend, the caller must be in either kernel
mode or executive mode. The default (bit 0 is clear) is to suspend the
process at supervisor mode, where executive or kernel mode ASTs can be
delivered to the process. If executive or kernel mode ASTs have been
delivered to a process suspended at supervisor mode, that process will
return to its suspended state after the AST routine executes.
Description
The Suspend Process service allows a process to suspend itself or
another process.
A suspended process can receive executive or kernel mode ASTs, unless
it is suspended at kernel mode. If a process is suspended at kernel
mode, the process cannot receive any ASTs or otherwise be executed
until another process resumes or deletes it. If you specify neither the
pidadr nor the prcnam argument, the
caller process is suspended.
If the longword value at address pidadr is 0, the PID
of the target process is returned.
The $SUSPND service requires system dynamic memory.
The $SUSPND service completes successfully if the target process is
already suspended.
Unless it has pages locked in the balance set, a suspended process can
be removed from the balance set to allow other processes to execute.
Note that a kernel mode suspend request can override a supervisor mode
suspend state, but a supervisor suspend request cannot override a
kernel mode suspend state.
The Resume Process ($RESUME) service allows a suspended process to
continue. If one or more resume requests are issued for a process that
is not suspended, a subsequent suspend request completes immediately;
that is, the process is not suspended. No count is maintained of
outstanding resume requests.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $SUSPND:
- GROUP privilege to suspend another process in the same group,
unless the process to be suspended has the same UIC as the calling
process
- WORLD privilege to suspend any other process in the system
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification cannot be written by the caller.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for completing the service.
|
|
SS$_IVLOGNAM
|
The specified process name has a length of 0 or has more than 15
characters.
|
|
SS$_NONEXPR
|
The specified process does not exist, or an invalid process
identification was specified.
|
|
SS$_NOPRIV
|
The target process was not created by the caller and the calling
process does not have GROUP or WORLD privilege, or flag bit 0 was set
from outer mode.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the OpenVMS Cluster system.
|
|
SS$_NOSUSPEND
|
The process was previously marked as not suspendable by the
PCB$V_NOSUSPEND flag.
|
|
SS$_REMRSRC
|
The remote node has insufficient resources to respond to the request.
(Bring this error to the attention of your system manager.)
|
|
SS$_UNREACHABLE
|
The remote node is a member of the cluster but is not accepting
requests. (This is normal for a brief period early in the system boot
process.)
|
|
SS$_WAIT_CALLERS_MODE
|
Bit 1 was used in the
flags argument.
|
$SYNCH
Checks the completion status of a system service that completes
asynchronously.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$SYNCH [efn] ,[iosb]
C Prototype
int sys$synch (unsigned int efn, struct _iosb *iosb);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag specified in the call to the system service
whose completion status is to be checked by $SYNCH. The
efn argument is a longword containing this number;
however, $SYNCH uses only the low-order byte.
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
I/O status block specified in the call to the system service whose
completion status is to be checked by $SYNCH. The iosb
argument is the address of this quadword I/O status block.
Description
The Synchronize service checks the completion status of a system
service that completes asynchronously. The service whose completion
status is to be checked must have been called with the
efn and iosb arguments specified,
because the $SYNCH service uses the event flag and I/O status block of
the service to be checked.
This service performs a true test for the completion of an asynchronous
service, such as $GETJPI. $SYNCH operates in the following way:
- When called, $SYNCH waits (by calling $WAITFR) for the event flag
to be set.
- When the event flag is set, $SYNCH checks to see whether the I/O
status block is nonzero. If it is nonzero, then the asynchronous
service has completed, and $SYNCH returns to the caller.
- If the I/O status block is the value 0, then the asynchronous
service has not yet completed and the event flag was set by the
completion of an event not associated with the completion of $GETJPI.
In this case, $SYNCH clears the event flag (by calling $CLREF) and
waits again (by calling $WAITFR) for the event flag to be set,
repeating this cycle until the I/O status block is nonzero.
The $SYNCH service always sets the specified event flag when it returns
to the caller. This ensures that different program segments can use the
same event flag without conflicting. For example, assume that calls to
$GETJPI and $GETSYI both specify the same event flag and that $SYNCH is
called to check for the completion of $GETJPI. If $GETSYI sets the
event flag, $SYNCH clears the flag and waits for $GETJPI to set it.
When $GETJPI sets the flag, $SYNCH returns to the caller and sets the
event flag. In this way, the flag set by $GETSYI is not lost, and
another call to $SYNCH will show the completion of $GETSYI.
The $SYNCH service is useful when a program calls an asynchronous
service but must perform some other work before testing for the
completion of the asynchronous service. In this case, the program
should call $SYNCH at that point when it must know that the service has
completed and when it is willing to wait for the service to actually
complete.
When a program calls an asynchronous service (for example, $QIO) and
actually waits in line (by calling $WAITFR) for its completion without
performing any other work, you could improve that program by calling
the synchronous form of that service (for example, $QIOW). The
synchronous services such as $QIOW execute code that checks for the
true completion status in the same way that $SYNCH does.
Required Access or Privileges
None
Required Quota
None
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. The asynchronous service has
completed, and the I/O status block contains the condition value
describing the completion status of the asynchronous service.
|
|
SS$_ACCVIO
|
The I/O status block cannot be read by the caller.
|
|
SS$_ILLEFC
|
An illegal event flag was specified.
|
|
SS$_UNASEFC
|
The process is not associated with the cluster containing the specified
event flag.
|
$TIMCON
Converts 128-bit Coordinated Universal Time (UTC) format to 64-bit
system format or 64-bit system format to 128-bit UTC format based on
the value of the convert flag.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$TIMCON [smnadr] ,[utcadr] ,cvtflg
C Prototype
int sys$timcon (struct _generic_64 *smnadr, unsigned int *utcadr [4],
unsigned long int cvtflg);
Arguments
smnadr
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read/write |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The 64-bit system format value that $TIMCON will use in the conversion.
The smnadr argument will be read from or written to
based on the value of the cvtflg argument. The
smnadr is required when converting UTC time to 64-bit
system format.
utcadr
| OpenVMS usage: |
coordinated universal time |
| type: |
utc_date_time |
| access: |
read/write |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
UTC time value that $TIMCON will use in the conversion. The
utcadr argument will be read from or written to based
on the value of the cvtflg argument. The
utcadr argument is required when converting 64-bit
system format to UTC time.
cvtflg
| OpenVMS usage: |
conversion flag |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
A longword indicating the direction of the conversion. If the
cvtflg value is 0, UTC time is converted to 64-bit
system value. If the cvtflg value is 1, 64-bit system
format is converted to UTC time.
Description
The Time Converter service converts 64-bit system format time to UTC
format, and vice versa.
When converting a 64-bit system format time to 128-bit UTC format time,
the time zone of the local system is used.
When converting a 128-bit UTC format time to a 64-bit system time, the
time zone differential factor encoded in the 128-bit buffer is used.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_INVTIME
|
The input time cannot be converted because its value is out of the
legal range or is a delta time, or the UTC is of an illegal format.
|
$TRNLNM
Returns information about a logical name.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$TRNLNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
C Prototype
int sys$trnlnm (unsigned int *attr, void *tabnam, void *lognam,
unsigned char *acmode, void *itmlst);
Arguments
attr
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Attributes controlling the search for the logical name. The
attr argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a longword bit mask
specifying these attributes.
Each bit in the longword corresponds to an attribute and has a symbolic
name. The $LNMDEF macro defines these symbolic names. To specify an
attribute, use its symbolic name or set its corresponding bit. All
undefined bits in the longword have the value 0.
If you do not specify this argument or specify it as the value 0 (no
bits set), the following attribute is not used:
| Attribute |
Description |
|
LNM$M_CASE_BLIND
|
If set, $TRNLNM does not distinguish between uppercase and lowercase
letters in the logical name to be translated.
|
|
LNM$M_INTERLOCKED
|
If set, $TRNLNM does not translate the current logical name until any
clusterwide logical name modifications in progress are completed. This
attribute is not set by default. If your application requires
translation using the most recent definition of a clusterwide logical
name, use this attribute to ensure that the translation is stalled
until all pending modifications have been made.
|
tabnam
| OpenVMS usage: |
logical_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) |
Name of the logical name table or the name of a searchlist logical name
that translates the name of one or more tables in which to search for
the specified logical name. The tabnam argument is the
32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha
systems) of a descriptor pointing to this name. This argument is
required.
The name must be entered in uppercase letters. (This requirement
differs from the $CRELNT system service, which automatically changes
tabnam to uppercase.)
If the table name is not the name of a logical name table, it is
assumed to be a logical name and is translated iteratively until either
the name of a logical name table is found or the number of translations
allowed by the system have been performed. If the table name translates
to a list of logical name tables, the tables are searched in the
specified order.
lognam
| OpenVMS usage: |
logical_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) |
Logical name about which information is to be returned. The
lognam argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha systems) of a descriptor
pointing to the logical name string. This argument is required.
acmode
| OpenVMS usage: |
access_mode |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
Access mode to be used in the translation. The acmode
argument is the 32-bit address (on VAX systems) or the 32- or 64-bit
address (on Alpha systems) of a byte specifying the access mode. The
$PSLDEF macro defines symbolic names for the four access modes.
When you specify the acmode argument, $TRNLNM ignores
all names (both logical names and table names) at access modes less
privileged than the specified access mode. The specified access mode is
not checked against that of the caller.
|
