Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS System Services Reference Manual
Previous Contents Index

Use NSA$_SUPPRESS, for example, when auditing events from server processes when the default values for many of these items need to explicitly reference the client context rather than be defaulted from the environment of the server.

The following section provides a list of additional item codes that are valid as an item descriptor in the itmlst argument.

NSA$_ACCESS_DESIRED

NSA$_ACCESS_DESIRED is a longword value specifying the access request mask as defined in $ARMDEF.

NSA$_ACCESS_MODE

NSA$_ACCESS_MODE is a byte value specifying an access mode associated with the event.

NSA$_ACCOUNT

NSA$_ACCOUNT is a string of 1 to 32 characters specifying the account name associated with the event.

NSA$_ASSOCIATION_NAME

NSA$_ASSOCIATION_NAME is a string of 1 to 256 characters specifying an association name.

NSA$_COMMAND_LINE

NSA$_COMMAND_LINE is a string of 1 to 2048 characters specifying a command line.

NSA$_CONNECTION_ID

NSA$_CONNECTION_ID is a longword value specifying a connection identification.

NSA$_DECNET_LINK_ID

NSA$_DECNET_LINK_ID is a longword value specifying a DECnet for OpenVMS logical link identification.

NSA$_DECNET_OBJECT_NAME

NSA$_DECNET_OBJECT_NAME is a string of 1 to 16 characters specifying a DECnet for OpenVMS object name.

NSA$_DECNET_OBJECT_NUMBER

NSA$_DECNET_OBJECT_NUMBER is a longword value specifying a DECnet for OpenVMS object number.

NSA$_DEFAULT_USERNAME

NSA$_DEFAULT_USERNAME is a string of 1 to 32 characters specifying a default local user name for incoming network proxy requests.

NSA$_DEVICE_NAME

NSA$_DEVICE_NAME is a string of 1 to 64 characters specifying the name of the device where the volume resides.

NSA$_DIRECTORY_ENTRY

NSA$_DIRECTORY_ENTRY is a string of 1 to 256 characters specifying the name of the directory entry associated with an XQP operation.

NSA$_DIRECTORY_ID

NSA$_DIRECTORY_ID is an array of three words specifying the directory file identification.

NSA$_DISMOUNT_FLAGS

NSA$_DISMOUNT_FLAGS is a longword value specifying the dismount flags that are defined by the $DMTDEF macro in STARLET.

NSA$_EFC_NAME

NSA$_EFC_NAME is a string of 1 to 16 characters specifying the event flag cluster name.

NSA$_FILE_ID

NSA$_FILE_ID is an array of three words specifying the file identification.

NSA$_FINAL_STATUS

NSA$_FINAL_STATUS is a longword value specifying the successful or unsuccessful status that caused the auditing facility to be invoked.

NSA$_HOLDER_NAME

NSA$_HOLDER_NAME is a string of 1 to 32 characters specifying the name of the user holding the identifier.

NSA$_HOLDER_OWNER

NSA$_HOLDER_OWNER is a longword value specifying the owner (UIC) of the holder.

NSA$_ID_ATTRIBUTES

NSA$_ID_ATTRIBUTES is a longword value specifying the attributes of the identifier, which are defined by the $KGBDEF macro in STARLET.

NSA$_IDENTIFIERS_USED

NSA$_IDENTIFIERS_USED is an array of longwords specifying the identifiers (from the access control entry [ACE] granting access) that were used to gain access to the object.

NSA$_ID_NAME

NSA$_ID_NAME is a string of 1 to 32 characters specifying the name of the identifier.

NSA$_ID_NEW_ATTRIBUTES

NSA$_ID_NEW_ATTRIBUTES is a longword value specifying the new attributes of the identifier, which are defined by the $KGBDEF macro in STARLET.

NSA$_ID_NEW_NAME

NSA$_ID_NEW_NAME is a string of 1 to 32 characters specifying the new name of the identifier.

NSA$_ID_NEW_VALUE

NSA$_ID_NEW_VALUE is a longword value specifying the new value of the identifier.

NSA$_ID_VALUE

NSA$_ID_VALUE is a longword value specifying the value of the identifier.

NSA$_ID_VALUE_ASCII

NSA$_ID_VALUE_ASCII is a longword specifying the value of the identifier.

NSA$_IMAGE_NAME

NSA$_IMAGE_NAME is a string of 1 to 1024 characters specifying the name of the image being executed when the event took place.

NSA$_INSTALL_FILE

NSA$_INSTALL_FILE is a string of 1 to 255 characters specifying the name of the installed file.

NSA$_INSTALL_FLAGS

