HP OpenVMS System Services Reference Manual


Previous Contents Index


$NXTVOL

The Next Volume service allows you to process the next tape volume in a multiple volume set. This service applies only to files on magnetic tape volumes.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$OPEN

The Open service makes an existing file available for processing by your program. The Open service specifies the type of record access to be used and determines whether the file can be shared. The Open service also performs an implicit Display service.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$PARSE

The Parse service analyzes the file specification string and fills in various NAM block fields.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$PARSE_ACL

Parses the specified text string and converts it to the binary representation for an access control entry (ACE).

Format

SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]


C Prototype

int sys$parse_acl (void *aclstr, void *aclent, unsigned short int *errpos, void *accnam, int (*routin)(void));


Arguments

aclstr


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

Formatted ACE that is parsed when $PARSE_ACL completes execution. The aclstr argument is the address of a string descriptor pointing to the text string to be parsed.

aclent


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

Description of the ACE that is parsed when $PARSE_ACL completes execution. The aclent argument is the address of a descriptor pointing to the buffer in which the ACE is written. The first byte of the buffer contains the length of the ACE; the second byte contains a value that identifies the type of ACE, which in turn defines the format of the ACE.

For information about the ACE types and their associated formats, see $FORMAT_ACL system service documentation.

errpos


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

Number of characters from aclstr processed by $PARSE_ACL. The errpos argument is the address of a word that receives the number of characters actually processed by the service. If the service fails, this count points to the failing point in the string.

accnam


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

Names of the bits in the access mask when $PARSE_ACL is executing. The accnam argument is the address of an array of 32 quadword descriptors that define the names of the bits in the access mask. Each element points to the name of a bit. The first element names bit 0, the second element names bit 1, and so on.

You can call LIB$GET_ACCNAM to retrieve the access name table for the class of object whose ACL is to be formatted. If you omit accnam, the following names are used:
Bit Name
Bit 0 READ
Bit 1 WRITE
Bit 2 EXECUTE
Bit 3 DELETE
Bit 4 CONTROL
Bit 5 BIT_5
Bit 6 BIT_6
.
.
.
 
Bit 31 BIT_31

nullarg


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

Placeholding argument reserved to HP.

Description

The Parse Access Control List Entry service parses the specified text string and converts it to the binary representation for an access control entry (ACE).

Required Access or Privileges

None

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The string or its descriptor cannot be read by the caller; the buffer descriptor cannot be read by the caller; the buffer cannot be written by the caller; or the buffer is too small to hold the ACL entry.
SS$_IVACL The format of the access control list entry is not valid.
SS$_NOSUCHID The specified identifier does not exist in the rights database.

$PERM_DIS_ALIGN_FAULT_REPORT (Alpha and Integrity servers)

On Alpha and Integrity server systems, disables user process alignment fault reporting.

Format

SYS$PERM_DIS_ALIGN_FAULT_REPORT


C Prototype

int sys$perm_dis_align_fault_report (void);


Arguments

None.

Description

The Disable Alignment Fault Reporting service disables user process alignment fault reporting.

See the description of the $PERM_REPORT_ALIGN_FAULT service for an example of a program that can be used to enable and disable user process alignment fault reporting.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT


Condition Values Returned

SS$_NORMAL The service completed successfully.

$PERM_REPORT_ALIGN_FAULT (Alpha and Integrity servers)

On Alpha and Integrity server systems, initializes user process alignment fault reporting.

Format

SYS$PERM_REPORT_ALIGN_FAULT


C Prototype

int sys$perm_report_align_fault (void);


Arguments

None.

Description

The Report Alignment Fault service allows the user to permanently enable user process alignment fault reporting for all subsequent images.

This service reports alignment faults only in exception mode. For more information about reporting modes, see the $START_ALIGN_FAULT_REPORT service.

Image alignment fault reporting takes precedence over process alignment fault reporting; that is, if both image and process alignment fault reporting are enabled, faults are reported to the image first.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT


Condition Values Returned

SS$_NORMAL The service completed successfully.


Example


/**********************************************************************/ 
/*                                                                    */ 
/* SET_ALIGN_REPORT.C                                                 */ 
/*                                                                    */ 
/*  This program can be used to permanently turn on and off           */ 
/*  alignment fault reporting for a process. After creating the       */ 
/*  executable, do:                                                   */ 
/*                                                                    */ 
/*        $ align :== $dir:set_align_report.exe                       */ 
/*        $ align on                                                  */ 
/*        $ run program        ! will generate align faults on screen */ 
/*        $ align off                                                 */ 
/*        $ run program        ! will not generate align faults       */ 
/*                                                                    */ 
/**********************************************************************/ 
 
