HP OpenVMS Systems Documentation

Creates and initializes a process context that is used by $GETJPI toscan processes on the local system or across the nodes in an OpenVMSCluster system.

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

Format

SYS$PROCESS_SCAN pidctx [,itmlst]

C Prototype

int sys$process_scan (unsigned int *pidctx, void *itmlst);

Arguments

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 thepidadr argument of $GETJPI. Thepidctx argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a longword that isto receive the process context longword. This longword normallycontains 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 aprevious 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 tocontrol the scan.

The itmlst argument is the 32-bit address (on VAXsystems) or the 32- or 64-bit address (on Alpha systems) of a list ofitem descriptors, each of which describes one selection criterion orcontrol option. Within each selection criterion you can include severalitem entries. An item list in 32-bit format is terminated by a longwordof 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 or64-bit.

The information in the item list is passed to the item descriptor inone of two ways. If the item descriptor can always hold the actualvalue of the selection criterion, the value is placed in the secondlongword of the item descriptor and the buffer length is specified as0. If the item descriptor points to the actual value of the selectioncriterion, the address of the value is placed in the second longword ofthe item descriptor and you must specify the buffer length for theselection criterion. Each item code description specifies whether theinformation is passed by value or by reference.

The following diagram depicts the format of a 32-bit item descriptorthat passes the selection criterion as a value:

The following diagram depicts the format of a 64-bit item descriptorthat passes the selection criterion as a value:

The following diagram depicts the format of a 32-bit item descriptorthat passes the selection criterion by reference:

The following diagram depicts the format of a 64-bit item descriptorthat passes the selection criterion by reference:

The following table defines the item descriptor fields:

Item Codes

PSCAN$_ACCOUNT

When you specify PSCAN$_ACCOUNT, $GETJPI returns information aboutprocesses that match the account field.

If the string supplied in the item descriptor is shorter than theaccount field, the string is blank-padded for the comparison unless theitem-specific flag PSCAN$M_PREFIX_MATCH is present.

Because the information is a character string, the selection value ispassed by reference. The length of the buffer is placed in the firstword of the item descriptor and the address of the buffer is placed inthe second longword.

Although the current length of the account field is 8 bytes, thePSCAN$_ACCOUNT buffer can be up to 64 bytes in length. If the bufferlength is 0 or greater than 64, the SS$_IVBUFLEN error is returned.

PSCAN$_AUTHPRI

When you specify PSCAN$_AUTHPRI, $GETJPI returns information aboutprocesses that match the authorized base priority field.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_CURPRIV

When you specify PSCAN$_CURPRIV, $GETJPI returns information aboutprocesses that match the current privilege field. Privilege bits aredefined by the $PRVDEF macro.

Because the bit mask information is too long to be passed by value, theinformation is passed by reference. The privilege buffer must beexactly 8 bytes, otherwise the SS$_IVBUFLEN error is returned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_GETJPI_BUFFER_SIZE

When you specify PSCAN$_GETJPI_BUFFER_SIZE, you determine the size of abuffer to be used by $GETJPI to process multiple requests in a singlemessage. Using this item code can greatly improve the performance ofscans on remote nodes, because fewer messages are needed. This itemcode is ignored during scans on the local node.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0. The buffer is allocated by $PROCESS_SCAN; you do nothave 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 thesame item code information. Because $GETJPI locates information formore than one process at a time, it is not possible to change the itemcodes or the length of the buffers used in the $GETJPI item list.$GETJPI checks each call and returns the error SS$_BADPARAM if anattempt 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 istransparent to a calling program, you are not required to change theway $GETJPI is called when you use this item code.

The $GETJPI buffer uses the process quota BYTLM. If the buffer is toolarge for the process quota, $GETJPI (not $PROCESS_SCAN) returns theerror SS$_EXBYTLM. If the buffer specified is not large enough tocontain the data for at least one process, $GETJPI returns the errorSS$_BADPARAM.

No item-specific flags are used with PSCAN$_GETJPI_BUFFER_SIZE.

PSCAN$_GRP

When you specify PSCAN$_GRP, $GETJPI returns information aboutprocesses that match the UIC group number.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. Because the value of the groupnumber is a word, the high-order word of the value is ignored. Thebuffer length must be specified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_HW_MODEL

When you specify PSCAN$_HW_MODEL, $GETJPI returns information aboutprocesses 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 thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_HW_NAME

When you specify PSCAN$_HW_NAME, $GETJPI returns information aboutprocesses that match the specified CPU hardware name, such asVAX-11/780, VAX 8800, or VAXstation II/GPX.

Because the information is a character string, the selection value ispassed by reference. The length of the selection value is placed in thefirst word of the item descriptor and the address of the buffer isplaced in the second longword.

The PSCAN$_HW_NAME buffer can be up to 128 bytes in length. If thebuffer length is 0 or greater than 128, the SS$_IVBUFLEN error isreturned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_JOBPRCCNT

When you specify PSCAN$_JOBPRCCNT, $GETJPI returns information aboutprocesses that match the subprocess count for the job (the count of allsubprocesses in the job tree).

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_JOBTYPE

When you specify PSCAN$_JOBTYPE, $GETJPI returns information aboutprocesses that match the job type. The job type values include thefollowing:

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 checkedby PSCAN$_JOBTYPE are similar to PSCAN$_MODE values.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_KT_COUNT

When you specify PSCAN$_KT_COUNT, $PROCESS_SCAN uses the current countof kernel threads for the process as a selection criteria.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_MASTER_PID

When you specify PSCAN$_MASTER_PID, $GETJPI returns information aboutprocesses that are descendants of the specified parent process. Themaster process is the first process created in the job tree. ThePSCAN$_OWNER item is similar, but the owner process is the process thatcreated the target process (the owner process might itself be asubprocess). 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 thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_MEM

When you specify PSCAN$_MEM, $GETJPI returns information aboutprocesses that match the UIC member number.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. Because the value of the membernumber is a word, the high-order word of the value is ignored. Thebuffer length must be specified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_MODE

When you specify PSCAN$_MODE, $GETJPI returns information aboutprocesses that match the specified mode. Mode values include thefollowing:

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 checkedby PSCAN$_MODE are similar to PSCAN$_JOBTYPE values.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_MULTITHREAD

When you specify PSCAN$_MULTITHREAD, $PROCESS_SCAN uses the maximumcount of kernel threads for the process as a selection criteria.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_NODE_CSID

When you specify PSCAN$_NODE_CSID, $GETJPI returns information aboutprocesses on the specified nodes. To scan all nodes in an OpenVMSCluster system, you specify a CSID of 0 and the item-specific flagPSCAN$M_NEQ.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_NODENAME

When you specify PSCAN$_NODENAME, $GETJPI returns information aboutprocesses that match the specified node names.

To scan all of the nodes in an OpenVMS Cluster system, specify the nodename using an asterisk wildcard (*) and the PSCAN$M_WILDCARDitem-specific flag.

Because the information is a character string, the selection value ispassed by reference. The length of the selection value is placed in thefirst word of the item descriptor and the address of the buffer isplaced in the second longword.

Although the current length of the node name is 6 bytes, thePSCAN$_NODENAME buffer can be up to 64 bytes in length. If the bufferlength is 0 or greater than 64, the SS$_IVBUFLEN error is returned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_OWNER

When you specify PSCAN$_OWNER, $GETJPI returns information aboutprocesses that are immediate descendants of the specified process. ThePSCAN$_MASTER_PID item is similar, but the owner process is the processthat created the target process (the owner process might itself be asubprocess). 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 thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_PRCCNT

When you specify PSCAN$_PRCCNT, $GETJPI returns information aboutprocesses that match the subprocess count (the count of all immediatedescendants of a given process). The PSCAN$_JOBPRCCNT item code issimilar, except that JOBPRCCNT is the count of all subprocesses in ajob.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_PRCNAM

When you specify PSCAN$_PRCNAM, $GETJPI returns information aboutprocesses that match the specified process names.

The process name string is blank-padded for the comparison unless theitem-specific flag PSCAN$M_PREFIX_MATCH is present.

Because the information is a character string, the selection value ispassed by reference. The length of the selection value is placed in thefirst word of the item descriptor and the address of the buffer isplaced in the second longword.

Although the current length of the process name field is 15 bytes, thePSCAN$_PRCNAM buffer can be up to 64 bytes in length. If the bufferlength is 0 or greater than 64, the SS$_IVBUFLEN error is returned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_PRI

When you specify PSCAN$_PRI, $GETJPI returns information aboutprocesses that match current priority. Note that the current priorityof a process can be temporarily increased as a result of system eventssuch as the completion of I/O.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_PRIB

When you specify PSCAN$_PRIB, $GETJPI returns information aboutprocesses that match base priority.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_STATE

When you specify PSCAN$_STATE, $GETJPI returns information aboutprocesses that match the specified process state. State values, forexample 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 thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_STS

When you specify PSCAN$_STS, $GETJPI returns information that matchesthe current status mask. Without any item-specific flags, the match isfor a process mask that is equal to the pattern. Status bits, forexample PCB$V_ASTPEN or PCB$V_PSWAPM, are defined by the $PCBDEF macro.

This bit mask item code uses an immediate value descriptor; theselection value is placed in the second longword of the itemdescriptor. The buffer length must be specified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_TERMINAL

When you specify PSCAN$_TERMINAL, $GETJPI returns information thatmatches the specified terminal names. The terminal name string isblank-padded for the comparison unless the item-specific flagPSCAN$M_PREFIX_MATCH is present.

Because the information is a character string, the selection value ispassed by reference. The length of the selection value is placed in thefirst word of the item descriptor and the address of the buffer isplaced in the second longword.

Although the current length of the terminal name field is 8 bytes, thePSCAN$_TERMINAL buffer can be up to 64 bytes in length. If the bufferlength is 0 or greater than 64, the SS$_IVBUFLEN error is returned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_UIC

When you specify PSCAN$_UIC, $GETJPI returns information aboutprocesses that match the UIC identifier. To convert an alphanumericidentifier name to the internal identifier, use the $ASCTOID systemservice before calling $PROCESS_SCAN.

This integer item code is passed by value; the value is placed in thesecond longword of the item descriptor. The buffer length must bespecified as 0.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$_USERNAME

When you specify PSCAN$_USERNAME, $GETJPI returns information aboutprocesses that match the specified user name.

The user name string is blank-padded for the comparison unless theitem-specific flag PSCAN$M_PREFIX_MATCH is present.

Because the information is a character string, the selection value ispassed by reference. The length of the selection value is placed in thefirst word of the item descriptor and the address of the buffer isplaced in the second longword.

Although the current length of the user name field is 12 bytes, thePSCAN$_USERNAME buffer can be up to 64 bytes in length. If the bufferlength is 0 or greater than 64, the SS$_IVBUFLEN error is returned.

The flags that can be used with this item code are listed inTable SYS-48.

PSCAN$M_BIT_ALL

