|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
|||||
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
Creates and initializes a process context that is used by $GETJPI to scan processes on the local system or across the nodes in an OpenVMS Cluster system.On Alpha systems, this service accepts 64-bit addresses.
SYS$PROCESS_SCAN pidctx [,itmlst]
int sys$process_scan (unsigned int *pidctx, void *itmlst);
pidctx
OpenVMS usage: process_id type: longword (unsigned) access: modify mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
Context value supplied by $PROCESS_SCAN to be used as the pidadr argument of $GETJPI. The pidctx argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a longword that is to receive the process context longword. This longword normally contains 0 or a previous context. If it contains a previous context, the old context is deleted. If it contains a value other than 0 or a previous context, the old value is ignored.itmlst
OpenVMS usage: 32-bit item_list_3 or 64-bit item_list_64b type: longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit access: read only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
Item list specifying selection criteria to be used by the scan or to control the scan.The itmlst argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a list of item descriptors, each of which describes one selection criterion or control option. Within each selection criterion you can include several item entries. An item list in 32-bit format is terminated by a longword of 0; an item list in 64-bit format is terminated by a quadword of 0. All items in an item list must be of the same format---either 32-bit or 64-bit.
The information in the item list is passed to the item descriptor in one of two ways. If the item descriptor can always hold the actual value of the selection criterion, the value is placed in the second longword of the item descriptor and the buffer length is specified as 0. If the item descriptor points to the actual value of the selection criterion, the address of the value is placed in the second longword of the item descriptor and you must specify the buffer length for the selection criterion. Each item code description specifies whether the information is passed by value or by reference.
The following diagram depicts the format of a 32-bit item descriptor that passes the selection criterion as a value:
The following diagram depicts the format of a 64-bit item descriptor that passes the selection criterion as a value:
The following diagram depicts the format of a 32-bit item descriptor that passes the selection criterion by reference:
The following diagram depicts the format of a 64-bit item descriptor that passes the selection criterion by reference:
The following table defines the item descriptor fields:
| Descriptor Field | Definition | ||||
|---|---|---|---|---|---|
| Buffer length | Buffer length is specified in a different way for the two types of item descriptors. | ||||
|
|||||
| Item code |
A word containing the selection criterion. These codes are defined by
the $PSCANDEF macro.
Each item code is described after this list of descriptor fields. |
||||
| Item value | A longword containing the actual value of the selection criterion. When you specify an item code that is passed by value, $PROCESS_SCAN searches for the actual value contained in the item list. See the description of the buffer address field for information about item codes that are passed by reference. | ||||
| Buffer address | A longword containing the user-supplied address of the buffer from which $PROCESS_SCAN retrieves information needed by the scan. When you specify an item code that is passed by reference, $PROCESS_SCAN uses the address as a pointer to the actual value. See the description of the item value field for information about item codes that are passed by value. | ||||
| Item-specific flags |
A longword that contains flags to help control selection information.
Item-specific flags, for example EQL or NEQ, are used to specify how
the value specified in the item descriptor is compared to the process
value.
These flags are defined by the $PSCANDEF macro. Some flags are common to multiple item codes; other flags are specific to an individual item code. See the description of each item code to determine which flags are used. For item codes that describe bit masks or character strings, these flags control how the bit mask or character string is compared with that in the process. By default, they are compared for equality. For item codes that describe integers, these flags specify an arithmetic comparison of an integer item with the process attribute. For example, a PSCAN$M_GTR selection specifying the value 4 for the item code PSCAN$_PRIB finds only the processes with a base priority above 4. Without one of these flags, the comparison is for equality. |
||||
| MBO | Must be 1. | ||||
| MBMO | Must be --1. |
Item-Specific Flags Table SYS-48 lists the flags and the item codes that can be used together. The flags are described in the section following the table:PSCAN$_ACCOUNT
When you specify PSCAN$_ACCOUNT, $GETJPI returns information about processes that match the account field.If the string supplied in the item descriptor is shorter than the account field, the string is blank-padded for the comparison unless the item-specific flag PSCAN$M_PREFIX_MATCH is present.
Because the information is a character string, the selection value is passed by reference. The length of the buffer is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
Although the current length of the account field is 8 bytes, the PSCAN$_ACCOUNT buffer can be up to 64 bytes in length. If the buffer length is 0 or greater than 64, the SS$_IVBUFLEN error is returned.
PSCAN$_AUTHPRI
When you specify PSCAN$_AUTHPRI, $GETJPI returns information about processes that match the authorized base priority field.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_CURPRIV
When you specify PSCAN$_CURPRIV, $GETJPI returns information about processes that match the current privilege field. Privilege bits are defined by the $PRVDEF macro.Because the bit mask information is too long to be passed by value, the information is passed by reference. The privilege buffer must be exactly 8 bytes, otherwise the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_GETJPI_BUFFER_SIZE
When you specify PSCAN$_GETJPI_BUFFER_SIZE, you determine the size of a buffer to be used by $GETJPI to process multiple requests in a single message. Using this item code can greatly improve the performance of scans on remote nodes, because fewer messages are needed. This item code is ignored during scans on the local node.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0. The buffer is allocated by $PROCESS_SCAN; you do not have to allocate a buffer.
If you use PSCAN$_GETJPI_BUFFER_SIZE with $PROCESS_SCAN, all calls to $GETJPI using the context established by $PROCESS_SCAN must request the same item code information. Because $GETJPI locates information for more than one process at a time, it is not possible to change the item codes or the length of the buffers used in the $GETJPI item list. $GETJPI checks each call and returns the error SS$_BADPARAM if an attempt is made to change the item list during a buffered process scan; however, the buffer addresses can be changed between $GETJPI calls.
Because the locating and buffering of information by $GETJPI is transparent to a calling program, you are not required to change the way $GETJPI is called when you use this item code.
The $GETJPI buffer uses the process quota BYTLM. If the buffer is too large for the process quota, $GETJPI (not $PROCESS_SCAN) returns the error SS$_EXBYTLM. If the buffer specified is not large enough to contain the data for at least one process, $GETJPI returns the error SS$_BADPARAM.
No item-specific flags are used with PSCAN$_GETJPI_BUFFER_SIZE.
PSCAN$_GRP
When you specify PSCAN$_GRP, $GETJPI returns information about processes that match the UIC group number.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. Because the value of the group number is a word, the high-order word of the value is ignored. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_HW_MODEL
When you specify PSCAN$_HW_MODEL, $GETJPI returns information about processes that match the specified CPU hardware model number.The hardware model number is an integer, such as VAX$K_V8840. The VAX$ symbols are defined by the $VAXDEF macro.
This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_HW_NAME
When you specify PSCAN$_HW_NAME, $GETJPI returns information about processes that match the specified CPU hardware name, such as VAX-11/780, VAX 8800, or VAXstation II/GPX.Because the information is a character string, the selection value is passed by reference. The length of the selection value is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
The PSCAN$_HW_NAME buffer can be up to 128 bytes in length. If the buffer length is 0 or greater than 128, the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_JOBPRCCNT
When you specify PSCAN$_JOBPRCCNT, $GETJPI returns information about processes that match the subprocess count for the job (the count of all subprocesses in the job tree).This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_JOBTYPE
When you specify PSCAN$_JOBTYPE, $GETJPI returns information about processes that match the job type. The job type values include the following:
Value Description JPI$K_LOCAL Local interactive process JPI$K_DIALUP Interactive process accessed by a modem line JPI$K_REMOTE Interactive process accessed by using SET HOST JPI$K_BATCH Batch process JPI$K_NETWORK Noninteractive network process JPI$K_DETACHED Detached process These values are defined by the $JPIDEF macro. Note that values checked by PSCAN$_JOBTYPE are similar to PSCAN$_MODE values.
This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_KT_COUNT
When you specify PSCAN$_KT_COUNT, $PROCESS_SCAN uses the current count of kernel threads for the process as a selection criteria.The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_MASTER_PID
When you specify PSCAN$_MASTER_PID, $GETJPI returns information about processes that are descendants of the specified parent process. The master process is the first process created in the job tree. The PSCAN$_OWNER item is similar, but the owner process is the process that created the target process (the owner process might itself be a subprocess). Although all jobs in a job tree must have the same master, they can have different owners.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_MEM
When you specify PSCAN$_MEM, $GETJPI returns information about processes that match the UIC member number.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. Because the value of the member number is a word, the high-order word of the value is ignored. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_MODE
When you specify PSCAN$_MODE, $GETJPI returns information about processes that match the specified mode. Mode values include the following:
Value Description JPI$K_INTERACTIVE Interactive process JPI$K_BATCH Batch job JPI$K_NETWORK Noninteractive network job JPI$K_OTHER Detached and other process These values are defined by the $JPIDEF macro. Note that values checked by PSCAN$_MODE are similar to PSCAN$_JOBTYPE values.
This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_MULTITHREAD
When you specify PSCAN$_MULTITHREAD, $PROCESS_SCAN uses the maximum count of kernel threads for the process as a selection criteria.The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_NODE_CSID
When you specify PSCAN$_NODE_CSID, $GETJPI returns information about processes on the specified nodes. To scan all nodes in an OpenVMS Cluster system, you specify a CSID of 0 and the item-specific flag PSCAN$M_NEQ.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_NODENAME
When you specify PSCAN$_NODENAME, $GETJPI returns information about processes that match the specified node names.To scan all of the nodes in an OpenVMS Cluster system, specify the node name using an asterisk wildcard (*) and the PSCAN$M_WILDCARD item-specific flag.
Because the information is a character string, the selection value is passed by reference. The length of the selection value is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
Although the current length of the node name is 6 bytes, the PSCAN$_NODENAME buffer can be up to 64 bytes in length. If the buffer length is 0 or greater than 64, the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_OWNER
When you specify PSCAN$_OWNER, $GETJPI returns information about processes that are immediate descendants of the specified process. The PSCAN$_MASTER_PID item is similar, but the owner process is the process that created the target process (the owner process might itself be a subprocess). Although all jobs in a job tree must have the same master, they can have different owners.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_PRCCNT
When you specify PSCAN$_PRCCNT, $GETJPI returns information about processes that match the subprocess count (the count of all immediate descendants of a given process). The PSCAN$_JOBPRCCNT item code is similar, except that JOBPRCCNT is the count of all subprocesses in a job.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_PRCNAM
When you specify PSCAN$_PRCNAM, $GETJPI returns information about processes that match the specified process names.The process name string is blank-padded for the comparison unless the item-specific flag PSCAN$M_PREFIX_MATCH is present.
Because the information is a character string, the selection value is passed by reference. The length of the selection value is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
Although the current length of the process name field is 15 bytes, the PSCAN$_PRCNAM buffer can be up to 64 bytes in length. If the buffer length is 0 or greater than 64, the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_PRI
When you specify PSCAN$_PRI, $GETJPI returns information about processes that match current priority. Note that the current priority of a process can be temporarily increased as a result of system events such as the completion of I/O.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_PRIB
When you specify PSCAN$_PRIB, $GETJPI returns information about processes that match base priority.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_STATE
When you specify PSCAN$_STATE, $GETJPI returns information about processes that match the specified process state. State values, for example SCH$C_COM and SCH$C_PFW, are defined by the $STATEDEF macro.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_STS
When you specify PSCAN$_STS, $GETJPI returns information that matches the current status mask. Without any item-specific flags, the match is for a process mask that is equal to the pattern. Status bits, for example PCB$V_ASTPEN or PCB$V_PSWAPM, are defined by the $PCBDEF macro.This bit mask item code uses an immediate value descriptor; the selection value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_TERMINAL
When you specify PSCAN$_TERMINAL, $GETJPI returns information that matches the specified terminal names. The terminal name string is blank-padded for the comparison unless the item-specific flag PSCAN$M_PREFIX_MATCH is present.Because the information is a character string, the selection value is passed by reference. The length of the selection value is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
Although the current length of the terminal name field is 8 bytes, the PSCAN$_TERMINAL buffer can be up to 64 bytes in length. If the buffer length is 0 or greater than 64, the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_UIC
When you specify PSCAN$_UIC, $GETJPI returns information about processes that match the UIC identifier. To convert an alphanumeric identifier name to the internal identifier, use the $ASCTOID system service before calling $PROCESS_SCAN.This integer item code is passed by value; the value is placed in the second longword of the item descriptor. The buffer length must be specified as 0.
The flags that can be used with this item code are listed in Table SYS-48.
PSCAN$_USERNAME
When you specify PSCAN$_USERNAME, $GETJPI returns information about processes that match the specified user name.The user name string is blank-padded for the comparison unless the item-specific flag PSCAN$M_PREFIX_MATCH is present.
Because the information is a character string, the selection value is passed by reference. The length of the selection value is placed in the first word of the item descriptor and the address of the buffer is placed in the second longword.
Although the current length of the user name field is 12 bytes, the PSCAN$_USERNAME buffer can be up to 64 bytes in length. If the buffer length is 0 or greater than 64, the SS$_IVBUFLEN error is returned.
The flags that can be used with this item code are listed in Table SYS-48.
| Item-Specific Flag | Description | Common to the Following $PROCESS_SCAN Item Codes |
|---|---|---|
| PSCAN$M_BIT_ALL | All bits set in pattern set in target | _CURPRIV |
| PSCAN$M_BIT_ANY | Any bit set in pattern set in target | _STS |
| PSCAN$M_CASE_BLIND | Match without regard to case of letters | _ACCOUNT |
| PSCAN$M_EQL | Match value exactly (the default) |
All except
_BUFFER_SIZE |
| PSCAN$M_GEQ | Match if value is greater than or equal to | _AUTHPRI |
| PSCAN$M_GTR | Match if value is greater than | _GRP |
| PSCAN$M_LEQ | Match if value is less than or equal to | _JOBPRCCNT |
| PSCAN$M_LSS | Match if value is less than | _PRI |
| _PRIB | ||
| PSCAN$M_NEQ | Match if value is not equal |
All except
_BUFFER_SIZE |
| PSCAN$M_OR | Match this value or the next value |
All except
_BUFFER_SIZE |
| PSCAN$M_PREFIX_MATCH | Match on leading substring | _HW_NAME |
| PSCAN$M_WILDCARD | Match a wildcard pattern |
_NODENAME
_PRCNAM _TERMINAL _USERNAME |
PSCAN$M_BIT_ALL
If the PSCAN$M_BIT_ALL flag is used, all bits set in the pattern mask specified by the item descriptor must also be set in the process mask. Other bits in the process mask can also be set.For item codes that describe bit masks, such as privilege masks and status words, this flag controls how the pattern bit mask specified by the item descriptor is compared with that in the process. By default, the bit masks are compared for equality.
The PSCAN$M_BIT_ALL flag is used only with bit masks.
PSCAN$M_BIT_ANY
If the PSCAN$M_BIT_ANY flag is used, a match occurs if any bit in the pattern mask is also set in the process mask.For item codes that describe bit masks, such as privilege masks and status words, this flag controls how the pattern bit mask specified by the item descriptor is compared with that in the process. By default, the bit masks are compared for equality.
The PSCAN$M_BIT_ANY flag is used only with bit masks.
PSCAN$M_CASE_BLIND
When you specify PSCAN$M_CASE_BLIND to compare the character string specified by the item descriptor with the character string value from the process, $PROCESS_SCAN does not distinguish between uppercase and lowercase letters.The PSCAN$M_CASE_BLIND flag is used only with character-string item codes. The PSCAN$M_CASE_BLIND flag can be specified with either the PSCAN$M_PREFIX_MATCH flag or the PSCAN$M_WILDCARD flag.
PSCAN$M_EQL
When you specify PSCAN$M_EQL, $PROCESS_SCAN compares the value specified by the item descriptor with the value from the process to see if there is an exact match.PSCAN$M_EQL and PSCAN$M_NEQ are used with bit masks, character strings, and integers to control how the item is interpreted. Only one of the flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned. If you want to specify that bits not set in the pattern mask must not be set in the process mask, use PSCAN$M_EQL.
PSCAN$M_GEQ
When you specify PSCAN$M_GEQ, $PROCESS_SCAN selects a process if the value from the process is greater than or equal to the value specified by the item descriptor.PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used with integer item codes only. Only one of these four flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned.
PSCAN$M_GTR
When you specify PSCAN$M_GTR, $PROCESS_SCAN selects a process if the value from the process is greater than the value specified by the item descriptor.PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used with integer item codes only. Only one of these four flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned.
PSCAN$M_LEQ
When you specify PSCAN$M_LEQ, $PROCESS_SCAN selects a process if the value from the process is less than or equal to the value specified by the item descriptor.PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used with integer item codes only. Only one of these four flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned.
PSCAN$M_LSS
When you specify PSCAN$M_LSS, $PROCESS_SCAN selects a process if the value from the process is less than the value specified by the item descriptor.PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used with integer item codes only. Only one of these four flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned.
PSCAN$M_NEQ
When you specify PSCAN$M_NEQ, $PROCESS_SCAN selects a process if the value from the process is not equal to the value specified by the item descriptor.PSCAN$M_EQL and PSCAN$M_NEQ are used with bit masks, character strings, and integers to control how the item is interpreted. Only one of the flags can be specified; if more than one of these flags is used, the SS$_BADPARAM error is returned.
PSCAN$M_OR
When you specify PSCAN$M_OR, $PROCESS_SCAN selects processes whose values match the current item descriptor or the next item descriptor. The next item descriptor must have the same item code as the item descriptor with the PSCAN$M_OR flag. Multiple items are chained together; all except the last item descriptor must have the PSCAN$M_OR flag.The PSCAN$M_OR flag can be specified with any other flag and can be used with bit masks, character strings, and integers. If the PSCAN$M_OR flag is used between different item codes, or if it is missing between identical item codes, the SS$_BADPARAM error is returned.
PSCAN$M_PREFIX_MATCH
When you specify PSCAN$M_PREFIX_MATCH, $PROCESS_SCAN compares the character string specified in the item descriptor to the leading characters of the requested process value.For example, to find all process names that start with the letters AB, use the string AB with the PSCAN$M_PREFIX_MATCH flag. If you do not specify the PSCAN$M_PREFIX_MATCH flag, the search looks for a process with the 2-character process name AB.
The PSCAN$M_PREFIX_MATCH flag also allows either the PSCAN$M_EQL or the PSCAN$M_NEQ flag to be specified. If you specify PSCAN$M_NEQ, the service matches those names that do not begin with the specified character string.
The PSCAN$M_PREFIX_MATCH flag is used only with character string item codes. The PSCAN$M_PREFIX_MATCH flag cannot be specified with the PSCAN$M_WILDCARD flag; if both of these flags are used, the SS$_BADPARAM error is returned.
PSCAN$M_WILDCARD
When you specify PSCAN$M_WILDCARD, the character string specified by the item descriptor is assumed to be a wildcard pattern. Acceptable wildcard characters are the asterisk (*), which allows the match to substitute any number of character in place of the asterisk, and the percent sign (%), which allows the match to substitute any one character in place of the percent sign. For example, if you want to search for all process names that begin with the letter A and end with the string ER, use the string A*ER with the PSCAN$M_WILDCARD flag. If the PSCAN$M_WILDCARD flag is not specified, the search looks for the 4-character process name A*ER.The PSCAN$M_WILDCARD is used only with character string item codes. The PSCAN$M_WILDCARD flag cannot be specified with the PSCAN$M_PREFIX_MATCH flag; if both of these flags are used, the SS$_BADPARAM error is returned. The PSCAN$M_NEQ flag can be used with PSCAN$M_WILDCARD to exclude values during a wildcard search.
The following restrictions apply to the flags above:
The Process Scan system service creates and initializes a process context that is used by $GETJPI to scan processes on the local system or across the nodes in an OpenVMS Cluster system. An item list is used to specify selection criteria to obtain information about specific processes, for example, all processes owned by one user or all batch processes.The output of the $PROCESS_SCAN service is a process context longword named pidctx. This process context is then provided to $GETJPI as the pidadr argument. The process context provided by $PROCESS_SCAN enables $GETJPI to search for processes across the nodes in an OpenVMS Cluster system and to select processes that match certain selection criteria.
The process context consumes process dynamic memory. This memory is deallocated when the end of the context is reached. For example, when the $GETJPI service returns SS$_NOMOREPROC or when $PROCESS_SCAN is called again with the same pidctx longword, the dynamic memory is deallocated. If you anticipate that a scan might be interrupted before it runs out of processes, $PROCESS_SCAN should be called a second time (without an itmlst argument) to release the memory. Dynamic memory is automatically released when the current image terminates.
$PROCESS_SCAN copies the item list and user buffers to the allocated dynamic memory. This means that the item lists and user buffers can be deallocated or reused immediately; they are not referenced during the calls to $GETJPI.
The item codes referenced by $PROCESS_SCAN are found in data structures that are always resident in the system, primarily the process control block (PCB) and the job information block (JIB). A scan of processes never forces a process that is swapped out of memory to be brought into memory to read nonresident information.
See the $GETJPI service for a C program example that uses the $PROCESS_SCAN service.
None
See the description for the PSCAN$_GETJPI_BUFFER_SIZE item.
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE
SS$_NORMAL The service completed successfully. SS$_ACCVIO The pidctx argument cannot be written by the caller; the item list cannot be read by the caller; or a buffer for a reference descriptor cannot be read. SS$_BADPARAM The item list contains an invalid item identifier, or an invalid combination of item-specific flags is present. Or, an item list containing both 32-bit and 64-bit item list entries was found. SS$_IVBUFLEN The buffer length field is invalid. For immediate value descriptors, the buffer length must be 0. For reference descriptors, the buffer length cannot be 0 or longer than the maximum for the specified item code. This error is also returned if the total length of the item list plus the length of all of the buffer fields is too large to process. SS$_IVSSRQ The pidctx argument was not supplied, or the item list is improperly formed (for example, multiple occurrences of a given item code were interspersed with other item codes).
Removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment.
SYS$PURGWS inadr
int sys$purgws (struct _va_range *inadr);
inadr
OpenVMS usage: address_range type: longword (unsigned) access: read only mechanism: by reference
Starting and ending virtual addresses of the range of pages to be purged. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. The addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.
The Purge Working Set service removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment; however, the Adjust Working Set Limit ($ADJWSL) service is the preferred mechanism for controlling a process's use of physical memory resources.The $PURGWS service locates pages within the specified range and removes them if they are in the working set.
If the starting and ending virtual addresses are the same, only that single page is purged.
To purge the entire working set, specify a range of pages from 0 through 7FFFFFFF; in this case, the image continues to execute and pages are faulted back into the working set as they are needed. If you exceed this range, the service returns SS$_NOPRIV. On Alpha systems, use the $PURGE_WS service to specify a larger page range.
None
None
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGE_WS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW
SS$_NORMAL The service completed successfully. SS$_ACCVIO The input address array cannot be read by the caller. SS$_NOPRIV A page in the specified range is in the system address space.
On Alpha systems, removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment.This service accepts 64-bit addresses.
SYS$PURGE_WS start_va_64 ,length_64
int sys$purge_ws (void *start_va_64, unsigned __int64 length_64);
start_va_64
OpenVMS usage: address type: quadword address access: read only mechanism: by value
The starting virtual address of the pages to be purged from the working set. The specified virtual address will be rounded down to a CPU-specific page boundary.length_64
OpenVMS usage: byte count type: quadword (unsigned) access: read only mechanism: by value
Length of the virtual address space to be purged from the working set. The specified length will be rounded up to a CPU-specific page boundary so that it includes all CPU-specific pages in the requested range.
The Purge Working Set service removes a specified range of pages from the current working set of the calling process to make room for pages required by a new program segment; however, the Adjust Working Set Limit ($ADJWSL) service is the preferred mechanism for controlling a process's use of physical memory resources.The $PURGE_WS service locates pages within the specified range and removes them if they are in the working set. To purge the entire working set, specify a range of pages from 0 through FFFFFFFF.FFFFFFFF (or to the highest possible process private virtual address, available from $GETJPI); in this case, the image continues to execute, and pages are faulted back into the working set.
None
None
$ADJWSL, $LCKPAG_64, $LKWSET_64, $PURGWS, $ULKPAG_64, $ULWSET_64
SS$_NORMAL The service completed successfully.
The Put service inserts a record into a file.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Writes informational and error messages to processes.On Alpha systems, this service accepts 64-bit addresses.
SYS$PUTMSG msgvec ,[actrtn] ,[facnam] ,[actprm]
int sys$putmsg (void *msgvec, void (*actrtn)(__unknown_params), void *facnam, unsigned __int64 actprm);
msgvec
OpenVMS usage: cntrlblk type: longword (unsigned) access: read only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
Message argument vector specifying the message or messages to be written and options that $PUTMSG is to use in writing the message or messages. The msgvec argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the message vector.The message vector consists of one longword followed by one or more message descriptors, one descriptor per message. The following diagram depicts the contents of the first longword:
The following table describes the message vector fields:
| Descriptor Field | Definition |
|---|---|
| Argument count | This word-length field specifies the total number of longwords in the message vector, not including the first longword (of which it is a part). |
| Default message options | This word-length field specifies which message component or components are to be written. The default message options field is a word-length bit vector wherein a bit, when set, specifies that the corresponding message component is to be written. For a description of each of these components, refer to the Description section. |
The following table shows the significant bit numbers. Note that the bit numbers shown (0, 1, 2, 3) are the bit positions from the beginning of the word; however, because the word is the second word in the longword, you should add the number 16 to each bit number to specify its exact offset within the longword.
| Bit | Value | Description |
|---|---|---|
| 0 |
1
0 |
Include message text
Do not include message text |
| 1 |
1
0 |
Include mnemonic name for message text
Do not include mnemonic name for message text |
| 2 |
1
0 |
Include severity level indicator
Do not include severity level indicator |
| 3 |
1
0 |
Include facility prefix
Do not include facility prefix |
Bits 4 through 15 must be 0.
You can override the default setting specified by the default message options field for any or all messages by specifying different options in the new message options field of any subsequent message descriptor. When you specify new message options, the options it specifies become the new default settings for all remaining messages until you specify new message options again.
The $PUTMSG service passes the default message options field to the $GETMSG service as the flags argument.
If you specify the default message options field as 0, the default message options for the process are used; you can set the process default message options by using the DCL command SET MESSAGE.
The Description section shows the format that $PUTMSG uses to write these message components.
Message Descriptors
Following the first longword of the message vector are one or more message descriptors. A message descriptor can have one of four possible formats, depending on the type of message it describes. There are four types of messages:
The following diagrams depict the message descriptors for each type of message:
Message Descriptor for User-Supplied Messages
| Message Descriptor Field | Definition |
|---|---|
| Message code | Longword value that uniquely identifies the message. The Description section discusses the message code; the OpenVMS Command Definition, Librarian, and Message Utilities Manual explains how to create message codes. |
| FAO parameter count | Word-length value specifying the number of longword $FAO parameters that follow in the message descriptor. The number of $FAO parameters needed depends on the $FAO directives used in the message text; some $FAO directives require one or more parameters, while some directives require none. |
| New message options | Word-length bit vector specifying new message options for the current message. The contents and format of this field are identical to that of the default message options field. |
| FAO parameter | Longword value used by an $FAO directive appearing in the message text. The $FAO parameters listed in the message descriptor must appear in the order in which they will be used by the $FAO directives in the message text. |
Message Descriptor for System Messages
| Message Descriptor Field | Definition |
|---|---|
| Message code | Longword value that uniquely identifies the message. The facility number field in the message code identifies the facility associated with the message. A system message has a facility number of 0. You cannot specify the FAO parameter count, new message options, and FAO parameter fields. Each longword following the message identification field in the message vector will be interpreted as another message identification. |
Message Descriptor for OpenVMS RMS Messages
| Message Descriptor Field | Definition |
|---|---|
| Message code | Longword value that uniquely identifies the message. The facility number field in the message code identifies the facility associated with the message. An OpenVMS RMS message has a facility number of 1. You cannot specify the FAO parameter count, new message options, and FAO parameter fields. The longword following the message identification field in the message vector will be interpreted as a standard value field (STV). |
| RMS status value | Longword containing an STV for use by an RMS message that has an associated STV value. The $PUTMSG service uses the STV value as an $FAO parameter or as another message identification, depending on the RMS message identified by the message identification field. If the RMS message does not have an associated STV, $PUTMSG ignores the STV longword in the message descriptor. |
Message Descriptor for System Exception Messages
| Message Descriptor Field | Definition |
|---|---|
| Message code |
Longword value that uniquely identifies the message. The facility
number field in the message code identifies the facility associated
with the message. A system exception message has a facility number of 0.
You cannot specify the FAO parameter count and new message options fields. The longword or longwords following the message code field in the message vector will be interpreted as $FAO parameters. |
On Alpha systems, 64-bit message vectors can be used for applications that require them. A 64-bit message vector begins with the same argument count longword as the 32-bit message vector. After the argument count longword is another longword containing the value SS$_SIGNAL64, which signals that a 64-bit message vector follows. Subsequent message vector elements have a layout analogous to 32-bit message vectors but are 64-bits wide.
For example, the following diagram depicts the format of a 32-bit message vector:
The 64-bit version of that same message vector would have the following format:
The $PUTMSG service accepts either the 32-bit or the 64-bit form of the message vector on Alpha systems.
| OpenVMS usage: | procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by 32- or 64-bit reference (Alpha) |
| mechanism: | by 32-bit reference (VAX) |
Note that the first argument passed to the action routine is the address of a character string descriptor pointing to the message text; the parameter specified by actprm is the second.
The action routine receives control after a message is formatted but before it is actually written to the user.
The completion code in general register R0 from the action routine indicates whether the message should be written. If the low-order bit of R0 is set (1), then the message will be written. If the low-order bit is cleared (0), then the message will not be written.
If you do not specify actrtn or specify it as 0 (the default), no action routine executes.
Because $PUTMSG writes messages only to SYS$ERROR and SYS$OUTPUT, an action routine is useful when output must be directed to, for example, a file.
| OpenVMS usage: | char_string |
| 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) |
If you do not specify facnam, $PUTMSG uses the default facility prefix associated with the message.
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
In the operating system, a message is identified by a longword value, which is called the message code. To construct a message code, you specify values for its four fields, using the Message utility. The following diagram depicts the longword message code:
Thus, each message has a unique longword value associated with it: its message code. You can give this longword value a symbolic name using the Message utility. Such a symbolic name is called the message symbol.
The Message utility describes how to construct a message symbol according to the conventions for operating system messages. Basically, the message symbol has two parts: (1) a facility prefix, which is an abbreviation of the name of the facility with which the message is associated, and (2) a mnemonic name for the message text, which serves to hint at the nature of the message. These two parts are separated by an underscore character (_) in the case of a user-constructed message and by a dollar sign/underscore ($_) in the case of system messages.
The message components written by $PUTMSG are derived both from the message code and from the message symbol. For additional information about both the message code and the message symbol, refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual.
The $PUTMSG service writes the message components in the following format:
|
%FACILITY-L-IDENT, message text |
where:
| % | Is the prefix used for the first message written. The hyphen (-) is the prefix used for the remaining messages. |
| FACILITY | Is the facility prefix taken from the message symbol. This facility prefix can be overridden by a facility prefix specified in the facnam argument in the call to $PUTMSG. |
| L | Is the severity level indicator. The severity level indicator is taken from the message code. |
| IDENT | Is a mnemonic name for the message text, taken from the message symbol. |
| message text | Is the message text specified in the message source file. |
The $PUTMSG service does not check the length of the argument list and therefore cannot return the SS$_INSFARG (insufficient arguments) condition value. Be sure you specify the required number of arguments.
If an error occurs while $PUTMSG calls the Formatted ASCII Output ($FAO) service, $FAO parameters specified in the message vector do not appear in the output.
You cannot call the $PUTMSG service from kernel mode.
None
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
SS$_NORMAL The service completed successfully.
#include <ssdef.h>
#include <rmsdef.h>
#include <starlet.h>
main()
{
int msgvec[] = {3, /* Arg count and message flags */
SS$_ABORT, /* Message code */
RMS$_FNF, /* RMS Message code */
0}; /* RMS Status value */
return (sys$putmsg(msgvec)); /* Generate message */
}
|
Queues an I/O request to a channel associated with a device. This service completes asynchronously; for synchronous completion, use the Queue I/O Request and Wait ($QIOW) service.For additional information about system service completion, refer to the Synchronize ($SYNCH) service.
On Alpha systems, this service accepts 64-bit addresses.
SYS$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
int sys$qio (unsigned int efn, unsigned short int chan, unsigned int func, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5, __int64 p6);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Event flag that $QIO is to set when the I/O operation completes. The efn argument is a longword value containing the number of the event flag; however, $QIO uses only the low-order byte.If you do not specify efn, event flag 0 is used.
When $QIO begins execution, it clears the specified event flag or event flag 0 if efn was not specified.
The specified event flag is set if the service terminates without queuing an I/O request.
chan
OpenVMS usage: channel type: longword (unsigned) access: read only mechanism: by value
I/O channel assigned to the device to which the request is directed. The chan argument is a longword value containing the number of the I/O channel; however, $QIO uses only the low-order word.Specifying an invalid value for the chan argument will result in either SS$_IVCHAN or SS$_IVIDENT being returned.
func
OpenVMS usage: function_code type: longword (unsigned) access: read only mechanism: by value
Device-specific function codes and function modifiers specifying the operation to be performed. The func argument is a longword containing the function code.Each device has its own function codes and function modifiers. For complete information about the function codes and function modifiers that apply to the particular device to which the I/O operation is to be directed, refer to the HP OpenVMS I/O User's Reference Manual.
iosb
OpenVMS usage: io_status_block type: quadword (unsigned) access: write only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
I/O status block to receive the final completion status of the I/O operation. The iosb argument is the address of the quadword I/O status block. The following diagram depicts the structure of the I/O status block.
The following table defines the I/O status block fields.
| Status Block Field | Definition |
|---|---|
| Condition value | Word-length condition value that $QIO returns when the I/O operation actually completes. |
| Transfer count | Number of bytes of data transferred in the I/O operation. For information about how specific devices handle this field of the I/O status block, refer to the HP OpenVMS I/O User's Reference Manual. |
| Device-specific information | Contents of this field vary depending on the specific device and on the specified function code. For information on how specific devices handle this field of the I/O status block, refer to the HP OpenVMS I/O User's Reference Manual. |
When $QIO begins execution, it clears the quadword I/O status block if the iosb argument is specified.
Though this argument is optional, HP strongly recommends that you specify it, for the following reasons:
| OpenVMS usage: | ast_procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by 32- or 64-bit reference (Alpha) |
| mechanism: | by 32-bit reference (VAX) |
The AST routine executes at the access mode of the caller of $QIO.
| OpenVMS usage: | user_arg |
| type: | quadword unsigned (Alpha); longword unsigned (VAX) |
| access: | read only |
| mechanism: | by 64-bit value (Alpha) |
| mechanism: | by 32-bit value (VAX) |
| OpenVMS usage: | varying_arg |
| type: | quadword (unsigned) (Alpha); longword unsigned (VAX) |
| access: | read only |
| mechanism: | by 32- or 64-bit reference or by 64-bit value depending on the I/O function (Alpha) |
| mechanism: | by 32-bit reference or by 32-bit value depending on the I/O function (VAX) |
For more information about these parameters, refer to the HP OpenVMS I/O User's Reference Manual.
The Queue I/O Request service operates only on assigned I/O channels and only from access modes that are equal to or more privileged than the access mode from which the original channel assignment was made.The $QIO service uses system dynamic memory to construct a database to queue the I/O request and might require additional memory depending on the queued device.
For $QIO, you can synchronize completion (1) by specifying the astadr argument to have an AST routine execute when the I/O completes or (2) by calling the Synchronize ($SYNCH) service to await completion of the I/O operation. The $QIOW service completes synchronously, and it is the best choice when synchronous completion is required.
For information about how to use the $QIO service for network operations, refer to the DECnet for OpenVMS Networking Manual.
LOG_IO or PHY_IO is required, depending upon the device type and the requested operation. DIAGNOSE is required to issue a $QIO with an associated diagnostic buffer. In addition, read or write access is generally required for the device. For more information, refer to the HP OpenVMS Guide to System Security.
The $QIO service uses the following quotas:
- The process's quota for buffered I/O limit (BIOLM) or direct I/O limit (DIOLM)
- The process's buffered I/O byte count (BYTLM) quota
- The process's AST limit (ASTLM) quota, if an AST service routine is specified
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR, $IO_CLEANUP, $IO_PERFORM, $IO_SETUP
SS$_NORMAL The service completed successfully. The I/O request was successfully queued. SS$_ABORT A network logical link was broken. SS$_ACCVIO Either the I/O status block cannot be written by the caller, or the parameters for device-dependent function codes are specified incorrectly. SS$_CONNECFAIL The connection to a network object timed out or failed. SS$_DEVOFFLINE The specified device is off line and not currently available for use. SS$_EXQUOTA The process has (1) exceeded its AST limit (ASTLM) quota, (2) exceeded its buffered I/O byte count (BYTLM) quota, (3) exceeded its buffered I/O limit (BIOLM) quota, (4) exceeded its direct I/O limit (DIOLM) quota, or (5) requested a buffered I/O transfer smaller than the buffered byte count quota limit (BYTLM), but when added to other current buffer requests, the buffered I/O byte count quota was exceeded. SS$_FILALRACC A logical link is already accessed on the channel (that is, a previous connect on the channel). SS$_ILLEFC You specified an illegal event flag number. SS$_INSFMEM The system dynamic memory is insufficient for completing the service. SS$_INVLOGIN The access control information was invalid at the remote node. SS$_IVCHAN You specified an invalid channel number, that is, a channel number of 0, or you failed to specify a channel number. SS$_IVIDENT You specified a channel number greater than the number of channels assigned for the process. SS$_IVDEVNAM The NCB has an invalid format or content. SS$_LINKABORT The network partner task aborted the logical link. SS$_LINKDISCON The network partner task disconnected the logical link. SS$_LINKEXIT The network partner task was started, but exited before confirming the logical link (that is, $ASSIGN to SYS$NET). SS$_NOLINKS No logical links are available. The maximum number of logical links as set for the executor MAXIMUM LINKS parameter was exceeded. SS$_NOPRIV The specified channel does not exist or was assigned from a more privileged access mode, or the process does not have the necessary privileges to perform the specified functions on the device associated with the specified channel. SS$_NOSUCHNODE The specified node is unknown. SS$_NOSUCHOBJ The network object number is unknown at the remote node; or for a TASK= connect, the named DCL command procedure file cannot be found at the remote node. SS$_NOSUCHUSER The remote node could not recognize the login information supplied with the connection request. SS$_NOT64DEVFUNC On Alpha systems, this fatal condition value is returned under the following circumstances: (1) The caller has specified a 64-bit virtual address in the P1 device dependent parameter but the device driver does not support 64-bit addresses with the requested I/O function. (2) The caller has specified a 64-bit address for a diagnostic buffer but the device driver does not support 64-bit addresses for diagnostic buffers. (3) Some device drivers might also return this condition value when 64-bit buffer addresses are passed using the P2 through P6 parameters and the driver does not support a 64-bit address with the requested I/O function. SS$_PATHLOST The path to the network partner task node was lost. SS$_PROTOCOL A network protocol error occurred. This error is most likely due to a network software error. SS$_REJECT The network object rejected the connection. SS$_REMRSRC The link could not be established because system resources at the remote node were insufficient. SS$_SHUT The local or remote node is no longer accepting connections. SS$_THIRDPARTY The logical link was terminated by a third party (for example, the system manager). SS$_TOOMUCHDATA The task specified too much optional or interrupt data. SS$_UNASEFC The process is not associated with the cluster containing the specified event flag. SS$_UNREACHABLE The remote node is currently unreachable.
Device-specific condition values; the HP OpenVMS I/O User's Reference Manual lists these condition values for each device.
The Queue I/O Request and Wait service queues an I/O request to a channel associated with a device.The $QIOW service completes synchronously; however, Digital recommends that you use an IOSB with this service to avoid premature completion.
For asynchronous completion, use the Queue I/O Request ($QIO) service.
In all other respects, $QIOW is identical to $QIO. For more information about $QIOW, refer to the description of $QIO.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.
On Alpha systems, this service accepts 64-bit addresses.
SYS$QIOW [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
int sys$qiow (unsigned int efn, unsigned short int chan, unsigned int func, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5, __int64 p6);
The Read service retrieves a specified number of bytes from a file (beginning on a block boundary) and transfers them to memory. A Read service using block I/O can be performed on any file organization.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Returns the current status of all 32 event flags in a local or common event flag cluster and indicates whether the specified event flag is set or clear.On Alpha systems, this service accepts 64-bit addresses.
SYS$READEF efn ,state
int sys$readef (unsigned int efn, unsigned int *state);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of any event flag in the cluster whose status is to be returned. The efn argument is a longword containing this number; however, $READEF uses only the low-order byte. Specifying an event flag within a cluster requests that $READEF return the status of all event flags in that cluster.There are two local event flag clusters, which are local to the process: cluster 0 and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1 contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127.
state
OpenVMS usage: mask_longword type: longword (unsigned) access: write only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
State of all event flags in the specified cluster. The state argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword into which $READEF writes the state (set or clear) of the 32 event flags in the cluster.
SS$_WASCLR The service completed successfully. The specified event flag is clear. Note that this is also the same value as SS$_NORMAL. SS$_WASSET The service completed successfully. The specified event flag is set. Note that while the message id is the same as SS$_ACCVIO, the severity bits are different. SS$_ACCVIO The longword that is to receive the current state of all event flags in the cluster cannot be written by the caller. SS$_ILLEFC You specified an illegal event flag number. SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.
Interface to the OpenVMS Registry database server.The $REGISTRY service allows you to query, update, and set keys, subkeys, and values in the OpenVMS Registry database.
The $REGISTRY service supports both asynchronous and synchronous operations. For asynchronous completion, use the Registry ($REGISTRY) system service.
For synchronous completion, use the Registry and Wait ($REGISTRYW) system service. The $REGISTRYW system service is identical to the $REGISTRY system service, except that $REGISTRYW returns to the caller after the system completes the requested operation. For additional information about system service completion, see the Synchronize ($SYNCH) system service.
This system service is 64-bit compatible.
SYS$REGISTRY [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or astadr_64] [,astprm or astprm_64] [,timeout]
int sys$registry (unsigned int efn, unsigned int func, void *, void *itmlst, struct _iosb *iosb, ...);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of the event flag to be used by $REGISTRY. If you do not specify the event flag, the system defaults to event flag 0. The event flag is initially cleared by $REGISTRY and then set when the operation completes.func
OpenVMS usage: function_code type: longword (unsigned) access: read only mechanism: by value
Function code specifying the action that $REGISTRY is to perform. The func argument is a longword containing this function code. The function code can contain function modifiers. For more information on function modifiers, see the Function Modifiers section.A single call to $REGISTRY can specify only one function code. All function codes require additional information to be passed in the call with the itmlst argument.
itmlst
OpenVMS usage: 32-bit item_list_3 or 64-bit item_list_64b type: longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit access: read only mechanism: by 32- or 64-bit reference
Item list supplying information that the system will use to perform the function specified by the func argument.The itmlst argument is the address of the item list. The item list consists of one or more sets of item descriptors. Each descriptor is either an item_list_3 or item_list_64b format.
Some function codes allow you to specify multiple operations in a single call. In this case, you must place the REG$_SEPARATOR item code between each set of item codes. Each request, separated by a REG$_SEPARATOR item code, can contain the item codes in any order.
You can specify item codes as either input or output parameters. Input parameters modify functions, set context, or describe the information to be returned. Output parameters return the requested information.
For item_list_3 lists, you must terminate the list with a longword of 0. For item_list_64b lists, you must terminate the list with a quadword of 0.
The following diagram shows the structure of an item_list_3 descriptor:
The following diagram shows the structure of an item_list_64b descriptor:
The following table defines the item descriptor fields:
| Descriptor Field | Definition |
|---|---|
| Buffer length | A word that specifies the length of the buffer. The buffer either supplies information to be used by $REGISTRY, or receives information from $REGISTRY. The required length of the buffer varies, depending on the item code specified. Each item code description specifies the required length. |
| Item code | A word containing a symbolic code that describes the type of information currently in the buffer or that is returned in the buffer. The buffer address field points to the location of the buffer. |
| Buffer address | A longword that contains the address of the buffer that specifies or receives the information. |
| Return length address | A longword that contains the address of a word that specifies the actual length in bytes of the information returned by $REGISTRY. The information resides in a buffer identified by the buffer address field. The field applies to output item list entries only, and must be 0 (zero) for input entries. If the return length address is 0, it is ignored. |
| OpenVMS usage: | status_block |
| type: | buffer |
| access: | write only |
| mechanism: | by reference |
If multiple operations are requested for a function code, the value returned in iosb is either SS$_NORMAL or SS$_REGERROR.
A more specific return status for each operation is returned in the REG$_RETURNSTATUS item code (if specified).
The iosb argument is the address of the $REGISTRY status block:
When $REGISTRY begins execution, it clears the quadword I/O status block if you specify the iosb argument.
Although the iosb argument is optional, HP strongly recommends that you specify it for the following reasons:
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $REGISTRY service. The condition value returned in R0 provides information about the success or failure of the service call itself; the condition value returned in the I/O status block provides information about the success or failure of the service operation.
To assess the success or failure of the call to $REGISTRY accurately, you must first check the condition value returned in R0. If R0 contains a successful value, you must check the condition value in the I/O status block.
The following table defines the item descriptor fields:
| Descriptor Field | Definition |
|---|---|
| Status | A longword specifying the final status of the $REGISTRY service. If you request multiple operations for a function code, the system returns either SS$_NORMAL or SS$_REGERROR to iosb. This field is set to 0 (zero) when the operation begins. |
| Reserved | A reserved longword. |
| OpenVMS usage: | ast_procedure |
| type: | procedure value |
| access: | call without stack unwinding |
| mechanism: | by reference |
If the $REGISTRY service is not called successfully (that is, if it returns an error immediately), the AST routine is not executed.
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
You can find a detailed description of each item code in the Item Codes section.
The OpenVMS Registry identifier is required only if you do not provide a valid NT access token and you do not have the SYSPRV privilege. If you have a granted REG$UPDATE identifier, you can perform all the functions in Table SYS-49.
| Function Code | Identifier | Description |
|---|---|---|
| REG$FC_CLOSE_KEY | REG$LOOKUP | Closes an open key or subkey. |
| REG$FC_CREATE_KEY | REG$UPDATE | Creates (and opens) a subkey. |
| REG$FC_DELETE_KEY | REG$UPDATE | Removes a subkey from a key. |
| REG$FC_DELETE_VALUE | REG$UPDATE | Removes a value from a key. |
| REG$FC_ENUM_KEY | REG$LOOKUP | Lists (enumerates) the subkeys of a key. |
| REG$FC_ENUM_VALUE | REG$LOOKUP | Lists (enumerates) the values of a key. |
| REG$FC_FLUSH_KEY | REG$UPDATE | Ensures that all information for the key is backed to disk. |
| REG$FC_MODIFY_KEY | REG$UPDATE | Modifies a key. |
| REG$FC_MODIFY_TREE_KEY | REG$UPDATE | Modifies a key and all its subkeys. |
| REG$FC_NOTIFY_CHANGE_KEY_VALUE | REG$UPDATE | Notifies when a key or value has changed. |
| REG$FC_OPEN_KEY | REG$LOOKUP | Opens a key or subkey. |
| REG$FC_QUERY_KEY | REG$LOOKUP | Fetches information about a key. |
| REG$FC_QUERY_VALUE | REG$LOOKUP | Fetches information about a value. |
| REG$FC_SEARCH_TREE_DATA | REG$LOOKUP | Searches the value data of key and its subkeys. |
| REG$FC_SEARCH_TREE_KEY | REG$LOOKUP | Searches the names of a key and its subkeys. |
| REG$FC_SEARCH_TREE_VALUE | REG$LOOKUP | Searches the values of a key and its subkeys. |
| REG$FC_SET_VALUE | REG$UPDATE | Changes the data associated with a value name. |
Item Codes Table SYS-50 provides a summary of item codes that are valid as an item descriptor in the itmlst argument. The table lists the item codes, input/output usage, and data types.REG$FC_CLOSE_KEY
This request releases the open resources of the specified key. If REG$_KEYID indicates a predefined key, the system ignores the action and returns success.Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_RETURNSTATUS No Output REG$FC_CREATE_KEY
If the key does not exist, this request creates a new subkey under the key specified by REG$_KEYID. If the key does exist, the system does not modify it.If you specify the REG$_KEYRESULT item code, the system opens the specified subkey.
The system returns the result in the REG$_DISPOSITION item code buffer.
Using this function code, you can group multiple requests into a single call to the $REGISTRY service. To use the multiple-request feature, you must use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
To set a value for a key, call the $REGISTRY service with the REG$FC_SET_VALUE function code.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_DISPOSITION No Output REG$_KEYID Yes Input REG$_KEYRESULT No Output REG$_LINKPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Input REG$_RETURNSTATUS No Output REG$_SECACCESS No Input REG$_SECURITYPOLICY No Input REG$_SEPARATOR No n/a REG$_SUBKEYNAME Yes Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_VOLATILE No Input If you specify the REG$_LINKPATH item code, it must point to a key path already defined in the OpenVMS Registry; otherwise the system returns the REG$_INVALIDPATH error.
Note
If you do not specify the REG$_CACHEACTION item code, the new key is created with the same cache action value as the parent key. The same rule applies to the REG$_VOLATILE and REG$_SECURITYPOLICY item codes.REG$FC_DELETE_KEY
This request removes the specified subkey and its values from the OpenVMS Registry database. If the specified key has subkeys, the key is not deleted. You must delete the subkeys first.Using this function code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_SUBKEYNAME Yes Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$FC_DELETE_VALUE
This request deletes the specified value from the key.Using this function code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_VALUENAME Yes Input REG$FC_ENUM_KEY
This request retrieves information about one subkey of the key. You identify the subkey in the REG$_SUBKEYINDEX item code.To enumerate all the key's subkeys, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_KEY function code. Begin with a REG$_SUBKEYINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Output REG$_CLASSNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LASTWRITE No Output REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Output REG$_SUBKEYINDEX Yes Input REG$_SUBKEYNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_VOLATILE No Output REG$FC_ENUM_VALUE
This request retrieves information about a value of the specified key identifier. The value to retrieve is identified in the REG$_VALUEINDEX item code.To enumerate all a key's values, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_VALUE function code. Begin with a REG$_VALUEINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Output REG$_DATATYPE No Output REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_VALUEDATA No Output REG$_VALUEDATASIZE No Output REG$_VALUEINDEX Yes Input REG$_VALUENAME No Output REG$_VOLATILE No Output REG$FC_FLUSH_KEY
This request writes all the information about a specified key to disk.This request returns only after the operation is complete and all attributes of the key have been written to the OpenVMS Registry database.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$FC_MODIFY_KEY
This request modifies a specified key's attributes.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Input REG$_NEWNAME No Input REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Input To remove the link from the specified key, enter a REG$_LINKPATH item code with an address of zero. You cannot add a link to a key that has either values or subkeys (or both).
REG$FC_MODIFY_TREE_KEY
This request modifies a specified key and all its subkey attributes. No link will be followed or modified.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Input REG$_CLASSNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Input REG$FC_NOTIFY_CHANGE_KEY_VALUE
This request notifies the calling process when a specified key or any of its subkeys has changed. That is, the requested function waits for the specified condition before returning.Specify the item codes as follows:
Item Code Required Parameter Type REG$_FLAGSUBKEY Yes Input REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_NOTIFYFILTER Yes Input REG$_RETURNSTATUS No Output REG$FC_OPEN_KEY
This request opens the specified key. If you do not specify a subkey, the system opens the key specified in REG$_KEYID.If REG$_KEYID specifies a key other than a predefined key, the system opens the key again (duplicates the key).
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYRESULT Yes Output REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_RETURNSTATUS No Output REG$_SECACCESS Yes Input REG$_SUBKEYNAME No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$FC_QUERY_KEY
This request retrieves attributes about a specified key.Specify the item codes as follows:
Item Code Required Parameter Type REG$_CACHEACTION No Output REG$_CLASSNAME No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_CLASSNAMEMAX No Output REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LASTWRITE No Output REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SECURITYPOLICY No Output REG$_SUBKEYNAMEMAX No Output REG$_SUBKEYSNUMBER Yes Output REG$_VALUEDATAMAX No Output REG$_VALUENAMEMAX No Output REG$_VALUENUMBER No Output REG$_VOLATILE No Output REG$FC_QUERY_VALUE
This request retrieves the type, data flags, and data for the specified value name.Using this function code, you can group multiple requests into a single call to the $REGISTRY service.
If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Output REG$_DATATYPE No Output REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_LINKCOUNT No Output REG$_LINKPATH No Output (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Output REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_VALUEDATA No Output REG$_VALUEDATASIZE No Output REG$_VALUENAME Yes Input REG$_VOLATILE No Output REG$FC_SEARCH_TREE_DATA
This request scans a specified key and all its descendants for a match with a specified set of data information.The set of data information can be either the REG$_DATAFLAGS item code, or the pair REG$_DATATYPE and REG$_VALUEDATA item codes, or all three item codes.
The REG$_FLAGOPCODE item code specifies how the REG$_DATAFLAGS item code should be matched against the database. (See the item codes description for more information about the REG$_FLAGOPCODE item code.)
Every time the system finds a match, it appends the path name relative to the specified key to the REG$_PATHBUFFER item code. A Unicode null character is used to separate the value path names.
If the buffer supplied by the application is not big enough to hold all the value path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the length required to complete the operation successfully is returned in the REG$_REQLENGTH item (if specified).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code.
(For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.)
Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.
Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Input REG$_DATATYPE No Input REG$_FLAGOPCODE No Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_PATHBUFFER Yes Output REG$_REQLENGTH No Output REG$_RETURNSTATUS No Output REG$_VALUEDATA No Input REG$FC_SEARCH_TREE_KEY
This request scans a specified key and all its descendants for a specified key path.For this function code, a valid key path is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but that cannot start with the backslash character (\).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.)
Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.
Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
An example of a valid key path is as follows:
hardware\system\*\disk%%Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.
If the buffer supplied by the application is not big enough to contain all the subkey path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the system returns the required length to complete the operation successfully in the REG$_REQLENGTH item (if specified).
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_PATHBUFFER Yes Output REG$_REQLENGTH No Output REG$_RETURNSTATUS No Output REG$FC_SEARCH_TREE_VALUE
This request scans a specified key and all its descendants for a specified value name.For this function code a valid key name is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but cannot start with the backslash character (\).
Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, Hardware\...\disks finds all the paths that start with the Hardware subkey and end with the disk subkey, with zero or more subkeys in between.)
Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.
Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.
An example of a valid key path is as follows:
hardware\system\...For this function code, a valid name is a Unicode string that can include the asterisk (*) and percent (%) wildcard characters.
Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.
If the buffer supplied by the application is not big enough to contain all the subkey path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the system returns the required length to complete the operation successfully in the REG$_REQLENGTH item (if specified).
Specify the item codes as follows:
Item Code Required Parameter Type REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_KEYID Yes Input REG$_PATHBUFFER Yes Output REG$_REQLENGTH No Output REG$_RETURNSTATUS No Output REG$_VALUENAME Yes Input REG$FC_SET_VALUE
This request sets value and type information for a specified key.Using this function code, you can group multiple requests into a single call to the $REGISTRY service.
If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
When a value is set to a link, the system validates the link unless you specify the REG$M_IGNORE_LINKS function code modifier.
Specify the item codes as follows:
Item Code Required Parameter Type REG$_DATAFLAGS No Input REG$_DATATYPE No Input REG$_KEYID Yes Input REG$_KEYPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKPATH No Input (Pointer to Unicode string. Unicode character is 4 bytes long.) REG$_LINKTYPE No Input REG$_RETURNSTATUS No Output REG$_SEPARATOR No n/a REG$_VALUEDATA No Input REG$_VALUENAME No Input
Complete descriptions of each item code are provided in the sections that follow this table.
| Item Code | Input/Output | Data Type |
|---|---|---|
| REG$_CACHEACTION | Input, output | Longword |
| REG$_CLASSNAME | Input, output | (Pointer to Unicode string. Unicode character is 4 bytes long.) |
| REG$_CLASSNAMEMAX | Output | Longword |
| REG$_DATAFLAGS | Input, output | Quadword |
| REG$_DATATYPE | Input, output | Longword |
| REG$_DISPOSITION | Output | Longword |
| REG$_FLAGOPCODE | Input | Longword |
| REG$_FLAGSUBKEY | Input | Longword |
| REG$_KEYID | Input, output | Longword |
| REG$_KEYPATH | Input | (Pointer to Unicode string. Unicode character is 4 bytes long.) |
| REG$_KEYRESULT | Output | Longword |
| REG$_LASTWRITE | Output | Quadword |
| REG$_LINKCOUNT | Output | Longword |
| REG$_LINKPATH | Input, output | (Pointer to Unicode string. Unicode character is 4 bytes long.) |
| REG$_LINKTYPE | Input, output | Longword |
| REG$_NEWNAME | Input | Unicode string |
| REG$_NOTIFYFILTER | Input | Longword |
| REG$_PATHBUFFER | Output | Buffer |
| REG$_REQLENGTH | Output | Longword |
| REG$_RETURNSTATUS | Output | Longword |
| REG$_SECACCESS | Input | Longword |
| REG$_SECURITYPOLICY | Input, output | Longword |
| REG$_SEPARATOR | n/a | None |
| REG$_SUBKEYINDEX | Input | Longword |
| REG$_SUBKEYNAME | Input, output | (Pointer to Unicode string. Unicode character is 4 bytes long.) |
| REG$_SUBKEYNAMEMAX | Output | Longword |
| REG$_SUBKEYSNUMBER | Output | Longword |
| REG$_VALUEDATA | Input, output | Buffer |
| REG$_VALUEDATAMAX | Output | Longword |
| REG$_VALUEDATASIZE | Output | Longword |
| REG$_VALUEINDEX | Input | Longword |
| REG$_VALUENAME | Input, output | Unicode string |
| REG$_VALUENAMEMAX | Output | Longword |
| REG$_VALUENUMBER | Output | Longword |
| REG$_VOLATILE | Input, output | Longword |
Function Modifiers You can optionally specify the high-order bits of a function code value with function modifiers. These individual bits can alter the operation of the function.REG$_CACHEACTION
The REG$_CACHEACTION item code is an input item code. It is a longword flag that specifies whether the information on a specified object should be written to disk immediately. It takes one of the following values:
Cache Value Description REG$K_WRITEBEHIND Write information about the specified object written to disk at a later time (default). REG$K_WRITETHRU Write information about the specified object to disk immediately.
Note
If you do not specify this item code, the value or key inherits its value from the parent object. By default, the entry points (REG$_HKEY_CLASSES_ROOT, REG$_HKEY_LOCAL_MACHINE, and REG$_HKEY_USERS) are set with a value equal to that of REG$K_WRITEBEHIND.REG$_CLASSNAME
The REG$_CLASSNAME item code is, depending on the function code, either an input or output item code.The class name is an information field for a key. The type of an object is an example of a class name. It can be composed of any string of Unicode characters. A Unicode character is 4 bytes long.
REG$_CLASSNAMEMAX
The REG$_CLASSNAMEMAX item code is an output item code. It receives the length, in bytes, of the longest string specifying a subkey class name.REG$_DATAFLAGS
Depending on the function code, the REG$_DATAFLAGS item code is either an input or output item code. It is a 64-bit application-dependent value data flag.REG$_DATATYPE
Depending on the function code, the REG$_DATATYPE item code is either an input or output item code.It is a longword that either specifies the type of information to be stored as a value data or receives the type of information of a specified value data component.
It takes one of the following values:
Type code Description REG$K_BINARY Binary data REG$K_DWORD A 32-bit number REG$K_EXPAND_SZ A string of Unicode characters REG$K_MULTI_SZ A concatenated array of REG$K_SZ strings REG$K_NONE No defined value type (default) REG$K_QWORD A 64-bit number REG$K_SZ A null-terminated Unicode string
Note
The difference between REG$K_EXPAND_SZ and REG$K_SZ:A string is a set of characters usually in human-readable form. Many value entries in the OpenVMS Registry are written using a string (REG_SZ) or an expandable string (REG_EXPAND_SZ) format.
An expandable string is usually human-readable text, but it can also include a variable that will be replaced when the string is called by an application.
For example, on a Windows NT system, in the value entry %SystemRoot%\System32\Bootok.exe , %SystemRoot% is the expandable portion of the variable. This part is replaced with the actual location of the directory that contains the Windows NT system files.
REG$_DISPOSITION
The REG$_DISPOSITION item code is an output item code. It is a longword and takes one of the following values:
Disposition value Description REG$K_CREATENEWKEY The key did not exist and was created. REG$K_OPENEXISTINGKEY The key existed and was opened. REG$_FLAGOPCODE
The REG$_FLAGOPCODE item code is an input item code. It is a longword flag that indicates how the REG$_DATAFLAGS input item code should be matched against the data flags field in the OpenVMS Registry database. It takes one of the following values:
Operator code options Description REG$K_ANY The data field in the OpenVMS Registry database must contain at least one of the flags in the REG$_DATAFLAGS input item code. REG$K_EXACTMATCH The REG$_DATAFLAGS input item code must match exactly the data flags field in the OpenVMS Registry database. REG$K_EXCLUDE The data flags field in the OpenVMS Registry database must not contain the flags in the REG$_DATAFLAGS input item code. REG$K_INCLUDE The data flags field in the OpenVMS Registry database must contain, at a minimum, the flags in the REG$_DATAFLAGS input item code. REG$K_NOTANY The data field in the OpenVMS Registry database must not contain any of the flags in the REG$_DATAFLAGS input item code. REG$_FLAGSUBKEY
The REG$_FLAGSUBKEY item code is an input item code. It is a longword Boolean field that indicates the following:
- If set to 1, report changes in a specified key and any of its subkeys.
- If set to 0, report changes to a specified key only.
REG$_KEYID
The REG$_KEYID item code is an input item code. It is a longword that contains the key identifier.REG$_KEYRESULT
The REG$_KEYRESULT item code is an output item code. It is a longword that receives a key identifier. The key identifier can be passed to other Registry calls using the REG$_KEYID item code.REG$_KEYPATH
The REG$_KEYPATH item code is an input item code. It is a string of Unicode characters that specifies a key path. A Unicode character is 4 bytes long.REG$_LASTWRITE
The REG$_LASTWRITE item code is an output item code. It is a quadword representation of absolute time that receives the time a specified key was last written to (including changes to its values).REG$_LINKCOUNT
The REG$_LINKCOUNT item code is an output item code. It is longword count of the number of symbolic links that refer to the item.REG$_LINKPATH
The REG$_LINKPATH item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the key path to which a specified key is linked. A Unicode character is 4 bytes long.REG$_LINKTYPE
The REG$_LINKTYPE item code is, depending on the function code, either an input or an output item code. It is longword type that indicates the link type.
Link Type Description REG$K_NONE No link (default) REG$K_SYMBOLICLINK Symbolic (logical) link REG$_NEWNAME
The REG$_NEWNAME item code is a string of Unicode characters that specifies the new name of the key.REG$_NOTIFYFILTER
The REG$_NOTIFYFILTER item code is an input item code. It is a longword mask that specifies which changes to the specified key and its subkeys and values to report. It takes any combination of the following values:
Value Description REG$M_CHANGEATTRIBUTES An attribute change of the specified key or its subkeys. REG$M_CHANGELASTSET Changes to the last write time of the specified key or its subkeys. REG$M_CHANGENAME A key name change, including creation and deletion, of the specified key or its subkeys.
Note
The system report changes to subkeys of the specified key only if the REG$_FLAGSUBKEY item code is set to 1.REG$_PATHBUFFER
The REG$_PATHBUFFER item code is an output item code. It is a buffer that receives a set of either key paths or value paths, separated by a null Unicode character (4 bytes long). (The third longword of the item descriptor contains the number of bytes written to the buffer.)REG$_REQLENGTH
The REG$_REQLENGTH item code is an output item code. It is a longword that receives the required buffer size (in bytes) to complete the operation successfully.REG$_RETURNSTATUS
The REG$_RETURNSTATUS item code is an output item code. It is a longword that receives the final completion status for a specified operation. For more information, see the Condition Values Returned section of this chapter.REG$_SECACCESS
The REG$_SECACCESS item code is an input item code. It is a longword mask that specifies the desired security access for the new key. It takes any combination of the following values:
Security access mask Description REG$M_ALLACCESS A combination of the following access values: REG$K_CREATELINK
REG$K_CREATESUBKEY
REG$K_ENUMSUBKEYS
REG$K_NOTIFY
REG$K_QUERYVALUE
REG$K_SETVALUEREG$M_CREATELINK Allows creation of a symbolic link. REG$M_CREATESUBKEY Allows creation of subkeys. REG$M_ENUMSUBKEYS Allows enumeration of subkeys. REG$M_EXECUTE Allows read access. REG$M_NOTIFY Allows change notification. REG$M_QUERYVALUE Allows queries of subkey data. REG$M_READ A combination of the following access values: REG$K_ENUMSUBKEYS
REG$K_QUERYVALUE
REG$K_NOTIFYREG$M_SETVALUE Allows setting of values and data. REG$M_WRITE A combination of the following access values: REG$K_CREATESUBKEY
REG$K_SETVALUEREG$_SECURITYPOLICY
The REG$_SECURITYPOLICY item code is an input item code. It is a longword that specifies the security policy to enforce for the key.It takes the following value:
Policy Setting Description REG$K_POLICY_NT_40 Access is required to the first key and the requested key (default). REG$_SEPARATOR
The REG$_SEPARATOR item code is an empty item code that provides a separator between sets of item codes.Using this item code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.
REG$_SUBKEYINDEX
The REG$_SUBKEYINDEX item code is an input item code. It is a longword that specifies the index of the subkey to retrieve.REG$_SUBKEYNAME
The REG$_SUBKEYNAME item code is an input item code. It is a string of Unicode characters that specifies the name of a subkey. A Unicode character is 4 bytes long.REG$_SUBKEYNAMEMAX
The REG$_SUBKEYNAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest subkey name.REG$_SUBKEYSNUMBER
The REG$_SUBKEYSNUMBER item code is an output item code. It is a longword that receives the number of subkeys contained in a specified key.REG$_VALUEDATA
The REG$_VALUEDATA item code is, depending on the function code, either an input or output item code. It is a buffer that contains either the value data component to write to the OpenVMS Registry (input), or it receives a data value component from the OpenVMS Registry (output).REG$_VALUEDATAMAX
The REG$_VALUEDATAMAX item code is an output item code. It is a longword that receives the length (in bytes) of the specified key's longest data component value.REG$_VALUEDATASIZE
The REG$_VALUEDATASIZE item code is an output item code. It is used to specify the address and size of a buffer that receives the length, in bytes, of the value data. The buffer size should be 4 bytes.REG$_VALUEINDEX
The REG$_VALUEINDEX item code is an input item code. It is a longword that specifies the index of the value to retrieve within a specified key. Note that the value index starts at zero and can be any value up to one less than the count returned by REG$_VALUENUMBER.REG$_VALUENAME
The REG$_VALUENAME item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the name of a value.REG$_VALUENAMEMAX
The REG$_VALUENAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest value name.REG$_VALUENUMBER
The REG$_VALUENUMBER item code is an output item code. It is a longword that receives the number of values contained in a specified key.REG$_VOLATILE
The REG$_VOLATILE item code identifies the volatility of an item. As an output, it returns the volatility of the object. On OpenVMS, volatile keys and values are lost when all nodes running an OpenVMS Registry server are rebooted. (In a standalone system, volatile keys and values are lost when the system reboots.)
Volatile Type Description REG$K_CLUSTER The item is removed when the cluster reboots. REG$K_NONE The item is not volatile (default).
For example, you can specify the function modifier REG$M_CASE_SENSITIVE with the function REG$FC_CREATE_KEY. When you use the function and function modifier together, the data passed to the OpenVMS Registry is treated as case sensitive. The two values are written in HP C as REG$M_CASE_SENSITIVE | REG$FC_CREATE_KEY .
The OpenVMS Registry function modifiers are defined in the header file REGDEF.H.
REG$M_CASE_SENSITIVE
Use case sensitive matching for keys and values.REG$M_DISABLE_WILDCARDS
Treat wildcard characters as normal characters for this function.REG$M_IGNORE_LINKS
Force the operation to not follow any symbolic links associated with a key or a value.By default, if a key or value is symbolically linked to another key or value, the system follows all links so that the operation specified by the function code is performed on the linked key or value.
When you specify the REG$M_IGNORE_LINKS function modifier, the operation specified by the function code affects only the specified key or value, not the linked key or value.
By default, if a key or value has a symbolic link, it can not be deleted. If you specify the REG$M_IGNORE_LINKS function modifier, the system deletes the key or value.
REG$M_NOW
Write to disk immediately, regardless of the REG$_CACHEACTION item code value.
The $REGISTRY service provides the means to create, delete and modify registry keys, key values, and key attributes.The $REGISTRY service uses process P1 space to store handles to keys.
The $REGISTRY service must be called at IPL 0, and requires system dynamic memory to deliver AST requests.
$REGISTRYW
SS$_NORMAL Normal successful completion. SS$_ACCVIO One of the arguments cannot be read/written. SS$_BADPARAM Function code or one of the item list code is invalid. SS$_EXASTLM Exceeded AST limit. SS$_INSFARG Insufficient number of argument supplied. SS$_INSFP1POOL Not enough process P1 space available. SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae. SS$_TOO_MANY_ARGS Too many arguments. REG$_ACCESSDENIED Requested access to key is denied. REG$_IPLTOOHIGH Callers above IPL 0 cannot call this service.
SS$_NORMAL Normal successful completion. SS$_ACCVIO One of the arguments cannot be read/written. SS$_BADPARAM Function code or one of the item list code is invalid. SS$_EXASTLM Exceeded AST limit. SS$_INSFARG Insufficient number of argument supplied. SS$_INSFP1POOL Not enough process P1 space available. SS$_NOIMPERSONATE The caller does not have the privilege to obtain information about the specified personae. SS$_TOO_MANY_ARGS Too many arguments. REG$_ACCESSDENIED Requested access to key is denied. REG$_BUFFEROVF Buffer overflow. REG$_DBALREADYLOADED Database is already loaded. REG$_DBNOTYETLOADED Database is not yet loaded. REG$_EXQUOTA Registry file quota or page file quota exceeded. REG$_HASLINK Key has a link to another key. REG$_HAVESUBKEYS Cannot delete a key with subkeys. REG$_INTERNERR Registry internal error. REG$_INVCACHEACTION Invalid cache action parameter. REG$_INVCREDENTIALS NT credentials are not valid. REG$_INVDATA Invalid data value. REG$_INVDATATYPE Invalid data type parameter. REG$_INVFUNCCODE Invalid function code. REG$_INVKEYFLAGS Invalid key flags. REG$_INVKEYID Key does not exist or invalid key ID was specified. REG$_INVKEYNAME Invalid key name. REG$_INVLINK Invalid link or link type. REG$_INVLINKPATH Invalid link path. REG$_INVPARAM Invalid parameter. REG$_INVPATH Invalid key path. REG$_INVSECDESCRIPTOR Invalid security descriptor. REG$_INVSECPOLICY Invalid security policy parameter. REG$_INVVALNAME Invalid value name. REG$_INVVOLROOTKEY Cannot create a new file with a volatile root key. REG$_IPLTOOHIGH Callers above IPL 0 cannot call this service. REG$_KEYCHANGED Key or subkey has changed. REG$_KEYLOCKED Key locked by another thread. REG$_KEYNAMEEXIST Key name already exists. REG$_NOKEY Specified key does not exist. REG$_NOMOREITEMS No more items for specified key. REG$_NOPATHFOUND Path not found. REG$_NORESPONSE OpenVMS Registry server failed to respond within the alloted time period. REG$_NOTROOTKEY Invalid root key index. REG$_NOTSUPPORTED Function code, item code, or item value is not supported. REG$_NOVALUE Specified value does not exist. REG$_REQRECEIVED Received request for key change notification. REG$_RESERVED Cannot delete or modify a reserved key or value. REG$_SECVIO Violates the security access method specified when this key was last opened. REG$_STRINGTOOLONG Input string too long. REG$_STRINGTRUNC Output buffer is not large enough to contain the converted string. REG$_TOOMANYOPENKEY Number of opened keys exceeds the limit. REG$_VALUEEXIST Value already exists. REG$_VOLMISMATCH Cannot create nonvolatile subkey for a volatile key.
This service can also return status values from the following system services: $CLREF, $SYNCH, $PERSONA_EXTENSION_LOOKUP, and $PERSONA_QUERY.
Interface to the OpenVMS Registry database server.The $REGISTRY service supports both asynchronous and synchronous operations. For asynchronous completion, use the Registry ($REGISTRY) system service.
For synchronous completion, use the Registry and Wait ($REGISTRYW) system service. The $REGISTRYW system service is identical to the $REGISTRY system service, except that $REGISTRYW returns to the caller after the system completes the requested operation. For additional information about system service completion, see the Synchronize ($SYNCH) system service.
This system service is 64-bit compatible.
SYS$REGISTRYW [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or astadr_64] [,astprm or astprm_64] [,timeout]
int sys$registryw (unsigned int efn, unsigned int func, void *, void *itmlst, struct _iosb *iosb, ...);
The Release service unlocks the record specified by the contents of the record file address (RAB$W_RFA) field of the RAB.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Releases ownership of an OpenVMS Galaxy lock.Note that this system service is supported only in an OpenVMS Alpha Galaxy environment.
For more information about programming with OpenVMS Galaxy system services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.
SYS$RELEASE_GALAXY_LOCK handle
int sys$release_galaxy_lock (unsigned __int64 lock_handle);
handle
OpenVMS usage: galaxy lock handle type: quadword (unsigned) access: read mechanism: input by value
The 64-bit lock handle that identifies the lock to be released. This value is returned by SYS$CREATE_GALAXY_LOCK.
This service releases ownership of an OpenVMS Galaxy lock. Because a Galaxy lock can be acquired multiple times by the same owner (nested ownership), the lock is not released until the ownership count goes to zero. If the lock ownership is completely released and there are other threads waiting for the lock, they are released from their wait states.Write access to lock.
None
$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE
SS$_NORMAL Normal completion. SS$_IVLOCKID Invalid lock id. SS$_IVLOCKOP Invalid lock operation. SS$_IVLOCKTBL Invalid lock table.
On VAX systems, terminates the current process' status as a vector consumer.
SYS$RELEASE_VP
None.
The Release Vector Processor service terminates the current process' status as a vector consumer. The $RELEASE_VP service waits for all pending vector instructions and vector memory operations to complete. It then declares that the process no longer needs a vector-present processor. As a result, the process relinquishes its use of the processor's vector registers and can be scheduled on another processor in the system.In systems that do not have vector-present processors but do have the VAX Vector Instruction Emulation facility (VVIEF) in use, this service relinquishes the process's use of VVIEF. VVIEF remains mapped in the process's address space.
None
None
$RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION
SS$_NORMAL The service completed successfully.
The Remove service deletes a file name from a directory. It is the reverse of the Enter service.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Deletes the specified holder record from the target identifier's list of holders.
SYS$REM_HOLDER id ,holder
int sys$rem_holder (unsigned int id, struct _generic_64 *holder);
id
OpenVMS usage: rights_id type: longword (unsigned) access: read only mechanism: by value
Binary value of target identifier whose holder is deleted when $REM_HOLDER completes execution. The id argument is a longword containing the identifier value.holder
OpenVMS usage: rights_holder type: quadword (unsigned) access: read only mechanism: by reference
Identifier of holder being deleted when $REM_HOLDER completes execution. The holder argument is the address of a quadword containing the UIC identifier of the holder in the first longword and the value of 0 in the second longword.
The Remove Holder Record from Rights Database service removes the specified holder record from the target identifier's list of holders.Write access to the rights database is required.
None
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_IDENT, $REVOKID
SS$_NORMAL The service completed successfully. SS$_ACCVIO The holder argument cannot be read by the caller. SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database. SS$_IVIDENT The specified identifier or holder identifier is of invalid format. SS$_NORIGHTSDB The rights database does not exist. SS$_NOSUCHID The specified identifier does not exist in the rights database, or the specified holder identifier does not exist in the rights database. 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.
Removes the specified identifier record and all its holder records (if any) from the rights database.
SYS$REM_IDENT id
int sys$rem_ident (unsigned int id);
id
OpenVMS usage: rights_id type: longword (unsigned) access: read only mechanism: by value
Binary value of identifier deleted from rights database when $REM_IDENT completes execution. The id argument is a longword containing the identifier value.
The Remove Identifier from Rights Database service removes from the rights database the specified identifier record, all its holder records (if any), and all records in identifiers that the deleted identifier held.Write access to the rights database is required.
None
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REVOKID
SS$_NORMAL The service completed successfully. SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database. SS$_IVIDENT The specified identifier is of invalid format. SS$_NORIGHTSDB The rights database does not exist. SS$_NOSUCHID The specified identifier does not exist in the rights database. 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.
You can use the Rename service to change the name, type, or version of a file, or to move a file to another directory by changing its directory specification. However, you cannot use this service to move a file to another device.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Requests reschedule of a process.
SYS$RESCHED
int sys$resched (void);
None.
The Reschedule Process service requests that the set of runnable processes on the system be evaluated by their priority, with the potential result that the current process may be descheduled and requeued.$RESCHED is intended to allow a process running at priority n to voluntarily relinquish the remainder of its run quantum to another process of the same priority. When the set of all runnable processes is evaluated, one of the following will occur:
- The process executing $RESCHED will be descheduled, while another process of equal or higher priority is selected to run. The descheduled process is placed at the end of its priority queue and all other processes at that priority will run before the process that called $RESCHED runs again. When the process does run again, $RESCHED completes and returns control to the application.
- If, after the evaluation of all runnable processes, the process that executed $RESCHED remains the highest-priority runnable process, that process remains current and continues to run. In this case, $RESCHED returns immediately.
None
None
None
SS$_NORMAL The service completed successfully.
On VAX systems, restores the saved exception state of the vector processor.
SYS$RESTORE_VP_EXCEPTION excid
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.
The Restore Vector Processor Exception State service restores from memory the vector exception state saved by a prior call to $SAVE_VP_EXCEPTION. After a routine invokes this service, the next vector instruction issued within the process causes the restored vector exception to be reported.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 function of this service.
None
BYTLM
$RELEASE_VP, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION
SS$_NORMAL The service completed successfully. 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$_ACCVIO The caller cannot read the exception ID longword. SS$_NOSAVPEXC No saved vector exception state exists for this exception ID.
On VAX systems, allows an AST routine or condition handler to restore the vector state of the mainline routine.
SYS$RESTORE_VP_STATE
None.
The Restore Vector State service allows an AST routine or a condition handler to restore the vector state of the process's mainline routine.By default, when an asynchronous routine (AST routine or condition handler) interrupts the execution of a mainline routine, the operating system creates a new vector state when the routine issues its first vector instruction. At this point, the vector state of the mainline routine is inaccessible to the asynchronous routine. If the asynchronous routine must manipulate the vector state of the mainline routine, it first calls $RESTORE_VP_STATE to restore the mainline's vector state.
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.
This service can be called only from a routine running in user mode.
None
None
$RELEASE_VP, $RESTORE_VP_EXCEPTION, $SAVE_VP_EXCEPTION
SS$_NORMAL The service completed successfully. Vector state of the mainline has been restored. 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$_BADSTACK Bad user stack encountered. SS$_BADCONTEXT The mainline vector state is corrupt. SS$_WRONGACMODE The system service was called from an access mode other than user mode.
Causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or cancels the effect of a subsequent suspend request.
SYS$RESUME [pidadr] ,[prcnam]
int sys$resume (unsigned int *pidadr, void *prcnam);
pidadr
OpenVMS usage: process_id type: longword (unsigned) access: modify mechanism: by reference
Process identification (PID) of the process to be resumed. 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 cluster.You must specify the pidadr argument to delete 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 resumed. The prcnam argument 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 1- to 15-character string. 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 resume 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 delete processes in other UIC groups.
The Resume Process service (1) causes a process previously suspended by the Suspend Process ($SUSPND) service to resume execution or (2) cancels the effect of a subsequent suspend request.If you specify neither the pidadr nor prcnam argument, the resume request is issued on behalf of the calling process.
If the longword value at address pidadr is 0, the PID of the target process is returned.
If one or more resume requests are issued for a process that is not suspended, a subsequent suspend request completes immediately; that is, the process is not suspended. No count of outstanding resume requests is maintained.
Depending on the operation, the calling process might need one of the following privileges to use $RESUME:
- GROUP privilege to resume execution of a process in the same group unless the process has the same UIC as the calling process
- WORLD privilege to resume execution of any process in the system
None
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE
SS$_NORMAL The service completed successfully. SS$_ACCVIO The process name string or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller. SS$_INCOMPAT The remote node is running an incompatible version of the operating system. SS$_IVLOGNAM The specified process name has a length of 0 or has more than 15 characters. SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified. SS$_NOPRIV The process does not have the privilege to resume the execution of the specified process. SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the cluster. SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.) SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)
Removes the specified identifier from the rights list of the process or the system. If the identifier is listed as a holder of any other identifier, the appropriate holder records are also deleted.
SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]
int sys$revokid (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name, unsigned int *prvatr, unsigned int segment);
pidadr
OpenVMS usage: process_id type: longword (unsigned) access: modify mechanism: by reference
Process identification (PID) number of the process affected when $REVOKID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use --1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant.prcnam
OpenVMS usage: process_name type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Process name on which $REVOKID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group.id
OpenVMS usage: rights_id type: quadword (unsigned) access: modify mechanism: by reference
Identifier and attributes to be removed when $REVOKID completes execution. The id argument is the address of a quadword containing the binary identifier code to be removed in the first longword and the attributes in the second longword.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 following symbols for each bit position are defined in the system macro library ($KGBDEF):
Bit Position Meaning When Set KGB$V_DYNAMIC Allows unprivileged 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_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. You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.
name
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Name of the identifier removed when $REVOKID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier.prvatr
OpenVMS usage: mask_longword type: longword (unsigned) access: write only mechanism: by reference
Attributes of the deleted identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier.
The Revoke Identifier from Process service removes the specified identifier from the rights list of the process or the system. If the identifier is listed as a holder of any other identifier, the appropriate holder records are also deleted.The result of passing the pidadr or the prcnam argument, or both, to $REVOKID is summarized in the following table.
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. 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. 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.
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.
None
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT
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.
The Rewind service sets the context of a record stream to the first record in the file. RMS alters the context of the next record to indicate the first record as being the next record.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this 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.
SYS$RMSRUNDWN buf-addr ,type-value
int sys$rmsrundwn (void *buf-addr, unsigned char *type-value);
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).
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.
None
None
$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
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.
On VAX systems, saves the pending exception state of the vector processor.
SYS$SAVE_VP_EXCEPTION excid
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.
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.
None
None
$RELEASE_VP, $RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE
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.
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.
SYS$SCAN_INTRUSION logfail_status ,failed_user ,job_type ,[source_terminal] ,[source_node] ,[source_user] ,[source_address] ,[failed_password] ,[parent_user] ,[parent_id] ,[flags]
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);
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, refer to the HP OpenVMS Guide to System Security.
failed_user
OpenVMS usage: char_string or item_list_3 type: character-coded text string or longword (unsigned) access: read only mechanism: by descriptor--fixed-length string descriptor or by reference
If the CIA$M_ITEMLIST flag is FALSE:This argument is the 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.
If the CIA$M_ITEMLIST flag is TRUE:
The failed_user argument is the address of a 32-bit item list. If the item list is used, one item, the CIA$_FAILED_USERNAME item, must be present in the item list.
The following table lists the valid item descriptions for the failed_user argument:
Item Description CIA$_FAILED_USERNAME Address of a buffer containing the failed user name. CIA$_SCSNODE Address of the 8-character null-padded SCS node name on which the intrusion happened. CIA$_USER_DATA Address of a 256-byte buffer, available for passing third party specified data. 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 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_ITEMLIST If FALSE, the failed_user argument is a character string. If TRUE, this argument is a 32-bit item list. 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.
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, refer to the HP OpenVMS Guide to System Security.
$SCAN_INTRUSION requires the SECURITY privilege.
None
$DELETE_INTRUSION, $SHOW_INTRUSION
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.
Schedules the awakening (restarting) of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service.
SYS$SCHDWK [pidadr] ,[prcnam] ,daytim ,[reptim]
int sys$schdwk (unsigned int *pidadr, void *prcnam, struct _generic_64 *daytim, struct _generic_64 *reptim);
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.The time interval specified cannot be less than 10 milliseconds; if it is, $SCHDWK automatically increases it to 10 milliseconds.
If you do not specify reptim, a default value of 0 is used, which specifies that the wakeup request is not to be repeated.
The Schedule Wakeup service schedules the awakening of a process that has placed itself in a state of hibernation with the Hibernate ($HIBER) service. A wakeup can be scheduled for a specified absolute time or for a delta time and can be repeated at fixed intervals.If you specify neither the pidadr nor the prcnam argument, the wakeup request is issued on behalf of the calling process. If the longword value at address pidadr is 0, the PID of the target process is returned.
$SCHDWK uses the system dynamic memory to allocate a timer queue entry.
If you issue one or more scheduled wakeup requests for a process that is not hibernating, a subsequent hibernate request by the target process completes immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.
You can cancel scheduled wakeup requests that have not yet been processed by using the Cancel Wakeup ($CANWAK) service.
If a specified absolute time value has already passed and no repeat time is specified, the timer expires at the next clock cycle (within 10 milliseconds).
Depending on the operation, the calling process might need one of the following privileges to use $SCHDWK:
- GROUP privilege to schedule wakeup requests for a process in the same group unless it has the same UIC
- WORLD privilege to schedule wakeup requests for any other process in the system
This service uses the process's timer queue entries (TQELM) quota. If you specify an AST routine, the service uses the AST limit (ASTLM) quota of the calling process to schedule a wakeup request.
$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SETIME, $SETIMR
SS$_NORMAL The service completed successfully. SS$_ACCVIO The expiration time, repeat time, process name string, or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller. SS$_EXQUOTA The process has exceeded its AST limit quota. SS$_INCOMPAT The remote node is running an incompatible version of the operating system. SS$_INSFMEM The system dynamic memory is insufficient for allocating a timer queue entry. SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters. SS$_IVTIME The specified delta repeat time is a positive value, or an absolute time plus delta repeat time is less than the current time. SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified. SS$_NOPRIV The process does not have the privilege to schedule a wakeup request for the specified process. SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the OpenVMS Cluster system. SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.) SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)
Affects process scheduling. This service is intended for use by a class scheduler process.
SYS$SCHED func ,p1 ,p2 ,p3
int sys$sched (unsigned int func, unsigned int *p1, unsigned int *p2, unsigned int *p3);
Function Codes This section defines each of the $SCHED function codes and describes the values of the p1 argument, p2 argument, and p3 argument for each function.func
OpenVMS usage: function_code type: longword (unsigned) access: write only mechanism: by value
Function code specifying the action $SCHED is to perform. The func argument is a longword containing this code.See the Function Codes section for a list of valid function codes for $SCHED.
p1, p2, p3
OpenVMS usage: longword type: longword (unsigned) access: varies mechanism: varies
The meaning of the p1, p2, and p3 arguments depends on the function code specified in the func argument, and is defined in the Function Codes section.
CSH$_READ_ALL
Returns a buffer containing information, including an index, EPID, and priority, for all processes.The format of the buffer is defined in the $CSHDEF macro and consists of a series of CSHP fields.
The following table shows the p1 argument, p2 argument, and p3 argument values for the CSH$_READ_ALL function code:
Argument Access Description p1 Read Address of the buffer. p2 Write Address of the longword size of the buffer. p3 Write Address of the longword size of the per-process entry. CSH$_READ_NEW
Returns a buffer containing information, including an index, EPID, and priority, for all processes for which a class assignment has not been made.The format of the buffer is defined in the $CSHDEF macro and consists of a series of CSHP fields.
The following table shows the p1 argument, p2 argument, and p3 argument values for the CSH$_READ_NEW function code:
Argument Access Description p1 Read Address of the buffer. p2 Write Address of the longword size of the buffer. p3 Write Address of the longword size of the per-process entry. The following table describes the information returned in the buffer fields for both CSH$_READ_ALL and CSH$_READ_NEW:
Buffer Field Definition CSHP$T_ACCOUNT Account string from the user authorization file (first eight characters). CSHP$L_CPUTIM Process CPU time used, in 10-millisecond ticks. CSHP$L_EPID Process ID (PID). If CSHP information is insufficient to determine the right class for a process, the PID can be used with the $GETJPI(W) system service to obtain additional detail. CSHP$W_PIX A unique integer assigned to the process for its duration. Applications might want to use this value to index arrays. CSHP$B_PRI Current process priority. CSHP$B_PRIB Base process priority. CSHP$L_STATUS Undefined; reserved to HP. CSH$_READ_QUANT
Returns a buffer containing information about how many ticks are left for each class. Data is returned in a series of longwords, one longword per class, starting with class number 0.The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_READ_QUANT function code:
Argument Access Description p1 Read Address of the buffer. p2 Read Address of the longword size of the buffer. p3 --- Unused. CSH$_SET_ATTN_AST
Enables attention asynchronous system traps (ASTs).The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_ATTN_AST function code:
Argument Access Description p1 Read Address of an AST routine. p2 Read Access mode to deliver AST. p3 --- Unused. CSH$_SET_CLASS
Places processes in classes with or without windfall capability. The caller supplies a buffer consisting of CSHC blocks.The format of the buffer is defined in the $CSHDEF macro. The following table describes the information contained in the buffer:
Buffer Field Definition CSHC$L_EPID Process ID (PID) of the process to affect. CSHC$W_CLASS Class into which to place the process. Class 65535 (hexadecimal FFFF) has a special interpretation: the associated process is not to be class scheduled and will, therefore, never run out of class quantum. The largest class number is 8191. CSHC$W_WINDFALL Determines whether the process is to share windfall. A value of 1 permits the process to share windfall; a value of 0 prevents the process from sharing windfall. Values other than 0 and 1 are undefined and can cause unpredictable behavior in future releases of the operating system. The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_CLASS function code:
Argument Access Description p1 Read Address of the buffer. p2 Read Address of the longword size of the buffer. p3 Read Address of the longword size of the entry used. Should be CSHC$K_LENGTH or equivalent. CSH$_SET_NEW
Indicates to the class scheduler that the next READ_NEW will return information about the calling process. This function should be used only in executive or kernel mode.The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_NEW function code:
Argument Access Description p1 --- Unused. p2 Read PID (by value). p3 --- Unused. CSH$_SET_QUANT
Establishes class quantum and enables class scheduling. The caller supplies a buffer that allocates CPU ticks to classes, one longword per class, starting with class number 0. Class-scheduled processes will have their quantum deducted from the appropriate longword, and will be removed from execution if class quantum is decremented to 0.The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_QUANT function code:
Argument Access Description p1 Read Address of the buffer. p2 Read Address of the longword size of buffer. p3 --- Unused. CSH$_SET_TIMEOUT
Establishes a nonstandard timeout. If the application does not issue a CSH$_SET_QUANT within the timeout period, all class scheduling is stopped and processes are returned to normal scheduling. The default value, 30 seconds, should be suitable for most circumstances.The following table defines the p1 argument, p2 argument, and p3 argument values when specifying the CSH$_SET_TIMEOUT function code:
Argument Access Description p1 --- Unused. p2 Read Time in seconds (by value). p3 --- Unused.
The Affect Process Scheduling service is used by class scheduler processes to affect scheduling.Use the func argument to specify which action $SCHED is to perform.
For more information on class scheduling, refer to the OpenVMS Programming Concepts Manual.
ALTPRI is required to affect processes. Group access is required to affect processes in the same UIC group. World access is required to affect processes in different UIC groups. SYSPRV is required to set the timeout value.
None
$GETJPI, $GETJPIW, $SETPRI
SS$_NORMAL Service completed successfully. SS$_ACCVIO Buffer, length, or size locations not writeable. SS$_BADPARAM Specified a class higher than currently defined, or an element size of 0 was specified. SS$_BUFFEROVF Buffer is too small, only some data transferred. SS$_INCLASS Returned if a process (specified by the input PID) already belongs to a scheduling class. This can happen if the process was previously class scheduled at login through the class scheduler permanent database file, or by issuing the command, SET PROCESS/SCHEDULING_CLASS="class_name". SS$_INSFMEM System dynamic memory is insufficient to complete the service. SS$_NOSUCHUSER Supplied PID is not valid.
The Search service scans a directory file and fills in various NAM block fields. This service should be preceded by the Parse service, in order to initialize the NAM block appropriately.Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
Enables or disables the delivery of asynchronous system traps (ASTs) for the access mode from which the service call was issued.
SYS$SETAST enbflg
int sys$setast (char enbflg);
enbflg
OpenVMS usage: boolean type: byte (unsigned) access: read only mechanism: by value
Value specifying whether ASTs are to be enabled. The enbflg argument is a byte containing this value. The value 1 enables AST delivery for the calling access mode; the value 0 disables AST delivery.
The Set AST Enable service enables or disables the delivery of ASTs for the access mode from which the service call was issued.When an image is executing in user mode, ASTs are always enabled for more privileged access modes. If ASTs are disabled for a more privileged access mode, the operating system cannot deliver ASTs for less privileged access modes until ASTs are enabled once again for the more privileged access mode. Therefore, a process that has disabled ASTs for a more privileged access mode must reenable ASTs for that mode before returning to a less privileged access mode.
None
$DCLAST, $SETPRA
SS$_WASCLR The service completed successfully. AST delivery was previously disabled for the calling access mode. SS$_WASSET The service completed successfully. AST delivery was previously enabled for the calling access mode.
Establishes a request for notification when an OpenVMS Cluster configuration event occurs.
SYS$SETCLUEVT event ,astadr ,[astprm] ,[acmode] ,[handle]
int sys$setcluevt (unsigned int event, void (*astadr)(__unknown_params), int astprm, unsigned int acmode, struct _generic_64 *handle);
event
OpenVMS usage: event_code type: longword (unsigned) access: read only mechanism: by value
Event code indicating the type of cluster configuration event for which an AST is to be delivered. The event argument is a value indicating which type of event is of interest.Each event type has a symbolic name. The $CLUEVTDEF macro defines the following symbolic names:
Symbolic Name Description CLUEVT$C_ADD One or more OpenVMS nodes have been added to the OpenVMS Cluster system. CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed from the OpenVMS Cluster system. astadr
OpenVMS usage: ast_procedure type: procedure value access: call without stack unwinding mechanism: by reference
Notification AST routine to receive control after a change in OpenVMS Cluster configuration occurs.astprm
OpenVMS usage: user_arg type: longword (unsigned) access: read only mechanism: by value
Optional AST parameter to be passed to the AST service routine. The astprm argument is a longword value containing the AST parameter.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Optional access mode at which the configuration event AST is to execute. The acmode argument is a longword containing the access mode.Each access mode has a symbolic name. The $PSLDEF macro defines the following symbols for the four access modes:
Symbol Access Mode PSL$C_KERNEL Kernel PSL$C_EXEC Executive PSL$C_SUPER Supervisor PSL$C_USER User The value of the access mode must not be more privileged than the access mode of the caller.
handle
OpenVMS usage: identifier type: quadword (unsigned) access: write only mechanism: by reference
Optional identifier to receive a value that uniquely identifies this AST request. $SETCLUEVT sets this handle to a unique value so that it can later be used to identify the request in the $CLRCLUEVT and $TSTCLUEVT services.
The Set Cluster Event service establishes a request for notification when a cluster configuration event occurs. The service establishes only one AST notification for a configuration event. To receive AST notification for all cluster configuration events, the $SETCLUEVT service must be reissued within the notification AST routine.The service will verify that the input parameters specify a valid request, allocate appropriate data structures to hold the request, and enqueue the request for notification.
You must specify an event type and an AST address. You can specify an AST parameter, the access mode, and an address into which to place the handle of this request.
Errors will be returned in the following cases:
- If quotas are exceeded, an error identifying the specific quota will be returned. It is important to note that this routine will return an error and will not retry an attempt to get quota if quota is exhausted on the first attempt. See the Condition Values Returned section for types of errors that can be returned.
- If the astadr argument is omitted, SS$_BADPARAM will be returned.
- If the event argument is omitted or incorrectly specified, SS$_BADPARAM will be returned.
- If the access mode parameter is more privileged than the mode of the caller, the mode of the caller will be used.
- If specified, the handle argument must be readable and writable from the mode of the caller. SS$_ACCVIO is returned if this is not the case.
None
None
$CLRCLUEVT, $TSTCLUEVT
SS$_NORMAL The service completed successfully. SS$_ACCVIO Unable to process parameters for improper use. SS$_BADPARAM The event was improperly specified. SS$_EXASTLM The process exceeded its quota for outstanding AST requests. SS$_INSFMEM The system dynamic memory is insufficient to complete the service.
Allows you to read and change the default directory string for the process.
SYS$SETDDIR [new-dir-addr] ,[length-addr] ,[cur-dir-addr]
int sys$setddir (void *newdiraddr, unsigned short int *lengthaddr, void *curdiraddr);
new-dir-addr
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
A descriptor of the new default directory. The new-dir-addr argument is the address of the descriptor that points to the buffer containing the new directory specification that RMS will use to set the new process-default directory. If the default directory is not to be changed, the value of the new-dir-addr argument should be 0.length-addr
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference
A word that is to receive the length of the current default directory. The length-addr argument is the address of the word that will receive the length. If you do not want this value returned, specify the value 0.cur-dir-addr
OpenVMS usage: char_string type: character-coded text string access: write only mechanism: by descriptor--fixed-length string descriptor
A descriptor of a buffer that is to receive the current default directory string. The cur-dir-addr argument is the address of the descriptor that points to the buffer area that is to receive the current directory string.
The Set Default Directory service allows you to read and change the default directory string for the process. You should restore the previous default directory string to its original state unless you want the changed default directory string to last beyond the exit of your image. The new directory name string is checked for correct syntax.There is no predefined macro of the form $SETDDIR_G or $SETDDIR_S to call this service.
On Alpha systems, the Set Default Directory service attempts to replace the default directory string with a DID abbreviation if the length of the resulting default directory exceeds 255 characters. If this happens, then in addition to the normal syntax check, the entire path to that specification, including the device, is verified and must exist for the call to succeed.
None
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
RMS$_NORMAL The service completed successfully. RMS$_DIR The directory name contains an error. RMS$_IAL The argument list is invalid.
Allows you to read and write the default file protection for the process.
SYS$SETDFPROT [new-def-prot-addr] ,[cur-def-prot-addr]
int sys$setdfprot (unsigned short int *newdefprotaddr, unsigned short int *curdefprotaddr);
new-def-prot-addr
OpenVMS usage: file_protection type: word (unsigned) access: read only mechanism: by reference
A word that specifies the new default file protection specification. The new-def-prot-addr argument is the address of the word that specifies the desired protection. If you do not want the process-default file protection to be changed, specify the value 0.cur-def-prot-addr
OpenVMS usage: file_protection type: word (unsigned) access: write only mechanism: by reference
A word that is to receive the current default file protection specification. The cur-def-prot-addr argument is the address of the word that receives the current process-default protection. If you do not want the current default file protection, specify the value 0.
The Set Default File Protection service allows you to read and write the default file protection for the process. You should restore the old default file protection specification unless you want the changed default to last beyond the exit of your image.There is no predefined macro of the form $SETDEFPROT_G or $SETDEFPROT_S to call this service.
None
None
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $GET_SECURITY, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SET_SECURITY, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
RMS$_NORMAL The service completed successfully. RMS$_IAL The argument list is invalid.
The Set Distributed Transaction Information service removes resource managers from transactions. It can also be used to modify transaction states.
SYS$SETDTI [efn], [flags], iosb, [astadr], [astprm], [contxt], func, itmlst
int sys$setdti (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int *contxt, unsigned short int *func, void *itmlst);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Flags specifying options for the service. The flags argument is a longword bit mask in which each bit corresponds to an option flag. The $DDTMDEF macro defines symbolic names for the option flag described in Table SYS-51. All undefined bits must be 0. If this argument is omitted, no flags are used.
Table SYS-51 $SETDTI Operation Flag Flag Name Description DDTM$M_SYNC Specifies successful synchronous completion by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in. iosb
OpenVMS usage: io_status_block type: quadword (unsigned) access: write only mechanism: by reference
The I/O status block in which the completion status of the service is returned as a condition value. See the Condition Values Returned section.The following diagram shows the structure of the I/O status block:
| OpenVMS usage: | ast_procedure |
| type: | procedure entry mask |
| access: | call without stack unwinding |
| mechanism: | by reference |
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
| OpenVMS usage: | contxt |
| type: | longword (unsigned) |
| access: | modify |
| mechanism: | by reference |
| OpenVMS usage: | function_code |
| type: | word (unsigned) |
| access: | read only |
| mechanism: | by value |
Table SYS-52 lists the available function codes:
| Function | Description |
|---|---|
| DTI$K_DELETE_RM_NAME | Deletes the resource manager specified in itmlst item DTI$_TRANSACTION_INFORMATION, DTI$T_PART_NAME from the transaction specified by DTI$_TRANSACTION_INFORMATION, DTI$T_TID. |
| DTI$K_DELETE_TRANSACTION | Deletes the transaction specified by itmlst item DTI$_TRANSACTION_INFORMATION, DTI$T_TID. |
| DTI$K_MODIFY STATE | Modifies the transaction specified by itmlst item DTI$_TRANSACTION_INFORMATION, DTI$T_TID, using the transaction state specified in DTI$_B_STATE. |
| OpenVMS usage: | item_list_3 |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by reference |
The following diagram depicts the format of a single item descriptor:
The following table describes the itmlst item descriptor fields:
| Field | Description |
|---|---|
| Buffer length | A word containing a user-supplied integer specifying the length (in bytes) of a buffer from which $SETDTI is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, $SETDTI will return an error status. |
| Item code | A word containing a user-supplied symbolic code specifying the search item that $SETDTI is to use. The $DTIDEF macro defines these codes. Each item code is described in the Item Codes section. |
| Buffer address | A longword containing the user-supplied address of the buffer from which $SETDTI reads the item information. |
| Return length address | This longword that is not used in the item list as all items are read-only. |
DTI$_TRANSACTION_INFORMATION
When you specify DTI$_TRANSACTION_INFORMATION, $SETDTI uses the fields in the following table to perform the $SETDTI call. Each function requires a specific set of fields from the transaction record to perform its operation. If one or more of these fields is not present or valid, then the $SETDTI call will fail. The fields required by each function are listed in the func argument description.
Item Description DTI$B_PART_NAME_LEN A byte containing the length of the participant name field DTI$T_PART_NAME. DTI$B_STATE A byte containing the state of the transaction. Two states are valid: DTI$K_COMMITTED and DTI$K_ABORTED. DTI$T_PART_NAME A character field containing DTI$B_PART_NAME_LEN characters that specifies a resource manager name. To ensure smooth operation in a mixed-network environment, refer to the chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for information on defining node names.
DTI$T_PART_LOG_ID Reserved by HP. DTI$T_TID A 16-byte field containing the transaction identifier.
The $SETDTI service can be used either to remove resource managers from transactions, or to modify transaction states.The $SETDTI service removes resource managers from a single transaction or from all transactions when they no longer have any further interest in a transaction. A call to $SETDTI typically follows a call to $GETDTI that established a search context and returned the state of an unresolved transaction.
When a resource manager is recovering from a system failure it will use $GETDTI to return the state of all unresolved transactions. If the resource manager can recover the transaction, then it needs to be removed from the transaction in the same way it would have been removed had it been able to call $ACK_EVENT with the forget status before the system failure.
To remove a resource manager, $SETDTI uses the following fields from the DTI$_TRANSACTION_INFORMATION item descriptor in the itmlst argument:
- Transaction Identifier (TID)
- Resource Manager name
- Resource Manager log identifier
This information, along with the search context, is used to remove the resource manager from the transaction. If the TID field is zero in the DTI$_TRANSACTION_INFORMATION item descriptor, then the resource manager will be removed from all committed transactions in which it was involved.
When searching for a resource manager, a comparison is made of the leftmost bytes in the transaction manager's log records. This feature enables multiple instances of resource manager classes to be removed from the transaction manager's log after performing a recovery.
The $SETDTI service can also be used to modify transaction states. It can perform two state transitions: from prepared to committed, or from prepared to aborted. To modify transaction states, $SETDTI uses the following fields from the DTI$_TRANSACTION_INFORMATION item descriptor in the itmlst argument:
- Transaction Identifier (TID)
- Transaction state
To modify a transaction state, first modify the DTI$B_STATE field in the DTI$_TRANSACTION_INFORMATION item descriptor to either DTI$K_COMMITTED and DTI$K_ABORTED. Then specify the function code DTI$K_MODIFY_TRANSACTION to instruct $SETDTI to perform the state transition.
Note that because DECdtm uses a presumed abort protocol, changing the transaction state to aborted is the same as deleting the transaction.
SYSPRV privilege is required to retrieve or modify information about transactions with which the process is not currently associated.
In most cases, the search context remains valid across multiple calls to $SETDTI. That is, a call to $GETDTI may be followed by one or more calls to $SETDTI without the context becoming invalid. However, the search context is invalidated when a resource manager is deleted from all transactions by specifying a zero TID.
SYSPRV is required to modify transactions with which the process is not currently associated.
BYTLM, ASTLM
$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW
SS$_NORMAL If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully. SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set). SS$_ACCVIO An argument was not accessible to the caller. SS$_BADLOGVER There was an invalid or unsupported log version. SS$_BADPARAM Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero. SS$_BADSTATE There was an invalid transaction state in the ITMLST. Valid states are DTI$K_COMMITTED and DTI$K_ABORTED. SS$_BUGCHECK A failure has occurred during the processing of the request. SS$_EXASTLM The process AST limit (ASTLM) was exceeded. SS$_ILLEFC The event flag number was invalid. SS$_INSFARGS A required argument was missing. SS$_INSFMEM There was insufficient system dynamic memory for the operation. SS$_INVLOG The log format is invalid. SS$_NOSUCHFILE The transaction manager log cannot be found. SS$_NOSUCHNODE The subordinate DECnet node is unknown. SS$_NOSUCHPART The participant is not part of the transaction. SS$_NOSUCHTID The designated TID is unknown. SS$_NOSYSPRV The caller does not have the SYSPRV privilege. SS$_PROTOCOL There is a message protocol error. SS$_REMRSRC There are insufficient resources at the remote node. SS$_UNREACHABLE A superior node is unreachable.
Sets the process current transaction and removes resource managers from transactions.$SETDTIW$ always waits for the request to complete before returning to the caller. Other than this, it is identical to $SETDTI.
SYS$SETDTIW [efn], [flags], iosb, [astadr], [astprm], [contxt], func, itmlst
int sys$setdtiw (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int *contxt, unsigned short int *func, void *itmlst);
Sets an event flag in a local or common event flag cluster. The condition value returned by $SETEF indicates whether the specified flag was previously set or clear. After the event flag is set, processes waiting for the event flag to be set resume execution.
SYS$SETEF efn
int sys$setef (unsigned int efn);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of the event flag to be set. The efn argument is a longword containing this number; however, $SETEF uses only the low-order byte.Two local event flag clusters are local to the process: cluster 0 and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1 contains event flag numbers 32 to 63.
There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127.
SS$_WASCLR The service completed successfully. The specified event flag was previously 0. SS$_WASSET The service completed successfully. The specified event flag was previously 1. SS$_ILLEFC You specified an illegal event flag number. SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.
Assigns a condition handler address to the primary, secondary, or last chance exception vectors, or removes a previously assigned handler address from any of these three vectors.
SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]
int sys$setexv (unsigned int vector, int (*addres)(__unknown_params), unsigned int acmode, void *(*(prvhnd)));
vector
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
Vector for which a condition handler is to be established or removed. The vector argument is a longword value. The value 0 (the default) specifies the primary exception vector; the value 1, the secondary vector; and the value 2, the last chance exception vector.addres
OpenVMS usage: procedure type: procedure value access: call without stack unwinding mechanism: by reference
Condition handler address to be established for the exception vector specified by the vector argument. The addres argument is a longword value containing the address of the condition handler routine.If you do not specify addres or specify it as the value 0, the condition handler address already established for the specified vector is removed; that is, the contents of the longword vector is set to 0.
acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode for which the exception vector is to be modified. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.The most privileged access mode used is the access mode of the caller. Exception vectors for access modes more privileged than the caller's access mode cannot be modified.
prvhnd
OpenVMS usage: procedure value type: longword (unsigned) access: write only mechanism: by reference
Previous condition handler address contained by the specified exception vector. The prvhnd argument is the address of a longword into which $SETEXV writes the handler's procedure value.
The Set Exception Vector service (1) assigns a condition handler address to the primary, secondary, or last chance exception vectors or (2) removes a previously assigned handler address from any of these three vectors. A process cannot modify a vector associated with a more privileged access mode.The operating system provides two different methods for establishing condition handlers:
- Using the call stack associated with each access mode. Each call frame includes a longword to contain the address of a condition handler associated with that frame.
- On VAX systems, the RTL routine LIB$ESTABLISH establishes a condition handler; the RTL routine LIB$REVERT removes a handler.
- Using the software exception vectors (by using $SETEXV) associated with each access mode. These vectors are set aside in the control region (P1 space) of the process.
The modular properties associated with the first method do not apply to the second. The software exception vectors are intended primarily for performance monitors and debuggers. For example, the primary exception vector and the last chance exception vector are used by the OpenVMS Debugger for user mode access, and DCL uses the last chance exception vector for supervisor mode access.
User mode exception vectors are canceled at image exit.
None
None
$DCLCMH, $UNWIND
SS$_NORMAL The service completed successfully. SS$_ACCVIO The longword to receive the previous contents of the vector cannot be written by the caller.
Changes the value of, or recalibrates, the system time.On Alpha systems, this service accepts 64-bit addresses.
SYS$SETIME [timadr]
int sys$setime (struct _generic_64 *timadr);
timadr
OpenVMS usage: date_time type: quadword (unsigned) access: read only mechanism: by 32- or 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
New absolute time value for the system time, specifying the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a quadword containing the new system time value. A negative (delta) time value is invalid.If you do not specify the value of timadr or specify it as 0, $SETIME recalibrates the system time using the time-of-year clock.
The Set System Time service (1) changes the value of or (2) recalibrates the system time, which is defined by a quadword value that specifies the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858.System time is the reference used for nearly all timer-related software activities in the operating system. After changing or recalibrating the system clock, $SETIME updates the timer queue by adjusting each element in the timer queue by the difference between the previous system time and the new system time.
The $SETIME service saves the new time (for future bootstrap operations) in the system image SYS$SYSTEM:SYS.EXE on VAX systems or SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE on Alpha systems. To save the time, the service assigns a channel to the system boot device and calls $QIOW. You need the LOG_IO user privilege to perform this operation.
To set system time, the calling process must have OPER, LOG_IO, and SYSPRV privileges.
None
$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIMR
SS$_NORMAL The service completed successfully. SS$_ACCVIO The quadword that contains the new system time value cannot be read by the caller. SS$_IVTIME The caller specified no time value or a negative time value and an invalid processor clock was found. SS$_NOIOCHAN No I/O channel is available for assignment. SS$_NOPRIV The process does not have the privileges to set the system time.
Sets the timer to expire at a specified time.On Alpha systems, this service accepts 64-bit addresses.
SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]
int sys$setimr (unsigned int efn, struct _generic_64 *daytim, void (*astadr)(__unknown_params), unsigned __int64 reqidt, unsigned int flags);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Event flag to be set when the timer expires. The efn argument is a longword value containing the number of the event flag; however, $SETIMR uses only the low-order byte.If you do not specify efn, event flag 0 is used.
When $SETIMR first executes, it clears the specified event flag or event flag 0.
daytim
OpenVMS usage: date_time type: quadword access: read only mechanism: by 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
Time at which the timer expires. The daytim argument is the 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a quadword time value. A positive time value specifies an absolute time at which the timer expires; a negative time value specifies an offset (delta time) from the current time.astadr
OpenVMS usage: ast_procedure type: procedure value access: call without stack unwinding mechanism: by 64-bit reference (Alpha) mechanism: by 32-bit reference (VAX)
AST service routine that is to execute when the timer expires. The astadr argument is the 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the procedure value of this routine. If you do not specify the value of astadr or specify it as 0 (the default), no AST routine executes.The AST routine, if specified, executes at the access mode of the caller.
reqidt
OpenVMS usage: user_arg type: longword (unsigned) access: read only mechanism: by value
Identification of the timer request. The reqidt argument is a longword value containing a number that uniquely identifies the timer request. If you do not specify reqidt, the value 0 is used.To cancel a timer request, the identification of the timer request (as specified by reqidt in $SETIMR) is passed to the Cancel Timer ($CANTIM) service (as the reqidt argument).
If you want to cancel specific timer requests but not all timer requests, be sure to specify a nonzero value for reqidt in the $SETIMR call; $CANTIM interprets an identification value of 0 as a request to cancel all timer requests.
You can specify unique values for reqidt for each timer request or give the same value to related timer requests. This permits selective canceling of a single timer request, a group of related timer requests, or all timer requests.
If you specify the astadr argument in the $SETIMR call, the value specified by the reqidt argument is passed as a parameter to the AST routine. If the AST routine requires more than one parameter, specify an address for the value of reqidt; the AST routine can then interpret that address as the beginning of a list of parameters.
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Longword of bit flags for the set timer operation. Currently, only bit 0 is used for the flags argument. When the low bit (bit 0) is set, it indicates that this timer request should be in units of CPU time, rather than elapsed time. When bit 0 is clear (the default), the timer request is in units of elapsed time. The flags argument is optional.
The Set Timer service sets the timer to expire at a specified time. When the timer expires, an event flag is set and (optionally) an AST routine executes. This service requires dynamic memory and executes at the access mode of the caller, as does the AST routine if one is specified.None
This service uses the process's timer queue entries (TQELM) quota. If you specify an AST routine, the service uses the AST limit (ASTLM) quota of the process.
$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME
SS$_NORMAL The service completed successfully. SS$_ACCVIO The expiration time cannot be read by the caller. SS$_EXQUOTA The process exceeded its quota for timer entries or its AST limit quota; or the system dynamic memory is insufficient for completing the request. SS$_ILLEFC You specified an illegal event flag number. SS$_INSFMEM The dynamic memory is insufficient for allocating a timer queue entry. SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.
Establishes a routine to receive control after a power recovery is detected.
SYS$SETPRA astadr ,[acmode]
int sys$setpra (int (*astadr)(__unknown_params), unsigned int acmode);
astadr
OpenVMS usage: ast_procedure type: procedure value access: call without stack unwinding mechanism: by reference
Power recovery AST routine to receive control when a power recovery is detected. The astadr argument is the address of this routine.If you specify astadr as the value 0, an AST is not delivered to the process when a power recovery is detected.
The system passes one parameter to the specified AST routine. This parameter is a longword value containing the length of time that the power was off, expressed as the number of 1/100th-of-a-second intervals that have elapsed.
acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode at which the power recovery AST routine is to execute. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.The most privileged access mode used is the access mode of the caller.
The Set Power Recovery AST service establishes a routine to receive control after a power recovery is detected.You can specify only one power recovery AST routine for a process. The AST entry point address is cleared at image exit.
The entry and exit conventions for the power recovery AST routine are the same as for all AST service routines.
None
One unit of quota is deducted from the process's ASTLM.
$DCLAST, $SETAST
For more information, refer to the chapter on AST services in the OpenVMS Programming Concepts Manual.
SS$_NORMAL The service completed successfully. SS$_EXQUOTA The process exceeded its quota for outstanding AST requests.
Changes the base priority of the process. The base priority is used to determine the order in which executable processes are to run.
SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg] ,[nullarg]
int sys$setpri (unsigned int *pidadr, void *prcnam, unsigned int pri, unsigned int *prvpri, unsigned int *pol, unsigned int *prvpol);
pidadr
OpenVMS usage: process_id type: longword (unsigned) access: modify mechanism: by reference
Process identification (PID) of the process whose priority is to be set. The pidadr argument is the address of the PID. The pidadr argument can refer to a process running on the local node or a process running on another node in the cluster.prcnam
OpenVMS usage: process_name type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Process name of the process whose priority is to be changed. The prcnam argument 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 1- to 15-character string. 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 only on behalf of processes in the same UIC group as the calling process. To set the priority for processes in other groups, you must specify the pidadr argument.
pri
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
New base priority to be established for the process. The pri argument is a longword value containing the new priority. Priorities that are not real time are in the range 0 through 15; real-time priorities are in the range 16 through 31.If the specified priority is higher than the base priority of the target process, and if the caller does not have ALTPRI privilege, then the base priority of the target process is used.
prvpri
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
Base priority of the process before the call to $SETPRI. The prvpri argument is the address of a longword into which $SETPRI writes the previous base priority of the process.policy
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
On Alpha systems, address of a longword containing the new scheduling policy for the process.The $JPIDEF macro defines the following symbols for the policy argument:
Symbol Meaning JPI$K_DEFAULT_POLICY The normal scheduling policy. The priority interval for this policy is defined as [0.. n], such that priorities [0..15] are interactive and priorities [16.. n] are real time. JPI$K_PSX_FIFO_POLICY POSIX FIFO scheduling policy. The priority interval for this policy is defined as [ n.. m] real-time priorities. JPI$K_PSX_RR_POLICY POSIX round-robin policy. The priority interval for this policy is defined as [ n.. m] real-time priorities. prvpol
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
On Alpha systems, address of a longword into which the previous scheduling policy for the process is written. If the policy argument is null, no change in policy is requested and prvpol returns the current policy.The valid priority intervals for specific scheduling policies might change in the future. Applications should, therefore, not use embedded numeric constants for scheduling priority, but should use the appropriate $GETSYI item codes to fetch the legal priority intervals. The application can then dynamically select a priority value that is within the interval. The $GETSYI item codes are:
- SYI$_DEF_PRIO_MAX, SYI$_DEF_PRIO_MIN
- SYI$_PSXFIFO_PRIO_MAX, SYI$_PSXFIFO_PRIO_MIN
- SYI$_PSXRR_PRIO_MAX, SYI$_PSXRR_PRIO_MIN
See the Item Codes section of the $GETSYI service description for more information about these item codes.
nullarg
OpenVMS usage: null_arg type: longword (unsigned) access: read only mechanism: by value
Placeholding argument reserved to HP.
The Set Priority service changes the base priority of the process or, optionally, changes the scheduling policy of the process. The base priority is used to determine the order in which executable processes are to run.The scheduling policy denotes the following:
- The basic scheduling discipline (FIFO, round-robin, and so forth).
- The preemption/compensation rules by which a running process is descheduled in favor of another process and, ultimately, rescheduled.
A source process can modify the priority or scheduling policy of a target process if any of the following are true:
- The source and target processes are in the same job tree.
- The source and target processes have the same UIC.
- The source process has WORLD privilege enabled.
- The source and target processes are in the same process group.
The value to which the priority of a process can be set can be subject to limitations. If the source has ALTPRI privilege enabled, the target can be set to any valid priority. Otherwise, the priority value specified by the source process is compared to the authorized priority of the target process and the smaller of the two values is used as the new base priority of the target process.
If you specify neither the pidadr nor the prcnam argument, $SETPRI sets the base priority of the calling process.
If the longword at address pidadr is the value 0, the PID of the target process is returned.
The base priority of a process remains in effect until specifically changed or until the process is deleted.
To determine the priority set by the $SETPRI service, use the Get Job/Process Information ($GETJPI) service.
Depending on the operation, the calling process might need one of the following privileges to use $SETPRI:
- GROUP privilege to change the priority of a process in the same group, unless the target process has the same UIC as the calling process.
- WORLD privilege to change the priority of any other process in the system.
- ALTPRI privilege to set any process's priority to a value greater than the target process's initial base priority. If a process does not have ALTPRI privilege, the priority value specified by the source process is compared to the authorized priority of the target process and the smaller of the two values is used as the new base priority of the target process.
None
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE
SS$_NORMAL The service completed successfully. SS$_ACCVIO The process name string or string descriptor cannot be read by the caller, or the process identification or previous priority longword cannot be written by the caller. SS$_ILLPOLICY An invalid scheduling policy was specified. SS$_ILLPRIPOL Setting the process to the specified priority and/or policy would result in an illegal policy/priority combination. The illegal combination can occur between the SETPRI policy and priority parameters themselves, or it can occur between either of the parameters and the current policy and/or priority of the target process. SS$_INCOMPAT The remote node is running an incompatible version of the operating system. SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters. SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified. SS$_NOPRIV The process does not have the privilege to affect other processes. SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the cluster. SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.) SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)
Allows a process to establish or to change its own process name.
SYS$SETPRN [prcnam]
int sys$setprn (void *prcnam);
prcnam
OpenVMS usage: process_name type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Process name to be given to the calling process. The prcnam argument is the address of a character string descriptor pointing to a 1- to 15-character process name string. If you do not specify prcnam, the calling process is given no name.
The Set Process Name service allows a process to establish or to change its own process name, which remains in effect until you change it (using $SETPRN) or until the process is deleted. Process names provide an identification mechanism for processes executing with the same group number. A process can also be identified by its process identification (PID).None
None
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRV, $SETRWM, $SUSPND, $WAKE
SS$_NORMAL The service completed successfully. SS$_ACCVIO The process name string or string descriptor cannot be read by the caller. SS$_DUPLNAM The specified process name duplicates one already specified within that group. SS$_IVLOGNAM The specified process name has a length of 0 or has more than 15 characters.
Allows a process to change the protection on a page or range of pages.
SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]
int sys$setprt (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode, unsigned int prot, unsigned char *prvprt);
inadr
OpenVMS usage: address_range type: longword (unsigned) access: read only mechanism: by reference
Starting and ending virtual addresses of the range of pages whose protection is to be changed. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.Addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.
If the starting and ending virtual addresses are the same, the protection is changed for a single page.
retadr
OpenVMS usage: address_range type: longword (unsigned) access: write only mechanism: by reference---array reference or descriptor
Starting and ending virtual addresses of the range of pages whose protection was actually changed by $SETPRT. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.If an error occurs while the protection is being changed, $SETPRT writes into retadr the range of pages that were successfully changed before the error occurred. If no pages were affected before the error occurred, $SETPRT writes the value --1 into each longword of the 2-longword array.
acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode associated with the call to $SETPRT. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.The $SETPRT service uses whichever of the following two access modes is least privileged: (1) the access mode specified by acmode or (2) the access mode of the caller. To change the protection of any page in the specified range, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.
prot
OpenVMS usage: page_protection type: longword (unsigned) access: read only mechanism: by value
Page protection to be assigned to the specified pages. The prot argument is a longword value containing the protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.The $PRTDEF macro defines the following symbolic names for the protection codes:
Symbol Description PRT$C_NA No access PRT$C_KR Kernel read only PRT$C_KW Kernel write PRT$C_ER Executive read only PRT$C_EW Executive write PRT$C_SR Supervisor read only PRT$C_SW Supervisor write PRT$C_UR User read only PRT$C_UW User write PRT$C_ERKW Executive read; kernel write PRT$C_SRKW Supervisor read; kernel write PRT$C_SREW Supervisor read; executive write PRT$C_URKW User read; kernel write PRT$C_UREW User read; executive write PRT$C_URSW User read; supervisor write OpenVMS Alpha systems convert PRT$C_NA to the next highest protection, kernel-read.
If you specify the protection as the value 0, the protection defaults to kernel read only.
prvprt
OpenVMS usage: page_protection type: byte (unsigned) access: write only mechanism: by reference
Protection previously assigned to the last page in the range. The prvprt argument is the address of a byte into which $SETPRT writes the protection of this page. The prvprt argument is useful only when protection for a single page is being changed.
The Set Protection on Pages service allows a process to change the protection on a page or range of pages.None
If a process changes the protection for any pages in a private section from read only to read/write, $SETPRT uses the paging file (PGFLQUOTA) quota of the process.
For pages in global sections, the new protection can alter only copy-on-reference pages.
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW
SS$_NORMAL The service completed successfully. SS$_ACCVIO The input address array cannot be read by the caller; the output address array or the byte to receive the previous protection cannot be written by the caller; or an attempt was made to change the protection of a nonexistent page. SS$_EXQUOTA The process exceeded its paging file quota while changing a page in a read-only private section to a read/write page. SS$_IVPROTECT The specified protection code has a numeric value of 1, less than 0, or greater than 15. SS$_LENVIO A page in the specified range is beyond the end of the program or control region. SS$_NOPRIV A page in the specified range is in the system address space; an attempt was made to change the protection of a valid global page, of an invalid global noncopy-on-reference page, or a PFN global or private page. SS$_PAGOWNVIO The process attempted to change the protection on a page owned by a more privileged access mode.
On Alpha systems, allows a process to change the protection on a page or range of pages.This service accepts 64-bit addresses.
SYS$SETPRT_64 start_va_64 ,length_64 ,acmode ,prot ,return_va_64 ,return_length_64 ,return_prot_64
int sys$setprt_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, unsigned int prot, void *(*(return_va_64)), unsigned __int64 *return_length_64, unsigned int *return_prot_64);
start_va_64
OpenVMS usage: address type: quadword address access: read only mechanism: by value
The starting virtual address of the range of pages whose protection is to be changed. The specified virtual address will be rounded down to a CPU-specific boundary.length_64
OpenVMS usage: byte count type: quadword (unsigned) access: read only mechanism: by value
Length of the virtual address space whose protection is to be changed. The specified length will be rounded up to a CPU-specific page boundary so that it includes all CPU-specific pages in the requested range.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode associated with the call to $SETPRT_64. The acmode argument is a longword containing the access mode.The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:
Value Symbolic Name Access Mode 0 PSL$C_KERNEL Kernel 1 PSL$C_EXEC Executive 2 PSL$C_SUPER Supervisor 3 PSL$C_USER User The most privileged access mode used is the access mode of the caller. To change the protection of any page in the specified range, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.
prot
OpenVMS usage: page_protection type: longword (unsigned) access: read only mechanism: by value
Page protection to be assigned to the specified pages. The prot argument is a longword value containing the protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.The $PRTDEF macro for MACRO-32 and the include file PRTDEF.H for C define the symbolic names for the protection codes.
return_va_64
OpenVMS usage: address type: quadword address access: write only mechanism: by 32- or 64-bit reference
The lowest process virtual address of the range of pages whose protection was actually changed. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.return_length_64
OpenVMS usage: byte count type: quadword (unsigned) access: write only mechanism: by 32- or 64-bit reference
The length of the virtual address range whose protection was actually changed. The return_length_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range in bytes.return_prot_64
OpenVMS usage: page_protection type: longword (unsigned) access: write only mechanism: by 32- or 64-bit reference
Protection previously assigned to the last page in the range. The return_prot_64 argument is the 32- or 64-bit virtual address of a naturally aligned longword into which $SETPRT_64 writes the protection of this page. The return_prot_64 argument is useful only when protection for a single page is being changed.
The Set Protection on Pages service allows a process to change the protection on a page or range of pages. For pages in a global section, the new protection can alter only copy-on-reference pages.If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64, return_length_64, and return_prot arguments.
If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully changed before the error occurred. If no pages were changed, the return_va_64 argument will contain the value -1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.
None
If a process changes the protection for any pages in a private section from read-only to read/write, $SETPRT_64 uses the paging file (PGFLQUOTA) quota of the process.
$CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $EXPREG_64, $MGBLSC_64
SS$_NORMAL The service completed successfully. SS$_ACCVIO The return_va_64 or the return_length_64 argument cannot be written by the caller. SS$_EXPGFLQUOTA The process exceeded its paging file quota while changing a page in a read-only private section to a read/write page. SS$_IVPROTECT The specified protection code has a numeric value of 1 or is greater than 15. SS$_LENVIO A page in the specified range is not in process private address space. SS$_NOSUCHPAG An attempt was made to change the protection on a nonexistent page. SS$_PAGNOTINREG A page in the specified range is not within the specified region. SS$_PAGTYPVIO A page in the specified range is not in process private address space. SS$_PAGOWNVIO The process attempted to change the protection on a page owned by a more privileged access mode.
Enables or disables specified privileges for the calling process.
SYS$SETPRV [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]
int sys$setprv (char enbflg, struct _generic_64 *prvadr, char prmflg, struct _generic_64 *prvprv);
enbflg
OpenVMS usage: boolean type: longword (unsigned) access: read only mechanism: by value
Indicator specifying whether the specified privileges are to be enabled or disabled. The enbflg argument is a longword value. The value 1 indicates that the privileges specified in the prvadr argument are to be enabled. The value 0 (the default) indicates that the privileges are to be disabled.prvadr
OpenVMS usage: mask_privileges type: quadword (unsigned) access: read only mechanism: by reference
Privileges to be enabled or disabled for the calling process. The prvadr argument is the address of a quadword bit vector wherein each bit corresponds to a privilege that is to be enabled or disabled.Each bit has a symbolic name. The $PRVDEF macro defines these names. You form the bit vector by specifying the symbolic name of each desired privilege in a logical OR operation. The following table provides the symbolic name and description of each privilege:
User Privilege Symbolic Name Description ACNT PRV$M_ACNT Create processes for which no accounting is done ALLSPOOL PRV$M_ALLSPOOL Allocate a spooled device ALTPRI PRV$M_ALTPRI Set (alter) any process priority AUDIT PRV$V_AUDIT Generate audit records BUGCHK PRV$M_BUGCHK Make bugcheck error log entries BYPASS PRV$M_BYPASS Bypass all protection CMEXEC PRV$M_CMEXEC Change mode to executive CMKRNL PRV$M_CMKRNL Change mode to kernel DIAGNOSE PRV$M_DIAGNOSE Can diagnose devices DOWNGRADE PRV$V_DOWNGRADE Can downgrade classification EXQUOTA PRV$M_EXQUOTA Can exceed quotas GROUP PRV$M_GROUP Group process control GRPNAM PRV$M_GRPNAM Place name in group logical name table GRPPRV PRV$V_GRPPRV Group access by means of system protection field IMPERSONATE PRV$M_IMPERSONATE Create detached processes under another UIC IMPORT PRV$V_IMPORT Mount a nonlabeled tape volume LOG_IO PRV$M_LOG_IO Perform logical I/O operations MOUNT PRV$M_MOUNT Issue mount volume QIO NETMBX PRV$M_NETMBX Create a network device OPER PRV$M_OPER All operator privileges PFNMAP PRV$M_PFNMAP Map to section by physical page frame number PHY_IO PRV$M_PHY_IO Perform physical I/O operations PRMCEB PRV$M_PRMCEB Create permanent common event flag clusters PRMGBL PRV$M_PRMGBL Create permanent global sections PRMMBX PRV$M_PRMMBX Create permanent mailboxes PSWAPM PRV$M_PSWAPM Change process swap mode READALL PRV$V_READALL Possess read access to everything SECURITY PRV$V_SECURITY Can perform security functions SETPRV PRV$M_SETPRV Set any process privileges SHARE PRV$M_SHARE Can assign a channel to a nonshared device SHMEM PRV$M_SHMEM Allocate structures in memory shared by multiple processors SYSGBL PRV$M_SYSGBL Create system global sections SYSLCK PRV$M_SYSLCK Queue systemwide locks SYSNAM PRV$M_SYSNAM Place name in system logical name table SYSPRV PRV$M_SYSPRV Access files and other resources as if you have a system UIC TMPMBX PRV$M_TMPMBX Create temporary mailboxes UPGRADE PRV$V_UPGRADE Can upgrade classification VOLPRO PRV$M_VOLPRO Override volume protection WORLD PRV$M_WORLD World process control If you do not specify prvadr or assign it the value 0, the privileges are not altered.
prmflg
OpenVMS usage: boolean type: longword (unsigned) access: read only mechanism: by value
Indicator specifying whether the privileges are to be affected permanently or temporarily. The prmflg argument is a longword value. The value 1 specifies that the privileges are to be affected permanently, that is, until you change them again by using $SETPRV or until the process is deleted. The value 0 (the default) specifies that the privileges are to be affected temporarily, that is, until the current image exits (at which time the permanently enabled privileges of the process will be restored).Setting the prmflg argument to nonzero changes privilege bits in both the CURPRIV mask and the PROCPRIV mask.
prvprv
OpenVMS usage: mask_privileges type: quadword (unsigned) access: write only mechanism: by reference
Privileges previously possessed by the calling process. The prvprv argument is the address of a quadword bit vector wherein each bit corresponds to a privilege that was previously either enabled or disabled. If you do not specify prvprv or assign it the value 0, the previous privilege mask is not returned.
The Set Privileges service enables or disables specified privileges for the calling process.The operating system maintains four separate privilege masks for each process:
- AUTHPRIV---Privileges that the process is authorized to enable, as designated by the system manager or the process creator. The AUTHPRIV mask never changes during the life of the process.
- PROCPRIV---Privileges that are designated as permanently enabled for the process. The PROCPRIV mask can be modified by $SETPRV.
- IMAGPRIV---Privileges with which the current image is installed.
- CURPRIV---Privileges that are currently enabled. The CURPRIV mask can be modified by $SETPRV.
When a process is created, its AUTHPRIV, PROCPRIV, and CURPRIV masks have the same contents. Whenever a system service (other than $SETPRV) must check the process privileges, that service checks the CURPRIV mask.
When a process runs an installed image, the privileges with which that image was installed are enabled in the CURPRIV mask. When the installed image exits, the PROCPRIV mask is copied to the CURPRIV mask.
The $SETPRV service can set bits only in the CURPRIV and PROCPRIV mask, but $SETPRV checks the AUTHPRIV mask to see whether a process can set specified privilege bits in the CURPRIV or PROCPRIV masks. Consequently, a process can give itself the SETPRV privilege only if this privilege is enabled in the AUTHPRIV mask.
You can obtain each of a process's four privilege masks by calling the $GETJPI (Get Job/Process Information) service and specifying the desired privilege mask or masks as item codes in the itmlst argument. You construct the item code for a privilege mask by prefixing the name of the privilege mask with the characters JPI$_ (for example, JPI$_CURPRIV is the item code for the current privilege mask).
The DCL command SET PROCESS/PRIVILEGES also enables or disables specified privileges; refer to the HP OpenVMS DCL Dictionary for details.
To set a privilege permanently, the calling process must be authorized to set the specified privilege, or the process must be executing in kernel or executive mode.
To set a privilege temporarily, one of the following three conditions must be true:
- The calling process must be authorized to set the specified privilege.
- The calling process must be executing in kernel or executive mode.
- The image currently executing must be one that was installed with the specified privilege.
None
$CANEXH, $CMKRNL, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETRWM, $SUSPND, $WAKE
SS$_NORMAL The service completed successfully. All privileges were enabled or disabled as specified. SS$_NOTALLPRIV The service completed successfully. Not all specified privileges were enabled; see the Description section for details. SS$_ACCVIO The privilege mask cannot be read or the previous privilege mask cannot be written by the caller. SS$_IVSTSFLG You specified a value other than 1 or 0 in either the prmflg argument or the enblfg argument.
Allows a process to specify what action system services should take when system resources required for their execution are unavailable.
Caution
Disabling resource waiting should be performed with caution, as doing so can have unexpected effects on constituent sharable images and runtime libraries.
SYS$SETRWM [watflg]
int sys$setrwm ( char watflg);
watflg
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
Indicator specifying whether system services should wait for required resources. The watflg argument is a longword value. The value 0 (the default) specifies that system services should wait until resources needed for their execution become available. The value 1 specifies that system services should return failure status immediately when resources needed for their execution are unavailable.The operating system enables resource wait mode for all processes. You can disable resource wait mode only by calling $SETRWM.
If resource wait mode is disabled, it remains disabled until it is explicitly reenabled or until the process is deleted.
The Set Resource Wait Mode service allows a process to specify what action system services should take when system resources required for their execution are unavailable.When resource wait mode is enabled, system services wait for the required system resources to become available and then continue execution. When resource wait mode is disabled, system services return to the caller when required system resources are unavailable. The condition value returned by $SETRWM indicates whether resource wait mode was previously enabled or previously disabled.
The following system resources and process quotas are affected by resource wait mode:
- System dynamic memory
- UNIBUS adapter map registers
- Direct I/O limit (DIOLM) quota
- Buffered I/O limit (BIOLM) quota
- Buffered I/O byte count limit (BYTLM) quota
None
None
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SUSPND, $WAKE
SS$_WASCLR The service completed successfully. Resource wait mode was previously enabled. SS$_WASSET The service completed successfully. Resource wait mode was previously disabled.
Controls whether a process automatically unshelves files.
SYS$SETSHLV [pidadr] ,[prcnam] ,[shlvflg]
int sys$setshlv (unsigned int *pidadr, void *prcnam, unsigned int shlvflg);
pidadr
OpenVMS usage: process_id type: longword (unsigned) access: modify mechanism: by reference
Process identification (PID) of the process. The pidadr argument is the address of the PID. The pidadr argument can only refer to a process running on the local node. You cannot modify a process on a remote node.You must specify the pidadr argument to modify a process whose UIC group number is different from that of the calling process.
prcnam
OpenVMS usage: process_name type: character--coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Process name of the process. The prcnam argument is the address of a character string descriptor pointing to the process name. You identify a process with a 1- to 15-character string.You can only use the prcnam argument to modify a process in the same UIC group as the calling process. To modify a process in another UIC group, you must specify the pidadr argument.
shlvflg
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
Value specifying whether automatic unshelving is to be turned on or off. The shlvflg argument is a longword containing this value. The value 0 turns automatic unshelving on. The value 1 turns automatic unshelving off.
The Set Automatic Unshelving service controls whether a process automatically unshelves files.The pidadr and prcnam default to the current process. If the longword at address pidadr is 0, the PID of the target process is returned.
The setting for automatic unshelving is inherited by subprocesses.
The DCL command SET PROCESS/[NO]AUTOUNSHELVE also controls automatic unshelving for a process; refer to the HP OpenVMS DCL Dictionary for details.
Depending on the operation, the calling process might need one of the following privileges to use $SETSHLV:
- GROUP privilege to modify a process in the same group, unless the target process has the same UIC as the calling process.
- WORLD privilege to modify any process in the system.
None
$GETJPI
SS$_WASCLR The service completed successfully. Automatic unshelving was previously on. SS$_WASSET The service completed successfully. Automatic unshelving was previously off. SS$_ACCVIO An argument was not accessible by the caller. SS$_BADPARAM The shlvflg argument was invalid. SS$_IVLOGNAM The prcnam argument was invalid. The process name string had either 0 characters or more than 15 characters. SS$_NONEXPR The specified process did not exist, or the specified process identification was invalid. SS$_NOPRIV The caller did not have the privilege to modify other processes. SS$_REMOTE_PROC The specified process was not on the local node. The service cannot modify a process on a remote node.
Allows a process to change the size of its supervisor, executive, and kernel stacks by altering the values in the stack limit and base arrays held in P1 (per-process) space.
SYS$SETSTK inadr ,[retadr] ,[acmode]
int sys$setstk (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode);
inadr
OpenVMS usage: address_range type: longword (unsigned) access: read only mechanism: by reference
Range of addresses that express the stack's new limits. The inadr argument is the address of a 2-longword array containing, in order, the address of the top of the stack and the address of the base of the stack. Because stacks in P1 space expand from high to low addresses, the address of the base of the stack must be greater than the address of the top of the stack.retadr
OpenVMS usage: address_range type: longword (unsigned) access: write only mechanism: by reference
Range of addresses that express the stack's previous limits. The retadr argument is the address of a 2-longword array into which $SETSTK writes, in the first longword, the previous address of the top of the stack and, in the second longword, the previous address of the base of the stack.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode of the stack to be altered. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes. The most privileged access mode used is the access mode of the caller.If acmode specifies user mode, $SETSTK performs no operation and returns the SS$_NORMAL condition value.
The Set Stack Limits service allows a process to change the size of its supervisor, executive, and kernel stacks by altering the values in the stack limit and base arrays held in P1 (per-process) space.The calling process can adjust the size of stacks only for access modes that are equal to or less privileged than the access mode of the calling process.
None
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW
SS$_NORMAL The service completed successfully. SS$_ACCVIO The input address array cannot be read by the caller; the input range is invalid; or the return address array cannot be written by the caller.
Allows a process to control whether it can be swapped out of the balance set.
SYS$SETSWM [swpflg]
int sys$setswm (char swpflg);
swpflg
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
Indicator specifying whether the process can be swapped. The swpflg argument is a longword value. The value 0 (the default) enables process swap mode, meaning the process can be swapped. The value 1 disables process swap mode, meaning the process cannot be swapped.
The Set Process Swap Mode service allows a process to control whether it can be swapped out of the balance set.When the process swap mode is enabled, the process can be swapped out; when disabled, the process remains in the balance set until (1) process swap mode is reenabled or (2) the process is deleted.
The $SETSWM service returns a condition value indicating whether process swap mode was enabled or disabled prior to the call to $SETSWM.
To change its process swap mode, the calling process must have PSWAPM privilege.
None
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW
To lock some but not necessarily all process pages into the balance set, use the Lock Pages in Memory ($LCKPAG) service.
For more information, refer to the chapter on memory management in the OpenVMS Programming Concepts Manual.
SS$_WASCLR The service completed successfully. The process was not previously locked in the balance set. SS$_WASSET The service completed successfully. The process was previously locked in the balance set. SS$_NOPRIV The process does not have the necessary PSWAPM privilege.
Modifies the user authorization file (UAF) record for a specified user.
SYS$SETUAI [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg] ,[nullarg] ,[nullarg]
int sys$setuai (unsigned int efn, unsigned int *contxt, void *usrnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);
nullarg
OpenVMS usage: null_arg type: longword (unsigned) access: read only mechanism: by value
Placeholding argument reserved to HP.efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Placeholding argument reserved to HP.contxt
OpenVMS usage: longword type: longword (unsigned) access: modify mechanism: by reference
A longword used to maintain authorization file context. The contxt argument is the address of a longword to receive a $SETUAI context value. On the initial call, this longword should contain the value --1. On subsequent calls, the value of the contxt argument from the previous call should be passed back in.usrnam
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor--fixed-length string descriptor
Name of the user whose UAF record is modified. The usrnam argument is the address of a descriptor pointing to a character text string containing the user name. The user name string can contain a maximum of 32 alphanumeric characters.itmlst
OpenVMS usage: item_list_3 type: longword (unsigned) access: read only mechanism: by reference
Item list specifying which information from the specified UAF record is to be modified. The itmlst argument is the address of a list of one or more item descriptors, each of which specifies an item code. The item list is terminated by the item code 0 or by the longword 0.The following diagram depicts the format of a single item descriptor:
The following table defines the item descriptor fields:
| Descriptor Field | Definition |
|---|---|
| Buffer length | A word specifying the length (in bytes) of the buffer in which $SETUAI is to write the information. The length of the buffer varies, depending on the item code specified in the item code field of the item descriptor, and is given in the description of each item code. If the value of the buffer length field is too small, $SETUAI truncates the data. |
| Item code | A word containing a user-supplied symbolic code specifying the item of information that $SETUAI is to set. The $UAIDEF macro defines these codes. |
| Buffer address | A longword address of the buffer that specifies the information to be set by $SETUAI. |
| Return length address | A longword containing the user-supplied address of a word in which $SETUAI writes the length in bytes of the information it actually set. |
The symbolic codes have the following format:
|
UAI$_code |
| OpenVMS usage: | io_status_block |
| type: | quadword (unsigned) |
| access: | write only |
| mechanism: | by reference |
| OpenVMS usage: | ast_procedure |
| type: | procedure entry mask |
| access: | call without stack unwinding |
| mechanism: | by reference |
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
UAI$_ACCOUNT
Sets, as a blank-padded 32-character string, the account name of the user.An account name can include up to 8 characters. Because the account name is a blank-filled string, however, the buffer length field of the item descriptor should specify 32 (bytes).
UAI$_ASTLM
Sets the AST queue limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_BATCH_ACCESS_P
Sets, as a 3-byte value, the range of times during which batch access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_BATCH_ACCESS_S
Sets, as a 3-byte value, the range of times during which batch access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_BIOLM
Sets the buffered I/O count limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_BYTLM
Sets the buffered I/O byte limit.Because the buffered I/O count limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_CLITABLES
Sets, as a character string, the name of the user-defined CLI table for the account, if any.Because the CLI table name can include up to 31 characters plus a size-byte prefix, the buffer length field of the item descriptor should specify 32 (bytes).
UAI$_CPUTIM
Sets the maximum CPU time limit (per session) for the process in 10-millisecond units.Because the maximum CPU time limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_DEFCLI
Sets, as an OpenVMS RMS file name component, the name of the command language interpreter used to execute the specified batch job. The file specification set assumes the device name and directory SYS$SYSTEM and the file type .EXE.Because a file name can include up to 31 characters plus a size-byte prefix, the buffer length field in the item descriptor should specify 32 (bytes).
UAI$_DEFDEV
Sets, as a 1- to 31-character string, the name of the default device.Because the device name string can include up to 31 characters plus a size-byte prefix, the buffer length field in the item descriptor should specify 32 (bytes).
UAI$_DEFDIR
Sets, as a 1- to 63-character string, the name of the default directory.Because the directory name string can include up to 63 characters plus a size-byte prefix, the buffer length field in the item descriptor should specify 64 (bytes).
UAI$_DEF_PRIV
Sets, as a quadword value, the default privileges for the user.Because the default privileges are set as a quadword value, the buffer length field in the item descriptor should specify 8 (bytes).
UAI$_DFWSCNT
Sets, in pages (on VAX systems) or pagelets (on Alpha systems), the default working set size.Because the default working set size is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_DIALUP_ACCESS_P
Sets, as a 3-byte value, the range of times during which dialup access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_DIALUP_ACCESS_S
Sets, as a 3-byte value, the range of times during which dialup access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_DIOLM
Sets the direct I/O count limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_ENCRYPT
Sets one of the values shown in the following table to identify the encryption algorithm for the primary password:
Symbolic Name Description UAI$C_AD_II Uses a CRC algorithm and returns a longword hash value. It was used in VAX VMS releases prior to Version 2.0. UAI$C_PURDY Uses a Purdy algorithm over salted input. It expects a blank-padded user name and returns a quadword hash value. This algorithm was used during VAX VMS Version 2.0 field test. UAI$C_PURDY_V Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This algorithm was used in VMS releases prior to Version 5.4. UAI$C_PURDY_S Uses the Purdy algorithm over salted input. It expects a variable-length user name and returns a quadword hash value. This is the current algorithm that the operating system uses for all new password changes. UAI$C_PREFERED_ALGORITHM Represents the latest encryption algorithm that the operating system uses to encrypt new passwords. Currently, it equates to UAI$C_PURDY_S. HP recommends that you use this symbol in source modules. Because the encryption algorithm is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).
UAI$_ENCRYPT2
Sets one of the following values, indicating the encryption algorithm for the secondary password. Refer to the UAI$_ENCRYPT item code for a description of the algorithms.UAI$C_AD_II
UAI$C_PURDY
UAI$C_PURDY_V
UAI$C_PURDY_S
UAI$C_PREFERED_ALGORITHMUAI$_ENQLM
Sets the lock queue limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_EXPIRATION
Sets, as a quadword absolute time value, the expiration date and time of the account.Because the absolute time value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).
UAI$_FILLM
Sets the open file limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_FLAGS
Sets, as a longword bit vector, the various login flags set for the user.Each flag is represented by a bit. The $UAIDEF macro defines the following symbolic names for these flags:
Symbol Description UAI$V_AUDIT All actions are audited. UAI$V_AUTOLOGIN User can only log in to terminals defined by the Automatic Login facility (ALF). UAI$V_CAPTIVE User is restricted to captive account. UAI$V_DEFCLI User is restricted to default command interpreter. UAI$V_DISACNT User account is disabled. Same as /FLAG = DISUSER qualifier in AUTHORIZE. UAI$V_DISCTLY User cannot use Ctrl/Y. UAI$V_DISFORCE_PWD_CHANGE User will not be forced to change expired passwords at login. UAI$V_DISIMAGE User cannot issue the RUN or MCR commands or use the foreign command mechanism in DCL. UAI$V_DISMAIL Announcement of new mail is suppressed. UAI$V_DISPWDDIC Automatic checking of user-selected passwords against the system dictionary is disabled. UAI$V_DISPWDHIS Automatic checking of user-selected passwords against previously used passwords is disabled. UAI$V_DISRECONNECT User cannot reconnect to existing processes. UAI$V_DISREPORT User will not receive last login messages. UAI$V_DISWELCOME User will not receive the login welcome message. UAI$V_EXTAUTH User is considered externally authenticated by an external user ID and password and not by the SYSUAF user name and password. The SYSUAF record is still used for checking login restrictions and quotas and for creating the user's OpenVMS process profile. UAI$V_GENPWD User is required to use generated passwords. UAI$V_LOCKPWD SET PASSWORD command is disabled. UAI$V_MIGRATEPWD User's SYSUAF password was set using AUTHORIZE or SYS$SETUAI and is likely to be inconsistent with the user's external user password. If password migration is enabled, the system will attempt to update the external authorization service the next time the user attempts a login. UAI$V_NOMAIL Mail delivery to user is disabled. UAI$V_PWD_EXPIRED Primary password is expired. UAI$V_PWD2_EXPIRED Secondary password is expired. UAI$V_RESTRICTED User is limited to operating under a restricted account. Clear the CAPTIVE flag (UAI$V_CAPTIVE), if set, before setting the RESTRICTED flag. (Refer to the HP OpenVMS Guide to System Security for a description of restricted and captive accounts.) UAI$_JTQUOTA
Sets the initial byte quota with which the jobwide logical name table is to be created.Because this quota is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_LASTLOGIN_I
Sets, as a quadword absolute time value, the date of the last interactive login.UAI$_LASTLOGIN_N
Sets, as a quadword absolute time value, the date of the last noninteractive login.UAI$_LGICMD
Sets, as an OpenVMS RMS file specification, the name of the default login command file.Because a file specification can include up to 63 characters plus a size-byte prefix, the buffer length field of the item descriptor should specify 64 (bytes).
UAI$_LOCAL_ACCESS_P
Sets, as a 3-byte value, the range of times during which local interactive access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_LOCAL_ACCESS_S
Sets, as a 3-byte value, the range of times during which local interactive access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_LOGFAILS
Sets the count of login failures.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_MAXACCTJOBS
Sets the maximum number of batch, interactive, and detached processes that can be active at one time for all users of the same account. The value 0 represents an unlimited number.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_MAXDETACH
Sets the detached process limit. The value 0 represents an unlimited number.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_MAXJOBS
Sets the active process limit. A value of 0 represents an unlimited number.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_NETWORK_ACCESS_P
Sets, as a 3-byte value, the range of times during which network access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_NETWORK_ACCESS_S
Sets, as a 3-byte value, the range of times during which network access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_OWNER
Sets, as a character string, the name of the owner of the account.Because the owner name can include up to 31 characters plus a size-byte prefix, the buffer length field of the item descriptor should specify 32 (bytes).
UAI$_PASSWORD
Sets the specified plaintext string as the primary password for the user and updates the primary password change date. You must have SYSPRV privilege to set passwords for any user account (including your own).The UAI$_PASSWORD and UAI$_PASSWORD2 item codes provide the building blocks for designing a site-specific SET PASSWORD utility. Note that if you create such a utility, you should also set the LOCKPWD bit in the user authorization file (UAF) to prevent users from using the DCL command SET PASSWORD and to prevent the LOGINOUT process from forcing password changes. If you create a site-specific SET PASSWORD utility, install the utility with SYSPRV privilege.
You must adhere to the following guidelines when specifying a password with UAI$_PASSWORD or UAI$_PASSWORD2:
- The password must meet the minimum password length defined for the user account.
- The password cannot exceed 32 characters in length.
- The password must be different from the previous password.
To clear the primary password, specify the value 0 in the buffer length field.
When you use $SETUAI to change the password on an account that has the UAI$V_EXTHAUTH flag set, the UAI$V_MIGRATEPWD flag is set automatically.
Note
If you specify UAI$_PASSWORD, the UAI$_PWD_DATE item is ignored.UAI$_PASSWORD2
Sets the specified plaintext string as the secondary password for the user and updates the secondary password change date. You must have SYSPRV privilege to set passwords for any user account (including your own).To clear the secondary password, specify the value 0 in the buffer length field.
Note
If you specify UAI$_PASSWORD2, the UAI$_PWD2_DATE item is ignored.UAI$_PBYTLM
Sets the paged buffer I/O byte count limit.Because the paged buffer I/O byte count limit is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_PGFLQUOTA
Sets, in pages (on VAX systems) or pagelets (on Alpha systems), the paging file quota.Because the paging file quota is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_PRCCNT
Sets the subprocess creation limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_PRI
Sets the default base priority.Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).
UAI$_PRIMEDAYS
Sets, as a byte bit vector, the primary and secondary days of the week.Each bit represents a day of the week, with the bit clear representing a primary day and the bit set representing a secondary day. The $UAIDEF macro defines the following symbolic names for these bits:
UAI$V_MONDAY
UAI$V_TUESDAY
UAI$V_WEDNESDAY
UAI$V_THURSDAY
UAI$V_FRIDAY
UAI$V_SATURDAY
UAI$V_SUNDAYUAI$_PRIV
Sets, as a quadword value, the names of the privileges that the user holds.Because the privileges are set as a quadword value, the buffer length field in the item descriptor should specify 8 (bytes).
UAI$_PWD
Sets, as a quadword value, the hashed primary password of the user.Because the hashed primary password is set as a quadword value, the buffer length field in the item descriptor should specify 8 (bytes).
When you use $SETUAI to change the password on an account that has the UAI$V_EXTHAUTH flag set, the UAI$V_MIGRATEPWD flag is set automatically.
UAI$_PWD_DATE
Sets, as a quadword absolute time value, the date of the last password change.Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).
A value of --1 indicates that the password could be marked as preexpired.
Note
If you specify UAI$_PASSWORD, the UAI$_PWD_DATE item is ignored.UAI$_PWD_LENGTH
Sets the minimum password length.Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).
UAI$_PWD_LIFETIME
Sets, as a quadword delta time value, the password lifetime.Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).
A quadword of 0 means that none of the password mechanisms will take effect.
UAI$_PWD2
Sets, as a quadword value, the hashed secondary password of the user.Because the hashed secondary password is set as a quadword value, the buffer length field in the item descriptor should specify 8 (bytes).
UAI$_PWD2_DATE
Sets, as a quadword absolute time value, the last date the secondary password was changed.Because this value is a quadword in length, the buffer length field in the item descriptor should specify 8 (bytes).
A value of --1 indicates that the password could be marked as preexpired.
Note
If you specify UAI$_PASSWORD2, the UAI$_PWD2_DATE item is ignored.UAI$_QUEPRI
Sets the maximum job queue priority in the range 0 through 31.Because this decimal number is a byte in length, the buffer length field in the item descriptor should specify 1 (byte).
UAI$_REMOTE_ACCESS_P
Sets, as a 3-byte value, the range of times during which batch access is permitted for primary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_REMOTE_ACCESS_S
Sets, as a 3-byte value, the range of times during which batch access is permitted for secondary days. Each bit set represents a 1-hour period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_SALT
Sets the salt field of the user's record to the value you provide. The salt value is used in the operating system hash algorithm to generate passwords. $SETUAI does not generate a new salt value for you.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
By copying the item codes UAI$_SALT, UAI$_ENCRYPT, UAI$_PWD, UAI$_PWD_DATE, and UAI$_FLAGS, a site-security administrator can construct a utility that propagates password changes throughout the network. Note, however, that HP does not recommend using the same password on more than one node in a network.
UAI$_SHRFILLM
Sets the shared file limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_TQCNT
Sets the timer queue entry limit.Because this decimal number is a word in length, the buffer length field in the item descriptor should specify 2 (bytes).
UAI$_UIC
Sets, as a longword, the user identification code (UIC). For the format of the UIC, refer to the HP OpenVMS Guide to System Security.UAI$_USER_DATA
Sets up to 255 bytes of information in the user data area of the system user authorization file (SYSUAF). This is the supported method for modifying the user data area of the SYSUAF. HP no longer supports direct user modification of the SYSUAF.To clear all the information in the user data area of the SYSUAF, specify $SETUAI with a buffer length field of 0.
UAI$_WSEXTENT
Sets the working set extent, in pages (on VAX systems) or pagelets (on Alpha systems), specified for the specified job or queue.Because the working set extent is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
UAI$_WSQUOTA
Sets the working set quota, in pages (on VAX systems) or pagelets (on Alpha systems), for the specified user.Because the working set quota is a longword decimal number, the buffer length field in the item descriptor should specify 4 (bytes).
The Set User Authorization Information service is used to modify the user authorization file (UAF) record for a specified user.The UAI$V_PWD_EXPIRED should only be set when the bit UAI$V_DISFORCE_PWD_CHANGE is set in the user's SYSUAF record and the comparison between the UAI$_PWD_DATE and UAI$_PWD_LIFETIME indicates a password is past its valid life.
For information about login and password expiration, see the Description section of the $GETUAI system service.
The following list describes the privileges you need to use the $SETUAI service:
- BYPASS or SYSPRV---Allows modification of any record in the UAF (user authorization file).
- GRPPRV---Allows modification of any record in the UAF whose UIC group matches that of the requester. Note, however, that you cannot change a UAF record whose UIC matches exactly the requester's UIC. Group managers with GRPPRV privilege are limited in the extent to which they can modify the UAF records of users in the same group; values such as privileges and quotas can be changed only if the modification does not exceed the values set in a group manager's UAF record.
- No privilege---Does not allow access to any UAF record.
None
$GETUAI
SS$_NORMAL The service completed successfully. SS$_ACCVIO The item list or input buffer cannot be read by the caller; or the return length buffer, output buffer, or status block cannot be written by the caller. SS$_BADPARAM The function code is invalid; the item list contains an invalid item code; a buffer descriptor has an invalid length; or the reserved parameter has a nonzero value. SS$_NOGRPPRV The user does not have the privileges required to modify the authorization information for other members of the UIC group. SS$_NOSYSPRV The user does not have the privileges required to modify the authorization information associated with the user or for users outside of the user's UIC group. RMS$_RSZ The UAF record is smaller than required; the caller's SYSUAF is likely corrupt.
This service can also return OpenVMS RMS status codes associated with operations on indexed files. For a description of RMS status codes that are returned by this service, refer to the OpenVMS Record Management Services Reference Manual.
| Previous | Next | Contents | Index |