Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $ADJSTK

> Modifies the stack pointer for a less privileged access mode. The operating system uses this service to modify a stack pointer for a less privileged access mode after placing arguments on the stack.

### Format

> SYS$ADJSTK [acmode] ,[adjust] ,newadr

### C Prototype

> int sys$adjstk (unsigned int acmode, short int adjust, void *(*(newadr)));

### Arguments

> #### acmode

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

> Access mode for which the stack pointer is to be adjusted. The acmode argument is this longword value. If not specified, the default value 0 (kernel access mode) is used.

> #### adjust

> OpenVMS usage: | word_signed
> type: | word (signed)
> access: | read only
> mechanism: | by value

> Signed adjustment value used to modify the value specified by the newadr argument. The adjust argument is a signed longword, which is the adjustment value.

> Only the low-order word of this argument is used. The value specified by the low-order word is added to or subtracted from (depending on the sign) the value specified by the newadr argument. The result is loaded into the stack pointer for the specified access mode.

> If the adjust argument is not specified or is specified as 0, the stack pointer is loaded with the value specified by the newadr argument.

> For additional information about the various combinations of values for adjust and newadr, see the Description section.

> #### newadr

> OpenVMS usage: | address
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> Value that adjust is to adjust. The newadr argument is the address of this longword value.

> The value specified by this argument is both read and written by $ADJSTK. The $ADJSTK service reads the value specified and adjusts it by the value of the adjust argument (if specified). After this adjustment is made, $ADJSTK writes the adjusted value back into the longword specified by newadr and then loads the stack pointer with the adjusted value.

> If the value specified by newadr is 0, the current value of the stack pointer is adjusted by the value specified by adjust. This new value is then written back into newadr, and the stack pointer is modified.

> For additional information about the various combinations of values for adjust and newadr, see the Description section.

### Description

> The Adjust Outer Mode Stack Pointer service modifies the stack pointer for a less privileged access mode. The operating system uses this service to modify a stack pointer for a less privileged access mode after placing arguments on the stack.

> Combinations of zero and nonzero values for the adjust and newadr arguments provide the following results:

> If the adjust argument specifies: | And the value specified by newadr is: | The stack pointer is:
> --- | --- | ---
> 0 | 0 | Not changed
> 0 | An address | Loaded with the address specified
> A value | 0 | Adjusted by the specified value
> A value | An address | Loaded with the specified address, adjusted by the specified value

> In all cases, the updated stack pointer value is written into the value specified by the newadr argument.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

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

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The value specified by newadr or a portion of the new stack segment cannot be written by the caller.
> SS$_NOPRIV | The specified access mode is equal to or more privileged than the calling access mode.

## $ADJWSL

> Adjusts a process's current working set limit by the specified number of pages (on VAX systems) or pagelets (on Alpha systems) and returns the new value to the caller. The working set limit specifies the maximum number of process pages or pagelets that can be resident in physical memory.

> On Alpha systems, this service accepts 64-bit addresses.

### Format

> SYS$ADJWSL [pagcnt] ,[wsetlm]

### C Prototype

> int sys$adjwsl (int pagcnt, unsigned int *wsetlm);

### Arguments

> #### pagcnt

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by value

> Signed adjustment value specifying the number of pages (on VAX systems) or pagelets (on Alpha systems) to add to (if positive) or subtract from (if negative) the current working set limit. The pagcnt argument is this signed longword value.

> Note that, on Alpha systems, the specified value is rounded up to an even multiple of the CPU-specific page size.

> If pagcnt is not specified or is specified as 0, no adjustment is made and the current working set limit is returned in the longword specified by the wsetlm argument (if this argument is specified).

> #### wsetlm

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | write only
> mechanism: | by 32- or 64-bit reference (Alpha)
> mechanism: | by 32-bit reference (VAX)

> Value of the working set limit, in pages (on VAX systems) or pagelets (on Alpha systems), returned by $ADJWSL. The wsetlm argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of this longword value. The wsetlm argument receives the newly adjusted value if pagcnt is specified, and it receives the prior, unadjusted value if pagcnt is not specified.

### Description

> The Adjust Working Set Limit service adjusts a process's current working set limit by the specified number of pages (on VAX systems) or pagelets (rounded up or down to a whole page count on Alpha systems) and returns the new value to the caller. The working set limit specifies the maximum number of process pages that can be resident in physical memory.

> If a program attempts to adjust the working set limit beyond the system-defined upper and lower limits, no error condition is returned; instead, the working set limit is adjusted to the maximum or minimum size allowed.

> Required Access or Privileges

> None

> Required Quota

> The initial value of a process's working set limit is controlled by the working set default (WSDEFAULT) quota. The maximum value to which it can be increased is controlled by the working set extent (WSEXTENT) quota; the minimum value to which it can be decreased is limited by the system parameter MINWSCNT.

> Related Services

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

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The longword specified by wsetlm cannot be written by the caller.

## $ALLOC