NSA$_INSTALL_FLAGS is a longword value specifying the INSTALL flags. They correspond to qualifiers for the Install utility; for example, NSA$M_INS_EXECUTE_ONLY.

NSA$_LNM_PARENT_NAME

NSA$_LNM_PARENT_NAME is a string of 1 to 31 characters specifying the name of the parent logical name table.

NSA$_LNM_TABLE_NAME

NSA$_LNM_TABLE_NAME is a string of 1 to 31 characters specifying the name of the logical name table.

NSA$_LOCAL_USERNAME

NSA$_LOCAL_USERNAME is a string of 1 to 32 characters specifying user names of the accounts available for incoming network proxy requests.

NSA$_LOGICAL_NAME

NSA$_LOGICAL_NAME is a string of 1 to 255 characters specifying the logical name associated with the device.

NSA$_MAILBOX_UNIT

NSA$_MAILBOX_UNIT is a longword value specifying the mailbox unit number.

NSA$_MATCHING_ACE

NSA$_MATCHING_ACE is an array of bytes specifying the ACE granting or denying access.

NSA$_MOUNT_FLAGS

NSA$_MOUNT_FLAGS is a quadword value specifying mount flags that are defined by the $MNTDEF macro in STARLET.

NSA$_NEW_IMAGE_NAME

NSA$_NEW_IMAGE_NAME is a string of 1 to 1024 characters specifying the name of the new image.

NSA$_NEW_OWNER

NSA$_NEW_OWNER is a longword value specifying the new process owner (UIC).

NSA$_NEW_PRIORITY

NSA$_NEW_PRIORITY is a longword value specifying the new process priority.

NSA$_NEW_PRIVILEGES

NSA$_NEW_PRIVILEGES is a quadword privilege mask specifying the new privileges. The $PRVDEF macro defines the list of available privileges.

NSA$_NEW_PROCESS_ID

NSA$_NEW_PROCESS_ID is a longword value specifying the new process identification.

NSA$_NEW_PROCESS_NAME

NSA$_NEW_PROCESS_NAME is a string of 1 to 15 characters specifying the name of the new process.

NSA$_NEW_PROCESS_OWNER

NSA$_NEW_PROCESS_OWNER is a longword value specifying the owner (UIC) of the new process.

NSA$_NEW_USERNAME

NSA$_NEW_USERNAME is a string of 1 to 32 characters specifying the new user name.

NSA$_OBJECT_CLASS

NSA$_OBJECT_CLASS is a string of 1 to 23 characters specifying the security object class associated with the event; for example, FILE.

NSA$_OBJECT_ID

NSA$_OBJECT_ID is an array of three words specifying the unique object identification code, which is currently applicable only to files; therefore, it is the file identification.

NSA$_OBJECT_MAX_CLASS

NSA$_OBJECT_MAX_CLASS is a 20-byte record specifying the maximum access classification of the object.

NSA$_OBJECT_MIN_CLASS

NSA$_OBJECT_MIN_CLASS is a 20-byte record specifying the minimum access classification of the object.

NSA$_OBJECT_NAME

NSA$_OBJECT_NAME is a string of 1 to 255 characters specifying an object's name.

NSA$_OBJECT_NAME_2

NSA$_OBJECT_NAME_2 is a string of 1 to 255 characters specifying an alternate object name; currently it applies to file-backed global sections where the alternate name of a global section is the file name.

NSA$_OBJECT_OWNER

NSA$_OBJECT_OWNER is a longword value specifying the UIC or general identifier of the process causing the auditable event.

NSA$_OBJECT_PROTECTION

NSA$_OBJECT_PROTECTION is a word, or an array of four longwords, specifying the UIC-based protection of the object.

NSA$_OLD_PRIORITY

NSA$_OLD_PRIORITY is a longword value specifying the former process priority.

NSA$_OLD_PRIVILEGES

NSA$_OLD_PRIVILEGES is a quadword privilege mask specifying the former privileges. The $PRVDEF macro defines the list of available privileges.

NSA$_PARAMS_INUSE

NSA$_PARAMS_INUSE is a string of 1 to 255 characters specifying the name of the parameter file given to the SYSGEN command USE.

NSA$_PARAMS_WRITE

NSA$_PARAMS_WRITE is a string of 1 to 255 characters specifying the file name for the SYSGEN command WRITE.

NSA$_PARENT_ID

NSA$_PARENT_ID is a longword value specifying the process identification (PID) of the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_NAME

NSA$_PARENT_NAME is a string of 1 to 15 characters specifying the parent's process name. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_OWNER

NSA$_PARENT_OWNER is longword value specifying the owner (UIC) of the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_USERNAME

