HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$PERSONA_DELETE

Deletes a persona created using the $PERSONA_CREATE, the $PERSONA_CLONE, or the $PERSONA_RESERVE service.

Format

SYS$PERSONA_DELETE persona


C Prototype

int sys$persona_delete (unsigned int *persona);


Arguments

persona


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

Address of a longword in which the persona identification handle is expected.

Description

The PERSONA_DELETE service frees the resources used by the persona. No changes to the caller's process are made as a result of calling $PERSONA_DELETE.

The persona argument is validated against the caller's mode, so an invalid argument can cause an access violation to be signaled.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO Access violation.
SS$_PERSONADELPEND Persona is in use; delete pending on release.
SS$_NODELPERMANENT Permanent personae cannot be deleted.

$PERSONA_DELETE_EXTENSION (Alpha and I64)

On Alpha and I64 systems, deletes an extension attached to a persona.

Format

SYS$PERSONA_DELETE_EXTENSION persona ,extensionID


C Prototype

int sys$persona_delete_extension (unsigned int *persona, unsigned int *extensionID);


Arguments

persona


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

Address of a longword containing the persona identification for which $PERSONA_DELETE_EXTENSION calls the registered Extension Delete function.

extensionID


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

Address of a longword containing the extension identification (EID) for which the registered DELETE routine is called in order to delete a persona extension block from the specified persona.

Description

This service deletes an extension data structure by calling the registered Extension Delete routine for the specified extension.

When a return fails, the persona extension is not deleted.

The VMS extension associated with each persona cannot be deleted. An attempt to delete that extension returns SS$_UNSUPPORTED.

Required Access or Privileges

This service requires that the caller have the IMPERSONATE privilege enabled or be in exec or kernel mode.

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_BADPARAM An invalid parameter was specified.
SS$_NOIMPERSONATE The caller does not have the privilege to delete pieces of the thread's original identity/persona.
SS$_NOSUCHEXT The extension specified does not exist in the persona.
SS$_PERSONANONGRATA The persona ID supplied was invalid.
SS$_UNSUPPORTED The specified extension cannot be deleted.

$PERSONA_EXTENSION_LOOKUP (Alpha and I64)

On Alpha and I64 systems, translates a text name of an extension (for example, VMS or NT) into an extension identification (EID) that can be used in other persona-related system services.

Format

SYS$PERSONA_EXTENSION_LOOKUP extensionName ,extensionID


C Prototype

int sys$persona_extension_lookup (void *extensionName, unsigned int *extensionID);


Arguments

extensionName


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

Address of a character string descriptor pointing to the name of the extension being looked up.

extensionID


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

Address of a longword into which the value of the extension identification (EID) returned by the service is written.

Description

This service translates a text name of an extension into an extension identification (EID) that can be used in other persona-related system services.

There are currently two extension names: VMS and NT.

Required Access or Privileges

None

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_FIND, $PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The string descriptor supplied in the extensionName argument cannot be read by the service.
SS$_BADPARAM An invalid argument was specified.
SS$_NOSUCHTEXT The supplied extensionName does not exist on this system.

$PERSONA_FIND (Alpha and I64)

On Alpha and I64 systems, enables the caller to find the personae within a process that have certain attributes or settings.

Format

SYS$PERSONA_FIND persona ,itmlst ,contxt


C Prototype

int sys$persona_find (unsigned int *persona, void *itmlst, unsigned int *contxt);


Arguments

persona


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

Address of a longword into which the persona identification that matches all of the items present in the item list is written.

itmlst


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

Attributes specifying which information about the persona is to be compared. The itmlst argument is the address of a list of item descriptors, each describing an item of information or an item list processing directive. The list of item descriptors is terminated by a longword value of 0.

The following diagram shows the format of a single item descriptor:


The following table lists the item descriptor fields and their definitions:

Field Description
Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $PERSONA_FIND is to locate the information. The length of the buffer depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, $PERSONA_FIND fails the comparison.
Item code A word containing a user-supplied symbolic code specifying the item of information $PERSONA_FIND is to test, or specifying a directive for processing subsequent items. The $ISSDEF macro defines these codes. Each item code is described in the Description section.
Buffer address A longword containing the user-supplied address of the buffer in which $PERSONA_FIND locates the information used for the comparison.
Return length address An unused longword containing the user-supplied address of a word into which the system service writes the length in bytes of the information it returned. This longword is unused for PERSONA_FIND.

contxt


OpenVMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference

Context value used when repeatedly calling $PERSONA_FIND. The contxt argument is the address of a longword used while $PERSONA_FIND searches for all personae that match the criteria. The context value must be initialized to zero, and the resulting context of each call to $PERSONA_FIND must be presented to each subsequent call. After contxt is passed to $PERSONA_FIND, you must not modify its value.

Description

This service enables the caller to find the personae within a process that have certain attributes or settings.

A persona identification is returned only if all the items specified in the item list match those in the persona and its extensions.

The item list cannot be changed between context-saved calls. Results are unpredictable if the item list is changed between calls.

Repeated calls to $PERSONA_FIND return subsequent matching personae. When the service returns SS$_NOMOREPROC, there are no more personae to examine.