> Allocates a device for exclusive use by a process and its subprocesses. No other process can allocate the device or assign channels to it until the image that called $ALLOC exits or explicitly deallocates the device with the Deallocate Device ($DALLOC) service.

### Format

> SYS$ALLOC devnam ,[phylen] ,[phybuf] ,[acmode] ,[flags]

### C Prototype

> int sys$alloc (void *devnam, unsigned short int *phylen, void *phybuf, unsigned int acmode, unsigned int flags);

### Arguments

> #### devnam

> OpenVMS usage: | device_name
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor--fixed-length string descriptor

> Device name of the device to be allocated. The devnam argument is the address of a character string descriptor pointing to the device name string.

> The string can be either a physical device name or a logical name. If it is a logical name, it must translate to a physical device name.

> #### phylen

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> Word into which $ALLOC writes the length of the device name string for the device it has allocated. The phylen argument is the address of this word.

> #### phybuf

> OpenVMS usage: | device_name
> type: | character-coded text string
> access: | write only
> mechanism: | by descriptor--fixed-length string descriptor

> Buffer into which $ALLOC writes the device name string for the device it has allocated. The phybuf argument is the address of a character string descriptor pointing to this buffer.

> #### acmode

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

> Access mode to be associated with the allocated device. The acmode argument is a longword containing the access mode.

> The most privileged access mode used is the access mode of the caller. Only equal or more privileged access modes can deallocate the device.

> #### flags

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

> Longword of status flags indicating whether to interpret the devnam argument as the type of device to be allocated. Only one flag exists, bit 0. When it is set, the $ALLOC service allocates the first available device that has the type specified in the devnam argument.

> This feature is available for the following mass storage devices:

> RA60 | RA80 | RA81 | RC25
> RCF25 | RK06 | RK07 | RL01
> RL02 | RM03 | RM05 | RM80
> RP04 | RP05 | RP06 | RP07
> RX01 | RX02 | TA78 | TA81
> TS11 | TU16 | TU58 | TU77
> TU78 | TU80 | TU81 |

### Description

> The Allocate Device service allocates a device for exclusive use by a process and its subprocesses. No other process can allocate the device or assign channels to it until the image that called $ALLOC exits or explicitly deallocates the device with the Deallocate Device ($DALLOC) service.

> When a process calls the Assign I/O Channel ($ASSIGN) service to assign a channel to a nonshareable, nonspooled device, such as a terminal or line printer, the device is implicitly allocated to the process.

> You can use this service only to allocate devices that either exist on the host system or are made available to the host system in an OpenVMS Cluster environment.

> Required Access or Privileges

> Read, write, or control access to the device is required.

> Required Quota

> None

> Related Services

> $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_BUFFEROVF | The service completed successfully. The physical name returned overflowed the buffer provided, and was truncated.
> SS$_DEVALRALLOC | The service completed successfully. The device was already allocated to the calling process.
> SS$_ACCVIO | The device name string, string descriptor, or physical name buffer descriptor cannot be read by the caller, or the physical name buffer cannot be written by the caller.
> SS$_DEVALLOC | The device is already allocated to another process, or an attempt to allocate an unmounted shareable device failed because other processes had channels assigned to the device.
> SS$_DEVMOUNT | The specified device is currently mounted and cannot be allocated, or the device is a mailbox.
> SS$_DEVOFFLINE | The specified device is marked off line.
> SS$_IVDEVNAM | The device name string contains invalid characters, or no device name string was specified.
> SS$_IVLOGNAM | The device name string has a length of 0 or has more than 63 characters.
> SS$_IVSTSFLG | The bits set in the longword of status flags are invalid.
> SS$_NODEVAVL | The specified device in a generic search exists but is allocated to another user.
> SS$_NONLOCAL | The device is on a remote node.
> SS$_NOPRIV | The requesting process attempted to allocate a spooled device and does not have the required privilege, or the device protection or access control list (or both) denies access.
> SS$_NOSUCHDEV | The specified device does not exist in the host system. This error is usually the result of a typographical error.
> SS$_TEMPLATEDEV | The process attempted to allocate a template device; a template device cannot be allocated.

The $ALLOC service can also return any condition value returned by $ENQ. For a list of these condition values, see the description of $ENQ.

## $ASCEFC

> Associates a named common event flag cluster with a process to execute the current image and to be assigned a process-local cluster number for use with other event flag services. If the named cluster does not exist but the process has suitable privilege, the service creates the cluster.

### Format

> SYS$ASCEFC efn ,name ,[prot] ,[perm]

### C Prototype

> int sys$ascefc (unsigned int efn, void *name, char prot, char perm);

### Arguments

> #### efn

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

> Number of any event flag contained within the desired common event flag cluster. The efn argument is a longword value specifying this number; however, $ASCEFC uses only the low-order byte.

> There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127. (Clusters 0 and 1 are process-local event flag clusters.)

> To associate with common event flag cluster 2, specify any flag number in the cluster (64 to 95); to associate with common event flag cluster 3, specify any event flag number in the cluster (96 to 127).

> #### name

> OpenVMS usage: | ef_cluster_name
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor--fixed-length string descriptor