If the PSCAN$M_BIT_ALL flag is used, all bits set in the pattern maskspecified 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 andstatus words, this flag controls how the pattern bit mask specified bythe 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 thepattern mask is also set in the process mask.

For item codes that describe bit masks, such as privilege masks andstatus words, this flag controls how the pattern bit mask specified bythe 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 stringspecified by the item descriptor with the character string value fromthe process, $PROCESS_SCAN does not distinguish between uppercase andlowercase letters.

The PSCAN$M_CASE_BLIND flag is used only with character-string itemcodes. The PSCAN$M_CASE_BLIND flag can be specified with either thePSCAN$M_PREFIX_MATCH flag or the PSCAN$M_WILDCARD flag.

PSCAN$M_EQL

When you specify PSCAN$M_EQL, $PROCESS_SCAN compares the valuespecified by the item descriptor with the value from the process to seeif 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 theflags can be specified; if more than one of these flags is used, theSS$_BADPARAM error is returned. If you want to specify that bits notset in the pattern mask must not be set in the process mask, usePSCAN$M_EQL.

PSCAN$M_GEQ

When you specify PSCAN$M_GEQ, $PROCESS_SCAN selects a process if thevalue from the process is greater than or equal to the value specifiedby the item descriptor.

PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used withinteger 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 isreturned.

PSCAN$M_GTR

When you specify PSCAN$M_GTR, $PROCESS_SCAN selects a process if thevalue from the process is greater than the value specified by the itemdescriptor.

PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used withinteger 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 isreturned.

PSCAN$M_LEQ

When you specify PSCAN$M_LEQ, $PROCESS_SCAN selects a process if thevalue from the process is less than or equal to the value specified bythe item descriptor.

PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used withinteger 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 isreturned.

PSCAN$M_LSS

When you specify PSCAN$M_LSS, $PROCESS_SCAN selects a process if thevalue from the process is less than the value specified by the itemdescriptor.

PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS are used withinteger 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 isreturned.

PSCAN$M_NEQ

When you specify PSCAN$M_NEQ, $PROCESS_SCAN selects a process if thevalue from the process is not equal to the value specified by the itemdescriptor.

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 theflags can be specified; if more than one of these flags is used, theSS$_BADPARAM error is returned.

PSCAN$M_OR

When you specify PSCAN$M_OR, $PROCESS_SCAN selects processes whosevalues match the current item descriptor or the next item descriptor.The next item descriptor must have the same item code as the itemdescriptor with the PSCAN$M_OR flag. Multiple items are chainedtogether; all except the last item descriptor must have the PSCAN$M_ORflag.

The PSCAN$M_OR flag can be specified with any other flag and can beused with bit masks, character strings, and integers. If the PSCAN$M_ORflag is used between different item codes, or if it is missing betweenidentical item codes, the SS$_BADPARAM error is returned.

PSCAN$M_PREFIX_MATCH

When you specify PSCAN$M_PREFIX_MATCH, $PROCESS_SCAN compares thecharacter string specified in the item descriptor to the leadingcharacters of the requested process value.

For example, to find all process names that start with the lettersAB, use the string AB with the PSCAN$M_PREFIX_MATCHflag. If you do not specify the PSCAN$M_PREFIX_MATCH flag, the searchlooks for a process with the 2-character process name AB.

The PSCAN$M_PREFIX_MATCH flag also allows either the PSCAN$M_EQL or thePSCAN$M_NEQ flag to be specified. If you specify PSCAN$M_NEQ, theservice matches those names that do not begin with thespecified character string.

The PSCAN$M_PREFIX_MATCH flag is used only with character string itemcodes. The PSCAN$M_PREFIX_MATCH flag cannot be specified with thePSCAN$M_WILDCARD flag; if both of these flags are used, theSS$_BADPARAM error is returned.

PSCAN$M_WILDCARD

When you specify PSCAN$M_WILDCARD, the character string specified bythe item descriptor is assumed to be a wildcard pattern. Acceptablewildcard characters are the asterisk (*), which allows the match tosubstitute any number of character in place of the asterisk, and thepercent sign (%), which allows the match to substitute any onecharacter in place of the percent sign. For example, if you want tosearch for all process names that begin with the letter A andend with the string ER, use the string A*ER with thePSCAN$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. ThePSCAN$M_WILDCARD flag cannot be specified with the PSCAN$M_PREFIX_MATCHflag; if both of these flags are used, the SS$_BADPARAM error isreturned. The PSCAN$M_NEQ flag can be used with PSCAN$M_WILDCARD toexclude values during a wildcard search.

The following restrictions apply to the flags above:

• Only one of the flags PSCAN$M_EQL, PSCAN$M_NEQ, PSCAN$M_BIT_ALL, PSCAN$M_BIT_ANY can be specified.
• PSCAN$M_CASE_BLIND item-specific flag also allows either the PSCAN$M_EQL or the PSCAN$M_NEQ flag to be specified.
• Only one of the flags PSCAN$M_EQL and PSCAN$M_WILD_CARD can be specified.

Description

The Process Scan system service creates and initializes a processcontext that is used by $GETJPI to scan processes on the local systemor across the nodes in an OpenVMS Cluster system. An item list is usedto specify selection criteria to obtain information about specificprocesses, for example, all processes owned by one user or all batchprocesses.

The output of the $PROCESS_SCAN service is a process context longwordnamed pidctx. This process context is then provided to$GETJPI as the pidadr argument. The process contextprovided by $PROCESS_SCAN enables $GETJPI to search for processesacross the nodes in an OpenVMS Cluster system and to select processesthat match certain selection criteria.

The process context consumes process dynamic memory. This memory isdeallocated when the end of the context is reached. For example, whenthe $GETJPI service returns SS$_NOMOREPROC or when $PROCESS_SCAN iscalled again with the same pidctx longword, thedynamic memory is deallocated. If you anticipate that a scan might beinterrupted before it runs out of processes, $PROCESS_SCAN should becalled a second time (without an itmlst argument) torelease the memory. Dynamic memory is automatically released when thecurrent image terminates.

$PROCESS_SCAN copies the item list and user buffers to the allocateddynamic memory. This means that the item lists and user buffers can bedeallocated or reused immediately; they are not referenced during thecalls to $GETJPI.

The item codes referenced by $PROCESS_SCAN are found in data structuresthat are always resident in the system, primarily the process controlblock (PCB) and the job information block (JIB). A scan of processesnever forces a process that is swapped out of memory to be brought intomemory to read nonresident information.

See the $GETJPI service for a C program example that uses the$PROCESS_SCAN service.

Required Access or Privileges

None

Required Quota

See the description for the PSCAN$_GETJPI_BUFFER_SIZE item.

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,$HIBER, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

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 thecalling process to make room for pages required by a new programsegment.

Format

SYS$PURGWS inadr

C Prototype

int sys$purgws (struct _va_range *inadr);

Argument

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 bepurged. The inadr argument is the address of a2-longword array containing, in order, the starting and ending processvirtual addresses. The addresses are adjusted up or down to fall onCPU-specific page boundaries. Only the virtual page number portion ofeach virtual address is used; the low-order byte-within-page bits areignored.

Description

The Purge Working Set service removes a specified range of pages fromthe current working set of the calling process to make room for pagesrequired by a new program segment; however, the Adjust Working SetLimit ($ADJWSL) service is the preferred mechanism for controlling aprocess's use of physical memory resources.

The $PURGWS service locates pages within the specified range andremoves them if they are in the working set.

If the starting and ending virtual addresses are the same, only thatsingle page is purged.

To purge the entire working set, specify a range of pages from 0through 7FFFFFFF; in this case, the image continues to execute andpages are faulted back into the working set as they are needed. If youexceed this range, the service returns SS$_NOPRIV. On Alpha systems,use the $PURGE_WS service to specify a larger page range.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,$LKWSET, $MGBLSC, $PURGE_WS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG,$ULWSET, $UPDSEC, $UPDSECW

Condition Values Returned

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 currentworking set of the calling process to make room for pages required by anew program segment.

This service accepts 64-bit addresses.

Format

SYS$PURGE_WS start_va_64 ,length_64

C Prototype

int sys$purge_ws (void *start_va_64, unsigned __int64 length_64);

Arguments

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 workingset. The specified virtual address will be rounded down to aCPU-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 boundaryso that it includes all CPU-specific pages in the requested range.

Description

The Purge Working Set service removes a specified range of pages fromthe current working set of the calling process to make room for pagesrequired by a new program segment; however, the Adjust Working SetLimit ($ADJWSL) service is the preferred mechanism for controlling aprocess's use of physical memory resources.

The $PURGE_WS service locates pages within the specified range andremoves them if they are in the working set. To purge the entireworking set, specify a range of pages from 0 through FFFFFFFF.FFFFFFFF(or to the highest possible process private virtual address, availablefrom $GETJPI); in this case, the image continues to execute, and pagesare faulted back into the working set.

Required Privileges

None

Required Quota

None

Related Services

$ADJWSL, $LCKPAG_64, $LKWSET_64, $PURGWS, $ULKPAG_64, $ULWSET_64

Condition Values Returned

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 thisservice.

Writes informational and error messages to processes.

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

Format

SYS$PUTMSG msgvec ,[actrtn] ,[facnam] ,[actprm]

C Prototype

int sys$putmsg (void *msgvec, void (*actrtn)(__unknown_params), void*facnam, unsigned __int64 actprm);

Arguments

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 bewritten and options that $PUTMSG is to use in writing the message ormessages. The msgvec argument is the 32- or 64-bitaddress (on Alpha systems) or the 32-bit address (on VAX systems) ofthe message vector.

The message vector consists of one longword followed by one or moremessage descriptors, one descriptor per message. The following diagramdepicts the contents of the first longword:

The following table describes the message vector fields:

The following table shows the significant bit numbers. Note that thebit numbers shown (0, 1, 2, 3) are the bit positions from the beginningof the word; however, because the word is the second word in thelongword, you should add the number 16 to each bit number to specifyits exact offset within the longword.

Bits 4 through 15 must be 0.

You can override the default setting specified by the default messageoptions field for any or all messages by specifying different optionsin the new message options field of any subsequent message descriptor.When you specify new message options, the options it specifies becomethe new default settings for all remaining messages until you specifynew 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 defaultmessage options for the process are used; you can set the processdefault message options by using the DCL command SET MESSAGE.

The Description section shows the format that $PUTMSG uses to writethese message components.

Message Descriptors

Following the first longword of the message vector are one or moremessage descriptors. A message descriptor can have one of four possibleformats, depending on the type of message it describes. There are fourtypes of messages:

• User-supplied
• System
• OpenVMS RMS
• System exception

The following diagrams depict the message descriptors for each type ofmessage:

Message Descriptor for User-Supplied Messages

Message Descriptor for System Messages

Message Descriptor for OpenVMS RMS Messages

Message Descriptor for System Exception Messages

On Alpha systems, 64-bit message vectors can be used for applicationsthat require them. A 64-bit message vector begins with the sameargument count longword as the 32-bit message vector. After theargument count longword is another longword containing the valueSS$_SIGNAL64, which signals that a 64-bit message vector follows.Subsequent message vector elements have a layout analogous to 32-bitmessage vectors but are 64-bits wide.

