Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $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 Only)

> On Alpha 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 Compaq. The value in this field is unpredictable.
> - iosa$q_count_q (offset 8)
>   This field is reserved for future use by Compaq. 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 Compaq. 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 Only)

> On Alpha 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

| privacy and legal statement |
4527PRO_103.HTML