 |
HP OpenVMS System Services Reference Manual
None
Required Quota
$UPDSEC uses the calling process's direct I/O limit (DIRIO) quota in
queuing the I/O request and uses the calling process's AST limit
(ASTLM) quota if the astadr argument is specified.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET,
$UPDSECW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. One or more I/O requests were
queued.
|
|
SS$_NOTMODIFIED
|
The service completed successfully. No pages in the input address range
were section pages that had been modified. No I/O requests were queued.
|
|
SS$_ACCVIO
|
The input address array cannot be read by the caller, or the output
address array cannot be written by the caller.
|
|
SS$_EXQUOTA
|
The process has exceeded its AST limit quota.
|
|
SS$_ILLEFC
|
You specified an illegal event flag number.
|
|
SS$_IVSECFLG
|
You specified an invalid flag.
|
|
+SS$_NOTCREATOR
|
The section is in memory shared by multiple processors and was created
by a process on another processor.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space.
|
|
SS$_PAGOWNVIO
|
A page in the specified range is owned by an access mode more
privileged than the access mode of the caller.
|
|
SS$_UNASCEFC
|
The process is not associated with the cluster containing the specified
event flag.
|
+VAX specific
$UPDSECW
Writes all modified pages in an active private or global section back
into the section file on disk. One or more I/O requests are queued,
based on the number of pages that have been modified.
The $UPDSECW service completes synchronously; that is, it returns to
the caller after writing all updated pages.
For asynchronous completion, use the Update Section File on Disk
($UPDSEC) service; $UPDSEC returns to the caller after queuing the
update request, without waiting for the pages to be updated.
In all other respects, $UPDSECW is identical to $UPDSEC. For all other
information about the $UPDSECW service, refer to the description of
$UPDSEC.
For additional information about system service completion, refer to
the Synchronize ($SYNCH) service.
Format
SYS$UPDSECW inadr [,retadr] [,acmode] [,updflg] [,efn] [,iosb]
[,astadr] [,astprm]
C Prototype
int sys$updsecw (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode, char updflg, unsigned int efn, struct _iosb *iosb,
void (*astadr)(__unknown_params), int astprm);
$UPDSEC_64 (Alpha and I64)
On Alpha and I64 systems, writes all pages (or only those pages
modified by the current process) in an active private or global disk
file section back into the section file on disk. One or more I/O
requests are queued to perform the write operation.
The $UPDSEC_64 service completes asynchronously. For synchronous
completion, use the Update Global Section File on Disk and Wait
($UPDSEC_64W) service.
This service accepts 64-bit addresses.
Format
SYS$UPDSEC_64 start_va_64 ,length_64 ,acmode ,updflg ,efn ,iosa_64
,return_va_64 ,return_length_64 [,astadr_64 [,astprm_64]]
C Prototype
int sys$updsec_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, unsigned int updflg, unsigned int efn, struct
_iosa *iosa_64, void *(*(return_va_64)), unsigned __int64
*return_length_64,...);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be written to the section
file. The specified virtual address is rounded down to a CPU-specific
page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address range to be written to the section file.
The length specified is rounded up to a CPU-specific page boundary so
that it includes all CPU-specific pages in the requested range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the service is performed. The
acmode argument is a longword containing the access
mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
The most privileged access mode used is the access mode of the caller.
A page cannot be written to disk unless the access mode used by
$UPDSEC_64 is equal to or more privileged than the access mode of the
owner of the page to be written.
updflg
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The update specifier for read/write global sections. The
updflg argument is a longword value. The value 0 (the
default) specifies that all read/write pages in the global section are
to be written to the section file on disk, whether or not they have
been modified. The value UPDFLG$M_WRT_MODIFIED specifies that the
caller is the only process actually writing the global section and that
only those pages that were actually modified by the caller are to be
written to the section file on disk.
Definitions for this flag can be found in the file SECDEF.H in
SYS$STARLET_C.TLB for C and in $SECDEF in STARLET.MLB for macro.
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read_only |
| mechanism: |
by value |
The event flag to be set when the section file on disk is actually
updated. The efn argument is a longword specifying the
number of the event flag; however, this service only uses the low-order
byte. If you do not specify the efn, event flag 0 is
used.
When you invoke $UPDSEC_64, the specified event flag or event flag 0 is
cleared. When the update operation is complete, the event flag is set.
iosa_64
| OpenVMS usage: |
io_status_area |
| type: |
IOSA structure |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The I/O status area to receive the final completion status of the
updating operation. The iosa_64 argument is the 32- or
64-bit virtual address of the I/O status area. The I/O status area
structure is 32 bytes in length.
The I/O status area structure definition can be found in $IOSADEF in
STARLET.MLB for macro and in the file IOSADEF.H in SYS$STARLET_C.TLB
for C.
When you call SYS$UPDSEC_64, the I/O status area is cleared. After the
update operation is complete (that is, when all I/O to the disk is
complete), the I/O status block is written as follows:
- isoa$l_status (offset 0)
The first word contains the condition
value return by SYS$QIO, indicating the final completion status.
The first bit in the second word is set only if an error occurred
during the I/O operation and the error was a hardware write error. The
remaining bits of the second word are zeros.
- iosa$l_resd (offset 4)
This field is reserved for future use
by HP. The value in this field is unpredictable.
- iosa$q_count_q (offset 8)
This field is reserved for future
use by HP. The value in this field is unpredictable.
- iosa$ph_upsec_nowrt_va (offset 16)
This field contains the
virtual address of the first byte in the first disk block that was not
written. In the case of an I/O error, this virtual address indicates
the disk block for which the error occurred.
- iosa$q_resq (offset 24)
This field is reserved for future use
by HP. The value in this field is unpredictable.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The process virtual address of the first page that was actually queued
for writing (in the first I/O request) back to the section file on the
disk. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the service
returns the virtual address.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The length of the first I/O request to write modified pages back to the
section file on disk. The return_length_64 argument is
the 32- or 64-bit virtual address of a naturally aligned quadword into
which the service returns the length of the virtual address range, in
bytes, written by the first I/O request.
astadr_64
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32- or 64-bit reference |
The asynchronous system trap (AST) routine to be executed when the
section file has been updated. The astadr_64 argument
is the 32- or 64-bit address of this routine. If you specify the
astadr_64 argument, the AST routine executes at the
access mode from which the section file update was requested.
astprm_64
| OpenVMS usage: |
user_arg |
| type: |
quadword |
| access: |
read only |
| mechanism: |
by value |
The AST parameter to be passed to the AST routine. The
astprm_64 argument is a quadword argument that is
passed to the AST routine.
Description
The Update Global Section File on Disk service writes all pages in an
active private or global section back into the section file on disk. If
the updflg argument indicates that only modified pages
are to be written back to the disk file, only those global pages
modified by the current process are queued to be written back into the
section file on disk.
Proper use of this service requires the caller to synchronize
completion of the update request. To do this, first check the condition
value returned. If SS$_NOTMODIFIED is returned, the caller can
continue. If SS$_NORMAL is returned, the caller should wait for the I/O
to complete and then check the I/O status for final completion status.
If any error is returned by this service, a value cannot be
returned in the memory locations pointed to by the
iosb_64, return_va_64, and
return_length_64 arguments.
Required Privileges
None
Required Quota
$UPDSEC_64 uses the calling process' direct I/O limit (DIRIO) quota in
queuing the I/O request and uses the calling process' AST limit (ASTLM)
quota if the astadr_64 argument is specified.
Related Services
$CRMPSC, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64,
$MGBLSC_64, $UPDSEC
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. One or more I/O requests were
queued.
|
|
SS$_NOTMODIFIED
|
The service completed successfully. No pages in the input address range
were section pages that had been modified. No I/O requests were queued.
|
|
SS$_ACCVIO
|
The
return_va_64,
return_length_64, or
iosb_64 argument cannot be written by the caller.
|
|
SS$_EXASTLM
|
The process has exceeded its AST limit quota.
|
|
SS$_EXBYTLM
|
The process has exceeded the byte count quota.
|
|
SS$_ILLEFC
|
An illegal event flag number was specified.
|
|
SS$_PAGNOTINREG
|
A page in the specified range is not within the process private address
space.
|
|
SS$_PAGOWNVIO
|
A page in the specified input address range is owned by a more
privileged access mode.
|
|
SS$_UNASCEFC
|
The process is not associated with the cluster containing the specified
event flag.
|
$UPDSEC_64W (Alpha and I64)
On Alpha and I64 systems, writes all modified pages in an active
private or global disk file section back into the section file on disk.
Zero or more I/O requests are queued, based on the number of pages that
have been modified.
The $UPDSEC_64W service completes synchronously; that is, it returns to
the caller after writing all updated pages.
In all other respects, $UPDSEC_64W is identical to $UPDSEC_64. For all
other information about the $UPDSEC_64W service, refer to the
description of $UPDSEC_64 in this manual.
This service accepts 64-bit addresses.
Format
SYS$UPDSEC_64W start_va_64 ,length_64 ,acmode ,updflg ,efn ,iosa_64
,return_va_64 ,return_length_64 [,astadr_64 [,astprm_64]]
C Prototype
int sys$updsec_64w (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, unsigned int updflg, unsigned int efn, struct
_iosa *iosa_64, void *(*(return_va_64)), unsigned __int64
*return_length_64,...);
$VERIFY_PROXY
Verifies that a proxy exists and returns a valid local user for the
caller to use to create a local login.
Format
SYS$VERIFY_PROXY rem_node ,rem_user ,[proposed_user] ,local_user
,local_user_length ,[flags]
C Prototype
int sys$verify_proxy (void *rem_node, void *rem_user, void
*proposed_user, void *local_user, unsigned short int *local_user_len,
unsigned int flags);
Arguments
rem_node
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Remote node name of the proxy to be verified. The
rem_node argument is the address of a character-string
descriptor pointing to the remote node name string.
A remote node name consists of 1 to 1024 characters. No specific
characters, format, or case are required for a remote node name string.
All node names are converted to their DECnet for OpenVMS full name
unless the PRX$M_BYPASS_EXPAND flag is set with the
flags argument.
Wildcards are not recognized. If you specify a wildcard character in
the rem_node argument, it is ignored and assumed to be
part of the requested node name.
rem_user
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Remote user name of the proxy to be verified. The
rem_user argument is the address of a character-string
descriptor pointing to the user name string.
A remote user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($), underscores (_), and brackets ([ ]). Any
lowercase characters specified are automatically converted to uppercase.
The rem_user argument can be specified in user
identification code (UIC) format ([group, member]).
Brackets are allowed only if the remote user name string specifies a
UIC. Group and member are character-string representations of octal
numbers with no leading zeros.
Wildcards are not allowed for the remote user specification. If
wildcard characters are present in the string specified by the
rem_user argument, the service returns SS$_BADPARAM.
proposed_user
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Local user the caller suggests be used for the proxy login. The
proposed_user argument is the address of a
character-string descriptor pointing to the proposed local user name.
The proposed local user consists of 1 to 32 alphanumeric characters,
including dollar signs ($) and underscores (_). Any lowercase
characters specified are automatically converted to uppercase.
See the Description section for information about the interaction of
this argument with the return value of the local_user
argument.
local_user
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Local user the caller must use for a proxy login. The
local_user argument is the address of a 32-byte
character-string descriptor pointer to receive the local user name the
caller must use for a proxy login for the proxy with the remote node
name specified by the rem_node argument and the remote
user name specified by the rem_user argument.
A local user name is a 32-character blank padded string of alphanumeric
characters, including dollar signs ($) and underscores (_).
local_user_length
| OpenVMS usage: |
output length |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the returned local user name in the
local_user argument. The
local_user_length argument is the address of an
unsigned word to receive the length, in bytes, of the character string
returned in the local_user argument.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Functional specification for the service and type of user the
local_user argument represents. The
flags argument is a longword bit mask wherein each bit
corresponds to an option.
Each flag option has a symbolic name. The $PRXDEF macro defines the
following symbolic name:
| Symbolic Name |
Description |
|
PRX$M_BYPASS_EXPAND
|
The service should not convert the node name specified in the
rem_node argument to its corresponding DECnet for
OpenVMS full name. If this flag is set, it is the caller's
responsibility to ensure that the fully expanded node name is passed
into the service.
|
Description
The Verify Proxy service verifies the existence of a proxy in the proxy
database and returns the local user name the caller must use for any
proxy logins.
The following description shows how the service determines which local
user name the caller must use for proxy logins.
Proxies that match the remote node and remote user specified by the
rem_node and rem_user arguments,
respectively, are searched in the following order if the remote user
name is not a UIC:
- rem_node::rem_user
- *::rem_user
- rem_node::*
- *::*
Proxies that match the remote node and remote user specified by the
rem_node and rem_user arguments,
respectively, are searched for in the following order if the remote
user name is a UIC:
- rem_node::rem_user
- *::rem_user
- rem_node::[group,*]
- rem_node::[*,member]
- rem_node::[*,*]
- *::*
The following table describes how the local user name the caller must
use for any proxy logins is determined if a matching proxy record is
found by the search:
Remote
User |
Proposed
User |
Proxy
Default User |
Proxy Local
User Names |
Returned Local
User Name |
|
rem_user
|
null
|
null
|
n/a
|
error
|
|
rem_user
|
null
|
default user
|
n/a
|
default user
|
|
rem_user
|
null
|
*
|
n/a
|
rem_user
|
|
rem_user
|
prop_user
|
default user
|
n/a
|
prop_user
|
|
rem_user
|
prop_user
|
default user
|
prop_user
|
prop_user
|
|
rem_user
|
prop_user
|
default user
|
local user
|
error
|
|
rem_user
|
prop_user
|
default user
|
*
|
rem_user if it equals prop_user
|
|
rem_user
|
prop_user
|
*
|
local user
|
rem_user if it equals prop_user
|
Required Access or Privileges
You must have SYSPRV privilege.
Required Quota
None
Related Services
$ADD_PROXY, $DELETE_PROXY, $DISPLAY_PROXY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
rem_node,
rem_user, or
proposed_user argument cannot be read by the service;
or the
local_user or
local_user_length argument cannot be written by the
service.
|
|
SS$_BADBUFLEN
|
The length of the
rem_node,
rem_user,
proposed_user, or
local_user argument was out of range.
|
|
SS$_BADPARAM
|
The
rem_user or
proposed_user argument contains an invalid user name.
|
|
SS$_NOREADALL
|
The caller does not have access to the proxy database.
|
|
|
|
This service can also return any of the following messages passed from
the security server, or any OpenVMS RMS error message encountered
during operations on the proxy database:
|
|
SECSRV$_BADLOCALUSERLEN
|
The local user name length is out of range.
|
|
SECSRV$_BADNODENAMELEN
|
The node name length is out of range.
|
|
SECSRV$_BADREMUSERLEN
|
The remote user name length is out of range.
|
|
SECSRV$_NOSUCHPROXY
|
The proxy specified by the
rem_node and
rem_user arguments does not exist in the proxy
database.
|
|
SECSRV$_NOSUCHUSER
|
No valid user was found for the requested proxy.
|
|
SECSRV$_PROXYNOTACTIVE
|
Proxy processing is currently stopped. Try the request again later.
|
|
SECSRV$_SERVERNOTACTIVE
|
The security server is not currently active. Try the request again
later.
|
|