For example, the following diagram depicts the format of a 32-bitmessage vector:

The 64-bit version of that same message vector would have the followingformat:

The $PUTMSG service accepts either the 32-bit or the 64-bit form of themessage vector on Alpha systems.

actrtn

Note that the first argument passed to the action routine is theaddress 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 butbefore it is actually written to the user.

The completion code in general register R0 from the action routineindicates whether the message should be written. If the low-order bitof R0 is set (1), then the message will be written. If the low-orderbit is cleared (0), then the message will not be written.

If you do not specify actrtn or specify it as 0 (thedefault), no action routine executes.

Because $PUTMSG writes messages only to SYS$ERROR and SYS$OUTPUT, anaction routine is useful when output must be directed to, for example,a file.

facnam

If you do not specify facnam, $PUTMSG uses the defaultfacility prefix associated with the message.

actprm

Description

In the operating system, a message is identified by a longword value,which is called the message code. To construct a message code, youspecify values for its four fields, using the Message utility. Thefollowing diagram depicts the longword message code:

Thus, each message has a unique longword value associated with it: itsmessage code. You can give this longword value a symbolic name usingthe Message utility. Such a symbolic name is called the message symbol.

The Message utility describes how to construct a message symbolaccording to the conventions for operating system messages. Basically,the message symbol has two parts: (1) a facility prefix, which is anabbreviation of the name of the facility with which the message isassociated, and (2) a mnemonic name for the message text, which servesto hint at the nature of the message. These two parts are separated byan underscore character (_) in the case of a user-constructed messageand by a dollar sign/underscore ($_) in the case of system messages.

The message components written by $PUTMSG are derived both from themessage code and from the message symbol. For additional informationabout both the message code and the message symbol, refer to theOpenVMS Command Definition, Librarian, and Message Utilities Manual.

The $PUTMSG service writes the message components in the followingformat:

where:

The $PUTMSG service does not check the length of the argument list andtherefore 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 notappear in the output.

You cannot call the $PUTMSG service from kernel mode.

Required Access or Privileges

None

Required Quota

None

Related Services

$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

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Example

#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. Thisservice completes asynchronously; for synchronous completion, use theQueue I/O Request and Wait ($QIOW) service.

For additional information about system service completion, refer tothe Synchronize ($SYNCH) service.

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

Format

SYS$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2] ,[p3],[p4] ,[p5] ,[p6]

C Prototype

int sys$qio (unsigned int efn, unsigned short int chan, unsigned intfunc, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5,__int64 p6);

Arguments

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. Theefn argument is a longword value containing the numberof 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 eventflag 0 if efn was not specified.

The specified event flag is set if the service terminates withoutqueuing 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 thenumber of the I/O channel; however, $QIO uses only the low-order word.

Specifying an invalid value for the chan argument willresult 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 theoperation to be performed. The func argument is alongword containing the function code.

Each device has its own function codes and function modifiers. Forcomplete information about the function codes and function modifiersthat apply to the particular device to which the I/O operation is to bedirected, 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/Ooperation. The iosb argument is the address of thequadword I/O status block. The following diagram depicts the structureof the I/O status block.

The following table defines the I/O status block fields.

When $QIO begins execution, it clears the quadword I/O status block ifthe iosb argument is specified.

Though this argument is optional, HP strongly recommends that youspecify it, for the following reasons:

• If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
• If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
• 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 $QIO service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $QIO, you must first check the condition value returned in R0. If R0 contains a successful value, then you must check the condition value in the I/O status block.

astadr

The AST routine executes at the access mode of the caller of $QIO.

astprm

p1 to p6

For more information about these parameters, refer to the HP OpenVMS I/O User's Reference Manual.

Description

The Queue I/O Request service operates only on assigned I/O channelsand only from access modes that are equal to or more privileged thanthe access mode from which the original channel assignment was made.

The $QIO service uses system dynamic memory to construct a database toqueue the I/O request and might require additional memory depending onthe queued device.

For $QIO, you can synchronize completion (1) by specifying theastadr argument to have an AST routine execute whenthe I/O completes or (2) by calling the Synchronize ($SYNCH) service toawait completion of the I/O operation. The $QIOW service completessynchronously, and it is the best choice when synchronous completion isrequired.

For information about how to use the $QIO service for networkoperations, refer to the DECnet for OpenVMS Networking Manual.

Required Access or Privileges

LOG_IO or PHY_IO is required, depending upon the device type and therequested operation. DIAGNOSE is required to issue a $QIO with anassociated diagnostic buffer. In addition, read or write access isgenerally required for the device. For more information, refer to theHP OpenVMS Guide to System Security.

Required Quota

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

Related Services

$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

Condition Values Returned

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.

Condition Values Returned in the I/O Status Block

Device-specific condition values; the HP OpenVMS I/O User's Reference Manual lists thesecondition values for each device.

The Queue I/O Request and Wait service queues an I/O request to achannel associated with a device.

The $QIOW service completes synchronously; however, Digital recommendsthat 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 informationabout $QIOW, refer to the description of $QIO.

For additional information about system service completion, refer tothe Synchronize ($SYNCH) service.

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

Format

SYS$QIOW [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1] ,[p2],[p3] ,[p4] ,[p5] ,[p6]

C Prototype

