OpenVMS System Services Reference Manual

Note that a value of 0 in either of the following tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.

prcnam pidadr Result

Omitted Omitted Current process ID is used; process ID is not returned.

Omitted 0 Current process ID is used; process ID is returned.

Omitted Specified Specified process ID is used.

Specified Omitted Specified process name is used; process ID is not returned.

Specified 0 Specified process name is used; process ID is returned.

Specified Specified Specified process ID is used and process name is ignored.

prcnam	pidadr	Result
Omitted	Omitted	Current process ID is used; process ID is not returned.
Omitted	0	Current process ID is used; process ID is returned.
Omitted	Specified	Specified process ID is used.
Specified	Omitted	Specified process name is used; process ID is not returned.
Specified	0	Specified process name is used; process ID is returned.
Specified	Specified	Specified process ID is used and process name is ignored.

The result of passing either the name or the id argument, or both, to SYS$REVOKID is summarized in the following table.

name id Result

Omitted Omitted Illegal. The INSFARG condition value is returned.

Omitted Specified Specified identifier value is used.

Specified Omitted Specified identifier name is used; identifier value is not returned.

Specified 0 Specified identifier name is used; identifier value is returned.

Specified Specified Specified identifier value is used and identifier name is ignored.

name	id	Result
Omitted	Omitted	Illegal. The INSFARG condition value is returned.
Omitted	Specified	Specified identifier value is used.
Specified	Omitted	Specified identifier name is used; identifier value is not returned.
Specified	0	Specified identifier name is used; identifier value is returned.
Specified	Specified	Specified identifier value is used and identifier name is ignored.

Because the Revoke Identifier from Process service removes the specified identifier from the rights list of the process or the system, this service is meant for use by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant for use by the general system user.

Required Access or Privileges

You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

Required Quota

None

Related Services

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

Condition Values Returned

SS$_WASCLR The service completed successfully; the rights list did not contain the specified identifier.

SS$_WASSET The service completed successfully; the rights list already held the specified identifier.

SS$_ACCVIO The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; name cannot be read; or prvatr cannot be written.

SS$_INSFARG You did not specify either the id or the name argument.

SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.

SS$_IVIDENT The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.

SS$_IVLOGNAM You specified an invalid process name.

SS$_NONEXPR You specified a nonexistent process.

SS$_NOPRIV The caller does not have CMKRNL privilege or is not running in executive or kernel mode; or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.

SS$_NOSUCHID The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.

SS$_NOSYSNAM The operation requires SYSNAM privilege.

SS$_RIGHTSFULL The rights list of the process or system is full.

RMS$_PRV The user does not have read 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.

$RMSRUNDWN

Closes all files opened by OpenVMS RMS for the image or process and halts I/O activity. This routine performs a $CLOSE service for each file opened for processing.

Format

SYS$RMSRUNDWN buf-addr ,type-value

C Prototype

int sys$rmsrundwn ( void *buf-addr, unsigned char *type-value);

ARGUMENTS

buf-addr

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor

A descriptor pointing to a 22-byte buffer that is to receive the device identification (16 bytes) and the file identification (6 bytes) of an improperly closed output file. The buf-addr argument is the address of the descriptor that points to the buffer.
type-value

OpenVMS usage: byte_unsigned

type: byte (unsigned)

access: read only

mechanism: by value

A single byte code that specifies the type of I/O rundown to be performed. The type-value argument is the actual value used.
This type of code has the following values and meanings:

0 Rundown of image and indirect I/O for process permanent files.

1 Rundown of image and process permanent files. The caller's mode must not be user.

2 Abort RMS I/O. The caller's mode must be either executive or kernel (the system calls the I/O rundown control routine with this argument for process deletion).

DESCRIPTION

The RMS Rundown service closes all files opened by OpenVMS RMS for the image or process and halts I/O activity. This routine performs a $CLOSE service for each file opened for processing. In addition to closing all files and terminating I/O activity, the I/O rundown control routine releases all locks held on records in shared files, clears buffers, and returns other resources allocated for file processing. You should continue to call the rundown control routine until you receive the success completion status code of RMS$_NORMAL.
Note that, prior to the execution of the $CLOSE service, the rundown control routine cancels all outstanding file operations specified in a File Access Block (FAB) or any QIO requests related to file operations (an Open, Create, or Extend service, for example). It also cancels any read/write requests to nondisk devices such as terminals or mailboxes prior to the execution of the $CLOSE service, resulting in possible loss of data. All read/write requests of disk I/O buffers, however, are allowed to complete, which guarantees that none of the data written to disk files will be lost.
There is no predefined macro of the form $RMSRUNDWN_G or $RMSRUNDWN_S to call this service.
Required Access or Privileges

