HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$ADD_IDENT

Adds the specified identifier to the rights database.

Format

SYS$ADD_IDENT name ,[id] ,[attrib] ,[resid]


C Prototype

int sys$add_ident (void *name, unsigned int id, unsigned int attrib, unsigned int *resid);


Arguments

name


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

Identifier name to be added to the rights database when $ADD_IDENT completes execution. The name argument is the address of a character-string descriptor pointing to the identifier name string.

An identifier name consists of 1 to 31 alphanumeric characters, including dollar signs ($) and underscores (_), and must contain at least one nonnumeric character. Any lowercase characters specified are automatically converted to uppercase.

id


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

Identifier to be created when $ADD_IDENT completes execution. The id argument is a longword containing the binary value of the identifier to be created.

If the id argument is omitted, $ADD_IDENT selects a unique available value from the general identifier space and returns it in resid, if it is specified.

attrib


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

Attributes placed in the identifier's record when $ADD_IDENT completes execution. The attrib argument is a longword containing a bit mask that specifies the attributes.

Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The symbols are defined in the system macro library ($KGBDEF). The symbolic name for each bit position is listed in the following table:

Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it from or add it to the process rights database by using the DCL command SET RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves.
KGB$V_NAME_HIDDEN Allows holders of an identifier to have it translated---either from binary to ASCII or vice versa---but prevents unauthorized users from translating the identifier.
KGB$V_NOACCESS Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

resid


OpenVMS usage: rights_id
type: longword (unsigned)
access: write only
mechanism: by reference

Identifier value assigned by the system when $ADD_IDENT completes execution. The resid argument is the address of a longword in which the system-assigned identifier value is written.

Description

The Add Identifier to Rights Database service adds the specified identifier to the rights database.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The name argument cannot be read by the caller, or the resid argument cannot be written by the caller.
SS$_BADPARAM The specified attributes contain invalid attribute flags.
SS$_DUPIDENT The specified identifier already exists in the rights database.
SS$_DUPLNAM The specified identifier name already exists in the rights database.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The format of the specified identifier is invalid.
SS$_NORIGHTSDB The rights database does not exist.
RMS$_PRV The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.


$ADD_PROXY

Adds a new proxy to, or modifies an existing proxy in, the proxy database.

Format

SYS$ADD_PROXY rem_node ,rem_user ,local_user ,[flags]


C Prototype

int sys$add_proxy (void *rem_node, void *rem_user, void *local_user, 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 added to or modified in the proxy database. The rem_node argument is the address of a character-string descriptor pointing to the remote node name string.

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

If you specify a single asterisk (*) for the rem_node argument, the user name specified by the rem_user argument on all nodes is served by the proxy.

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 added to or modified in the proxy database. The rem_user argument is the address of a character-string descriptor pointing to the user name string.

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

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

If you specify a single asterisk (*) for the rem_user argument, all users from the node specified by the rem_node argument are served by the same user names specified by the local_user argument.

local_user


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

Local user name to add to the proxy record specified by the rem_node and rem_user arguments in the proxy database as either the default user or local user. The local_user argument is the address of a character-string descriptor pointing to the local user name.

A local user name consists of 1 to 32 alphanumeric characters, including dollar signs ($) and underscores (_). Any lowercase characters specified are automatically converted to uppercase.

The user name specified by the local_user argument must be a user name known to the local system.

If the PRX$M_DEFAULT flag is specified in the flags argument, the user name specified by the local_user argument will be added to the proxy record in the proxy database as the default user. If a default user already exists for the specified proxy record, the default user is placed into the proxy's local user list and is replaced by the user name specified by the local_user argument.

Proxy records can contain no more than 16 local users and 1 default user. To add multiple users to a single proxy, you must call this service once for each local user.

flags


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

Functional specification for the service and type of user the local_user argument represents. The flags argument is a longword bit mask wherein each bit corresponds to an option.

Each flag option has a symbolic name. The $PRXDEF macro defines the following symbolic names:

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.
PRX$M_DEFAULT The user name specified by the local_user argument is the default user for the proxy. If this flag is not specified, the user name specified by the local_user argument is added to the proxy record's local user list.
PRX$M_IGNORE_RETURN The service should not wait for a return status from the security server. No return status from the server's function will be returned to the caller.

Description

The Add Proxy service adds a new proxy to, or modifies an existing proxy in, the proxy database.

Required Access or Privileges

The caller must have either SYSPRV privilege or a UIC group less than or equal to the MAXSYSGRP system parameter.

Required Quota

None

Related Services

$DELETE_PROXY, $DISPLAY_PROXY, $VERIFY_PROXY


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The rem_node, rem_user, local_user, or flags argument cannot be read by the service.
SS$_BADPARAM An invalid flag was specified in the flags argument.
SS$_BADBUFLEN The length of the rem_node, rem_user, or local_user argument was out of range.
SS$_NOSYSPRV 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$_DUPLICATEUSER The user name specified by the local_user argument already exists in the proxy record's local user list.
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.
SECSRV$_TOOMANYUSERS The specified proxy already has 16 local users and cannot accommodate any more.

$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 or I64 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 and I64 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 or I64 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 and I64 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 or I64)
mechanism: by 32-bit reference (VAX)

Value of the working set limit, in pages (on VAX systems) or pagelets (on Alpha or I64 systems), returned by $ADJWSL. The wsetlm argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha and I64 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 and I64 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.


Previous Next Contents Index