NSA$_PARENT_USERNAME is a string of 1 to 32 characters specifying the user name associated with the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PASSWORD

NSA$_PASSWORD is a string of 1 to 32 characters specifying the password used in an unsuccessful break-in attempt. By default, system security alarms do not include break-in passwords.

NSA$_PRIVILEGES

NSA$_PRIVILEGES is a quadword privilege mask specifying the privileges used to gain access. The $PRVDEF macro defines the list of available privileges.

NSA$_PRIVS_MISSING

NSA$_PRIVS_MISSING is a longword or a quadword privilege mask specifying the privileges that are needed. The privileges are defined by a macro in STARLET; see the $CHPDEF macro for definition as a longword mask, and see the $PRVDEF macro for definition as a quadword privilege mask.

NSA$_PRIVS_USED

NSA$_PRIVS_USED is a longword or a quadword privilege mask specifying the privileges used to gain access to the object. The privileges are defined by a macro in STARLET; see the $CHPDEF macro for definition as a longword mask and see the $PRVDEF macro for definition as a quadword privilege mask.

NSA$_PROCESS_ID

NSA$_PROCESS_ID is a longword value specifying the PID of the process causing the auditable event.

NSA$_PROCESS_NAME

NSA$_PROCESS_NAME is a string of 1 to 15 characters specifying the process name that caused the auditable event.

NSA$_REM_ASSOCIATION_NAME

NSA$_REM_ASSOCIATION_NAME is a string of 1 to 256 characters specifying the interprocess communication (IPC) remote association name.

NSA$_REMOTE_LINK_ID

NSA$_REMOTE_LINK_ID is a longword value specifying the remote logical link ID.

NSA$_REMOTE_NODE_FULLNAME

NSA$_REMOTE_NODE_FULLNAME is a string of 1 to 255 characters specifying the fully expanded DECnet for OpenVMS node name of the remote process.

NSA$_REMOTE_NODE_ID

NSA$_REMOTE_NODE_ID is a string of 4 to 24 characters specifying the DECnet for OpenVMS node address of the remote process. A value 4 bytes in length is a DECnet Phase IV node address. A value with length greater than 4 bytes is a DECnet/OSI NSAP address.

NSA$_REMOTE_NODENAME

NSA$_REMOTE_NODENAME is a string of 1 to 6 characters specifying the DECnet for OpenVMS node name of the remote process.

NSA$_REMOTE_USERNAME

NSA$_REMOTE_USERNAME is a string of 1 to 32 characters specifying the user name of the remote process.

NSA$_REQUEST_NUMBER

NSA$_REQUEST_NUMBER is a longword value specifying the request number associated with the system service call.

NSA$_RESOURCE_NAME

NSA$_RESOURCE_NAME is a string of 1 to 32 characters specifying the lock resource name.

NSA$_SECTION_NAME

NSA$_SECTION_NAME is a string of 1 to 42 characters specifying the global section name.

NSA$_SNAPSHOT_BOOTFILE

NSA$_SNAPSHOT_BOOTFILE is a string of 1 to 255 characters specifying the name of the snapshot boot file, the saved system image file from which the system just booted.

NSA$_SNAPSHOT_SAVE_FILNAM

NSA$_SNAPSHOT_SAVE_FILNAM is a string of 1 to 255 characters specifying the name of the snapshot save file, which is the original location of the snapshot file at the time that the system was saved.

NSA$_SNAPSHOT_TIME

NSA$_SNAPSHOT_TIME is a quadword value specifying the time the picture of the configuration was taken and saved in the snapshot boot file.

NSA$_SOURCE_PROCESS_ID

NSA$_SOURCE_PROCESS_ID is a longword value specifying the process identification of the process originating the request.

NSA$_SUBJECT_CLASS

NSA$_SUBJECT_CLASS is a 20-byte record specifying the current access class of the process causing the auditable event.

NSA$_SUBJECT_OWNER

NSA$_SUBJECT_OWNER is a longword value specifying the owner (UIC) of the process causing the event.

NSA$_SYSTEM_ID

NSA$_SYSTEM_ID is a longword value specifying the SCS identification of the cluster node where the event took place (system parameter SCSSYSTEMID).

NSA$_SYSTEM_NAME

NSA$_SYSTEM_NAME is a string of 1 to 6 characters specifying the System Communications Services (SCS) node name where the event took place (system parameter SCSNODE).

NSA$_SYSTEM_SERVICE_NAME

NSA$_SYSTEM_SERVICE_NAME is a string of 1 to 256 characters specifying the name of the system service associated with the event.

NSA$_SYSTIM_NEW