OpenVMS Persona Item Codes

The following table contains the item codes specific to the OpenVMS persona extension data:

Item Code Use+ Size (bytes) Description
ISS$_USERNAME Q,M,F 32 OpenVMS user name as text string
ISS$_ACCOUNT Q,M,F 32 OpenVMS account name as text string
ISS$_DOMAIN Q,F 32 OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
ISS$_PRINCIPAL Q,F 64 OpenVMS user name as text string
ISS$_EXTENSION Q,F 32 The text string VMS
ISS$_WORKPRIV Q,M 8 Working privilege mask
ISS$_WORKCLASS Q,M Varying Working classification
ISS$_RIGHTS Q Varying Enabled list of rights identifiers
ISS$_NOAUDIT Q,M 4 No audit counter---0 means audits disabled
ISS$_UIC Q,M,F 4 Current UIC
ISS$_AUTHPRIV Q,M 8 Authorized privilege mask
ISS$_PERMPRIV Q,M 8 Permanent privilege mask
ISS$_IMAGE_WORKPRIV Q,M 8 Image working privilege mask
ISS$_ENABLED Q 4 Mask of enabled rights chains
ISS$_AUTHRIGHTS Q Varying Authorized list of rights identifiers
ISS$_MINCLASS Q Varying Minimum classification
ISS$_MAXCLASS Q Varying Maximum classification

+Use descriptions are: Query, Modify, and Find.

Required Access or Privileges

The caller may require extension-specific privileges to search on some data items. The Persona Item Codes section lists the privileges that are needed.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The item list cannot be read by the caller.
SS$_BADPARAM An invalid parameter was specified.
SS$_BADITMCOD The item list contains an invalid item code.
SS$_IVCONTEXT The context value is invalid.
SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae.
SS$_NOMOREPROC There are no more personae to check.
SS$_NOSUCHEXT The extension requested does not exist on the system.

$PERSONA_MODIFY (Alpha and I64)

On Alpha and I64 systems, sets attribute values for a persona.

Format

SYS$PERSONA_MODIFY persona ,itmlst


C Prototype

int sys$persona_modify (unsigned int *persona, void *itmlst);


Arguments

persona


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

Address of a longword containing the persona identification for which this service is to set information.

itmlst


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

Attributes specifying which information in the persona is to be modified. The itmlst argument is the address of a list of item descriptors, each describing an item of information or an item list processing directive. The list of item descriptors is terminated by a longword value of 0.

The following diagram shows the format of a single item descriptor:


The following table lists the item descriptor fields and their definitions:

Field Description
Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer from which $PERSONA_MODIFY is to get information.
Item code A word containing a user-supplied symbolic code specifying the item of information $PERSONA_MODIFY is to change, or specifying a directive for processing subsequent items. The $ISSDEF macro defines these codes. Each item code is described in the Description section.
Buffer address A longword containing the user-supplied address of the buffer from which $PERSONA_MODIFY is to get the information.
Return length address This field is ignored on a call to PERSONA_MODIFY.

Description

The Modify Persona Data service sets attribute values for a persona.

OpenVMS Persona Item Codes

The following table contains the item codes specific to the OpenVMS persona extension data:

Item Code Use+ Size (bytes) Description
ISS$_USERNAME Q,M,F 32 OpenVMS user name as text string
ISS$_ACCOUNT Q,M,F 32 OpenVMS account name as text string
ISS$_DOMAIN Q,F 32 OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
ISS$_PRINCIPAL Q,F 64 OpenVMS user name as text string
ISS$_EXTENSION Q,F 32 The text string VMS
ISS$_WORKPRIV Q,M 8 Working privilege mask
ISS$_WORKCLASS Q,M Varying Working classification
ISS$_RIGHTS Q Varying Enabled list of rights identifiers
ISS$_NOAUDIT Q,M 4 No audit counter---0 means audits disabled
ISS$_UIC Q,M,F 4 Current UIC
ISS$_AUTHPRIV Q,M 8 Authorized privilege mask
ISS$_PERMPRIV Q,M 8 Permanent privilege mask
ISS$_IMAGE_WORKPRIV Q,M 8 Image working privilege mask
ISS$_ENABLED Q 4 Mask of enabled rights chains
ISS$_AUTHRIGHTS Q Varying Authorized list of rights identifiers
ISS$_MINCLASS Q Varying Minimum classification
ISS$_MAXCLASS Q Varying Maximum classification

+Use descriptions are: Query, Modify, and Find.

Required Access or Privileges

This service requires that the caller have the IMPERSONATE privilege enabled or be in exec or kernel mode.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_QUERY, $PERSONA_RESERVE


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The item list cannot be read by the caller, or the buffer cannot be read by the caller.
SS$_BADPARAM An invalid parameter was specified.
SS$_BADITMCOD The item list contains an invalid item code.
SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae.
SS$_NOSUCHEXT The extension requested does not exist on the system.
SS$_PERSONANONGRATA The persona ID supplied was invalid. This service may also return status codes associated with the various extension routines.


Previous Next Contents Index