[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index

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:

  1. rem_node::rem_user
  2. *::rem_user
  3. rem_node::*
  4. *::*

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:

  1. rem_node::rem_user
  2. *::rem_user
  3. rem_node::[group,*]
  4. rem_node::[*,member]
  5. rem_node::[*,*]
  6. *::*

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.


Previous Next Contents Index