> Name of the common event flag cluster with which to associate. The name argument is the address of a character string descriptor pointing to this name string.

> The character string descriptor can be 1 to 15 bytes in length, and each byte can be any 8-bit value.

> Common event flag clusters are accessible only to processes having the same UIC group number, and each such process must associate with the cluster using the same name (specified in the name argument). The operating system implicitly associates the group UIC number with the name, making the name unique to a UIC group.

> You can specify any name from 1 to 43 characters. All processes mapping to the same global section must specify the same name. Note that the name is case sensitive.

> Use of characters valid in logical names is strongly encouraged. Valid values include alphanumeric characters, the dollar sign ($), and the underscore (_). If the name string begins with an underscore (_), the underscore is stripped and the resultant string is considered to be the actual name. Use of the colon (:) is not permitted.

> Names are first subject to a logical name translation, after the application of the prefix GBL$ to the name. If the result translates, it is used as the name of the section. If the resulting name does not translate, the name specified by the caller is used as the name of the section.

> Additional information on logical name translations and on section name processing is available in the OpenVMS Programming Concepts Manual.

> #### prot

> OpenVMS usage: | Boolean
> type: | byte (unsigned)
> access: | read only
> mechanism: | by value

> Protection specifier that allows or disallows access to the common event flag cluster for processes with the same UIC group number as the creating process. The prot argument is a longword value, which is interpreted as Boolean.

> The default value 0 specifies that any process with the same UIC group number as the creating process can access the event flag cluster. The value 1 specifies that only processes having the UIC of the creating process can access the event flag cluster.

> When the prot argument is 1, all access to the Group category is denied.

> The process must have associate access to access an existing common event flag cluster.

> #### perm

> OpenVMS usage: | Boolean
> type: | byte (unsigned)
> access: | read only
> mechanism: | by value

> Permanent specifier that marks a common event flag cluster as either permanent or temporary. The perm argument is a longword value, which is interpreted as Boolean.

> The default value 0 specifies that the cluster is temporary. The value 1 specifies that the cluster is permanent.

### Description

> The Associate Common Event Flag Cluster service associates a named common event flag cluster with a process for the execution of the current image and to assign it a process-local cluster number for use with other event flag services. A process needs associate access to call the $ASCEFC service.

> When a process associates with a common event flag cluster, that cluster's reference count is increased by 1. The reference count is decreased when a process disassociates from the cluster, whether explicitly with the Disassociate Common Event Flag Cluster ($DACEFC) service or implicitly at image exit.

> Temporary clusters are automatically deleted when their reference count goes to 0; you must explicitly mark permanent clusters for deletion with the Delete Common Event Flag Cluster ($DLCEFC) service.

> When a new cluster is created, a security profile is created with the process UIC as the owner of the common event flag cluster; the remaining characteristics are taken from the COMMON_EVENT_CLUSTER.DEFAULT template profile.

> Because the $ASCEFC service automatically creates the common event flag cluster if it does not already exist, cooperating processes need not be concerned with which process executes first to create the cluster. The first process to call $ASCEFC creates the cluster and the others associate with it regardless of the order in which they call the service.

> The initial state for all event flags in a newly created common event flag cluster is 0.

> If a process has already associated a cluster number with a named common event flag cluster and then issues another call to $ASCEFC with the same cluster number, the service disassociates the number from its first assignment before associating it with its second.

> If you previously called any system service that will set an event flag (and the event flag is contained within the cluster being reassigned), the event flag will be set in the newly associated named cluster, not in the previously associated named cluster.

> Required Access or Privileges

> The calling process must have PRMCEB privilege to create a permanent common event flag cluster.

> Required Quota

> Creation of temporary common event flag clusters uses the quota of the process for timer queue entries (TQELM); the creation of a permanent cluster does not affect the quota. The quota is restored to the creator of the cluster when all processes associated with the cluster have disassociated.

> Related Services

> $CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The cluster name string or string descriptor cannot be read by the caller.
> SS$_EXPORTQUOTA | The process has exceeded the number of event flag clusters with which processes on this port of the multiport (shared) memory can associate.
> SS$_EXQUOTA | The process has exceeded its timer queue entry quota; this quota controls the creation of temporary common event flag clusters.
> SS$_INSFMEM | The system dynamic memory is insufficient for completing the service.
> SS$_ILLEFC | You specified an illegal event flag number. The cluster number must be in the range of event flags 64 through 127.
> SS$_INTERLOCK | The bit map lock for allocating common event flag clusters from the specified shared memory is locked by another process.
> SS$_IVLOGNAM | The cluster name string has a length of 0 or has more than 15 characters.
> SS$_NOPRIV | The process does not have the privilege to create a permanent cluster; the process does not have the privilege to create a common event flag cluster in memory shared by multiple processors; or the protection applied to an existing cluster by its creator prohibits association.
> SS$_NOSHMBLOCK | The common event flag cluster has no shared memory control block available.
> SS$_SHMNOTCNT+ | The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

+VAX specific

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_002.HTML