HP OpenVMS Systems Documentation

Converts 128-bit Coordinated Universal Time (UTC) format to 64-bitsystem format or 64-bit system format to 128-bit UTC format based onthe 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 tobased on the value of the cvtflg argument. Thesmnadr is required when converting UTC time to 64-bitsystem 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. Theutcadr argument will be read from or written to basedon the value of the cvtflg argument. Theutcadr argument is required when converting 64-bitsystem 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 thecvtflg value is 0, UTC time is converted to 64-bitsystem value. If the cvtflg value is 1, 64-bit systemformat is converted to UTC time.

Description

The Time Converter service converts 64-bit system format time to UTCformat, 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, thetime 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.

Forces a transaction state change for a transaction in which there isat least one RM participant that has set the DDTM$M_COORDINATOR flag.

Format

SYS$TRANS_EVENT [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,rm_id,tx_event

C Prototype

int sys$trans_event (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid[4], unsigned int rm_id, unsigned int tx_event);

Arguments

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Number of the event flag that is set when the service completes. Ifthis argument is omitted, event flag 0 is used.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Reserved to HP. This argument must be zero.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

The I/O status block in which the completion status of the service isreturned as a condition value. See the Condition Values Returnedsection.

The outcome of the state change is indicated by the contents of the I/Ostatus block.

The following diagram shows the structure of the I/O status block:

astadr

astprm

tid

rm_id

tx_event

Description

The $TRANS_EVENT system service is used by coordinating RM participantsto change the state of transactions.

Preconditions for the successful completion of $TRANS_EVENT include:

• The caller must have the SYSPRV privilege or be in either executive or kernel mode.
• The RM participant must have set the DDTM$M_COORDINATOR flag on the call to $JOIN_RM. Coordinating resource managers cannot join the transaction by calling $ACK_EVENT.
• The access mode of the caller must be the same as or more privileged than that of the transaction within the process.

Table SYS-58 Completion Semantics of the$TRANS_EVENT Service

Operation	Completion Semantics
DDTM$K_TX_PREPARE	A vote has been received from each RM participant and synchronized branch. The status code returned is the combination of the individual votes. The possible values are: SS$_PREPARED. All participants are ready to commit the transaction. Thus all RM participants voted "yes" and all synchronized branches called $END_BRANCH. Note that a read-only vote from an RM participant is counted as a "yes" vote but this response is not returned if all RM participants voted read-only. Unsynchronized branches are assumed to be willing to commit. A further operation (commit or abort) is necessary to complete the transaction. SS$_FORGET. All participants are ready to permit the transaction to be committed but do not require any further notification of transaction events. Thus no further $TRANS_EVENT calls are required for this transaction. Possible reasons for this response are: All RM participants voted read-only. The specified transaction (TID) did not exist. The specified transaction was already prepared (Cyclic graph). SS$_VETO. The transaction cannot be committed. No further $TRANS_EVENT calls are required for this transaction. One reason why the transaction cannot commit, an abort reason code, is placed in the second longword of the iosb argument.
DDTM$K_TX_COMMIT	The only status code returned on successful completion is SS$_FORGET. Sufficient information has been hardened by the DECdtm transaction manager to commit the transaction.
DDTM$K_TX_ABORT	The only status code returned on successful completion is SS$_FORGET. Abort processing has been initiated.

Required Privileges

SYSPRV is required unless the caller is in executive or kernel mode.

Required Quotas

None.

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW,$END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW,$SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW,$START_TRANS, $START_TRANSW, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL	The request was successfully queued. This value is only returned in R0.
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	Invalid value for tx_event parameter.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_FORGET	No further $TRANS_EVENT calls are required for this transaction. If tx_event = DDTM$K_TX_ABORT, then abort processing has been initiated. If tx_event = DDTM$K_TX_COMMIT, then sufficient information has been hardened to commit the transaction. If tx_event = DDTM$K_TX_PREPARE, then one of the following has occurred: All participants voted read-only. The tid was not known. The rm_id was not known.
SS$_ILLEFC	The event flag number was invalid.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_NOLOG	The local node did not have a transaction log.
SS$_NOPRIV	The specified rm_id was not a coordinator of the specified transaction.
SS$_NOSYSPRV	The caller is in user or supervisor mode but did not have SYSPRV set.
SS$_PREPARED	All participants are ready to commit the transaction. A further operation (commit or abort) is necessary to complete the transaction.
SS$_TPDISABLED	The TP_SERVER process was not running on the local node.
SS$_VETO	The tx_event parameter contains the value DDTM$K_TX_PREPARE, and DECdtm or a participant was not in a position to accept an order to commit. One reason why the transaction must abort is supplied in the abort reason code field of the IOSB. No further call to $TRANS_EVENT is needed for a transaction when this condition code is returned.
SS$_WRONGACMODE	The access mode of the caller was less privileged than that of a branch of the transaction in this process.
SS$_WRONGSTATE	The transaction was in the wrong state for the attempted operation: Commit operation when transaction is not prepared. Any operation while another call is in progress.

Forces a transaction state change for a transaction in which there isat least one RM participant that has specified the DDTM$M_COORDINATORflag.

$TRANS_EVENTW always waits for the request to complete before returningto the caller. Other than this, it is identical to $TRANS_EVENT.

Format

SYS$TRANS_EVENTW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,rm_id,tx_event

C Prototype

int sys$trans_eventw (unsigned int efn, unsigned int flags, struct_iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, )

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. Theattr argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a longword bit maskspecifying these attributes.

Each bit in the longword corresponds to an attribute and has a symbolicname. The $LNMDEF macro defines these symbolic names. To specify anattribute, use its symbolic name or set its corresponding bit. Allundefined bits in the longword have the value 0.

If you do not specify this argument or specify it as the value 0 (nobits set), the following attributes are 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 namethat translates the name of one or more tables in which to search forthe specified logical name. The tabnam argument is the32-bit address (on VAX systems) or the 32- or 64-bit address (on Alphasystems) of a descriptor pointing to this name. This argument isrequired.

The name must be entered in uppercase letters. (This requirementdiffers from the $CRELNT system service, which automatically changestabnam to uppercase.)

If the table name is not the name of a logical name table, it isassumed to be a logical name and is translated iteratively until eitherthe name of a logical name table is found or the number of translationsallowed by the system have been performed. If the table name translatesto a list of logical name tables, the tables are searched in thespecified 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. Thelognam argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a descriptorpointing 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 acmodeargument is the 32-bit address (on VAX systems) or the 32- or 64-bitaddress (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 ignoresall names (both logical names and table names) at access modes lessprivileged than the specified access mode. The specified access mode isnot checked against that of the caller.

If you do not specify acmode, $TRNLNM performs thetranslation without regard to access mode; however, the translationprocess proceeds from the outermost to the innermost access modes.Thus, if two logical names with the same name but at different accessmodes exist in the same table, $TRNLNM translates the name with theoutermost access mode.

itmlst

OpenVMS usage:	32-bit item_list_3 or 64-bit item_list_64b
type:	longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Item list describing the information that $TRNLNM is to return. Theitmlst argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a list of itemdescriptors, each of which specifies or controls an item of informationto be returned. An item list in 32-bit format is terminated by alongword of 0; an item list in 64-bit format is terminated by aquadword of 0. All items in an item list must be of the sameformat---either 32-bit or 64-bit.

The following diagram depicts the 32-bit format of a single itemdescriptor:

The following table defines the item descriptor fields for 32-bit itemlist entries:

The following diagram depicts the 64-bit format of a single itemdescriptor:

The following table defines the item descriptor fields for 64-bit itemlist entries:

Item Codes

LNM$_ACMODE

Returns the access mode that was associated with the logical name atthe time of its creation. The buffer address field in the itemdescriptor is the address of a byte in which $TRNLNM writes the accessmode.

LNM$_ATTRIBUTES

Returns the attributes of the logical name and the equivalence nameassociated with the current LNM$_INDEX value.

The buffer address field of the item descriptor points to a longwordbit mask wherein each bit corresponds to an attribute. The $TRNLNMservice sets the corresponding bit for each attribute possessed byeither the logical name or the equivalence name.

The $LNMDEF macro defines the following symbolic names for theseattributes:

Attribute	Description
LNM$M_CONCEALED	If $TRNLNM sets this bit, the equivalence name at the current index value for the logical name is a concealed logical name, as interpreted by OpenVMS RMS.
LNM$M_CONFINE	If $TRNLNM sets this bit, the logical name is not copied from a process to any of its spawned subprocesses. The DCL command SPAWN creates subprocesses.
LNM$M_CRELOG	If $TRNLNM sets this bit, the logical name was created using the $CRELOG system service.
LNM$M_EXISTS	If $TRNLNM sets this bit, an equivalence name with the specified index does exist.
LNM$M_NO_ALIAS	If $TRNLNM sets this bit, the name of the logical name cannot be given to another logical name defined in the same table at an outer access mode.
LNM$M_TABLE	If $TRNLNM sets this bit, the logical name is the name of a logical name table.
LNM$M_CLUSTERWIDE	If $TRNLNM sets this bit, the logical name is in a clusterwide table.
LNM$M_TERMINAL	If $TRNLNM sets this bit, the equivalence name for the logical name cannot be subjected to further (recursive) logical name translation.

LNM$_CHAIN

Processes another item list immediately following the current itemlist. The LNM$_CHAIN item code must be the last one in the current itemlist. The buffer address field of the item descriptor points to thenext item list.

You can chain together 32-bit and 64-bit item lists.

LNM$_INDEX

Searches for an equivalence name that has the specified index value.The buffer address field of the item descriptor points to a longwordcontaining a user-specified integer in the range 0 to 127.

If you do not specify this item code, the implied value of LNM$_INDEXis 0 and $TRNLNM returns information about the equivalence name atindex 0.

Because a logical name can have more than one equivalence name and eachequivalence name is identified by an index value, you should specifythe LNM$_INDEX item code first in the item list, before specifyingLNM$_STRING, LNM$_LENGTH, or LNM$_ATTRIBUTES. These item codes returninformation about the equivalence name identified by the current indexvalue, LNM$_INDEX.

LNM$_LENGTH

Returns the length of the equivalence name string corresponding to thecurrent LNM$_INDEX value. The buffer address field in the itemdescriptor is the address of the longword in which $TRNLNM writes thislength.

If an equivalence name does not exist at the current LNM$_INDEX value,$TRNLNM returns the value 0 to the longword pointed to by the returnlength field of the item descriptor.

LNM$_MAX_INDEX

Each equivalence name for the logical name has an index associated withit. When you specify LNM$_MAX_INDEX, $TRNLNM returns a value equal tothe largest equivalence name index. The buffer address field in theitem descriptor is the address of a longword in which $TRNLNM writesthis value. If the logical name exists but has no equivalence name(and, therefore, no index value), $TRNLNM returns a value of --1.

LNM$_STRING

Returns the equivalence name string corresponding to the currentLNM$_INDEX value. The buffer address field of the item descriptorpoints to a buffer containing this string. The return length addressfield of the item descriptor contains an address of a word thatcontains the length of this string in bytes. The maximum length of theequivalence name string is 255 characters.

If an equivalence name does not exist at the current LNM$_INDEX value,$TRNLNM returns the value 0 in the return length address field of theitem descriptor.

LNM$_TABLE

Returns the name of the table containing the logical name beingtranslated. The buffer address field of the item descriptor points tothe buffer in which $TRNLNM returns this name. The return lengthaddress field of the item descriptor specifies the address of a word inwhich $TRNLNM writes the size of the table name. The maximum length ofthe table name is 31 characters.

Description

The Translate Logical Name service returns information about a logicalname. You need read access to a shareable logical name table totranslate a logical name located in that shareable logical name table.

For conventions regarding logical names for process-permanent files,refer to the chapter "Logical Name Services" in the OpenVMS Programming Concepts Manual.

Required Access or Privileges

Read access is required.

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRELNM, $CRELNT, $CRETVA, $CRMPSC, $DELLNM, $DELTVA,$DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK,$SETSWM, $ULWSET, $UPDSEC, $UPDSECW

Condition Values Returned

SS$_NORMAL	The service completed successfully. An equivalence name for the logical name has been found.
SS$_ACCVIO	The service cannot access the location or locations specified by one or more arguments.
SS$_BADPARAM	One or more arguments have an invalid value, or a logical name table name or logical name was not specified. Or, an item list containing both 32-bit and 64-bit item list entries was found.
SS$_BUFFEROVF	The service completed successfully. The buffer length field in an item descriptor specified an insufficient value, so the buffer was not large enough to hold the requested data.
SS$_IVLOGNAM	The tabnam argument or lognam argument specifies a string whose length is not in the required range of 1 through 255 characters.
SS$_IVLOGTAB	The tabnam argument does not specify a logical name table.
SS$_NOLOGNAM	The logical name was not found in the specified logical name table or tables.
SS$_NOPRIV	The caller lacks the necessary privilege to access the specified name.
SS$_TOOMANYLNAM	Logical name translation of the table name exceeded the allowable depth (10 translations).

The Truncate service shortens a sequential file.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Simulates the occurrence of a cluster configuration event to test thefunctionality of the notification AST.

Format

SYS$TSTCLUEVT [handle] ,[acmode] ,[event]

C Prototype

int sys$tstcluevt (unsigned int *handle, unsigned int acmode, unsignedint event);

Arguments

handle

OpenVMS usage:	identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Identification of the asynchronous system trap (AST) to be tested. Thehandle argument uniquely identifies the request and isreturned when the $SETCLUEVT service is called.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode for which a configuration event AST is to be triggered. Theacmode argument is a longword containing the accessmode.

Each access mode has a symbolic name. The $PSLDEF macro defines thefollowing symbols for the four access modes:

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

event

OpenVMS usage:	event_code
type:	longword (unsigned)
access:	read only
mechanism:	by value

Event code indicating the type of configuration for which an AST is tobe triggered.

Each event type has a symbolic name. The $CLUEVTDEF macro defines thefollowing symbolic names:

Symbolic Name	Description
CLUEVT$C_ADD	One or more OpenVMS nodes have been added to the OpenVMS Cluster system.
CLUEVT$C_REMOVE	One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.

Description

The Test Cluster Event service simulates the occurrence of a clusterconfiguration event to test the functionality of the notification ASTs.The service allows an application to test itself and must be issuedfrom within the same process as the application being tested.$TSTCLUEVT does not affect other processes in the cluster.

The service will allow one specific AST to be fired via thehandle argument, or all ASTs for a specificconfiguration event via the event argument. Specifyingboth the event and the handlearguments will return an error.

If the handle argument is specified, the value of theacmode argument must not be greater than the accessmode of the caller and must match the mode specified when the$SETCLUEVT service was called.

If the event argument is specified, those ASTs thatmatch the value specified in the acmode argument, orthat match the caller's mode, will be triggered.

Required Access or Privileges

None

Required Quota

None

Related Services

$CLRCLUEVT, $SETCLUEVT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	There is an unsatisfactory combination of event and handle parameters, or the event was specified incorrectly.
SS$_NOSUCHOBJ	No request was found that matches the description supplied.

Unlocks pages that were previously locked in memory by the Lock Pagesin Memory ($LCKPAG) service. Locked pages are automatically unlockedand deleted at image exit.

Format

SYS$ULKPAG inadr ,[retadr] ,[acmode]

C Prototype

int sys$ulkpag (struct _va_range *inadr, struct _va_range *retadr,unsigned int acmode);

Arguments

inadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Starting and ending virtual addresses of the pages to be unlocked. Theinadr argument is the address of a 2-longword arraycontaining, in order, the starting and ending process virtual addresses.

Only the virtual page number portion of each virtual address is used;the low-order byte-within-page bits are ignored. If the starting andending virtual addresses are the same, a single page is unlocked.

If more than one page is being unlocked and you need to determinespecifically which pages had been previously unlocked, you shouldunlock the pages one at a time, that is, one page per call to $ULKPAG.The condition value returned by $ULKPAG indicates whether the page waspreviously unlocked.

retadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	write only
mechanism:	by reference---array reference or descriptor

Starting and ending process virtual addresses of the pages actuallyunlocked by $ULKPAG. The retadr argument is theaddress of a 2-longword array containing, in order, the starting andending process virtual addresses.

If an error occurs while multiple pages are being unlocked,retadr specifies those pages that were successfullyunlocked before the error occurred. If no pages were successfullyunlocked, both longwords in the retadr array containthe value --1.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode on behalf of which the request is being made. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines the symbols for the four access modes.

The most privileged access mode used is the access mode of the caller.To unlock any specified page, the resultant access mode must be equalto or more privileged than the access mode of the owner of that page.

Description

The Unlock Pages from Memory service unlocks pages that were previouslylocked in memory by the Lock Pages in Memory ($LCKPAG) service. Lockedpages are automatically unlocked and deleted at image exit.

On Alpha systems, if you are attempting to unlock executable code, youshould issue multiple $ULKPAG calls: one to unlock the code pages andothers to unlock the linkage section references to these pages.

Required Access or Privileges

To call the $ULKPAG service, a process must have PSWAPM privilege.

Required Quota

None

Related Services

For more information, refer to the chapter on memory management in theOpenVMS Programming Concepts Manual.

Condition Values Returned

SS$_WASCLR	The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET	The service completed successfully. All of the specified pages were previously locked.
SS$_ACCVIO	The input array cannot be read by the caller; the output array cannot be written by the caller; or a page in the specified range is inaccessible or does not exist.

On Alpha systems, unlocks pages that were previously locked in memoryby the Lock Pages in Memory ($LCKPAG_64) service.

This service accepts 64-bit addresses.

Format

SYS$ULKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64,return_length_64

C Prototype

int sys$ulkpag_64 (void *start_va_64, unsigned __int64 length_64,unsigned int acmode, 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 unlocked. The specifiedvirtual address will be 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 space to be unlocked. The specifiedlength will be rounded up to a CPU-specific page boundary so that itincludes 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 request is being made. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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.To unlock any specified page, the resultant access mode must be equalto or more privileged than the access mode of the owner of that page.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the unlocked virtual addressrange. The return_va_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword into which the servicereturns 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 virtual address range unlocked. Thereturn_length_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned quadword into which the service returnsthe length of the virtual address range in bytes.

Description

The Unlock Pages from Memory service unlocks pages that were previouslylocked in memory by the Lock Pages in Memory ($LCKPAG_64) service.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments.

If a condition value other than SS$_ACCVIO is returned, the returnedaddress and returned length indicate the pages that were successfullyunlocked before the error occurred. If no pages were unlocked, thereturn_va_64 argument will contain the value -1, and avalue cannot be returned in the memory location pointed to bythe return_length_64 argument.

Required Privileges

To call the $ULKPAG_64 service, a process must have PSWAPM privilege.

Required Quota

None

Related Services

$LCKPAG_64, $ULKPAG

Condition Values Returned

SS$_WASCLR	The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET	The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO	The return_va_64 or return_length_64 argument cannot be written by the caller, or an attempt was made to unlock pages by a caller whose access mode is less privileged than the access mode associated with the pages.

Unlocks pages that were previously locked in the working set by theLock Pages in Working Set ($LKWSET) service.

Format

SYS$ULWSET inadr ,[retadr] ,[acmode]

C Prototype

int sys$ulwset (struct _va_range *inadr, struct _va_range *retadr,unsigned int acmode);

Arguments

inadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference---array reference or descriptor

Starting and ending virtual addresses of the pages to be unlocked. Theinadr argument is the address of a 2-longword arraycontaining, in order, the starting and ending process virtual addresses.

Only the virtual page number portion of each virtual address is used;the low-order byte-within-page bits are ignored. If the starting andending virtual address are the same, a single page is unlocked.

If more than one page is being unlocked and you need to determinespecifically which pages had been previously unlocked, you shouldunlock the pages one at a time, that is, one page per call to $ULWSET.The condition value returned by $ULWSET indicates whether the page waspreviously unlocked.

retadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	write only
mechanism:	by reference---array reference or descriptor

Starting and ending process virtual addresses of the pages that wereactually unlocked by $CRMPSC. The retadr argument isthe address of a 2-longword array containing, in order, the startingand ending process virtual addresses.

If an error occurs while multiple pages are being unlocked,retadr specifies those pages that were successfullyunlocked before the error occurred. If no pages were successfullyunlocked, both longwords in the retadr array containthe value --1.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode on behalf of which the request is being made. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines the symbols for the four access modes.

The most privileged access mode used is the access mode of the caller.To unlock any specified page, the resultant access mode must be equalto or more privileged than the access mode of the owner of that page.

Description

The Unlock Pages from Working Set service unlocks pages that werepreviously locked in the working set by the Lock Pages in Working Set($LKWSET) service. Unlocked pages become candidates for replacementwithin the working set of the process.

On Alpha systems, if you are attempting to unlock executable code, youshould issue multiple $ULKWSET calls: one to unlock the code pages andothers to unlock the linkage section references to these pages.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,$LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $UPDSEC,$UPDSECW

Condition Values Returned

SS$_WASCLR	The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET	The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO	The inadr argument cannot be read by the caller; the retadr argument cannot be written by the caller; or a page in the specified range is inaccessible or does not exist.
SS$_NOPRIV	A page in the specified range is in the system address space.

On Alpha systems, unlocks a virtual address range that was previouslylocked in the working set by the Lock Pages in Working Set ($LKWSET_64)service.

This service accepts 64-bit addresses.

Format

SYS$ULWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64,return_length_64

C Prototype

int sys$ulwset_64 (void *start_va_64, unsigned __int64 length_64,unsigned int acmode, 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 unlocked from theworking set. The specified virtual address will be rounded down to aCPU-specific page boundary.

length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Length of the virtual address space to be unlocked from the workingset. The specified length will be rounded up to a CPU-specific pageboundary so that it includes all CPU-specific pages in the requestedrange.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode on behalf of which the request is being made. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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.To unlock any specified page, the resultant access mode must be equalto or more privileged than the access mode of the owner of that page.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the unlocked virtual addressrange. The return_va_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword into which the servicereturns 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 virtual address range unlocked. Thereturn_length_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned quadword into which the service returnsthe length of the virtual address range in bytes.

Description

The Unlock Pages from Working Set service unlocks pages that werepreviously locked in the working set by the Lock Pages in Working Set($LKWSET_64) service. Unlocked pages become candidates for replacementwithin the working set of the process.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments.

If a condition value other than SS$_ACCVIO is returned, the returnedaddress and returned length indicate the pages that were successfullyunlocked before the error occurred. If no pages were unlocked, thereturn_va_64 argument will contain the value -1, and avalue cannot be returned in the memory location pointed to bythe return_length_64 argument.

Required Privileges

None

Required Quota

None

Related Services

$LKWSET_64, $PURGE_WS, $ULWSET

Condition Values Returned

SS$_WASCLR	The service completed successfully. At least one of the specified pages was previously unlocked.
SS$_WASSET	The service completed successfully. All of the specified pages were previously locked in the working set.
SS$_ACCVIO	The return_va_64 or return_length_64 argument cannot be written by the caller, or an attempt was made to unlock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
SS$_PAGNOTINREG	A page in the specified range is not within process private address space.

Unwinds the procedure call stack.

Format

SYS$UNWIND [depadr] ,[newpc]

C Prototype

int sys$unwind (unsigned int *depadr, void *newpc);

Arguments

depadr

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Depth to which the procedure call stack is to be unwound. Thedepadr argument is the address of a longword value.The value 0 specifies the call frame of the procedure that wasexecuting when the condition occurred (that is, no call frames areunwound); the value 1 specifies the caller of that frame; the value 2specifies the caller of the caller of that frame, and so on.

If depadr specifies the value 0, no unwind occurs and$UNWIND returns a successful condition value in R0.

If you do not specify depadr, $UNWIND unwinds thestack to the call frame of the procedure that called the procedure thatestablished the condition handler that is calling the $UNWIND service.This is the default and the normal method of unwinding the procedurecall stack.

newpc

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by value

New value for the program counter (PC); this value replaces the currentvalue of the PC in the call frame of the procedure that receivescontrol when the unwinding operation is complete. Thenewpc argument is a longword value containing theaddress at which execution is to resume.

Execution resumes at this address when the unwinding operation iscomplete.

If you do not specify newpc, execution resumes at thelocation specified by the PC in the call frame of the procedure thatreceives control when the unwinding operation is complete.

Description

The Unwind Call Stack service unwinds the procedure call stack; thatis, it removes a specified number of call frames from the stack.Optionally, it can return control to a new program counter (PC)unwinding the stack. The $UNWIND service is intended to be called fromwithin a condition-handling routine.

The actual unwind is not performed immediately. Rather, the returnaddresses in the call stack are modified so that, when the conditionhandler returns, the unwind procedure is called from each frame beingunwound.

During the actual unwinding of the call stack, $UNWIND examines eachframe in the call stack to see if a condition handler has beendeclared. If a handler has been declared, $UNWIND calls the handlerwith the condition value SS$_UNWIND (indicating that the call stack isbeing unwound) in the condition name argument of the signal array. Whenyou call a condition handler with this condition value, that handlercan perform any procedure-specific cleanup operations that might berequired. After the condition handler returns, the call frame isremoved from the stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$DCLCMH, $SETEXV

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The call stack is not accessible to the caller. This condition is detected when the call stack is scanned to modify the return address.
SS$_INSFRAME	There are insufficient call frames to unwind to the specified depth.
SS$_NOSIGNAL	No signal is currently active for an exception condition.
SS$_UNWINDING	An unwind operation is already in progress.

The Update service allows you to modify the contents of an existingrecord in a file residing on a disk device.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Writes all modified pages in an active private or global section backinto the section file on disk. One or more I/O requests are queued,based on the number of pages that have been modified.

Format

SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb] ,[astadr],[astprm]

C Prototype

int sys$updsec (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);

Arguments

inadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference---array reference or descriptor

Starting and ending virtual addresses of the pages that are to bewritten to the section file if they have been modified. Theinadr argument is the address of a 2-longword arraycontaining, in order, the starting and ending process virtualaddresses. Addresses are adjusted up or down to CPU-specific pages.

Only the virtual page number portion of each virtual address is used;the low-order byte-within-page bits are ignored.

$UPDSEC scans pages starting at the address contained in the firstlongword specified by inadr and ending at the addresscontained in the second longword. Within this range, $UPDSEC locatesread/write pages that have been modified and writes them (contiguously,if possible) to the section file on disk. Unmodified pages are alsowritten to disk if they share the same cluster with modified pages.

If the starting and ending virtual addresses are the same, a singlepage is written to the section file if the page has been modified.

The address specified by the second longword might be smaller than theaddress specified by the first longword.

retadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	write only
mechanism:	by reference---array reference or descriptor

Addresses of the first and last pages that were actually queued forwriting, in the first $QIO request, back to the section file on disk.The retadr argument is the address of a 2-longwordarray containing, in order, the addresses of the first and last pages.Addresses always are adjusted up or down to fall on CPU-specificboundaries.

If $UPDSEC returns an error condition value in R0, each longwordspecified by retadr contains the value --1. In thiscase, an event flag is not set, no asynchonous system trap (AST) isdelivered, and the I/O status block is not written to.

acmode

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode on behalf of which the service is performed. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines the symbols for the four access modes.

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 $UPDSECis equal to or more privileged than the access mode of the owner of thepage to be written.

updflg

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

Update specifier for read/write global sections. Theupdflg argument is a longword value. The value 0 (thedefault) specifies that all read/write pages in the global section areto be written to the section file on disk, whether or not they havebeen modified. The value 1 specifies that the caller is the only or thelast process having the global section mapped for write access and thatonly modified pages should be written to the section file on disk.

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Event flag to be set when the section file on disk is actually updated.The efn argument is a longword specifying the numberof the event flag; however, $UPDSEC uses only the low-order byte.

If you do not specify efn, event flag 0 is used.

When you invoke $UPDSEC, the specified event flag or event flag 0 iscleared; when the update operation is complete, the event flag is set.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the final completion status of the updatingoperation. The iosb argument is the address of thequadword I/O status block.

When you invoke $UPDSEC, the I/O status block is cleared. After theupdate operation is complete, that is, when all I/O to the disk iscomplete, the I/O status block is written as follows:

• The first word contains the condition value returned by $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.
• The second longword contains the virtual address of the first page that was not written.

Though this argument is optional, HP strongly recommends that youspecify it for the following reasons:

• If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
• If you are using $SYNCH to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
• The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to $UPDSEC. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $UPDSEC, you must check the condition values returned in both R0 and the I/O status block.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference---procedure reference or descriptor

AST routine to be executed when the section file has been updated. Theastadr argument is the address of this routine.

If you specify astadr, the AST routine executes at theaccess mode from which the section file update was requested.

astprm

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

AST parameter to be passed to the AST routine. Theastprm argument is this longword parameter.

Description

The Update Section File on Disk service writes all modified pages in anactive 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 thathave been modified.

Proper use of this service requires the caller to synchronizecompletion of the update request. You do this by first checking thecondition value returned in R0 by $UPDSEC. If SS$_NOTMODIFIED isreturned, the caller can continue. If SS$_NORMAL is returned, thecaller should wait for the I/O to complete and then check the firstword of the I/O status block for the final completion status. You canuse the Synchronize ($SYNCH) service to determine whether the I/Ooperation has actually completed.

On VAX systems, for a global section located in memory shared bymultiple processors, only processes running on the processor thatcreated the section can specify that global section in a call to$UPDSEC. Processes on another processor that attempt to update thesection file receive an error condition.

Required Access or Privileges

None

Required Quota

$UPDSEC uses the calling process's direct I/O limit (DIRIO) quota inqueuing 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.

Writes all modified pages in an active private or global section backinto 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 tothe 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 theupdate request, without waiting for the pages to be updated.

In all other respects, $UPDSECW is identical to $UPDSEC. For all otherinformation about the $UPDSECW service, refer to the description of$UPDSEC.

For additional information about system service completion, refer tothe 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);

On Alpha systems, writes all pages (or only those pages modified by thecurrent process) in an active private or global disk file section backinto the section file on disk. One or more I/O requests are queued toperform the write operation.

The $UPDSEC_64 service completes asynchronously. For synchronouscompletion, 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 sectionfile. The specified virtual address is rounded down to a CPU-specificpage 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 sothat 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. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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 theowner 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. Theupdflg argument is a longword value. The value 0 (thedefault) specifies that all read/write pages in the global section areto be written to the section file on disk, whether or not they havebeen modified. The value UPDFLG$M_WRT_MODIFIED specifies that thecaller is the only process actually writing the global section and thatonly those pages that were actually modified by the caller are to bewritten to the section file on disk.

Definitions for this flag can be found in the file SECDEF.H inSYS$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 actuallyupdated. The efn argument is a longword specifying thenumber of the event flag; however, this service only uses the low-orderbyte. If you do not specify the efn, event flag 0 isused.

When you invoke $UPDSEC_64, the specified event flag or event flag 0 iscleared. 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 theupdating operation. The iosa_64 argument is the 32- or64-bit virtual address of the I/O status area. The I/O status areastructure is 32 bytes in length.

The I/O status area structure definition can be found in $IOSADEF inSTARLET.MLB for macro and in the file IOSADEF.H in SYS$STARLET_C.TLBfor C.

When you call SYS$UPDSEC_64, the I/O status area is cleared. After theupdate operation is complete (that is, when all I/O to the disk iscomplete), 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 queuedfor writing (in the first I/O request) back to the section file on thedisk. The return_va_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword into which the servicereturns 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 thesection file on disk. The return_length_64 argument isthe 32- or 64-bit virtual address of a naturally aligned quadword intowhich the service returns the length of the virtual address range, inbytes, 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 thesection file has been updated. The astadr_64 argumentis the 32- or 64-bit address of this routine. If you specify theastadr_64 argument, the AST routine executes at theaccess 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. Theastprm_64 argument is a quadword argument that ispassed to the AST routine.

Description

The Update Global Section File on Disk service writes all pages in anactive private or global section back into the section file on disk. Ifthe updflg argument indicates that only modified pagesare to be written back to the disk file, only those global pagesmodified by the current process are queued to be written back into thesection file on disk.

Proper use of this service requires the caller to synchronizecompletion of the update request. To do this, first check the conditionvalue returned. If SS$_NOTMODIFIED is returned, the caller cancontinue. If SS$_NORMAL is returned, the caller should wait for the I/Oto complete and then check the I/O status for final completion status.

If any error is returned by this service, a value cannot bereturned in the memory locations pointed to by theiosb_64, return_va_64, andreturn_length_64 arguments.

Required Privileges

None

Required Quota

$UPDSEC_64 uses the calling process' direct I/O limit (DIRIO) quota inqueuing 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.

On Alpha systems, writes all modified pages in an active private orglobal disk file section back into the section file on disk. Zero ormore I/O requests are queued, based on the number of pages that havebeen modified.

The $UPDSEC_64W service completes synchronously; that is, it returns tothe caller after writing all updated pages.

In all other respects, $UPDSEC_64W is identical to $UPDSEC_64. For allother information about the $UPDSEC_64W service, refer to thedescription 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,...);

Verifies that a proxy exists and returns a valid local user for thecaller 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. Therem_node argument is the address of a character-stringdescriptor pointing to the remote node name string.

A remote node name consists of 1 to 1024 characters. No specificcharacters, format, or case are required for a remote node name string.All node names are converted to their DECnet for OpenVMS full nameunless the PRX$M_BYPASS_EXPAND flag is set with theflags argument.

Wildcards are not recognized. If you specify a wildcard character inthe rem_node argument, it is ignored and assumed to bepart 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. Therem_user argument is the address of a character-stringdescriptor pointing to the user name string.

A remote user name consists of 1 to 32 alphanumeric characters,including dollar signs ($), underscores (_), and brackets ([ ]). Anylowercase characters specified are automatically converted to uppercase.

The rem_user argument can be specified in useridentification code (UIC) format ([group, member]).Brackets are allowed only if the remote user name string specifies aUIC. Group and member are character-string representations of octalnumbers with no leading zeros.

Wildcards are not allowed for the remote user specification. Ifwildcard characters are present in the string specified by therem_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. Theproposed_user argument is the address of acharacter-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 lowercasecharacters specified are automatically converted to uppercase.

See the Description section for information about the interaction ofthis argument with the return value of the local_userargument.

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. Thelocal_user argument is the address of a 32-bytecharacter-string descriptor pointer to receive the local user name thecaller must use for a proxy login for the proxy with the remote nodename specified by the rem_node argument and the remoteuser name specified by the rem_user argument.

A local user name is a 32-character blank padded string of alphanumericcharacters, 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 thelocal_user argument. Thelocal_user_length argument is the address of anunsigned word to receive the length, in bytes, of the character stringreturned 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 thelocal_user argument represents. Theflags argument is a longword bit mask wherein each bitcorresponds to an option.

Each flag option has a symbolic name. The $PRXDEF macro defines thefollowing 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 proxydatabase and returns the local user name the caller must use for anyproxy logins.

The following description shows how the service determines which localuser name the caller must use for proxy logins.

Proxies that match the remote node and remote user specified by therem_node and rem_user arguments,respectively, are searched in the following order if the remote username 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 therem_node and rem_user arguments,respectively, are searched for in the following order if the remoteuser 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 mustuse for any proxy logins is determined if a matching proxy record isfound 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.

The Wait service suspends image execution until an asynchronous recordservice completes. Upon completion of the service, RMS returns controlto your program at the point following the Wait service call.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Tests a specific event flag and returns immediately if the flag is set;otherwise, the process is placed in a wait state until the event flagis set.

Format

SYS$WAITFR efn

C Prototype

int sys$waitfr (unsigned int efn);

Argument

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Number of the event flag for which to wait. The efnargument is a longword containing this number; however, $WAITFR usesonly the low-order byte.

Description

The Wait for Single Event Flag service tests a specific event flag andreturns immediately if the flag is set. Otherwise, the process isplaced in a wait state until the event flag is set. The wait statecaused by this service can be interrupted by an asynchronous systemtrap (AST) if (1) the access mode at which the AST executes is equal toor more privileged than the access mode from which the $WAITFR servicewas issued and (2) the process is enabled for ASTs at that access mode.

When a wait state is interrupted by an AST and after the AST serviceroutine completes execution, the operating system repeats the $WAITFRrequest on behalf of the process. At this point, if the event flag hasbeen set, the process resumes execution.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WFLAND, $WFLOR

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

Activates a process that has placed itself in a state of hibernationwith the Hibernate ($HIBER) service.

This service accepts 64-bit addresses.

Format

SYS$WAKE [pidadr] ,[prcnam]

C Prototype

int sys$wake (unsigned int *pidadr, void *prcnam);

Arguments

pidadr

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference

Process identification (PID) of the process to be activated. Thepidadr argument is the 32- or 64-bit address of alongword that contains the PID. The pidadr argumentcan refer to a process running on the local node or a process runningon another node in the cluster.

prcnam

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

Process name of the process to be activated. Theprcnam argument is the 32- or 64-bit address of a 32-or 64-bit character string descriptor pointing to the process name. Aprocess running on the local node can be identified with a 1 to 15character string.

To identify a process on a particular node in a cluster, specify thefull process name, which includes the node name as well as the processname. The full process name can contain up to 23 characters.

The process name is implicitly qualified by the UIC group number of thecalling process. For this reason, you can use theprcnam argument only if the process to be activated isin the same UIC group as the calling process. To activate a process inanother UIC group, you must specify the pidadrargument.

Description

The Wake Process from Hibernation service activates a process that hasplaced itself in a state of hibernation with the Hibernate ($HIBER)service. If you specify neither the pidadr nor theprcnam argument, the wake request is issued for thecalling process.

If the longword at address pidadr is the value 0, thePID of the target process is returned.

If one or more wake requests are issued for a process not currentlyhibernating, a subsequent hibernate request completes immediately; thatis, the process does not hibernate. No count of outstanding wakeuprequests is maintained.

You can also activate a hibernating process with the Schedule Wakeup($SCHDWK) service.

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing privileges to use $WAKE:

• GROUP privilege to wake another process in the same group, unless the process has the same UIC as the calling process
• WORLD privilege to wake 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,$SUSPND

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$_IVLOGNAM	The specified process name string has a length of 0 or has more than 15 characters.
SS$_NONEXPR	The specified process does not exist, or you specified an invalid process identification.
SS$_NOPRIV	The process does not have the privilege to wake the specified process.
SS$_NOSUCHNODE	The process name refers to a node that is not currently recognized as part of the VSMcluster system.
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.)