None
Required Quota

None
Related Services

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

Condition Values Returned

RMS$_NORMAL The service completed successfully.

RMS$_CCF The I/O rundown routine cannot close the file.

RMS$_IAL The argument list is invalid. An output file could not be closed successfully, and the user buffer could not be written.

$SAVE_VP_EXCEPTION (VAX Only)

On VAX systems, saves the pending exception state of the vector processor.

Format

SYS$SAVE_VP_EXCEPTION excid

ARGUMENT

excid

OpenVMS usage: context

type: longword (unsigned)

access: read only

mechanism: by reference

Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. The excid argument is the address of a longword containing this ID.

DESCRIPTION

The Save Vector Processor Exception State service saves in memory any pending vector exception state and clears the vector processor's current exception state.
By default, when an AST or condition handler interrupts the execution of a mainline routine, the operating system saves the mainline routine's vector state, including its vector exception state. Any other routine that executes synchronously with, or asynchronously to, currently executing vectorized code and that performs vector operations itself must preserve the preempted routine's vector exception state across its own execution. It does so by using the $SAVE_VP_EXCEPTION and $RESTORE_VP_EXCEPTION services. Used together, these services ensure that vector exceptions occurring as a result of activity in the original routine are serviced by existing condition handlers within that routine.
In systems that do not have vector-present processors but do have the VAX Vector Instruction Emulation facility (VVIEF) in use, VVIEF emulates the functions of this service.
Required Access or Privileges

None
Required Quota

None
Related Services

$RELEASE_VP, $RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE

Condition Values Returned

SS$_NORMAL The service completed successfully. There were no pending vector exceptions. The service also returns this status when executed in a system that does not have vector-present processors and that does not have the VAX Vector Instruction Emulation facility (VVIEF) loaded.

SS$_WASSET The service completed successfully. Pending vector exception state has been saved.

SS$_ACCVIO The caller cannot write the exception ID longword.

SS$_INSFMEM Insufficient system dynamic memory exists for completing the service.

$SCAN_INTRUSION

Scans the intrusion database for suspects or intruders during a login attempt, audits login failures and updates records, or adds new records to the intrusion database.

Format

SYS$SCAN_INTRUSION logfail_status ,failed_user ,job_type ,[source_terminal] ,[source_node] ,[source_user] ,[source_addr] ,[failed_password] ,[parent_user] ,[parent_id] ,[flags]

C Prototype

int sys$scan_intrusion (unsigned int logfail_status, void *failed_user, unsigned int job_type, void *source_terminal, void *source_node, void *source_user, void *source_address, void *failed_password, void *parent_user, unsigned int parent_id, unsigned int flags);

ARGUMENTS

logfail_status

OpenVMS usage: status code

type: longword (unsigned)

access: read only

mechanism: by value

Reason why the user's login attempt failed. The logfail_status argument is a longword containing the login failure status code.
The logfail_status argument can contain any valid message code. For example, the value of the logfail_status argument is SS$_NOSUCHUSER if the user name the user entered does not exist on the system.
If the logfail_status argument contains a failure status, the service performs a suspect scan. Here, the service searches the intrusion database for intruder suspects as well as intruders. If the value of the logfail_status argument is a successful message, such as SS$_NORMAL, the service scans the database only for intruders. For more information about how the database works, see the OpenVMS Guide to System Security.
failed_user

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

User name associated with the unsuccessful login attempt. The failed_user argument is the address of a character-string descriptor pointing to the failed user name.
A failed user name consists of 1 to 32 alphanumeric characters.
job_type

OpenVMS usage: job type

type: longword (unsigned)

access: read only

mechanism: by value

Type of job that failed. The job_type argument is a longword indicating the type of job that failed.
The $JPIDEF macro defines the following values for the job_type argument:

JPI$K_BATCH
JPI$K_DETACHED
JPI$K_DIALUP
JPI$K_LOCAL
JPI$K_NETWORK
JPI$K_REMOTE