#include <stdio> 
#include <ctype> 
#include <ssdef> 
 
 
/*                alignment fault reporting system services           */ 
extern         sys$perm_report_align_fault(), 
               sys$perm_dis_align_fault_report(); 
 
main(argc, argv) 
  int                argc; 
  char               *argv[]; 
{ 
  int                status; 
 
  /* check arguments */ 
  if (argc < 2) { 
    printf ("Insufficient arguments\n"); 
    return (40); 
  } 
 
  /* check if the argument is on or off */ 
  if ((strcmp ("ON", argv[1]) == 0) || (strcmp ("on", argv[1]) == 0)) 
    /* on, turn alignment fault reporting on for this process */ 
    status = sys$perm_report_align_fault (); 
 
  else if ((strcmp ("OFF", argv[1]) == 0) || (strcmp ("off", argv[1]) == 0)) 
    /* off, turn alignment fault reporting off for this process */ 
    status = sys$perm_dis_align_fault_report (); 
 
  else 
    return (SS$_BADPARAM); 
 
  /* return status */ 
  return (status); 
} 
 
 
      

This example shows a program that can be used to enable and disable alignment fault reporting for a process.


$PERSONA_ASSUME (Alpha and Integrity servers)

On Alpha and Integrity server systems, allows an OpenVMS thread to assume the identity of another persona.

Format

SYS$PERSONA_ASSUME persona ,[flags], [previous], [acmode]


C Prototype

int sys$persona_assume (unsigned int *persona, unsigned int flags, unsigned int *previous, unsigned int acmode);


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.

If the value passed is ISS$C_ID_NATURAL, then the state of the calling thread is returned to the natural persona.

flags


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

Ignored.

previous


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

Address of a longword into which the persona identification handle of the currently active persona being replaced is written.

acmode


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

Access mode to be considered when assuming a persona. 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 use this persona.


Description

This service establishes the specified persona as the active security profile and returns the persona identification handle of the persona that was active at the point in which the call to this service was made.

On image exit, the natural persona is assumed and all nonpermanent personae are deleted.

The arguments are 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

None

Related Services

$PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_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; the desired access is granted.
SS$_ACCVIO Access violation.
SS$_INSFARG Certain required arguments were not specified.
SS$_IVMODE The caller cannot create a persona that is more privileged than the caller.
SS$_NOPRIV The operation requires IMPERSONATE privilege.
SS$_PERSONANONGRATA Invalid persona argument.

$PERSONA_CLONE (Alpha and Integrity servers)

On Alpha and Integrity server systems, creates a copy of an existing persona within the context of the current process. The service returns the assigned persona identification for the new persona in the persona argument. This persona can be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CLONE persona ,[input]


C Prototype

int sys$persona_clone (unsigned int *persona, unsigned int *input);


Arguments

persona


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

Address of a longword into which the persona identification handle is written.

input


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

Address of a longword containing the persona identification of the persona to be cloned. If this argument is 0, null, or absent, the currently active persona is cloned.

Description

The Clone Persona service creates a copy of an existing persona within the context of the current process. The service returns the assigned persona identification for the new persona in the persona argument. This persona can be assumed using the $PERSONA_ASSUME service.

On image exit, the natural persona is assumed and all nonpermanent personae are deleted.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_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$_ACCVIO Access violation.
SS$_EXQUOTA The caller lacks sufficient quota to allocate a new persona.
SS$_INSFMEM Insufficient memory.
SS$_IVMODE The caller cannot create a persona that is more privileged than the caller.
SS$_PERSONANONGRATA The persona ID supplied was invalid.

$PERSONA_CREATE (Alpha and Integrity servers)

On Alpha and Integrity server systems, creates a persona that can be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CREATE persona ,[usrnam] ,[flags], [usrpro], [itmlst]


C Prototype

int sys$persona_create (unsigned int *persona, void *usrnam, unsigned int flags, unsigned int *usrpro, unsigned int *itmlst);


Arguments

persona


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

Address of a longword into which the persona identification handle is written.

usrnam


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

Name of the user to be impersonated. The usrnam argument is the address of a descriptor pointing to a character string containing the user name. The string can contain a maximum of 32 alphanumeric characters.

flags


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

The $ISSDEF macro defines these codes:

usrpro


OpenVMS usage: char_string
type: opaque byte stream
access: read only
mechanism: by descriptor

Buffer containing an encoded security profile. The usrpro argument is the address of a descriptor pointing to a buffer that contains encoded security profile data. This profile can be created by calling the SYS$CREATE_USER_PROFILE system service.

itmlst


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

Attributes describing modifications to the security profile. The itmlst argument is the address of an item_list defining changes to be made to the specified user profile.

This section lists the ISS$ item codes and definitions.


Item Codes

ISS$_WORKPRIV

$PERSONA_CREATE sets the working privileges for the new persona as a quadword value.

ISS$_MODE

$PERSONA_CREATE sets the access mode of the new persona as a longword value. The mode cannot be more privileged than that of the caller.

ISS$_FLAGS

$PERSONA_CREATE sets the flags field of the new persona as a longword bit mask. The following bits are currently defined for this field:

ISS$_RIGHTS_INDEX

The index indicates into which rights chain the rights are placed. Values for the index are: ISS$M_ENABLED_PERSONA, ISS$M_ENABLED_SYSTEM, ISS$M_ENABLED_INSTALLED, ISS$M_ENABLED_SUBSYSTEM, and ISS$M_ENABLED_TEMPORARY. All subsequent rights item packets use the index until a new ISS$_RIGHTS_INDEX item changes the index. If a rights index is not specified, the rights item packets will use the PERSONA chain as the default. Rights item packets include: ISS$_AUTHRIGHTS, ISS$_RIGHTS, ISS$_ADD_AUTHRIGHTS, and ISS$_ADD_RIGHTS.

ISS$_AUTHRIGHTS (Reserved for use by HP.)

$PERSONA_CREATE sets the user authorized rights of the new persona as a list of quadword values. Any existing authorized rights will be overwritten. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

ISS$_RIGHTS

$PERSONA_CREATE sets the user rights of the new persona as a list of quadword (paired longword) values. Any existing authorized rights will be overwritten. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes. The format of the list is the same as ISS$_AUTHRIGHTS.

The format of the list is as follows:


ISS$_USERNAME

$PERSONA_CREATE sets the user name of the new persona as a 32-byte character string.

ISS$_ACCOUNT

$PERSONA_CREATE sets the account of the new persona as a 32-byte character string.

ISS$_NOAUDIT

$PERSONA_CREATE sets the No Audit field of the new persona as a longword value.

ISS$_UIC

$PERSONA_CREATE sets the UIC of the new persona as a longword value.

ISS$_AUTHPRIV

$PERSONA_CREATE sets the authorized privileges for the new persona as a quadword value.

ISS$_PERMPRIV

$PERSONA_CREATE sets the permanent privileges for the new persona as a quadword value.

ISS$_IMAGE_WORKPRIV

$PERSONA_CREATE sets the image working privileges for the new persona as a quadword value.

ISS$_ENABLED

$PERSONA_CREATE sets the Rights Enable field of the new persona as a longword bit mask. These bits correspond to the indices of the different rights chains. By setting the bit in the ENABLED field, the corresponding rightslist chain will be enabled, and its rights will be included in all rights checks. Valid bits are: ISS$V_ENABLED_PERSONA, ISS$V_ENABLED_SUBSYSTEM, ISS$V_ENABLED_IMAGE, ISS$V_ENABLED_SYSTEM, and ISS$V_ENABLED_TEMPORARY.

ISS$_ADD_AUTHRIGHTS

$PERSONA_CREATE adds the rights to the current list of authorized rights. $PERSONA_CREATE expects the same format as that outlined in ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

ISS$_ADD_RIGHTS

$PERSONA_CREATE adds the rights to the current list of rights. $PERSONA_CREATE expects the same format as that outlined in ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA rights chain. See ISS$_RIGHTS_INDEX for more information on specifying different indexes.

Description

When you call this service, you can specify either the usrnam or usrpro argument, but not both. The required information specifying the OpenVMS user is read from either the User Authorization File (UAF) and rights database or the usrpro buffer and is stored in system memory. Any modifications specified in the itmlst are then applied to complete the new persona. A persona identification handle that refers to the created persona is returned in the persona argument. This service creates a default VMS extension for the persona.

It is possible to call $PERSONA_CREATE in any mode. To call $PERSONA_CREATE in kernel mode, the calling sequence is different. Only the usrpro argument is valid (usrnam cannot be used because kernel mode access to the SYSUAF file is not allowed), and it is necessary to set the PSB$M_NOACESS value in the flags.


Previous Next Contents Index