Allows a process to specify a set of event flags for which it wants towait.

Format

SYS$WFLAND efn ,mask

C Prototype

int sys$wfland (unsigned int efn, unsigned int mask);

Arguments

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Number of any event flag within the event flag cluster to be used. Theefn argument is a longword containing this number;however, $WFLAND uses only the low-order byte. Specifying the number ofan event flag within the cluster serves to identify the event flagcluster.

There are two local event flag clusters: cluster 0 and cluster 1.Cluster 0 contains event flag numbers 0 to 31, and cluster 1 containsevent flag numbers 32 to 63.

There are two common event flag clusters: cluster 2 and cluster 3.Cluster 2 contains event flag numbers 64 to 95, and cluster 3 containsevent flag numbers 96 to 127.

mask

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Event flags for which the process is to wait. The maskargument is a longword bit vector wherein a bit, when set, selects thecorresponding event flag for which to wait.

Description

The Wait for Logical AND of Event Flags service allows a process tospecify a set of event flags for which it wants to wait. The process isput in a wait state until all specified event flags are set, at whichtime $WFLAND returns to the caller and execution resumes.

The wait state caused by this service can be interrupted by anasynchronous system trap (AST) if (1) the access mode at which the ASTexecutes is equal to or more privileged than the access mode from whichthe $WAITFR service was issued and (2) the process is enabled for ASTsat that access mode.