NSA$_SYSTIM_NEW is a quadword value specifying the new system time.

NSA$_SYSTIM_OLD

NSA$_SYSTIM_OLD is a quadword value specifying the old system time.

NSA$_TARGET_DEVICE_NAME

NSA$_TARGET_DEVICE_NAME is a string of 1 to 64 characters specifying the target device name.

NSA$_TARGET_PROCESS_CLASS

NSA$_TARGET_PROCESS_CLASS is a 20-byte record specifying the target process classification.

NSA$_TARGET_PROCESS_ID

NSA$_TARGET_PROCESS_ID is a longword value specifying the target process identifier (PID).

NSA$_TARGET_PROCESS_NAME

NSA$_TARGET_PROCESS_NAME is a string of 1 to 64 characters specifying the target process name.

NSA$_TARGET_PROCESS_OWNER

NSA$_TARGET_PROCESS_OWNER is a longword value specifying the target owner (UIC).

NSA$_TARGET_USERNAME

NSA$_TARGET_USERNAME is a string of 1 to 32 characters specifying the target process user name.

NSA$_TERMINAL

NSA$_TERMINAL is a string of 1 to 256 characters specifying the name of the terminal to which the process was connected when the auditable event occurred.

NSA$_TIME_STAMP

NSA$_TIME_STAMP is a quadword value specifying the time when the event occurred.

NSA$_TRANSPORT_NAME

NSA$_TRANSPORT_NAME is a string of 1 to 256 characters specifying the name of the transport: interprocess communication, DECnet for OpenVMS, or System Management Integrator (SMI), which handles requests from SYSMAN (ASCII string).

NSA$_UAF_ADD

NSA$_UAF_ADD is a string of 1 to 32 characters specifying the name of the authorization record being added.

NSA$_UAF_COPY

NSA$_UAF_COPY is a string of 1 to 32 characters specifying the new name of the authorization record being copied from NSA$_UAF_SOURCE.

NSA$_UAF_DELETE

NSA$_UAF_DELETE is a string of 1 to 32 characters specifying the name of the authorization record being removed.

NSA$_UAF_MODIFY

NSA$_UAF_MODIFY is a string of 1 to 32 characters specifying the name of the authorization record being modified.

NSA$_UAF_RENAME

NSA$_UAF_RENAME is a string of 1 to 32 characters specifying the name of the authorization record being renamed.

NSA$_UAF_SOURCE

NSA$_UAF_SOURCE is a string of 1 to 32 characters specifying the user name of the source record for an Authorize utility (AUTHORIZE) copy operation.

NSA$_USERNAME

NSA$_USERNAME is a string of 1 to 32 characters specifying the user name of the process causing the auditable event.

NSA$_VOLUME_NAME

NSA$_VOLUME_NAME is a string of 1 to 15 characters specifying a volume name.

NSA$_VOLUME_SET_NAME

NSA$_VOLUME_SET_NAME is a string of 1 to 15 characters specifying a volume set name.

Description

The Audit Event service can be called by any program that enforces a security policy to append an event message to the audit log file or send an alarm to an operator terminal. For example, AUTHORIZE calls $AUDIT_EVENT whenever a UAF record is altered, and LOGINOUT calls the service whenever a user logs in.

$AUDIT_EVENT takes the event message, checks the auditing database to determine whether a class of event is being audited, and, if the event class is enabled, creates an alarm or audit record.

$AUDIT_EVENT completes asynchronously; that is, it does not wait for final status. For synchronous completion, use the $AUDIT_EVENTW service.

Required Access or Privileges

AUDIT

Required Quota

None

Related Services

$CHECK_ACCESS, $CHECK_PRIVILEGE, $CHKPRO

Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO A parameter is not accessible.
SS$_BADBUFADR The buffer address is invalid or not readable.
SS$_BADBUFLEN The specified buffer length is invalid or out of range.
SS$_BADCHAIN The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.
SS$_BADITMCOD The specified item code is invalid or out of range.
SS$_EVTNOTENAB The event is not enabled.
SS$_INSFARG A required item code or parameter is missing.
SS$_INVAJLNAM The alarm or audit journal name is invalid.
SS$_IVSTSFLG The specified system service flags are invalid.
SS$_NOAUDIT The caller does not have the required privilege to perform the audit.
SS$_OVRMAXAUD There is insufficient memory to perform the audit.
SS$_SYNCH An audit was not required.

$AUDIT_EVENTW

Determines whether a security-related event should be reported. If the event should be reported, the service sends the event report to the audit server.