source_terminal

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Source terminal where the login attempt is occurring. The source_terminal argument is the address of a character-string descriptor pointing to the device name of the terminal from which the login attempt originates.
A source terminal device name consists of 1 to 64 alphanumeric characters, including underscores (_) and colons (:).
source_node

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Name of the node from which the user's login attempt originates. The source_node argument is the address of a character-string descriptor pointing to the source node name string.
A source node name consists of 1 to 1024 characters. No specific characters, format, or case is required for a source node name string.
source_user

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

User name associated with the login attempt. The source_user argument is the address of a character-string descriptor pointing to the source user name string.
A source user name consists of 1 to 32 alphanumeric characters, including dollar signs ($) and underscores (_).
source_addr

OpenVMS usage: node address

type: descriptor

access: read only

mechanism: by reference

Source DECnet for OpenVMS address from which the login attempt originates. The source_addr argument is the address of a descriptor containing the source node address.
failed_password

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Password the user entered for the login attempt. The failed_password argument is the address of a character-string descriptor pointing to the plaintext password the user entered in order to log in.
A failed password is a password of 0 to 32 characters that did not allow the user to log in to the system. This argument is not stored in the intrusion database and is only used for auditing during break-in attempts.
parent_user

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Parent process name of the failed login. The parent_user argument is the address of a character-string descriptor pointing to the parent process name of the failed login process.
A parent process name consists of 1 to 15 characters. This argument should be specified only for failed spawn commands.
parent_id

OpenVMS usage: process_id

type: longword (unsigned)

access: read only

mechanism: by value

Process identification of the parent process from which the login was attempted. The parent_id argument is a longword containing the parent process identification.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Operational instructions for the service. The flags argument is a longword bit mask wherein each bit corresponds to an option.
Each flag option has a symbolic name. The $CIADEF macro defines the following valid names for the $SCAN_INTRUSION service.

Symbolic Name Description

CIA$M_NOAUDIT If set, this flag indicates that the service should instruct the security server to not audit the login failure or the break-in attempt. If the flag is set, you are expected to do your own auditing.

CIA$M_IGNORE_RETURN Specifies that the service should not wait for the return status from the security server. No return status from the server's function will be returned to the caller.

CIA$M_REAL_USERNAME If set, indicates that the user name passed as the failed user name is read and known to the system.

CIA$M_SECONDARY_PASSWORD Indicates that the failed password passed to the service was the secondary password. If the flag is clear, the password is assumed to be the primary password.

Symbolic Name	Description
CIA$M_NOAUDIT	If set, this flag indicates that the service should instruct the security server to not audit the login failure or the break-in attempt. If the flag is set, you are expected to do your own auditing.
CIA$M_IGNORE_RETURN	Specifies that the service should not wait for the return status from the security server. No return status from the server's function will be returned to the caller.
CIA$M_REAL_USERNAME	If set, indicates that the user name passed as the failed user name is read and known to the system.
CIA$M_SECONDARY_PASSWORD	Indicates that the failed password passed to the service was the secondary password. If the flag is clear, the password is assumed to be the primary password.

DESCRIPTION

The Scan Intrusion Database service performs the following functions:

Scans the intrusion database for intruders so that successful logins are evaded if the system is taking evasive action.
Adds login failures to the intrusion database.
Changes records in the intrusion database from suspects to intruders when the number of login failures by the specified user or from the specified source reaches the value of the LGI_BREAK_LIM system parameter.
Disables user accounts if the LGI_BRK_DISUSER flag is set and the number of login attempts on a real user has reached LGI_BRK_LIM.
Audits login failures or break-in attempts on behalf of the caller.

The information that $SCAN_INTRUSION stores in the intrusion database is based on the setting of the LGI_BRK_TERM system parameter and the information passed by the caller. For more information about how the intrusion database functions and the use of the LGI system parameters, see the OpenVMS Guide to System Security.
Required Access or Privileges

$SCAN_INTRUSION requires the SECURITY privilege.
Required Quota

None
Related Services

$DELETE_INTRUSION, $SHOW_INTRUSION

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO One or more of the arguments were not readable.

SS$_BADBUFLEN The length of one or more of the specified arguments is out of range.

SS$_BADPARAM An invalid flag was specified in the flags argument.

SS$_NOSECURITY The caller does not have SECURITY privilege.