int sys$qiow (unsigned int efn, unsigned short int chan, unsigned intfunc, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64astprm, 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 Readservice using block I/O can be performed on any file organization.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Returns the current status of all 32 event flags in a local or commonevent flag cluster and indicates whether the specified event flag isset or clear.

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

Format

SYS$READEF efn ,state

C Prototype

int sys$readef (unsigned int efn, unsigned int *state);

Arguments

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 flagwithin a cluster requests that $READEF return the status of all eventflags in that cluster.

There are two local event flag clusters, which are local to theprocess: cluster 0 and cluster 1. Cluster 0 contains event flag numbers0 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 containsevent 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. Thestate argument is the 32- or 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of a longword intowhich $READEF writes the state (set or clear) of the 32 event flags inthe cluster.

Condition Values Returned

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 synchronousoperations. 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 callerafter the system completes the requested operation. For additionalinformation about system service completion, see the Synchronize($SYNCH) system service.

This system service is 64-bit compatible.

Format

SYS$REGISTRY [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr orastadr_64] [,astprm or astprm_64] [,timeout]

C Prototype

int sys$registry (unsigned int efn, unsigned int func, void *, void*itmlst, struct _iosb *iosb, ...);

Arguments

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 specifythe event flag, the system defaults to event flag 0. The event flag isinitially cleared by $REGISTRY and then set when the operationcompletes.

func

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

Function code specifying the action that $REGISTRY is to perform. Thefunc argument is a longword containing this functioncode. The function code can contain function modifiers. For moreinformation on function modifiers, see the FunctionModifiers section.

A single call to $REGISTRY can specify only one function code. Allfunction codes require additional information to be passed in the callwith 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 thefunction 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. Eachdescriptor is either an item_list_3 or item_list_64b format.

Some function codes allow you to specify multiple operations in asingle call. In this case, you must place the REG$_SEPARATOR item codebetween each set of item codes. Each request, separated by aREG$_SEPARATOR item code, can contain the item codes in any order.

You can specify item codes as either input or output parameters. Inputparameters modify functions, set context, or describe the informationto be returned. Output parameters return the requested information.

For item_list_3 lists, you must terminate the list with a longword of0. For item_list_64b lists, you must terminate the list with a quadwordof 0.

The following diagram shows the structure of anitem_list_3 descriptor:

The following diagram shows the structure of anitem_list_64b descriptor:

The following table defines the item descriptor fields:

iosb or iosa_64

If multiple operations are requested for a function code, the valuereturned in iosb is either SS$_NORMAL or SS$_REGERROR.

A more specific return status for each operation is returned in theREG$_RETURNSTATUS item code (if specified).

The iosb argument is the address of the $REGISTRYstatus block:

When $REGISTRY begins execution, it clears the quadword I/O statusblock if you specify the iosb argument.

Although the iosb argument is optional, HP stronglyrecommends that you specify it for the following reasons:

• If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
• If you are using the $SYNCH system service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.

The condition value returned in R0 and the condition value returned inthe I/O status block provide information about different aspects of thecall to the $REGISTRY service. The condition value returned in R0provides information about the success or failure of the service callitself; the condition value returned in the I/O status block providesinformation 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 containsa successful value, you must check the condition value in the I/Ostatus block.

The following table defines the item descriptor fields:

astadr or astadr_64

If the $REGISTRY service is not called successfully (that is, if itreturns an error immediately), the AST routine is not executed.

astprm or astprm_64

timeout

You can find a detailed description of each item code in theItem Codes section.

The OpenVMS Registry identifier is required only if you do not provide avalid NT access token and you do not have the SYSPRV privilege. If youhave a granted REG$UPDATE identifier, you can perform all the functionsin Table SYS-49.

REG$FC_CLOSE_KEY

This request releases the open resources of the specified key. IfREG$_KEYID indicates a predefined key, the system ignores the actionand 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 thekey specified by REG$_KEYID. If the key does exist, the system does notmodify it.

If you specify the REG$_KEYRESULT item code, the system opens thespecified subkey.

The system returns the result in the REG$_DISPOSITION item code buffer.

Using this function code, you can group multiple requests into a singlecall to the $REGISTRY service. To use the multiple-request feature, youmust use the REG$_SEPARATOR item code to indicate the end of the set ofitem codes for the current request and that there is another request toprocess.

To set a value for a key, call the $REGISTRY service with theREG$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 pathalready defined in the OpenVMS Registry; otherwise the system returns theREG$_INVALIDPATH error.

Note If you do not specify the REG$_CACHEACTION item code, the new key iscreated with the same cache action value as the parent key. The samerule applies to the REG$_VOLATILE and REG$_SECURITYPOLICY item codes.

REG$FC_DELETE_KEY

This request removes the specified subkey and its values from theOpenVMS Registry database. If the specified key has subkeys, the key isnot deleted. You must delete the subkeys first.

Using this function code, you can group multiple requests into a singlecall to the $REGISTRY service. If you use this multiple-requestfeature, use the REG$_SEPARATOR item code to indicate the end of theset of item codes for the current request and that there is anotherrequest 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 singlecall to the $REGISTRY service. If you use this multiple-requestfeature, use the REG$_SEPARATOR item code to indicate the end of theset of item codes for the current request and that there is anotherrequest 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. Youidentify 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 untilthe 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 keyidentifier. The value to retrieve is identified in the REG$_VALUEINDEXitem 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 untilthe 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 allattributes 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 itemcode with an address of zero. You cannot add a link to a key that haseither values or subkeys (or both).

REG$FC_MODIFY_TREE_KEY

This request modifies a specified key and all its subkey attributes. Nolink 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 anyof its subkeys has changed. That is, the requested function waits forthe 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 systemopens 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 specifiedvalue name.

Using this function code, you can group multiple requests into a singlecall to the $REGISTRY service.

If you use this multiple-request feature, use the REG$_SEPARATOR itemcode to indicate the end of the set of item codes for the currentrequest 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 matchwith 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 threeitem codes.

The REG$_FLAGOPCODE item code specifies how the REG$_DATAFLAGS itemcode should be matched against the database. (See the item codesdescription for more information about the REG$_FLAGOPCODE item code.)

Every time the system finds a match, it appends the path name relativeto the specified key to the REG$_PATHBUFFER item code. A Unicode nullcharacter is used to separate the value path names.

If the buffer supplied by the application is not big enough to hold allthe value path names found, the system returns the SS$_BUFFEROVF errormessage in the iosb argument, and the length requiredto complete the operation successfully is returned in theREG$_REQLENGTH item (if specified).

Use the ellipsis (...) wildcard to match zero or more subkeys in theREG$_KEYPATH item code.

(For example,Hardware\...\disks finds all the paths that start with theHardware subkey and end with thedisk subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion ofa subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name inthe 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 aspecified key path.

For this function code, a valid key path is a Unicode string that caninclude the ellipsis (...), asterisk (*), or percent (%) wildcardcharacter, but that cannot start with the backslash character (\).

Use the ellipsis (...) wildcard to match zero or more subkeys in theREG$_KEYPATH item code. (For example,Hardware\...\disks finds all the paths that start with theHardware subkey and end with thedisk subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion ofa subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name inthe 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 namerelative to the specified key identifier to the REG$_PATHBUFFER itemcode. A Unicode null character (4 bytes) separates the subkey pathnames.

If the buffer supplied by the application is not big enough to containall the subkey path names found, the system returns the SS$_BUFFEROVFerror message in the iosb argument, and the systemreturns the required length to complete the operation successfully inthe 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 aspecified value name.

For this function code a valid key name is a Unicode string that caninclude the ellipsis (...), asterisk (*), or percent (%) wildcardcharacter, but cannot start with the backslash character (\).

Use the ellipsis (...) wildcard to match zero or more subkeys in theREG$_KEYPATH item code. (For example,Hardware\...\disks finds all the paths that start with theHardware subkey and end with thedisk subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion ofa subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name inthe 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 caninclude the asterisk (*) and percent (%) wildcard characters.

Every time the system finds a match, the system appends its path namerelative to the specified key identifier to the REG$_PATHBUFFER itemcode. A Unicode null character (4 bytes) separates the subkey pathnames.

If the buffer supplied by the application is not big enough to containall the subkey path names found, the system returns the SS$_BUFFEROVFerror message in the iosb argument, and the systemreturns the required length to complete the operation successfully inthe 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 singlecall to the $REGISTRY service.

If you use this multiple-request feature, use the REG$_SEPARATOR itemcode to indicate the end of the set of item codes for the currentrequest and that there is another request to process.

When a value is set to a link, the system validates the link unless youspecify 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 sectionsthat follow this table.

REG$_CACHEACTION

The REG$_CACHEACTION item code is an input item code. It is a longwordflag that specifies whether the information on a specified objectshould be written to disk immediately. It takes one of the followingvalues:

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 itsvalue 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, eitheran input or output item code.

The class name is an information field for a key. The type of an objectis an example of a class name. It can be composed of any string ofUnicode characters. A Unicode character is 4 bytes long.

REG$_CLASSNAMEMAX

The REG$_CLASSNAMEMAX item code is an output item code. It receives thelength, in bytes, of the longest string specifying a subkey class name.

REG$_DATAFLAGS

Depending on the function code, the REG$_DATAFLAGS item code is eitheran input or output item code. It is a 64-bit application-dependentvalue data flag.

REG$_DATATYPE

Depending on the function code, the REG$_DATATYPE item code is eitheran input or output item code.

It is a longword that either specifies the type of information to bestored as a value data or receives the type of information of aspecified 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. Manyvalue entries in the OpenVMS Registry are written using astring (REG_SZ) or an expandablestring (REG_EXPAND_SZ) format. An expandable string is usually human-readable text, but it can alsoinclude a variable that will be replaced when the string is called byan 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 longwordand 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 longwordflag that indicates how the REG$_DATAFLAGS input item code should bematched against the data flags field in the OpenVMS Registry database. Ittakes 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 longwordBoolean 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 thatcontains the key identifier.

REG$_KEYRESULT

The REG$_KEYRESULT item code is an output item code. It is a longwordthat receives a key identifier. The key identifier can be passed toother Registry calls using the REG$_KEYID item code.

REG$_KEYPATH

The REG$_KEYPATH item code is an input item code. It is a string ofUnicode characters that specifies a key path. A Unicode character is 4bytes long.

REG$_LASTWRITE

The REG$_LASTWRITE item code is an output item code. It is a quadwordrepresentation of absolute time that receives the time a specified keywas last written to (including changes to its values).

REG$_LINKCOUNT

The REG$_LINKCOUNT item code is an output item code. It is longwordcount of the number of symbolic links that refer to the item.

REG$_LINKPATH

The REG$_LINKPATH item code is, depending on the function code, eitheran input or an output item code. It is a string of Unicode charactersthat specifies the key path to which a specified key is linked. AUnicode character is 4 bytes long.

REG$_LINKTYPE

The REG$_LINKTYPE item code is, depending on the function code, eitheran input or an output item code. It is longword type that indicates thelink 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 thatspecifies the new name of the key.

REG$_NOTIFYFILTER

The REG$_NOTIFYFILTER item code is an input item code. It is a longwordmask that specifies which changes to the specified key and its subkeysand 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 theREG$_FLAGSUBKEY item code is set to 1.

REG$_PATHBUFFER

The REG$_PATHBUFFER item code is an output item code. It is a bufferthat receives a set of either key paths or value paths, separated by anull Unicode character (4 bytes long). (The third longword of the itemdescriptor contains the number of bytes written to the buffer.)

REG$_REQLENGTH

The REG$_REQLENGTH item code is an output item code. It is a longwordthat receives the required buffer size (in bytes) to complete theoperation successfully.

REG$_RETURNSTATUS

The REG$_RETURNSTATUS item code is an output item code. It is alongword that receives the final completion status for a specifiedoperation. For more information, see the Condition ValuesReturned section of this chapter.

REG$_SECACCESS

The REG$_SECACCESS item code is an input item code. It is a longwordmask that specifies the desired security access for the new key. Ittakes 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_SETVALUE
REG$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_NOTIFY
REG$M_SETVALUE	Allows setting of values and data.
REG$M_WRITE	A combination of the following access values: REG$K_CREATESUBKEY REG$K_SETVALUE

REG$_SECURITYPOLICY

The REG$_SECURITYPOLICY item code is an input item code. It is alongword 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 aseparator between sets of item codes.

Using this item code, you can group multiple requests into a singlecall to the $REGISTRY service. If you use this multiple-requestfeature, use the REG$_SEPARATOR item code to indicate the end of theset of item codes for the current request and that there is anotherrequest to process.

REG$_SUBKEYINDEX

The REG$_SUBKEYINDEX item code is an input item code. It is a longwordthat specifies the index of the subkey to retrieve.

REG$_SUBKEYNAME

The REG$_SUBKEYNAME item code is an input item code. It is a string ofUnicode characters that specifies the name of a subkey. A Unicodecharacter is 4 bytes long.

REG$_SUBKEYNAMEMAX

The REG$_SUBKEYNAMEMAX item code is an output item code. It is alongword that receives the length (in characters) of a specified key'slongest subkey name.

REG$_SUBKEYSNUMBER

The REG$_SUBKEYSNUMBER item code is an output item code. It is alongword that receives the number of subkeys contained in a specifiedkey.

REG$_VALUEDATA

The REG$_VALUEDATA item code is, depending on the function code, eitheran input or output item code. It is a buffer that contains either thevalue data component to write to the OpenVMS Registry (input), or itreceives a data value component from the OpenVMS Registry (output).

REG$_VALUEDATAMAX

The REG$_VALUEDATAMAX item code is an output item code. It is alongword that receives the length (in bytes) of the specified key'slongest data component value.

REG$_VALUEDATASIZE

The REG$_VALUEDATASIZE item code is an output item code. It is used tospecify the address and size of a buffer that receives the length, inbytes, 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 longwordthat specifies the index of the value to retrieve within a specifiedkey. Note that the value index starts at zero and can be any value upto one less than the count returned by REG$_VALUENUMBER.

REG$_VALUENAME

The REG$_VALUENAME item code is, depending on the function code, eitheran input or an output item code. It is a string of Unicode charactersthat specifies the name of a value.

REG$_VALUENAMEMAX

The REG$_VALUENAMEMAX item code is an output item code. It is alongword that receives the length (in characters) of a specified key'slongest value name.

REG$_VALUENUMBER

The REG$_VALUENUMBER item code is an output item code. It is a longwordthat receives the number of values contained in a specified key.

REG$_VOLATILE

The REG$_VOLATILE item code identifies the volatility of an item. As anoutput, it returns the volatility of the object. On OpenVMS, volatilekeys and values are lost when all nodes running an OpenVMS Registry serverare rebooted. (In a standalone system, volatile keys and values arelost 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_SENSITIVEwith the function REG$FC_CREATE_KEY. When you use the function andfunction modifier together, the data passed to the OpenVMS Registry istreated as case sensitive. The two values are written in HP C asREG$M_CASE_SENSITIVE | REG$FC_CREATE_KEY.

The OpenVMS Registry function modifiers are defined in the header fileREGDEF.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 akey or a value.

By default, if a key or value is symbolically linked to another key orvalue, the system follows all links so that the operation specified bythe function code is performed on the linked key or value.

When you specify the REG$M_IGNORE_LINKS function modifier, theoperation specified by the function code affects only the specified keyor value, not the linked key or value.

By default, if a key or value has a symbolic link, it can not bedeleted. If you specify the REG$M_IGNORE_LINKS function modifier, thesystem deletes the key or value.

REG$M_NOW

Write to disk immediately, regardless of the REG$_CACHEACTION item codevalue.

Description

The $REGISTRY service provides the means to create, delete and modifyregistry 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 systemdynamic memory to deliver AST requests.

Related Services

$REGISTRYW

Condition Values Returned

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.

Condition Values Returned in the I/O Status Block

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 systemservices: $CLREF, $SYNCH, $PERSONA_EXTENSION_LOOKUP, and $PERSONA_QUERY.

Interface to the OpenVMS Registry database server.

The $REGISTRY service supports both asynchronous and synchronousoperations. 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 callerafter the system completes the requested operation. For additionalinformation about system service completion, see the Synchronize($SYNCH) system service.

This system service is 64-bit compatible.

Format

SYS$REGISTRYW [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr orastadr_64] [,astprm or astprm_64] [,timeout]

C Prototype

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 therecord file address (RAB$W_RFA) field of the RAB.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Releases ownership of an OpenVMS Galaxy lock.

Note that this system service is supported only in an OpenVMS AlphaGalaxy environment.

For more information about programming with OpenVMS Galaxy systemservices, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

Format

SYS$RELEASE_GALAXY_LOCK handle

C Prototype

int sys$release_galaxy_lock (unsigned __int64 lock_handle);

Arguments

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. Thisvalue is returned by SYS$CREATE_GALAXY_LOCK.

Description

This service releases ownership of an OpenVMS Galaxy lock. Because aGalaxy lock can be acquired multiple times by the same owner (nestedownership), the lock is not released until the ownership count goes tozero. If the lock ownership is completely released and there are otherthreads waiting for the lock, they are released from their wait states.

Required Access or Privileges

Write access to lock.

Required Quota

None

Related Services

$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

Condition Values Returned

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 vectorconsumer.

Format

SYS$RELEASE_VP

Arguments

None.

Description

The Release Vector Processor service terminates the current process'status as a vector consumer. The $RELEASE_VP service waits for allpending vector instructions and vector memory operations to complete.It then declares that the process no longer needs a vector-presentprocessor. As a result, the process relinquishes its use of theprocessor's vector registers and can be scheduled on another processorin the system.

In systems that do not have vector-present processors but do have theVAX Vector Instruction Emulation facility (VVIEF) in use, this servicerelinquishes the process's use of VVIEF. VVIEF remains mapped in theprocess's address space.

Required Access or Privileges

None

Required Quota

None

Related Services

$RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION

Condition Values Returned

SS$_NORMAL

The service completed successfully.

The Remove service deletes a file name from a directory. It is thereverse of the Enter service.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Deletes the specified holder record from the target identifier's listof holders.

Format

SYS$REM_HOLDER id ,holder

C Prototype

int sys$rem_holder (unsigned int id, struct _generic_64 *holder);

Arguments

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 alongword 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 completesexecution. The holder argument is the address of aquadword containing the UIC identifier of the holder in the firstlongword and the value of 0 in the second longword.

Description

The Remove Holder Record from Rights Database service removes thespecified holder record from the target identifier's list of holders.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

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

Condition Values Returned

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 OpenVMSRMS, this service can also return RMS status codes associated withoperations 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 (ifany) from the rights database.

Format

SYS$REM_IDENT id

C Prototype

int sys$rem_ident (unsigned int id);

Argument

id

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

Binary value of identifier deleted from rights database when $REM_IDENTcompletes execution. The id argument is a longwordcontaining the identifier value.

Description

The Remove Identifier from Rights Database service removes from therights database the specified identifier record, all its holder records(if any), and all records in identifiers that the deleted identifierheld.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

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

Condition Values Returned

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 OpenVMSRMS, this service can also return RMS status codes associated withoperations 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 ofa file, or to move a file to another directory by changing itsdirectory specification. However, you cannot use this service to move afile to another device.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Requests reschedule of a process.

Format

SYS$RESCHED

C Prototype

int sys$resched (void);

Arguments

None.

Description

The Reschedule Process service requests that the set of runnableprocesses on the system be evaluated by their priority, with thepotential result that the current process may be descheduled andrequeued.

$RESCHED is intended to allow a process running at priority nto voluntarily relinquish the remainder of its run quantum to anotherprocess of the same priority. When the set of all runnable processes isevaluated, one of the following will occur:

1. 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.
2. 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.

Required Access or Privileges

None

Required Quota

None

Related Services

None

Condition Values Returned

SS$_NORMAL

The service completed successfully.

On VAX systems, restores the saved exception state of the vectorprocessor.

Format

SYS$RESTORE_VP_EXCEPTION excid

Argument

excid

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

Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. Theexcid argument is the address of a longword containingthis ID.

Description

The Restore Vector Processor Exception State service restores frommemory the vector exception state saved by a prior call to$SAVE_VP_EXCEPTION. After a routine invokes this service, the nextvector instruction issued within the process causes the restored vectorexception to be reported.

By default, when an AST or condition handler interrupts the executionof a mainline routine, the operating system saves the mainlineroutine's vector state, including its vector exception state. Any otherroutine that executes synchronously with, or asynchronously to,currently executing vectorized code and that performs vector operationsitself must preserve the preempted routine's vector exception stateacross its own execution. It does so by using the $SAVE_VP_EXCEPTIONand $RESTORE_VP_EXCEPTION services.

Used together, these services ensure that vector exceptions occurringas a result of activity in the original routine are serviced byexisting condition handlers within that routine.

In systems that do not have vector-present processors but do have theVAX Vector Instruction Emulation facility (VVIEF) in use, VVIEFemulates the function of this service.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$RELEASE_VP, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION

Condition Values Returned

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 restorethe vector state of the mainline routine.

Format

SYS$RESTORE_VP_STATE

Arguments

None.

Description

The Restore Vector State service allows an AST routine or a conditionhandler to restore the vector state of the process's mainline routine.

By default, when an asynchronous routine (AST routine or conditionhandler) interrupts the execution of a mainline routine, the operatingsystem creates a new vector state when the routine issues its firstvector instruction. At this point, the vector state of the mainlineroutine is inaccessible to the asynchronous routine. If theasynchronous routine must manipulate the vector state of the mainlineroutine, it first calls $RESTORE_VP_STATE to restore the mainline'svector state.

In systems that do not have vector-present processors but do have theVAX Vector Instruction Emulation facility (VVIEF) in use, VVIEFemulates the functions of this service.

This service can be called only from a routine running in user mode.

Required Access or Privileges

None

Required Quota

None

Related Services

$RELEASE_VP, $RESTORE_VP_EXCEPTION, $SAVE_VP_EXCEPTION

Condition Values Returned

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 subsequentsuspend request.

Format

SYS$RESUME [pidadr] ,[prcnam]

C Prototype

int sys$resume (unsigned int *pidadr, void *prcnam);

Arguments

pidadr

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

Process identification (PID) of the process to be resumed. Thepidadr argument is the address of a longwordcontaining the PID. The pidadr argument can refer to aprocess running on the local node or a process running on another nodein the cluster.

You must specify the pidadr argument to deleteprocesses 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 argumentis the address of a character string descriptor pointing to the processname.

A process running on the local node can be identified with a 1- to15-character string. To identify a process on a particular node on acluster, specify the full process name, which includes the node name aswell as the process name. The full process name can contain up to 23characters.

You can use the prcnam argument to resume onlyprocesses in the same UIC group as the calling process, because processnames are unique to UIC groups, and the operating system uses the UICgroup number of the calling process to interpret the process namespecified by the prcnam argument. You must use thepidadr argument to delete processes in other UICgroups.

Description

The Resume Process service (1) causes a process previously suspended bythe Suspend Process ($SUSPND) service to resume execution or (2)cancels the effect of a subsequent suspend request.

If you specify neither the pidadr norprcnam argument, the resume request is issued onbehalf of the calling process.

If the longword value at address pidadr is 0, the PIDof the target process is returned.

If one or more resume requests are issued for a process that is notsuspended, a subsequent suspend request completes immediately; that is,the process is not suspended. No count of outstanding resume requestsis maintained.

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing 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

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,$HIBER, $PROCESS_SCAN, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,$WAKE

Condition Values Returned

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 orthe system. If the identifier is listed as a holder of any otheridentifier, the appropriate holder records are also deleted.

Format

SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

C Prototype

int sys$revokid (unsigned int *pidadr, void *prcnam, struct _generic_64*id, void *name, unsigned int *prvatr, unsigned int segment);

Arguments

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 isthe address of a longword containing the PID of the process to beaffected. You use --1 to indicate the system rights list. Whenpidadr is passed, it is also returned; therefore, youmust 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 prcnamargument is the address of a character string descriptor containing theprocess name. The maximum length of the name is 15 characters. Becausethe UIC group number is interpreted as part of the process name, youmust use pidadr to specify the rights list of aprocess 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 completesexecution. The id argument is the address of aquadword containing the binary identifier code to be removed in thefirst longword and the attributes in the second longword.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The following symbols for each bitposition 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 passedif you specify name, you must pass it as a variablerather 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. Thename argument is the address of a descriptor pointingto 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 prvatrargument is the address of a longword used to store the attributes ofthe identifier.

Description

The Revoke Identifier from Process service removes the specifiedidentifier from the rights list of the process or the system. If theidentifier is listed as a holder of any other identifier, theappropriate holder records are also deleted.

The result of passing the pidadr or theprcnam argument, or both, to $REVOKID is summarized inthe following table.

Note that a value of 0 in either of the following tables indicates thatthe 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 theid argument, or both, to SYS$REVOKID is summarized inthe 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 thespecified identifier from the rights list of the process or the system,this service is meant for use by a privileged subsystem to alter theaccess rights profile of a user, based on installation policy. It isnot meant for use by the general system user.

Required Access or Privileges

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

Required Quota

None

Related Services

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

Condition Values Returned

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

Because the rights database is an indexed file accessed with OpenVMSRMS, this service can also return RMS status codes associated withoperations 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 firstrecord in the file. RMS alters the context of the next record toindicate the first record as being the next record.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

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

Format

SYS$RMSRUNDWN buf-addr ,type-value

C Prototype

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

Arguments

buf-addr

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

A descriptor pointing to a 22-byte buffer that is to receive the deviceidentification (16 bytes) and the file identification (6 bytes) of animproperly closed output file. The buf-addr argumentis 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 beperformed. The type-value argument is the actual valueused.

This type of code has the following values and meanings:

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

Description

The RMS Rundown service closes all files opened by OpenVMS RMS for theimage or process and halts I/O activity. This routine performs a $CLOSEservice for each file opened for processing. In addition to closing allfiles and terminating I/O activity, the I/O rundown control routinereleases all locks held on records in shared files, clears buffers, andreturns other resources allocated for file processing. You shouldcontinue to call the rundown control routine until you receive thesuccess completion status code of RMS$_NORMAL.

Note that, prior to the execution of the $CLOSE service, the rundowncontrol routine cancels all outstanding file operations specified in aFile Access Block (FAB) or any QIO requests related to file operations(an Open, Create, or Extend service, for example). It also cancels anyread/write requests to nondisk devices such as terminals or mailboxesprior to the execution of the $CLOSE service, resulting in possibleloss of data. All read/write requests of disk I/O buffers, however, areallowed to complete, which guarantees that none of the data written todisk files will be lost.

There is no predefined macro of the form $RMSRUNDWN_G or $RMSRUNDWN_Sto call this service.

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

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

On VAX systems, saves the pending exception state of the vectorprocessor.

Format

SYS$SAVE_VP_EXCEPTION excid

Argument

excid

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

Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. Theexcid argument is the address of a longword containingthis ID.

Description

The Save Vector Processor Exception State service saves in memory anypending vector exception state and clears the vector processor'scurrent exception state.

By default, when an AST or condition handler interrupts the executionof a mainline routine, the operating system saves the mainlineroutine's vector state, including its vector exception state. Any otherroutine that executes synchronously with, or asynchronously to,currently executing vectorized code and that performs vector operationsitself must preserve the preempted routine's vector exception stateacross its own execution. It does so by using the $SAVE_VP_EXCEPTIONand $RESTORE_VP_EXCEPTION services. Used together, these servicesensure that vector exceptions occurring as a result of activity in theoriginal routine are serviced by existing condition handlers withinthat routine.

In systems that do not have vector-present processors but do have theVAX Vector Instruction Emulation facility (VVIEF) in use, VVIEFemulates the functions of this service.

Required Access or Privileges

None

Required Quota

None

Related Services

$RELEASE_VP, $RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE

Condition Values Returned

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

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

Format

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

C Prototype

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

Arguments

logfail_status

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

Reason why the user's login attempt failed. Thelogfail_status argument is a longword containing thelogin failure status code.

The logfail_status argument can contain any validmessage code. For example, the value of thelogfail_status argument is SS$_NOSUCHUSER if the username the user entered does not exist on the system.

If the logfail_status argument contains a failurestatus, the service performs a suspect scan. Here, the service searchesthe intrusion database for intruder suspects as well as intruders. Ifthe value of the logfail_status argument is asuccessful message, such as SS$_NORMAL, the service scans the databaseonly 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 loginattempt. The failed_user argument is the address of acharacter-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-bititem list. If the item list is used, one item, the CIA$_FAILED_USERNAMEitem, must be present in the item list.

The following table lists the valid item descriptions for thefailed_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 alongword indicating the type of job that failed.

The $JPIDEF macro defines the following values for thejob_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. Thesource_terminal argument is the address of acharacter-string descriptor pointing to the device name of the terminalfrom which the login attempt originates.

A source terminal device name consists of 1 to 64 alphanumericcharacters, 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. Thesource_node argument is the address of acharacter-string descriptor pointing to the source node name string.

A source node name consists of 1 to 1024 characters. No specificcharacters, 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. Thesource_user argument is the address of acharacter-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 attemptoriginates. The source_addr argument is the address ofa 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. Thefailed_password argument is the address of acharacter-string descriptor pointing to the plaintext password the userentered to log in.

A failed password is a password of 0 to 32 characters that did notallow the user to log in to the system. This argument is not stored inthe intrusion database and is only used for auditing during break-inattempts.

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. Theparent_user argument is the address of acharacter-string descriptor pointing to the parent process name of thefailed login process.

A parent process name consists of 1 to 15 characters. This argumentshould 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 wasattempted. The parent_id argument is a longwordcontaining the parent process identification.

flags

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

Operational instructions for the service. The flagsargument is a longword bit mask wherein each bit corresponds to anoption.

Each flag option has a symbolic name. The $CIADEF macro defines thefollowing 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.

Description

The Scan Intrusion Database service performs the following functions:

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

The information that $SCAN_INTRUSION stores in the intrusion databaseis based on the setting of the LGI_BRK_TERM system parameter and theinformation passed by the caller. For more information about how theintrusion database functions and the use of the LGI system parameters,refer to the HP OpenVMS Guide to System Security.

Required Access or Privileges

$SCAN_INTRUSION requires the SECURITY privilege.

Required Quota

None

Related Services

$DELETE_INTRUSION, $SHOW_INTRUSION

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	One or more of the arguments were not readable.
SS$_BADBUFLEN	The length of one or more of the specified arguments is out of range.
SS$_BADPARAM	An invalid flag was specified in the flags argument.
SS$_NOSECURITY	The caller does not have SECURITY privilege.
This service can also return any of the following messages passed from the security server:
SECSRV$_INSUFINFO	Not enough information is supplied to form an intrusion record.
SECSRV$_INTRUDER	An intruder matching the information passed to the service exists in the intrusion database.
SECSRV$_NOMATCH	No intruders or suspects exist that match the information passed to the service.
SECSRV$_SERVERNOTACTIVE	The security server is not currently active. Try the request again later.
SECSRV$_SUSPECT	A suspect matching the information passed to the service exists in the intrusion database.

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

Format

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

C Prototype

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

Arguments

pidadr

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

Process identification (PID) of the process to be awakened. Thepidadr argument is the address of a longwordcontaining the PID. The pidadr argument can refer to aprocess running on the local node or a process running on another nodein the OpenVMS Cluster system.

You must specify the pidadr argument to awakenprocesses 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 theaddress of a character string descriptor pointing to the process name.A process running on the local node can be identified with a string offrom 1 to 15 characters.

To identify a process on a particular node on a cluster, specify thefull process name, which includes the node name as well as the processname. The full process name can contain up to 23 characters.

You can use the prcnam argument to awaken onlyprocesses in the same UIC group as the calling process because processnames are unique to UIC groups, and the operating system uses the UICgroup number of the calling process to interpret the process namespecified by the prcnam argument. You must use thepidadr argument to awaken processes in other UICgroups.

daytim

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

Time at which the process is to be awakened. Thedaytim argument is the address of a quadwordcontaining this time in the system 64-bit time format. A positive timevalue specifies an absolute time at which the specified process is tobe 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. Thereptim argument is the address of a quadwordcontaining this time interval. The time interval must be expressed indelta time format.

The time interval specified cannot be less than 10 milliseconds; if itis, $SCHDWK automatically increases it to 10 milliseconds.

If you do not specify reptim, a default value of 0 isused, which specifies that the wakeup request is not to be repeated.

Description

The Schedule Wakeup service schedules the awakening of a process thathas placed itself in a state of hibernation with the Hibernate ($HIBER)service. A wakeup can be scheduled for a specified absolute time or fora delta time and can be repeated at fixed intervals.

If you specify neither the pidadr nor theprcnam argument, the wakeup request is issued onbehalf of the calling process. If the longword value at addresspidadr 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 thatis not hibernating, a subsequent hibernate request by the targetprocess 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 beenprocessed by using the Cancel Wakeup ($CANWAK) service.

If a specified absolute time value has already passed and no repeattime is specified, the timer expires at the next clock cycle (within 10milliseconds).

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing 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

Required Quota

This service uses the process's timer queue entries (TQELM) quota. Ifyou specify an AST routine, the service uses the AST limit (ASTLM)quota of the calling process to schedule a wakeup request.

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SETIME, $SETIMR

Condition Values Returned

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 classscheduler process.

Format

SYS$SCHED func ,p1 ,p2 ,p3

C Prototype

int sys$sched (unsigned int func, unsigned int *p1, unsigned int *p2,unsigned int *p3);

Arguments

func

OpenVMS usage:	function_code
type:	longword (unsigned)
access:	write only
mechanism:	by value

Function code specifying the action $SCHED is to perform. Thefunc 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, andp3 arguments depends on the function code specified inthe func argument, and is defined in the FunctionCodes section.

CSH$_READ_ALL

Returns a buffer containing information, including an index, EPID, andpriority, for all processes.

The format of the buffer is defined in the $CSHDEF macro and consistsof a series of CSHP fields.

The following table shows the p1 argument,p2 argument, and p3 argument valuesfor 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, andpriority, for all processes for which a class assignment has not beenmade.

The format of the buffer is defined in the $CSHDEF macro and consistsof a series of CSHP fields.

The following table shows the p1 argument,p2 argument, and p3 argument valuesfor 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 bufferfields 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 leftfor each class. Data is returned in a series of longwords, one longwordper class, starting with class number 0.

The following table defines the p1 argument,p2 argument, and p3 argument valueswhen 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 valueswhen 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. Thecaller supplies a buffer consisting of CSHC blocks.

The format of the buffer is defined in the $CSHDEF macro. The followingtable 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 valueswhen 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 returninformation about the calling process. This function should be usedonly in executive or kernel mode.

The following table defines the p1 argument,p2 argument, and p3 argument valueswhen 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 callersupplies a buffer that allocates CPU ticks to classes, one longword perclass, starting with class number 0. Class-scheduled processes willhave their quantum deducted from the appropriate longword, and will beremoved from execution if class quantum is decremented to 0.

The following table defines the p1 argument,p2 argument, and p3 argument valueswhen 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 aCSH$_SET_QUANT within the timeout period, all class scheduling isstopped and processes are returned to normal scheduling. The defaultvalue, 30 seconds, should be suitable for most circumstances.

The following table defines the p1 argument,p2 argument, and p3 argument valueswhen specifying the CSH$_SET_TIMEOUT function code:

Argument	Access	Description
p1	---	Unused.
p2	Read	Time in seconds (by value).
p3	---	Unused.

Description

The Affect Process Scheduling service is used by class schedulerprocesses to affect scheduling.

Use the func argument to specify which action $SCHEDis to perform.

For more information on class scheduling, refer to the OpenVMS Programming Concepts Manual.

Required Access or Privileges

ALTPRI is required to affect processes. Group access is required toaffect processes in the same UIC group. World access is required toaffect processes in different UIC groups. SYSPRV is required to set thetimeout value.

Required Quota

None

Related Services

$GETJPI, $GETJPIW, $SETPRI

Condition Values Returned

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 NAMblock fields. This service should be preceded by the Parse service, inorder to initialize the NAM block appropriately.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Enables or disables the delivery of asynchronous system traps (ASTs)for the access mode from which the service call was issued.

Format

SYS$SETAST enbflg

C Prototype

int sys$setast (char enbflg);

Argument

enbflg

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

Value specifying whether ASTs are to be enabled. Theenbflg argument is a byte containing this value. Thevalue 1 enables AST delivery for the calling access mode; the value 0disables AST delivery.

Description

The Set AST Enable service enables or disables the delivery of ASTs forthe access mode from which the service call was issued.

Required Access or Privileges

When an image is executing in user mode, ASTs are always enabled formore privileged access modes. If ASTs are disabled for a moreprivileged access mode, the operating system cannot deliver ASTs forless privileged access modes until ASTs are enabled once again for themore privileged access mode. Therefore, a process that has disabledASTs for a more privileged access mode must reenable ASTs for that modebefore returning to a less privileged access mode.

Required Quota

None

Related Services

$DCLAST, $SETPRA

Condition Values Returned

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 Clusterconfiguration event occurs.

Format

SYS$SETCLUEVT event ,astadr ,[astprm] ,[acmode] ,[handle]

C Prototype

int sys$setcluevt (unsigned int event, void(*astadr)(__unknown_params), int astprm, unsigned int acmode, struct_generic_64 *handle);

Arguments

event

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

Event code indicating the type of cluster configuration event for whichan AST is to be delivered. The event argument is avalue indicating which type of event is of interest.

Each event type has a symbolic name. The $CLUEVTDEF macro defines thefollowing 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 OpenVMSCluster 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. Theastprm argument is a longword value containing the ASTparameter.

acmode

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

Optional access mode at which the configuration event AST is toexecute. The acmode argument is a longword containingthe access mode.

Each access mode has a symbolic name. The $PSLDEF macro defines thefollowing 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 theaccess 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 thisAST request. $SETCLUEVT sets this handle to a unique value so that itcan later be used to identify the request in the $CLRCLUEVT and$TSTCLUEVT services.

Description

The Set Cluster Event service establishes a request for notificationwhen a cluster configuration event occurs. The service establishes onlyone AST notification for a configuration event. To receive ASTnotification for all cluster configuration events, the $SETCLUEVTservice must be reissued within the notification AST routine.

The service will verify that the input parameters specify a validrequest, allocate appropriate data structures to hold the request, andenqueue the request for notification.

You must specify an event type and an AST address. You can specify anAST parameter, the access mode, and an address into which to place thehandle 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.

Required Access or Privileges

None

Required Quota

None

Related Services

$CLRCLUEVT, $TSTCLUEVT

Condition Values Returned

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 theprocess.

Format

SYS$SETDDIR [new-dir-addr] ,[length-addr] ,[cur-dir-addr]

C Prototype

int sys$setddir (void *newdiraddr, unsigned short int *lengthaddr, void*curdiraddr);

Arguments

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. Thenew-dir-addr argument is the address of the descriptorthat points to the buffer containing the new directory specificationthat RMS will use to set the new process-default directory. If thedefault directory is not to be changed, the value of thenew-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 wordthat 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 defaultdirectory string. The cur-dir-addr argument is theaddress of the descriptor that points to the buffer area that is toreceive the current directory string.

Description

The Set Default Directory service allows you to read and change thedefault directory string for the process. You should restore theprevious default directory string to its original state unless you wantthe changed default directory string to last beyond the exit of yourimage. The new directory name string is checked for correct syntax.

There is no predefined macro of the form $SETDDIR_G or $SETDDIR_S tocall this service.

On Alpha systems, the Set Default Directory service attempts to replacethe default directory string with a DID abbreviation if the length ofthe resulting default directory exceeds 255 characters. If thishappens, then in addition to the normal syntax check, the entire pathto that specification, including the device, is verified and must existfor the call to succeed.

Required Access or Privileges

None

Required Quota

None

Related Services

$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

Condition Values Returned

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 theprocess.

Format

SYS$SETDFPROT [new-def-prot-addr] ,[cur-def-prot-addr]

C Prototype

int sys$setdfprot (unsigned short int *newdefprotaddr, unsigned shortint *curdefprotaddr);

Arguments

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 theword that specifies the desired protection. If you do not want theprocess-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 protectionspecification. The cur-def-prot-addr argument is theaddress of the word that receives the current process-defaultprotection. If you do not want the current default file protection,specify the value 0.

Description

The Set Default File Protection service allows you to read and writethe default file protection for the process. You should restore the olddefault file protection specification unless you want the changeddefault to last beyond the exit of your image.

There is no predefined macro of the form $SETDEFPROT_G or $SETDEFPROT_Sto call this service.

Required Access or Privileges

None

Required Quota

None

Related Services

$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

Condition Values Returned

RMS$_NORMAL	The service completed successfully.
RMS$_IAL	The argument list is invalid.

The Set Distributed Transaction Information service removes resourcemanagers from transactions. It can also be used to modify transactionstates.

Format

SYS$SETDTI [efn], [flags], iosb, [astadr], [astprm], [contxt], func,itmlst

C Prototype

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);

Arguments

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. Ifthis 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 flagsargument is a longword bit mask in which each bit corresponds to anoption flag. The $DDTMDEF macro defines symbolic names for the optionflag described in Table SYS-51. All undefined bits must be 0. If thisargument 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 isreturned as a condition value. See the Condition Values Returnedsection.

The following diagram shows the structure of the I/O status block:

astadr

astprm

contxt

func

Table SYS-52 lists the available function codes:

itmlst

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

The following table describes the itmlst itemdescriptor fields:

Item Codes

DTI$_TRANSACTION_INFORMATION

When you specify DTI$_TRANSACTION_INFORMATION, $SETDTI uses the fieldsin the following table to perform the $SETDTI call. Each functionrequires a specific set of fields from the transaction record toperform its operation. If one or more of these fields is not present orvalid, then the $SETDTI call will fail. The fields required by eachfunction 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.

Description

The $SETDTI service can be used either to remove resource managers fromtransactions, or to modify transaction states.

The $SETDTI service removes resource managers from a single transactionor from all transactions when they no longer have any further interestin a transaction. A call to $SETDTI typically follows a call to $GETDTIthat established a search context and returned the state of anunresolved transaction.

When a resource manager is recovering from a system failure it will use$GETDTI to return the state of all unresolved transactions. If theresource manager can recover the transaction, then it needs to beremoved from the transaction in the same way it would have been removedhad it been able to call $ACK_EVENT with the forget status before thesystem failure.

To remove a resource manager, $SETDTI uses the following fields fromthe DTI$_TRANSACTION_INFORMATION item descriptor in theitmlst argument:

• Transaction Identifier (TID)
• Resource Manager name
• Resource Manager log identifier

This information, along with the search context, is used to remove theresource manager from the transaction. If the TID field is zero in theDTI$_TRANSACTION_INFORMATION item descriptor, then the resource managerwill be removed from all committed transactions in which it wasinvolved.

When searching for a resource manager, a comparison is made of theleftmost bytes in the transaction manager's log records. This featureenables multiple instances of resource manager classes to be removedfrom the transaction manager's log after performing a recovery.

The $SETDTI service can also be used to modify transaction states. Itcan perform two state transitions: from prepared to committed, or fromprepared to aborted. To modify transaction states, $SETDTI uses thefollowing fields from the DTI$_TRANSACTION_INFORMATION item descriptorin the itmlst argument:

• Transaction Identifier (TID)
• Transaction state

To modify a transaction state, first modify the DTI$B_STATE field inthe DTI$_TRANSACTION_INFORMATION item descriptor to eitherDTI$K_COMMITTED and DTI$K_ABORTED. Then specify the function codeDTI$K_MODIFY_TRANSACTION to instruct $SETDTI to perform the statetransition.

Note that because DECdtm uses a presumed abort protocol, changing thetransaction state to aborted is the same as deleting the transaction.

SYSPRV privilege is required to retrieve or modify information abouttransactions with which the process is not currently associated.

In most cases, the search context remains valid across multiple callsto $SETDTI. That is, a call to $GETDTI may be followed by one or morecalls to $SETDTI without the context becoming invalid. However, thesearch context is invalidated when a resource manager is deleted fromall transactions by specifying a zero TID.

Required Privileges

SYSPRV is required to modify transactions with which the process is notcurrently associated.

Required Quotas

BYTLM, ASTLM

Related Services

$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

Condition Values Returned

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 fromtransactions.

$SETDTIW$ always waits for the request to complete before returning tothe caller. Other than this, it is identical to $SETDTI.

Format

SYS$SETDTIW [efn], [flags], iosb, [astadr], [astprm], [contxt], func,itmlst

C Prototype

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. Thecondition value returned by $SETEF indicates whether the specified flagwas previously set or clear. After the event flag is set, processeswaiting for the event flag to be set resume execution.

Format

SYS$SETEF efn

C Prototype

int sys$setef (unsigned int efn);

Argument

efn

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

Number of the event flag to be set. The efn argumentis a longword containing this number; however, $SETEF uses only thelow-order byte.

Two local event flag clusters are local to the process: cluster 0 andcluster 1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1contains 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 containsevent flag numbers 96 to 127.

Condition Values Returned

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 lastchance exception vectors, or removes a previously assigned handleraddress from any of these three vectors.

Format

SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]

C Prototype

int sys$setexv (unsigned int vector, int (*addres)(__unknown_params),unsigned int acmode, void *(*(prvhnd)));

Arguments

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, thesecondary 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 vectorspecified by the vector argument. Theaddres argument is a longword value containing theaddress of the condition handler routine.

If you do not specify addres or specify it as thevalue 0, the condition handler address already established for thespecified vector is removed; that is, the contents of the longwordvector 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. Theacmode argument is a longword containing the accessmode. 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'saccess 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 exceptionvector. The prvhnd argument is the address of alongword into which $SETEXV writes the handler's procedure value.

Description

The Set Exception Vector service (1) assigns a condition handleraddress to the primary, secondary, or last chance exception vectors or(2) removes a previously assigned handler address from any of thesethree vectors. A process cannot modify a vector associated with a moreprivileged access mode.

The operating system provides two different methods for establishingcondition 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 tothe second. The software exception vectors are intended primarily forperformance monitors and debuggers. For example, the primary exceptionvector and the last chance exception vector are used by the OpenVMSDebugger for user mode access, and DCL uses the last chance exceptionvector for supervisor mode access.

User mode exception vectors are canceled at image exit.

Required Access or Privileges

None

Required Quota

None

Related Services

$DCLCMH, $UNWIND

Condition Values Returned

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.

Format

SYS$SETIME [timadr]

C Prototype

int sys$setime (struct _generic_64 *timadr);

Argument

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 of100-nanosecond intervals since 00:00 o'clock, November 17, 1858. Thetimadr argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a quadwordcontaining the new system time value. A negative (delta) time value isinvalid.

If you do not specify the value of timadr or specifyit as 0, $SETIME recalibrates the system time using the time-of-yearclock.

Description

The Set System Time service (1) changes the value of or (2)recalibrates the system time, which is defined by a quadword value thatspecifies 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 softwareactivities in the operating system. After changing or recalibrating thesystem clock, $SETIME updates the timer queue by adjusting each elementin the timer queue by the difference between the previous system timeand the new system time.

The $SETIME service saves the new time (for future bootstrapoperations) in the system image SYS$SYSTEM:SYS.EXE on VAX systems orSYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE on Alpha systems. To save thetime, the service assigns a channel to the system boot device and calls$QIOW. You need the LOG_IO user privilege to perform this operation.

Required Access or Privileges

To set system time, the calling process must have OPER, LOG_IO, andSYSPRV privileges.

Required Quota

None

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIMR

Condition Values Returned

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.

Format

SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]

C Prototype

int sys$setimr (unsigned int efn, struct _generic_64 *daytim, void(*astadr)(__unknown_params), unsigned __int64 reqidt, unsigned intflags);

Arguments

efn

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

Event flag to be set when the timer expires. The efnargument 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 orevent 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 argumentis the 64-bit address (on Alpha systems) or the 32-bit address (on VAXsystems) of a quadword time value. A positive time value specifies anabsolute time at which the timer expires; a negative time valuespecifies 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. Theastadr argument is the 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of the procedure valueof this routine. If you do not specify the value ofastadr or specify it as 0 (the default), no ASTroutine executes.

The AST routine, if specified, executes at the access mode of thecaller.

reqidt

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

Identification of the timer request. The reqidtargument is a longword value containing a number that uniquelyidentifies the timer request. If you do not specifyreqidt, the value 0 is used.

To cancel a timer request, the identification of the timer request (asspecified by reqidt in $SETIMR) is passed to theCancel Timer ($CANTIM) service (as the reqidtargument).

If you want to cancel specific timer requests but not all timerrequests, be sure to specify a nonzero value forreqidt in the $SETIMR call; $CANTIM interprets anidentification value of 0 as a request to cancel all timer requests.

You can specify unique values for reqidt for eachtimer request or give the same value to related timer requests. Thispermits selective canceling of a single timer request, a group ofrelated timer requests, or all timer requests.

If you specify the astadr argument in the $SETIMRcall, the value specified by the reqidt argument ispassed as a parameter to the AST routine. If the AST routine requiresmore than one parameter, specify an address for the value ofreqidt; the AST routine can then interpret thataddress 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 bit0 is used for the flags argument. When the low bit(bit 0) is set, it indicates that this timer request should be in unitsof CPU time, rather than elapsed time. When bit 0 is clear (thedefault), the timer request is in units of elapsed time. Theflags argument is optional.

Description

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 ASTroutine executes. This service requires dynamic memory and executes atthe access mode of the caller, as does the AST routine if one isspecified.

Required Access or Privileges

None

Required Quota

This service uses the process's timer queue entries (TQELM) quota. Ifyou specify an AST routine, the service uses the AST limit (ASTLM)quota of the process.

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME

Condition Values Returned

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 isdetected.

Format

SYS$SETPRA astadr ,[acmode]

C Prototype

int sys$setpra (int (*astadr)(__unknown_params), unsigned int acmode);

Arguments

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 isdetected. The astadr argument is the address of thisroutine.

If you specify astadr as the value 0, an AST is notdelivered to the process when a power recovery is detected.

The system passes one parameter to the specified AST routine. Thisparameter is a longword value containing the length of time that thepower was off, expressed as the number of 1/100th-of-a-second intervalsthat 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. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines symbols for the access modes.

The most privileged access mode used is the access mode of the caller.

Description

The Set Power Recovery AST service establishes a routine to receivecontrol after a power recovery is detected.

You can specify only one power recovery AST routine for a process. TheAST entry point address is cleared at image exit.

The entry and exit conventions for the power recovery AST routine arethe same as for all AST service routines.

Required Access or Privileges

None

Required Quota

One unit of quota is deducted from the process's ASTLM.

Related Services

$DCLAST, $SETAST

For more information, refer to the chapter on AST services in theOpenVMS Programming Concepts Manual.

Condition Values Returned

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 todetermine the order in which executable processes are to run.

Format

SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg] ,[nullarg]

C Prototype

int sys$setpri (unsigned int *pidadr, void *prcnam, unsigned int pri,unsigned int *prvpri, unsigned int *pol, unsigned int *prvpol);

Arguments

pidadr

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

Process identification (PID) of the process whose priority is to beset. The pidadr argument is the address of the PID.The pidadr argument can refer to a process running onthe 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. Theprcnam argument is the address of a character stringdescriptor pointing to the process name.

A process running on the local node can be identified with a 1- to15-character string. To identify a process on a particular node on acluster, specify the full process name, which includes the node name aswell as the process name. The full process name can contain up to 23characters.

You can use the prcnam argument only on behalf ofprocesses in the same UIC group as the calling process. To set thepriority for processes in other groups, you must specify thepidadr argument.

pri

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

New base priority to be established for the process. Thepri argument is a longword value containing the newpriority. Priorities that are not real time are in the range 0 through15; real-time priorities are in the range 16 through 31.

If the specified priority is higher than the base priority of thetarget process, and if the caller does not have ALTPRI privilege, thenthe 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. Theprvpri argument is the address of a longword intowhich $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 schedulingpolicy for the process.

The $JPIDEF macro defines the following symbols for thepolicy 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 previousscheduling policy for the process is written. If thepolicy argument is null, no change in policy isrequested and prvpol returns the current policy.

The valid priority intervals for specific scheduling policies mightchange in the future. Applications should, therefore, not use embeddednumeric constants for scheduling priority, but should use theappropriate $GETSYI item codes to fetch the legal priority intervals.The application can then dynamically select a priority value that iswithin 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 moreinformation about these item codes.

nullarg

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

Placeholding argument reserved to HP.

Description

The Set Priority service changes the base priority of the process or,optionally, changes the scheduling policy of the process. The basepriority is used to determine the order in which executable processesare 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 atarget 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 subjectto limitations. If the source has ALTPRI privilege enabled, the targetcan be set to any valid priority. Otherwise, the priority valuespecified by the source process is compared to the authorized priorityof the target process and the smaller of the two values is used as thenew base priority of the target process.

If you specify neither the pidadr nor theprcnam argument, $SETPRI sets the base priority of thecalling process.

If the longword at address pidadr is the value 0, thePID of the target process is returned.

The base priority of a process remains in effect until specificallychanged or until the process is deleted.

To determine the priority set by the $SETPRI service, use the GetJob/Process Information ($GETJPI) service.

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing 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.

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,$HIBER, $PROCESS_SCAN, $RESUME, $SETPRN, $SETPRV, $SETRWM, $SUSPND,$WAKE

Condition Values Returned

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.

Format

SYS$SETPRN [prcnam]

C Prototype

int sys$setprn (void *prcnam);

Argument

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. Theprcnam argument is the address of a character stringdescriptor pointing to a 1- to 15-character process name string. If youdo not specify prcnam, the calling process is given noname.

Description

The Set Process Name service allows a process to establish or to changeits own process name, which remains in effect until you change it(using $SETPRN) or until the process is deleted. Process names providean identification mechanism for processes executing with the same groupnumber. A process can also be identified by its process identification(PID).

Required Access or Privileges

None

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,$HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRV, $SETRWM, $SUSPND,$WAKE

Condition Values Returned

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.

Format

SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]

C Prototype

int sys$setprt (struct _va_range *inadr, struct _va_range *retadr,unsigned int acmode, unsigned int prot, unsigned char *prvprt);

Arguments

inadr

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

Starting and ending virtual addresses of the range of pages whoseprotection is to be changed. The inadr argument is theaddress of a 2-longword array containing, in order, the starting andending process virtual addresses.

Addresses are adjusted up or down to fall on CPU-specific pageboundaries. Only the virtual page number portion of each virtualaddress is used; the low-order byte-within-page bits are ignored.

If the starting and ending virtual addresses are the same, theprotection 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 whoseprotection was actually changed by $SETPRT. The retadrargument is the address of a 2-longword array containing, in order, thestarting and ending process virtual addresses.

If an error occurs while the protection is being changed, $SETPRTwrites into retadr the range of pages that weresuccessfully changed before the error occurred. If no pages wereaffected before the error occurred, $SETPRT writes the value --1 intoeach 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. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines symbols for the access modes.

The $SETPRT service uses whichever of the following two access modes isleast privileged: (1) the access mode specified byacmode or (2) the access mode of the caller. To changethe protection of any page in the specified range, the resultant accessmode must be equal to or more privileged than the access mode of theowner 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. Theprot argument is a longword value containing theprotection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.

The $PRTDEF macro defines the following symbolic names for theprotection 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 defaultsto 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. Theprvprt argument is the address of a byte into which$SETPRT writes the protection of this page. The prvprtargument is useful only when protection for a single page is beingchanged.

Description

The Set Protection on Pages service allows a process to change theprotection on a page or range of pages.

Required Access or Privileges

None

Required Quota

If a process changes the protection for any pages in a private sectionfrom 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 onlycopy-on-reference pages.

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,$LKWSET, $MGBLSC, $PURGWS, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,$UPDSECW

Condition Values Returned

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 pageor range of pages.

This service accepts 64-bit addresses.

Format

SYS$SETPRT_64 start_va_64 ,length_64 ,acmode ,prot ,return_va_64,return_length_64 ,return_prot_64

C Prototype

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);

Arguments

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 isto be changed. The specified virtual address will be rounded down to aCPU-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 boundaryso 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. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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, theresultant access mode must be equal to or more privileged than theaccess 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. Theprot argument is a longword value containing theprotection 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 Cdefine 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 whoseprotection was actually changed. The return_va_64argument is the 32- or 64-bit virtual address of a naturally alignedquadword 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 actuallychanged. The return_length_64 argument is the 32- or64-bit virtual address of a naturally aligned quadword into which theservice 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. Thereturn_prot_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned longword into which $SETPRT_64 writesthe protection of this page. The return_prot_64argument is useful only when protection for a single page is beingchanged.

Description

The Set Protection on Pages service allows a process to change theprotection 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 valuecannot be returned in the memory locations pointed to by thereturn_va_64, return_length_64, andreturn_prot arguments.

If a condition value other than SS$_ACCVIO is returned, the returnedaddress and returned length indicate the pages that were successfullychanged before the error occurred. If no pages were changed, thereturn_va_64 argument will contain the value -1, and avalue cannot be returned in the memory location pointed to bythe return_length_64 argument.

Required Privileges

None

Required Quota

If a process changes the protection for any pages in a private sectionfrom read-only to read/write, $SETPRT_64 uses the paging file(PGFLQUOTA) quota of the process.

Related Services

$CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64,$EXPREG_64, $MGBLSC_64

Condition Values Returned

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.

Format

SYS$SETPRV [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]

C Prototype

int sys$setprv (char enbflg, struct _generic_64 *prvadr, char prmflg,struct _generic_64 *prvprv);

Arguments

enbflg

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

Indicator specifying whether the specified privileges are to be enabledor disabled. The enbflg argument is a longword value.The value 1 indicates that the privileges specified in theprvadr argument are to be enabled. The value 0 (thedefault) 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. Theprvadr argument is the address of a quadword bitvector wherein each bit corresponds to a privilege that is to beenabled 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 desiredprivilege in a logical OR operation. The following table provides thesymbolic 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 affectedpermanently or temporarily. The prmflg argument is alongword value. The value 1 specifies that the privileges are to beaffected 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 enabledprivileges of the process will be restored).

Setting the prmflg argument to nonzero changesprivilege 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. Theprvprv argument is the address of a quadword bitvector wherein each bit corresponds to a privilege that was previouslyeither enabled or disabled. If you do not specifyprvprv or assign it the value 0, the previousprivilege mask is not returned.

Description

The Set Privileges service enables or disables specified privileges forthe calling process.

The operating system maintains four separate privilege masks for eachprocess:

• 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 maskshave 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 thatimage was installed are enabled in the CURPRIV mask. When the installedimage 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 setspecified privilege bits in the CURPRIV or PROCPRIV masks.Consequently, a process can give itself the SETPRV privilege only ifthis 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 thedesired privilege mask or masks as item codes in theitmlst argument. You construct the item code for aprivilege mask by prefixing the name of the privilege mask with thecharacters JPI$_ (for example, JPI$_CURPRIV is the item codefor the current privilege mask).

The DCL command SET PROCESS/PRIVILEGES also enables or disablesspecified privileges; refer to the HP OpenVMS DCL Dictionary for details.

Required Access or Privileges

To set a privilege permanently, the calling process must be authorizedto set the specified privilege, or the process must be executing inkernel or executive mode.

To set a privilege temporarily, one of the following three conditionsmust 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.

Required Quota

None

Related Services

$CANEXH, $CMKRNL, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI,$GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETRWM,$SUSPND, $WAKE