When a wait state is interrupted by an AST and after the AST serviceroutine completes execution, the operating system repeats the $WFLANDrequest on behalf of the process. At this point, if all the specifiedevent flags have been set, the process resumes execution.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLOR

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

Allows a process to specify a set of event flags for which it wants towait.

Format

SYS$WFLOR efn ,mask

C Prototype

int sys$wflor (unsigned int efn, unsigned int mask);

Arguments

efn

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

Number of any event flag within the event flag cluster to be used. Theefn argument is a longword containing this number;however, $WFLOR uses only the low-order byte. Specifying the number ofan event flag within the cluster serves to identify the event flagcluster.

There are two local event flag clusters: cluster 0 and cluster 1.Cluster 0 contains event flag numbers 0 to 31, and cluster 1 containsevent flag numbers 32 to 63.

There are two common event flag clusters: cluster 2 and cluster 3.Cluster 2 contains event flag numbers 64 to 95, and cluster 3 containsevent flag numbers 96 to 127.

mask

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Event flags for which the process is to wait. The maskargument is a longword bit vector wherein a bit, when set, selects thecorresponding event flag for which to wait.

Description

The Wait for Logical OR of Event Flags service allows a process tospecify a set of event flags for which it wants to wait. The process isput in a wait state until any one of the specified event flags is set,at which time $WFLOR returns to the caller and execution resumes.

The wait state caused by this service can be interrupted by anasynchronous system trap (AST) if (1) the access mode at which the ASTexecutes is equal to or more privileged than the access mode from whichthe $WFLOR service was issued and (2) the process is enabled for ASTsat that access mode.

When a wait state is interrupted by an AST and after the AST serviceroutine completes execution, the operating system repeats the $WFLORrequest on behalf of the process. At this point, if any of thespecified event flags has been set, the process resumes execution.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCEFC, $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

The Write service transfers a user-specified number of bytes (beginningon a block boundary) to an RMS file of any file organization.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

The following table lists the obsolete system services and the currentservices that have replaced them.