This service can also return any of the following messages passed from the security server:

SECSRV$_INSUFINFO Not enough information is supplied to form an intrusion record.

SECSRV$_INTRUDER An intruder matching the information passed to the service exists in the intrusion database.

SECSRV$_NOMATCH No intruders or suspects exist that match the information passed to the service.

SECSRV$_SERVERNOTACTIVE The security server is not currently active. Try the request again later.

SECSRV$_SUSPECT A suspect matching the information passed to the service exists in the intrusion database.

$SCHDWK

Schedules the awakening (restarting) of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service.

Format

SYS$SCHDWK [pidadr] ,[prcnam] ,daytim ,[reptim]

C Prototype

int sys$schdwk (unsigned int *pidadr, void *prcnam, struct _generic_64 *daytim, struct _generic_64 *reptim);

ARGUMENTS

pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: modify

mechanism: by reference

Process identification (PID) of the process to be awakened. The pidadr argument is the address of a longword containing the PID. The pidadr argument can refer to a process running on the local node or a process running on another node in the OpenVMS Cluster system.
You must specify the pidadr argument to awaken processes in other UIC groups.
prcnam

OpenVMS usage: process_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed length string descriptor

Name of the process to be awakened. The prcnam is the address of a character string descriptor pointing to the process name. A process running on the local node can be identified with a string of from 1 to 15 characters.
To identify a process on a particular node on a cluster, specify the full process name, which includes the node name as well as the process name. The full process name can contain up to 23 characters.
You can use the prcnam argument to awaken only processes in the same UIC group as the calling process because process names are unique to UIC groups, and the operating system uses the UIC group number of the calling process to interpret the process name specified by the prcnam argument. You must use the pidadr argument to awaken processes in other UIC groups.
daytim

OpenVMS usage: date_time

type: quadword

access: read only

mechanism: by reference

Time at which the process is to be awakened. The daytim argument is the address of a quadword containing this time in the system 64-bit time format. A positive time value specifies an absolute time at which the specified process is to be awakened. A negative time value specifies an offset (delta time) from the current time.
reptim

OpenVMS usage: date_time

type: quadword (unsigned)

access: read only

mechanism: by reference

Time interval at which the wakeup request is to be repeated. The reptim argument is the address of a quadword containing this time interval. The time interval must be expressed in delta time format.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P063.HTM
  OSSG Documentation
  22-NOV-1996 13:00:25.51
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_WASCLR	The service completed successfully; the rights list did not contain the specified identifier.
SS$_WASSET	The service completed successfully; the rights list already held the specified identifier.
SS$_ACCVIO	The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; name cannot be read; or prvatr cannot be written.
SS$_INSFARG	You did not specify either the id or the name argument.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.
SS$_IVLOGNAM	You specified an invalid process name.
SS$_NONEXPR	You specified a nonexistent process.
SS$_NOPRIV	The caller does not have CMKRNL privilege or is not running in executive or kernel mode; or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.
SS$_NOSUCHID	The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.
SS$_NOSYSNAM	The operation requires SYSNAM privilege.
SS$_RIGHTSFULL	The rights list of the process or system is full.
RMS$_PRV	The user does not have read access to the rights database.

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

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

0	Rundown of image and indirect I/O for process permanent files.
1	Rundown of image and process permanent files. The caller's mode must not be user.
2	Abort RMS I/O. The caller's mode must be either executive or kernel (the system calls the I/O rundown control routine with this argument for process deletion).

RMS$_NORMAL	The service completed successfully.
RMS$_CCF	The I/O rundown routine cannot close the file.
RMS$_IAL	The argument list is invalid. An output file could not be closed successfully, and the user buffer could not be written.

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

SS$_NORMAL	The service completed successfully. There were no pending vector exceptions. The service also returns this status when executed in a system that does not have vector-present processors and that does not have the VAX Vector Instruction Emulation facility (VVIEF) loaded.
SS$_WASSET	The service completed successfully. Pending vector exception state has been saved.
SS$_ACCVIO	The caller cannot write the exception ID longword.
SS$_INSFMEM	Insufficient system dynamic memory exists for completing the service.

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

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

OpenVMS usage:	node address
type:	descriptor
access:	read only
mechanism:	by reference

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

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

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

OpenVMS usage:	date_time
type:	quadword
access:	read only
mechanism:	by reference