The $AUDIT_EVENTW service completes synchronously; that is, it returns only after receiving an explicit confirmation from the audit server that the associated audit, if enabled, has been performed.

For asynchronous completion, use the Audit Event ($AUDIT_EVENT) service. In all other respects, $AUDIT_EVENTW is identical to $AUDIT_EVENT. For additional information about $AUDIT_EVENTW, refer to the $AUDIT_EVENT service.

Format

SYS$AUDIT_EVENTW efn ,[flags] ,itmlst ,audsts ,[astadr] ,[astprm]

C Prototype

int sys$audit_eventw (unsigned int efn, unsigned int flags, void *itmlst, unsigned int *audsts, void (*astadr)(__unknown_params), int astprm);

$AVOID_PREEMPT

Requests that the EXEC avoid preempting the calling process or thread.

Format

SYS$AVOID_PREEMPT enable

C Prototype

int sys$avoid_preempt (int enable);

Arguments

enable


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

Enables or disables preemption avoidance. If the enable argument is set to 1, preemption avoidance is enabled; if 0, preemption avoidance is disabled.

Description

The Avoid Process Preemption service is a caller's mode service that sets a thread-specific bit that informs the scheduler that this thread desires to avoid preemption. Before setting the bit, it checks if the process or thread has already benefited from preemption avoidance during this time on the processor, and if it has, calls the $RESCHED system service to give up the processor.

If quantum end is reached when this bit is set, the scheduler will "borrow" the next quantum for this process or thread. It will give the process or thread another quantum immediately and allow it to resume execution. The next time that the process or thread is eligible for scheduling, it will be placed at the end of the scheduling queue without any execution time, skipping its next quantum.

If another process or thread of the same base priority attempts to preempt a process or thread that has this bit set, this preemption can be avoided if the process had the ALTPRI privilege when the $SETUP_AVOID_PREEMPT service was called. In this case, the priority of the current thread is boosted to the same level as the thread attempting preemption, denying the attempted preemption.

Required Access or Privileges

ALTPRI

Required Quota

None

Related Services

$RESCHED, $SETUP_AVOID_PREEMPT

Condition Values Returned

SS$_NORMAL The service completed successfully.

$BINTIM

Converts an ASCII string to an absolute or delta time value in the system 64-bit time format suitable for input to the Set Timer ($SETIMR) or Schedule Wakeup ($SCHDWK) service.

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

Format

SYS$BINTIM timbuf ,timadr

C Prototype

int sys$bintim (void *timbuf, struct _generic_64 *timadr);

Arguments

timbuf


OpenVMS usage: time_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Buffer that holds the ASCII time to be converted. The timbuf argument specifies the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a character string descriptor pointing to the time string. The time string specifies the absolute or delta time to be converted by $BINTIM. The data type table describes the time string.

timadr


OpenVMS usage: date_time
type: quadword
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)

Time value that $BINTIM has converted. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of the quadword system time, which receives the converted time.

Description

The Convert ASCII String to Binary Time service converts an ASCII string to an absolute or delta time value in the system 64-bit time format suitable for input to the Set Timer ($SETIMR) or Schedule Wakeup ($SCHDWK) service. The service executes at the access mode of the caller and does not check whether address arguments are accessible before it executes. Therefore, an access violation causes an exception condition if the input buffer or buffer descriptor cannot be read or the output buffer cannot be written.

This service does not check the length of the argument list and therefore cannot return the SS$_INSFARG (insufficient arguments) error status code. If the service does not receive enough arguments (for example, if you omit required commas in the call), errors can result.

The required ASCII input strings have the following format:

The following table lists the length (in bytes), contents, and range of values for each field in the absolute time and delta time formats:
Field Length
(Bytes) 		Contents Range of Values
dd 2 Day of month 1--31
-- 1 Hyphen Required syntax
mmm 3 Month JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
-- 1 Hyphen Required syntax
yyyy 4 Year 1858--9999
blank n Blank Required syntax
hh 2 Hour 00--23
: 1 Colon Required syntax
mm 2 Minutes 00--59
: 1 Colon Required syntax
ss 2 Seconds 00--59
. 1 Period Required syntax
cc 2 Hundredths of a second 00--99
dddd 4 Number of days (in 24-hour units) 000--9999

Month abbreviations must be uppercase.

The hundredths-of-second field represents a true fraction. For example, the string .1 represents ten-hundredths of a second (one-tenth of a second) and the string .01 represents one-hundredth of a second. Also, you can add a third digit to the hundredths-of-second field; this thousandths-of-second digit is used to round the hundredths-of-second value. Digits beyond the thousandths-of-second digit are ignored.

The following two syntax rules apply to specifying the ASCII input string: