HP OpenVMS Systems Documentation

Deletes a Resource Manager instance (RMI) from the calling process.

Format

SYS$FORGET_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

C Prototype

int sys$forget_rm (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intrm_id);

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 listed in Table SYS-38. All undefined bits must be 0. If thisargument is omitted, no flags are used.

Table SYS-38 $FORGET_RM Option 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

rm_id

Description

The $FORGET_RM system service:

• Deletes the specified Resource Manager instance (RMI) from the calling process.
• Tries to abort all transactions that have not already committed and that have Resource Manager (RM) participants associated with that RMI.
• Removes all RM participants associated with the RMI from their transactions.
• Implicitly acknowledges all unacknowledged event reports delivered to that RMI or to its RM participants. The reply given in the implicit acknowledgment depends on the type of the event as follows:

Table SYS-39 $FORGET_RM's Implicit Acknowledgments

Type of Event	Reply
Abort	SS$_NORMAL
Commit	SS$_REMEMBER
Prepare	SS$_VETO (with the DDTM$_SEG_FAIL reason code)
One-phase commit	SS$_VETO
Default transaction started	SS$_NORMAL
Nondefault transaction started	SS$_NORMAL

Preconditions for the successful completion of $FORGET_RM are:

• The calling process must contain the specified RMI.
• The access mode of the caller must be the same as or more privileged than that of the specified RMI.

Postconditions on successful completion of $FORGET_RM are described inTable SYS-40:

Table SYS-40 Postconditions When$FORGET_RM Completes Successfully

Postcondition	Meaning
The specified RMI is deleted from the calling process.	The result is that: Its identifier is invalid. Any subsequent calls to $JOIN_RM or $FORGET_RM that pass its identifier will fail. The DECdtm transaction manager will deliver no more event reports to that RMI.
There are no RM participants associated with the RMI.	Removes all RM participants associated with the specified RMI from their transactions. Thus the DECdtm transaction manager will deliver no more event reports to those RM participants. For an RM participant that had an unacknowledged event report, the postconditions are the same as those of the appropriate implicit acknowledgment (see Table SYS-39) except that the RM participant is always removed from the transaction.
There are no unacknowledged event reports delivered to the RMI or its RM participants.	All unacknowledged event reports are implicitly acknowledged by this call to $FORGET_RM (see Table SYS-39). Thus a subsequent call to $ACK_EVENT that acknowledges one of these event reports will fail.
Quotas are returned.	Returns the following quotas: The BYTLM quota consumed by the call to $DECLARE_RM that created the RMI. The ASTLM quotas consumed by all calls to $JOIN_RM or $ACK_EVENT that added RM participants associated with the RMI.

Note that when a process terminates (normally or abnormally), a$FORGET_RM is automatically performed for each RMI in that process. Andwhen an image terminates (normally or abnormally), a $FORGET_RM isautomatically performed for each user mode RMI in that process.

There is also a wait form of the service, $FORGET_RMW.

Required Privileges

None

Required Quotas

None

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_RMW, $GETDTI, $GETDTIW,$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $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$_BADPARAM	An option flag was invalid.
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$_WRONGACMODE	The access mode of the caller was less privileged than that of the RMI.
SS$_NOSUCHRM	The calling process did not contain the specified RMI.

Deletes a Resource Manager instance (RMI) from the calling process.

$FORGET_RMW always waits for the request to complete before returningto the caller. Other than this, it is identical to $FORGET_RM.

Format

SYS$FORGET_RMW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

C Prototype

int sys$forget_rmw (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intrm_id);

Formats the specified access control entry (ACE) into a text string.

Format

SYS$FORMAT_ACL aclent ,[acllen] ,aclstr ,[width] ,[trmdsc] ,[indent],[accnam] ,[nullarg]

C Prototype

int sys$format_acl (void *aclent, unsigned short int *acllen, void*aclstr, unsigned short int *width, void *trmdsc, unsigned short int*indent, unsigned int *accnam, int (*routin)(__unknown_params));

Arguments

aclent

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

Description of the ACE formatted when $FORMAT_ACL completes execution.The aclent argument is the address of a descriptorpointing to a buffer containing the description of the input ACE. Thefirst byte of the buffer contains the length of the ACE; the secondbyte contains a value that identifies the type of ACE, which in turndetermines the ACE format.

For more information about the ACE format, see the Description section.

acllen

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

Length of the output string resulting when $FORMAT_ACL completesexecution. The acllen argument is the address of aword containing the number of characters written toaclstr.

aclstr

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

Formatted ACE resulting when $FORMAT_ACL completes its execution. Theaclstr argument is the address of a string descriptorpointing to a buffer containing the output string.

width

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

Maximum width of the formatted ACE resulting when $FORMAT_ACL completesits execution. The width argument is the address of aword containing the maximum width of the formatted ACE. If thisargument is omitted or contains the value 0, an infinite length displayline is assumed. When the width is exceeded, the character specified bytrmdsc is inserted.

trmdsc

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

Line termination characters used in the formatted ACE. Thetrmdsc argument is the address of a descriptorpointing to a character string containing the termination charactersthat are inserted for each formatted ACE when the width has beenexceeded.

indent

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

Number of blank characters beginning each line of the formatted ACE.The indent argument is the address of a wordcontaining the number of blank characters that you want inserted at thebeginning of each formatted ACE.

accnam

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

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

You can call LIB$GET_ACCNAM to retrieve the access name table for theclass of object whose ACL is to be formatted.

If you omit accnam, the following names are used:

Bit	Name
Bit 0	READ
Bit 1	WRITE
Bit 2	EXECUTE
Bit 3	DELETE
Bit 4	CONTROL
Bit 5	BIT_5
Bit 6	BIT_6
. . .
Bit 31	BIT_31

nullarg

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

Placeholding argument reserved to HP.

Description

The Format Access Control List Entry service formats the specifiedaccess control entry (ACE) into text string representation. There areseven types of ACE:

• Alarm ACE
• Application ACE
• Audit ACE
• Creator ACE
• Default Protection ACE
• Identifier ACE
• Subsystem ACE

The format for each of the ACE types is described in the followingsections and the byte offsets and type values for each ACE type aredefined in the $ACEDEF system macro library.

Alarm ACE

The access Alarm ACE generates a security alarm. Its format is asfollows:

The following table describes the ACE fields and lists the symbol namefor each:

The flag field contains information specific to Alarm ACEs andinformation applicable to all types of ACEs. The following symbols arebit offsets to the Alarm ACE information:

The following symbols are bit offsets to ACE information that isindependent of ACE type:

The following symbol values are offsets to bits within the access mask.You can also obtain the symbol values as masks with the appropriate bitset using the prefix ACE$M rather than ACE$V:

Application ACE

The Application ACE contains application-dependent information. Itsformat is as follows:

The following table describes the ACE fields and lists the symbol namefor each:

The flag field contains information specific to Application ACEs andinformation applicable to all types of ACEs. The following symbol is abit offset to the Application ACE information:

The following symbols are bit offsets to ACE information that isindependent of ACE type:

Audit ACE

The Audit ACE sets a security audit. Its format is as follows:

The following table describes the ACE fields and lists the symbol namefor each:

The following symbols are bit offsets to ACE information that isindependent of ACE type:

The following symbol values are offsets to bits within the access mask.You can also obtain the symbol values as masks with the appropriate bitset using the prefix ACE$M rather than ACE$V.

Creator ACE

The Creator ACE controls access to an object based on creators. Itsformat is as follows:

The following table describes the ACE fields and lists the symbol namefor each:

The following symbols are bit offsets to ACE information that isindependent of ACE type:

The following symbol values are offsets to bits within the maskindicating the access mode granted in the system, owner, group, andworld fields:

You can also obtain the symbol values as masks with the appropriate bitset by using the prefix ACE$M rather than ACE$V.

Default Protection ACE

The Default Protection ACE specifies the UIC-based protection for allfiles created in the directory. You can use this type of ACE only inthe ACL of a directory file. Its format is as follows:

The following table describes the ACE fields and lists the symbol namefor each:

The flag field contains information applicable to all types of ACEs.The following symbols are bit offsets to ACE information that isindependent of ACE type:

The system interprets the bits within the access mask as shown in thefollowing table. The following symbol values are offsets to bits withinthe mask indicating the access mode granted in the system, owner,group, and world fields:

You can also obtain the symbol values as masks with the appropriate bitset by using the prefix ACE$M rather than ACE$V.

Identifier ACE

The Identifier ACE controls access to an object based on identifiers.Its format is as follows:

The following table describes the ACE fields and lists the symbol namefor each:

The flags field contains information specific to Identifier ACEs andinformation applicable to all types of ACEs. The following symbol is abit offset to Identifier ACE information:

The following symbols are bit offsets to ACE information that isindependent of ACE type:

The following symbol values are offsets to bits within the maskindicating the access mode granted in the system, owner, group, andworld fields:

You can also obtain the symbol values as masks with the appropriate bitset by using the prefix ACE$M rather than ACE$V.

Subsystem ACE

The Subsystem ACE maintains protected subsystems. Its format is asfollows:

The following table describes the ACE fields and lists the symbol namefor each:

A Subsystem ACE can contain multiple identifier/attribute pairs. Inthis case, the Subsystem ACE is an array of identifiers and attributesstarting at ACE$Q_IMAGE_IDS. Beginning at this offset, KGB$L_IDENTIFIERand KGB$L_ATTRIBUTES are used to address each of the separate longwords.

The number of identifier/attribute pairs is computed by subtractingACE$C_LENGTH from ACE$W_SIZE and dividing by KGB$S_IDENTIFIER.

The following symbols are bit offsets to ACE information that isindependent of ACE type:

The following symbol values are offsets to bits within the maskindicating the access mode granted in the system, owner, group, andworld fields:

You can also obtain the symbol values as masks with the appropriate bitset by using the prefix ACE$M rather than ACE$V.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $CREATE_USER_PROFILE,$FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_AUDIT, $GET_SECURITY,$GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT,$REM_HOLDER, $REM_IDENT, $REVOKID, $SET_RESOURCE_DOMAIN, $SET_SECURITY

Condition Values Returned

SS$_BUFFEROVF	The service completed successfully. The output string has overflowed the buffer and has been truncated.
SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The ACL entry or its descriptor cannot be read by the caller, or the string descriptor cannot be read by the caller, or the length word or the string buffer cannot be written by the caller.

Converts a security auditing event message from binary format to ASCIItext.

Format

SYS$FORMAT_AUDIT fmttyp ,audmsg ,[outlen] ,outbuf ,[width] ,[trmdsc],[routin] ,[fmtflg]

C Prototype

int sys$format_audit (unsigned int fmttyp, void *audmsg, unsigned shortint *outlen, void *outbuf, unsigned short int *width, void *trmdsc, int(*routin)(__unknown_params), unsigned int fmtflg);

Arguments

fmttyp

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

Format for the message. The fmttyp argument is a valueindicating whether the security audit message should be in briefformat, which is one line of information, or full format. The defaultis full format. Refer to the HP OpenVMS System Manager's Manual for examples of formattedoutput.

The following table defines the brief and full formats:

Value	Meaning
NSA$C_FORMAT_STYLE_BRIEF	Use a brief format for the message.
NSA$C_FORMAT_STYLE_FULL	Use a full format for the message.

audmsg

OpenVMS usage:	char_string
type:	byte stream (unsigned)
access:	read only
mechanism:	by reference

Security auditing message to format. The audmsgargument is the address of a buffer containing the message thatrequires formatting.

outlen

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

Length of the formatted security audit message. Theoutlen argument is the address of the word receivingthe final length of the ASCII message.

outbuf

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

Buffer holding the formatted message. The outbufargument is the address of a descriptor pointing to the bufferreceiving the message.

width

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

Maximum width of the formatted message. The widthargument is the address of a word containing the line width value. Thedefault is 80 columns.

The width argument does not work consistently. In mostcases, if you specify both the width argument and thefull format style (NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores thewidth argument. The minimum width is 80 columns; lowervalues do not limit the width to less than 80. If you specify a widthgreater than 80 columns, most lines are not joined to use the fullwidth.

In most cases, you should avoid using the widthargument.

trmdsc

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

Line termination characters used in a full format message. Thetrmdsc argument is the address of a descriptorpointing to the line termination characters to insert within a linesegment whenever the width is reached.

routin

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by reference

Routine that writes a formatted line to the output buffer. Theroutin argument is the address of a routine calledeach time a line segment is formatted. The argument passed to theroutine is the address of a character string descriptor for the linesegment.

When an application wants event messages in the brief format,$FORMAT_AUDIT calls the routine twice to format the first eventmessage. The first time it is called, the routine passes a stringcontaining the column titles for the message. The second and subsequentcalls to the routine pass the formatted event message. By using thisroutine argument, a caller can gain control at various points in theprocessing of an audit event message.

fmtflg

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

Determines the formatting of certain kinds of audit messages. Thefmtflg argument is a mask specifying whether sensitiveinformation should be displayed or column titles built for messages inbrief format. For example, the operating system uses bit 0 to suppressplain-text passwords from security alarm messages.

The following table describes the significant bits:

Bit	Value	Description
0	1	Do not format sensitive information.
	0	Format sensitive information.
1	1	Build a column title for messages in brief format. (You must specify a fmttyp of brief and a routin argument.)
	0	Do not build column titles.

Description

The Format Security Audit Event Message service converts a securityauditing event message from binary format to ASCII text and can filtersensitive information. $FORMAT_AUDIT allows the caller to format amessage in a multiple-line format or a single-line format and tailorthe information for a display device of a specific width.

$FORMAT_AUDIT is intended for utilities that need to format thesecurity auditing event messages received from the audit serverlistener mailbox or the system security audit log file.

Required Access or Privileges

None

Required Quota

$FORMAT_AUDIT can cause a process to exceed its page-file quota(PGFLQUOTA) if it has to format a long auditing event message. Thecaller of $FORMAT_AUDIT can also receive quota violations from servicesthat $FORMAT_AUDIT uses, such as $IDTOASC, $FAO, and $GETMSG.

Related Services

$AUDIT_EVENT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_MSGNOTFND	The service completed successfully; however, the message code cannot be found and a default message has been returned.
SS$_ACCVIO	The item list cannot be read by the caller, or the buffer length or buffer cannot be written by the caller.
SS$_BADPARAM	The item list contains an invalid identifier.
SS$_BUFFEROVF	The service completed successfully; however, the formatted output string overflowed the output buffer and has been truncated.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVCHAN	The format of the specified identifier is not valid. This condition value returned is not directly returned by $FORMAT_AUDIT. It is indirectly returned when $FORMAT_AUDIT in turn calls another service, such as an identifier translation or binary time translation service.
SS$_IVIDENT	The format of the specified identifier is invalid.
SS$_NOSUCHID	The specified identifier name does not exist in the rights database. This condition value returned is not directly returned by $FORMAT_AUDIT. It is indirectly returned when $FORMAT_AUDIT in turn calls another service, such as an identifier translation or binary time translation service.

The Free service unlocks all records that were previously locked forthe record stream.

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

On Alpha systems, releases a user capability, indicating to otherprocesses that the resource is now available.

This service accepts 64-bit addresses.

Format

SYS$FREE_USER_CAPABILITY cap_num [,prev_num] [,flags]

C Prototype

int sys$free_user_capability (int *cap_num, struct _generic_64*prev_mask, struct _generic_64 *flags);

Arguments

cap_num

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Capability number to be released by the calling Kernel thread. Thisnumber can range from 1 to 16. The cap_num argument isthe 32- or 64-bit address of the longword containing the usercapability number.

prev_mask

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The previous user capability reservation mask before execution of thisservice call. The prev_mask argument is the 32- or64-bit address of a quadword into which the service writes a quadwordbit mask specifying the previously reserved user capabilities.

flags

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Options selected for the user capability reservation. Theflags argument is a quadword bit vector wherein a bitcorresponds to an option.

Each option (bit) has a symbolic name, which the $CAPDEF macro defines.The flags argument is constructed by performing alogical OR operation using the symbolic names of each desired option.

At this time, all bits are reserved to HP and must be 0.

Description

The Release a Reserved User Capability service releases a usercapability back to the global pool, making it available for subsequentcalls to $GET_USER_CAPABILITY. The state of all user capabilities inthe system are kept in SCH$GQ_RESERVED_USER_CAPS; this service clearsthe bit position in that cell reflecting the capability numberspecified in cap_num.

This service can also return the state of the global reservation bitmask prior to a release operation.

Required Privileges

The caller must have both ALTPRI and WORLD privileges to call$FREE_USER_CAPABILITY to release a user capability. No privileges arerequired if $FREE_USER_CAPABILITY is called only to retrieve thecurrent user capability reservation mask.

Required Quota

None

Related Services

$GET_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_INSFARG	Fewer than the required number of arguments were specified, or no operation was specified.
SS$_NOPRIV	Insufficient privilege for the attempted operation.
SS$_TOO_MANY_ARGS	Too many arguments were presented to the system service.
SS$_WASCLR	The requested user capability was already released.

The Get service retrieves a record from a file.

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

Returns information about the state of transactions.

Format

SYS$GETDTI [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[log_id] ,[contxt],search ,itmlst

C Prototype

int sys$getdti (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intlog_id [4], unsigned int *contxt, void *search, 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 these optionflags described in Table SYS-41. All undefined bits must be 0. If thisargument is omitted, no flags are used.

Table SYS-41 $GETDTI Option Flags

Flag Name	Description
DDTM$M_FULL_STATE	Indicates that the $GETDTI call for a specified TID is not to complete until the ABORTED or COMMITTED state can be returned. Thus, if another node or coordinating resource manager must be contacted and it is currently unreachable, this service does not return until the node can be contacted. Indicates on a wildcard search that only transactions known to be in the ABORTED or COMMITTED states are to be returned.
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

log_id

If you do not specify the same log id used by the transaction managerto write transaction information, then $GETDTI will return an error.

If the log_id argument is specified as a zero UID,then $GETDTI will use the current active log for this node. If thespecified transaction cannot be found in this log, then the returnedstate will be aborted. The log identifier can only be specified as zerowhen the DTI$_SEARCH_AS_NODE item is absent or results in a search thatspecifies the local node. Note that the log_idargument cannot be specified as a zero address.

To ensure smooth operation in a mixed-network environment, refer to thechapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, forinformation on defining node names.

contxt

The search context is valid only after a successful call to $GETDTI andis invalidated by a subsequent call to $GETDTI.

The context is also used as input to $SETDTI after a successful call to$GETDTI. Calls to $SETDTI do not modify or invalidate the context.

search

The search argument is the address of a list of itemdescriptors, each of which describes a search item. The list of itemdescriptors is terminated by a longword of 0. Each item descriptor inthe search item list acts as an input argument to $GETDTI and as suchis only required to be read only.

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

The following table describes the search itemdescriptor fields:

itmlst

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

The following table describes the itmlst itemdescriptor fields:

Search Item Codes

DTI$_SEARCH_AS_NODE

When you specify DTI$_SEARCH_AS_NODE, $GETDTI limits the get request tothe specified node name. This can be used during cluster failoverrecovery processing to allow another node in the cluster to act onbehalf of the failed node. The DTI$_SEARCH_AS_NODE item descriptorshould point to an ASCII string containing a valid node name string.

To ensure smooth operation in a mixed-network environment, refer to thechapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, forinformation on defining node names.

DTI$_SEARCH_RESOLVED_STATE

When you specify DTI$_SEARCH_RESOLVED_STATE, the buffer address pointsto a transaction record that describes the search conditions for this$GETDTI call. The following fields are used from this transactionrecord and must be specified before $GETDTI can proceed. The $DTIDEFmacro defines these fields.

DTI$_SEARCH_RESOLVED_STATE uses the DTI$_TRANSACTION_INFORMATION itemin the itmlst argument to write the followinginformation:

Itmlst Item Codes

DTI$_TRANSACTION_INFORMATION

When you specify DTI$_TRANSACTION_INFORMATION, $GETDTI returns thefollowing fields dependent on the search criteria established by thesearch argument.

Each record may be composed of some of the following items:

The DTI$_TRANSACTION_INFORMATION item buffer size should be at leastequal to the symbolic value DTI$S_TRANSACTION_INFORMATION defined by$DTIDEF.

Description

During recovery from a failure, a resource manager calls $GETDTI torequest the state of certain transactions with which it had beeninvolved. As part of the recovery, the resource manager identifies anyunresolved transactions, so that they can be processed to completion.

The $GETDTI service returns the resolved state of in-doubt transactionsto recovering resource managers. The DDTM$M_FULL_STATE flag instructs$GETDTI to return only the transactions in the DTI$K_COMMITTED orDTI$K_ABORTED states (or an error status of SS$_NOSUCHTID). The actiontaken depends on whether a transaction identifier is specified:

• If a transaction identifier is specified in DTI$T_TID, $GETDTI does not return until the resolved state of the transaction is available.
• If DTI$T_TID is 0, $GETDTI ignores transactions that are not in the DTI$K_COMMITTED or DTI$K_ABORTED states.

This can mean that the $GETDTI call may have to wait for other DECdtmnodes or a coordinating CRM to become available. This is therecommended method of obtaining an in-doubt transaction outcome forrecovering resource managers.

Alternatively, $GETDTI can be used to return the current known state oftransactions. Intermediate states may be returned. In particular,DTI$K_PREPARED indicates that a DECdtm node is unavailable andDTI$K_PREPARING indicates that a coordinating CRM is unavailable.

If $GETDTI is called during normal system operation to resolve thestate of transactions that have not failed, then the returnedtransaction state can be any of the states listed in Table SYS-42.

A $GETDTI call may also be used in an OpenVMS Cluster environment toperform recovery on behalf of a resource manager on a failed node. Toperform this action, the DTI$_SEARCH_AS_NODE search item descriptor isused to inform $GETDTI of the node for which recovery is beingperformed. This action is equivalent to performing the $GETDTI requeston the failed node. The use of DTI$_SEARCH_AS_NODE will performcorrectly when the target node is either available or unavailable. Ifthe target node is available when the $GETDTI call is executed, therequest is re-routed to the target node for execution.

To obtain information about transactions, $GETDTI must be given a setof search criteria. The criteria are specified as parameters and aspart of an itemlist for the search argument using theDTI$_SEARCH_RESOLVED_STATE item descriptor. The transaction informationrequired by $GETDTI to resolve a transaction includes:

• Transaction Identifier (TID).
• Resource Manager name.
• Transaction Manager log identifier.
• Resource Manager log identifier.
• Optionally, a remote node name.

If you specify a TID as 0, $GETDTI assumes a wildcard operation andreturns the requested information for each TID in the log that it hasprivilege to access, one TID per call. To perform a wildcard operation,you must call $GETDTI in a loop, testing for the condition valueSS$_NOSUCHTID after each call and exiting the loop when SS$_NOSUCHTIDis returned.

A resource manager is identified by its name in DTI$T_PART_NAME. Awildcard search can be specified for the resource manager with thisitem. The leftmost characters supplied in this string are matchedagainst all resource managers with the same leftmost characters intheir names.

If a resource manager name entered as the item has a length of 0, allresource managers are selected.

Transaction managers and resource managers maintain log files to keep arecord of transactions and their related states. During recovery, it isimportant that the transaction manager and resource manager usematching log files. The transaction manger log identifier is returnedby the $DECLARE_RM service call. It should be recorded in the resourcemanager's log records and supplied to $GETDTI as the value of thelog-id argument. If the wrong resource manager log, orthe wrong transaction manager log, is used, the discrepancy will resultin an error from $GETDTI or $SETDTI.

The contxt argument is used by $GETDTI to establish asearch context when it is returning the resolved state of atransaction. The search context indicates the node and transactionmanager log identifier for use in a subsequent $SETDTI operation todelete the resource manager from the transaction. The search context iscreated when the contxt argument is invalid, orre-used if the contxt argument is valid. The searchcontext is deleted when a call is made to $GETDTI that returnsSS$_NOSUCHTID. The search context is maintained exclusively by $GETDTIand $SETDTI and should not be modified by the caller, with an exceptionof initially zeroing the context. SYSPRV privilege is required toretrieve or modify information about transactions with which theprocess is not currently associated.

Required Privileges

SYSPRV is required to retrieve information about transactions withwhich the process is not currently 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, $GETDTIW,$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $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 is an invalid or unsupported log version.
SS$_BADPARAM	The option flags, SEARCH or ITMLST are invalid.
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 is not authorized to examine the specified transaction.
SS$_PROTOCOL	There is a message protocol error.
SS$_REMOTE_PROC	There was an attempt to use a node when it is not part of the OpenVMS Cluster.
SS$_REMRSRC	There are insufficient resources at the remote node.
SS$_UNREACHABLE	A superior node is unreachable.

Returns information about the resolved state of transactions and theprocess default transaction identifier.

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

Format

SYS$GETDTIW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[contxt],[log_id] ,search ,itmlst

C Prototype

int sys$getdtiw (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intlog_id [4], unsigned int *contxt, void *search, void *itmlst);

Returns information related to the primary and secondary devicecharacteristics of an I/O device.

For synchronous completion, use the Get Device/Volume Information andWait ($GETDVIW) service. The $GETDVIW service is identical to the$GETDVI service in every way except that $GETDVIW returns to the callerwith the requested information.

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

Format

SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr] [,astprm][,nullarg]

C Prototype

int sys$getdvi (unsigned int efn, unsigned short int chan, void*devnam, void *itmlst, struct _iosb *iosb, void(*astadr)(__unknown_params), int astprm, struct _generic_64 *nullarg);

Arguments

efn

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

Number of the event flag to be set when $GETDVI returns the requestedinformation. The efn argument is a longword containingthis number; however, $GETDVI uses only the low-order byte.

Upon request initiation, $GETDVI clears the specified event flag (orevent flag 0 if efn was not specified). Then, when$GETDVI returns the requested information, it sets the specified eventflag (or event flag 0).

chan

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

Number of the I/O channel assigned to the device about whichinformation is desired. The chan argument is a wordcontaining this number.

To identify a device to $GETDVI, you can specify either thechan or devnam argument, but youshould not specify both. If you specify both arguments, thechan argument is used.

If you specify neither chan nordevnam, $GETDVI uses a default value of 0 forchan.

devnam

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

The name of the device about which $GETDVI is to return information.The devnam argument is the address of a characterstring descriptor pointing to this name string.

The device name string can be either a physical device name or alogical name. If the first character in the string is an underscore(_), the string is considered a physical device name; otherwise, thestring is considered a logical name and logical name translation isperformed until either a physical device name is found or the systemdefault number of translations has been performed.

If the device name string contains a colon (:), the colon and thecharacters that follow it are ignored.

To identify a device to $GETDVI, you can specify either thechan or devnam argument, but youshould not specify both. If both arguments are specified, thechan argument is used.

If you specify neither chan nordevnam, $GETDVI uses a default value of 0 forchan.

itmlst

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

Item list specifying which information about the device is to bereturned. The itmlst argument is the address of a listof item descriptors, each of which describes an item of information.The list of item descriptors is terminated by a longword of 0. Thefollowing diagram depicts the format of a single item descriptor:

The following table defines the item descriptor fields:

iosb

When you specify the iosb argument, $GETDVI sets thequadword to 0 upon request initiation. Upon request completion, acondition value is returned to the first longword; the second longwordis reserved to HP.

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 $GETDVI 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 $GETDVI, you must check the condition values returned in both R0 and the I/O status block.

astadr

If you specify astadr, the AST routine executes at thesame access mode as the caller of the $GETDVI service.

astprm

nullarg

Item Codes

DVI$_ACPPID

Returns the ACP process ID as an unsigned integer longword.

DVI$_ACPTYPE

Returns the ACP type code as an unsigned integer longword. Thefollowing symbols define each of the ACP type codes that $GETDVI canreturn:

Symbol	Description
DVI$C_ACP_F11V1	Files-11 Level 1
DVI$C_ACP_F11V2	Files-11 Level 2
DVI$C_ACP_F11V5	Files-11 Level 5
DVI$C_ACP_MTA	Magnetic tape
DVI$C_ACP_NET	Networks
DVI$C_ACP_REM	Remote I/O

DVI$_ALL

Returns a string that is either TRUE or FALSE to indicate whether thedevice is allocated or not allocated.

DVI$_ALLDEVNAM

Returns the allocatable device name as a 64-byte, zero-filled string.

The allocatable device name, sometimes called the allocation-classdevice name, uniquely identifies each device that is currentlyaccessible to any given node in an OpenVMS cluster or to a single-nodeOpenVMS system. This item code generates the same name on every systemfor a device that is accessible on multiple cluster nodes throughmultiple paths or servers.

The device name string returned by the DVI$_ALLDEVNAM item code isrecommended for use with the $ASSIGN service, regardless of whether thesystem is clustered or whether the device is cluster accessible,because it returns the same string value for all conditions.

Another possible use for the DVI$_ALLDEVNAM item code might be anapplication wherein processes need to coordinate their access todevices (not volumes) using the lock manager. In this case, the programwould make the device a resource to be locked by the lock manager,specifying as the resource name the following concatenated components:(1) a user facility prefix followed by an underscore character and (2)the allocatable device name of the device.

Depending on the device type and characteristics, the format of thereturned name may include an allocation class or node name prefix.

Note that the name returned by the DVI$_DEVLOCKNAM item code should beused to coordinate access to volumes.

DVI$_ALLOCLASS

Returns the allocation class of the host as a longword integer between0 and 32767. An allocation class is a unique number between 0 and 32767that the system manager assigns to a pair of hosts and the dual-patheddevices that the hosts make available to other nodes in the cluster.

The allocation class provides a way for you to access dual-patheddevices through either of the hosts that act as servers to the cluster.In this way, if one host of an allocation class set is not available,you can gain access to a device specified by that allocation classthrough the other host of the allocation class. You do not have to beconcerned about which host of the allocation class provides access tothe device. Specifically, the device name string has the followingformat:

$allocation_class$device_name

For a detailed discussion of allocation classes, refer to OpenVMS Cluster Systems.

DVI$_ALT_HOST_AVAIL

Returns a longword that is interpreted as Boolean. A value of 1indicates that the host serving the alternate path is available; avalue of 0 indicates that it is not available.

The host is the node that makes the device available to other nodes inthe OpenVMS Cluster system. A host node can be either a VAX system withan MSCP server or an HSC50 controller.

A dual-pathed device is one that is made available to the cluster bytwo hosts. Each of the hosts provides access (serves a path) to thedevice for users. One host serves the primary path; the other hostserves the alternate path. The primary path is the path that the systemcreates through the first available host.

You should not be concerned with which host provides access to thedevice. When accessing a device, you specify the allocation class ofthe desired device, not the name of the host that serves it.

If the host serving the primary path fails, the system automaticallycreates a path to the device through the alternate host.

DVI$_ALT_HOST_NAME

Returns the name of the host serving the alternate path as a 64-byte,zero-filled string.

For more information about hosts, dual-pathed devices, and primary andalternate paths, refer to the description of the DVI$_ALT_HOST_AVAILitem code.

DVI$_ALT_HOST_TYPE

Returns a four-byte string containing an arbitrary text description ofthe OpenVMS host or cluster storage controller that is serving thisstorage device. The particular text string displayed was provided tothe local OpenVMS system by the remote System Communications Services(SCS) server.

Storage devices are served within an OpenVMS Cluster utilizing the SCSprotocol, with the server running on a remote OpenVMS system or on anSCS-capable storage controller. The alternate host type value displayedis determined from the local cluster storage hardware configuration,and indicates the type of devices serving the storage for the availableSCS path or paths to the particular storage device.

Item codes in this group include: DVI$_HOST_TYPE, DVI$_ALT_HOST_TYPE,DVI$_HOST_AVAIL, and DVI$_ALT_HOST_AVAIL. Also related isDVI$_HOST_NAME.

HP suggests this item code be used solely for display purposes, andshould not be used during an attempt to determine the particularcluster hardware configuration.

DVI$_CLUSTER

Returns the volume cluster size as an unsigned integer longword. Thisitem code is applicable only to disks.

DVI$_CYLINDERS

Returns the number of cylinders on the volume as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_DEVBUFSIZ

Returns the device buffer size (for example, the width of a terminal orthe block size of a tape) as an unsigned integer longword.

DVI$_DEVCHAR

Returns device-independent characteristics as a 4-byte bit vector. Eachcharacteristic is represented by a bit. When $GETDVI sets a bit, thedevice has the corresponding characteristic. Each bit in the vector hasa symbolic name. The $DEVDEF macro defines the following symbolic names:

Symbol	Description
DEV$V_REC	Device is record oriented.
DEV$V_CCL	Device is a carriage control device.
DEV$V_TRM	Device is a terminal.
DEV$V_DIR	Device is directory structured.
DEV$V_SDI	Device is single-directory structured.
DEV$V_SQD	Device is sequential and block oriented.
DEV$V_SPL	Device is being spooled.
DEV$V_OPR	Device is an operator.
DEV$V_RCT	Disk contains Revector Cache Table (RCT). This bit is set for every DSA disk.
DEV$V_NET	Device is a network device.
DEV$V_FOD	Device is files oriented.
DEV$V_DUA	Device is dual ported.
DEV$V_SHR	Device is shareable.
DEV$V_GEN	Device is a generic device.
DEV$V_AVL	Device is available for use.
DEV$V_MNT	Device is mounted.
DEV$V_MBX	Device is a mailbox.
DEV$V_DMT	Device is marked for dismount.
DEV$V_ELG	Device has error logging enabled.
DEV$V_ALL	Device is allocated.
DEV$V_FOR	Device is mounted foreign.
DEV$V_SWL	Device is software write locked.
DEV$V_IDV	Device can provide input.
DEV$V_ODV	Device can provide output.
DEV$V_RND	Device allows random access.
DEV$V_RTM	Device is a real-time device.
DEV$V_RCK	Device has read-checking enabled.
DEV$V_WCK	Device has write-checking enabled.

Note that each device characteristic has its own individual $GETDVIitem code with the format DVI$_xxxx, where xxxx are thecharacters following the underscore character in the symbolic name forthat device characteristic.

For example, when you specify the item code DVI$_REC, $GETDVI returns alongword value that is interpreted as Boolean. If the value is 0, thedevice is not record oriented; if the value is 1, it is recordoriented. This information is identical to that returned in theDEV$V_REC bit of the longword vector specified by the DVI$_DEVCHAR itemcode.

The buffer must specify a longword for all of thesedevice-characteristic item codes.

DVI$_DEVCHAR2

Returns additional device-independent characteristics as a 4-byte bitvector. Each bit in the vector, when set, corresponds to a symbolicname. The $DEVDEF macro defines the following symbolic names:

Symbol	Description
DEV$V_CLU	Device is available clusterwide.
DEV$V_DET	Device is detached terminal.
DEV$V_RTT	Device has remote terminal UCB extension.
DEV$V_CDP	Dual-pathed device with two UCBs.
DEV$V_2P	Two paths are known to this device.
DEV$V_MSCP	Device accessed using MSCP (disk or tape). Before using this bit to differentiate between types of disk and tape devices, be sure that no other more appropriate differentiation mechanism exists.
DEV$V_SSM	Device is a shadow set member.
DEV$V_SRV	Device is served by the MSCP server.
DEV$V_RED	Device is redirected terminal.
DEV$V_NNM	Device has node$ prefix.
DEV$V_WBC	Device supports write-back caching.
DEV$V_WTC	Device supports write-through caching.
DEV$V_HOC	Device supports host caching.
DEV$V_LOC	Device accessible by local (non-emulated) controller.
DEV$V_DFS	Device is DFS-served.
DEV$V_DAP	Device is DAP accessed.
DEV$V_NLT	Device is not-last-track; that is, it has no bad block. Information is on its last track.
DEV$V_SEX	Device (tape) supports serious exception handling.
DEV$V_SHD	Device is a member of a host-based shadow set.
DEV$V_VRT	Device is a shadow set virtual unit.
DEV$V_LDR	Loader present (tapes).
DEV$V_NOLB	Device ignores server load balancing requests.
DEV$V_NOCLU	Device will never be available clusterwide.
DEV$V_VMEM	Virtual member of a constituent set.
DEV$V_SCSI	Device is a SCSI device.
DEV$V_WLG	Device has write-logging capability.
DEV$V_NOFE	Device does not support forced error.

DVI$_DEVCLASS

Returns the device class as an unsigned integer longword. Each classhas a corresponding symbol. The $DCDEF macro defines these symbols. Thefollowing table describes each device class symbol:

Symbol	Description
DC$_DISK	Disk device
DC$_TAPE	Tape device
DC$_SCOM	Synchronous communications device
DC$_CARD	Card reader
DC$_TERM	Terminal
DC$_LP	Line printer
DC$_REALTIME	Real-time
DC$_MAILBOX	Mailbox
DC$_MISC	Miscellaneous device

DVI$_DEVDEPEND

Returns device-dependent characteristics as a 4-byte bit vector. Todetermine what information is returned for a particular device, referto the HP OpenVMS I/O User's Reference Manual.

Note that, for terminals only, individual $GETDVI item codes areprovided for most of the informational items returned in theDVI$_DEVDEPEND longword bit vector. The names of these item codes havethe format DVI$_TT_xxxx, where xxxx is the characteristicname. The same characteristic name follows the underscore character inthe symbolic name for each bit (defined by the $TTDEF macro) in theDVI$_DEVDEPEND longword. For example, the DVI$_TT_NOECHO item codereturns the same information as that returned in the DVI$_DEVDEPEND bitwhose symbolic name is TT$V_NOECHO.

Each such item code requires that the buffer specify a longword value,which is interpreted as Boolean. A value of 0 indicates that theterminal does not have that characteristic; a value of 1 indicates thatit does.

The list of these terminal-specific item codes follows this list ofitem codes.

DVI$_DEVDEPEND2

Returns additional device-dependent characteristics as a 4-byte bitvector. Refer to the HP OpenVMS I/O User's Reference Manual to determine what information isreturned for a particular device.

Note that, for terminals only, individual $GETDVI item codes areprovided for most of the informational items returned in theDVI$_DEVDEPEND2 longword bit vector. As with DVI$_DEVDEPEND, the samecharacteristic name appears in the item code as appears in the symbolicname defined for each bit in the DVI$_DEVDEPEND2 longword, except thatin the case of DVI$_DEVDEPEND2, the symbolic names for bits are definedby the $TT2DEF macro.

The list of these terminal-specific item codes follows this list ofitem codes.

DVI$_DEVICE_TYPE_NAME

Returns a string identifying the type of device about which informationwas requested.

DVI$_DEVLOCKNAM

Returns the device lock name, which is a 64-byte string. The devicelock name uniquely identifies each volume or volume set in an OpenVMSCluster system or in a single-node system. This item code is applicableonly to disks.

The item code is applicable to all disk volumes and volume sets:mounted, not mounted, mounted shared, mounted private, or mountedforeign.

The device lock name is assigned to a volume when it is first mounted,and you cannot change this name, even if the volume name itself ischanged. This allows any process on any node in an OpenVMS Clustersystem to access a uniquely identified volume.

One use for the device lock name might be in an application whereinprocesses need to coordinate their access to files using the lockmanager. In this case, the program would make the file a resource to belocked by the lock manager, specifying as the resource name thefollowing concatenated components: (1) a user facility prefix followedby an underscore character, (2) the device lock name of the volume onwhich the file resides, and (3) the file ID of the file.

DVI$_DEVNAM

Returns a displayable device name as a 64-byte, zero-filled string.

DVI$_DEVNAM returns a displayable device name; however, it may notreturn a unique name for cluster-accessible devices. For this reason,the DVI$_DEVNAM item code is not recommended for use with the $ASSIGNservice. Use the DVI$_ALLDEVNAM item code with the $ASSIGN service.

Depending on the device type and characteristics, the format of thereturned name may include an allocation class or node name prefix.

The DVI$_DEVNAM item code is provided solely for compatibility withexisting programs from previous OpenVMS releases; therefore, HPrecommends that you use the DVI$_ALLDEVNAM, DVI$_FULLDEVNAM, orDVI$_DISPLAY_DEVNAM item codes, depending on the function required.

DVI$_DEVSTS

Returns device-dependent status information as a 4-byte bit vector. The$UCBDEF macro defines symbols for the status bits. For thisdevice-dependent information, refer to the HP OpenVMS I/O User's Reference Manual.

DVI$_DEVTYPE

Returns the device type as an unsigned integer longword. The $TTDEFmacro defines symbols for the device types.

DVI$_DFS_ACCESS

Returns a Boolean value indicating whether a device is a DFS serveddisk. A value of 0 indicates that the device is a DFS served disk; avalue of 1 indicates that the device is not.

This information allows you to determine if a function works on remotedisk devices with DFS. Access control lists (ACLs), for example, cannotbe set or displayed on local disk devices with DFS.

DVI$_DISPLAY_DEVNAM

Returns a displayable device name as a 256-byte, zero-filled string.

The format of the returned name includes the allocatable device namefor the device (see DVI$_ALLDEVNAM) followed by any current primary orsecondary path information for the device.

Depending on the device type and characteristics, the format of thereturned name may include an allocation class or node name prefix.

The device name string returned by the DVI$_DISPLAY_DEVNAM item codecannot be used used for the $ASSIGN service. Use the DVI$_ALLDEVNAMitem code to form the device name for the $ASSIGN service.

DVI$_ERRCNT

Returns the error count of the device as an unsigned lognword. Theerror count may have been reset with the SET DEVICE/RESET=ERRCNTcommand. If the error count has been reset, use the SHOW DEVICE/FULLcommand to display the date and time that the error count was reset.

DVI$_EXPSIZE

Returns the current expansion limit on the volume.

DVI$_FC_NODE_NAME

DVI$_FC_PORT_NAME

Returns the Fibre Channel Node or Port name for the Fibre Channel HostBus Adapter as a zero-filled string for each of these values. If aFibre Channel Disk or Tape is directly attached to the system, then thecodes also work for these devices.

The maximum length of this string may change in the future; therefore,HP recommends that you pass a 32-byte buffer to this function. A returnlength address should also be passed with the call and examined whenthe function completes.

If the return length is equal to the size of the buffer, then call$GETDVI again with a larger buffer to ensure that the complete name hasbeen read.

DVI$_FREEBLOCKS

Returns the number of free blocks on a disk as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_FULLDEVNAM

Returns a displayable device name as a 64-byte, zero-filled string.

DVI$_FULLDEVNAM returns a displayable device name, which includesappropriate identification to distinguish cluster-accessible devices byincluding the allocation class or node name in the device string.

One use for the DVI$_FULLDEVNAM item code might be to retrieve the nameof a device in order to have that name displayed on a terminal.However, you should not use this name as a resource name as input tothe lock manager; use the name returned by the DVI$_DEVLOCKNAM itemcode for locking volumes and the name returned by DVI$_ALLDEVNAM forlocking devices.

Depending on the device type and characteristics, the format of thereturned name may include an allocation class or node name prefix.

The name returned by the DVI$_FULLDEVNAM item code can be used for the$ASSIGN service. HP recommends that you use the DVI$_ALLDEVNAM itemcode to form the name for the $ASSIGN service, so that the name appearsthe same regardless of which OpenVMS Cluster node is accessing thedevice.

DVI$_HOST_AVAIL

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the host serving the primary path is available; a valueof 0 indicates that it is not available.

For more information about hosts, dual-pathed devices, and primary andalternate paths, refer to the description of the DVI$_ALT_HOST_AVAILitem code.

DVI$_HOST_COUNT

Returns, as a longword integer, the number of hosts that make thedevice available to other nodes in the OpenVMS Cluster system. One ortwo hosts, but no more, can make a device available to other nodes inthe cluster.

For more information about hosts, dual-pathed devices, and primary andalternate paths, refer to the description of the DVI$_ALT_HOST_AVAILitem code.

DVI$_HOST_NAME

Returns the name of the host serving the primary path as a 64-byte,zero-filled string.

For more information about hosts, dual-pathed devices, and primary andalternate paths, refer to the description of the DVI$_ALT_HOST_AVAILitem code.

DVI$_HOST_TYPE

Returns a four-byte string containing an arbitrary text description ofthe OpenVMS host or cluster storage controller that is serving thisstorage device. The particular text string displayed was provided tothe local OpenVMS system by the remote System Communications Services(SCS) server.

Storage devices are served within an OpenVMS Cluster utilizing the SCSprotocol, with the server running on a remote OpenVMS system or on anSCS-capable storage controller. The host type value displayed isdetermined from the local cluster storage hardware configuration, andindicates the type of devices serving the storage for the available SCSpath or paths to the particular storage device.

Item codes in this group include: DVI$_HOST_TYPE, DVI$_ALT_HOST_TYPE,DVI$_HOST_AVAIL, and DVI$_ALT_HOST_AVAIL. Also related isDVI$_HOST_NAME.

HP suggests this item code be used solely for display purposes, andshould not be used during an attempt to determine the particularcluster hardware configuration.

DVI$_LOCKID

Returns the lock ID of the lock on a disk. The lock manager locks adisk if it is available to all nodes in an OpenVMS Cluster system andit is either allocated or mounted. A disk is available to all nodes inan OpenVMS Cluster system if, for example, it is served by an HSCcontroller or MSCP server or if it is a dual-ported MASSBUS disk.

The buffer must specify a longword into which $GETDVI is to return the4-byte hexadecimal lock ID.

DVI$_LOGVOLNAM

Returns the logical name of the volume or volume set as a 64-bytestring.

DVI$_MAXBLOCK

Returns the maximum number of blocks on the volume as an unsignedinteger longword. This item code is applicable only to disks.

DVI$_MAXFILES

Returns the maximum number of files on the volume as an unsignedinteger longword. This item code is applicable only to disks.

DVI$_MEDIA_ID

Returns the nondecoded media ID as a longword. This item code isapplicable only to disks and tapes.

DVI$_MEDIA_NAME

Returns the name of the volume type (for example, RK07 or TA78) as a64-byte, zero-filled string. This item code is applicable only to disksand tapes.

DVI$_MEDIA_TYPE

Returns the device name prefix of the volume (for example, DM for anRK07 device or MU for a TA78 device) as a 64-byte, zero-filled string.This item code is applicable only to disks and tapes.

DVI$_MOUNTCNT

Returns the mount count for the volume as an unsigned integer longwordand displays the number of times the volume has been mounted on thelocal system.

The value of MOUNTCNT displayed by the SHOW DEVICE command is the totalof all mounts of the volume across all members of the cluster.

DVI$_MPDEV_CURRENT_PATH

Returns the current path name for multipath devices as a string.

If the device is not part of a multipath set, $GETDVI will return thename of the device path if the class driver for this device supportspath names. SYS$DKDRIVER, SYS$DUDRIVER, SYS$MKDRIVER, and SYS$GKDRIVERsupport path names.

If the class driver for the device does not support path names, $GETDVIreturns a null string.

DVI$_MSCP_UNIT_NUMBER

Returns the internal coded value for MSCP unit numbers as a longwordinteger. This item code is reserved to HP.

DVI$_MT3_DENSITY

Returns the density of the device. Valid for tapes only. This code isan unsigned longword integer.

DVI$_MT3_SUPPORTED

The return value of 1 indicates that the device supports tape densitycodes defined by MT3DEF. Valid for tapes only. This code is an unsignedlongword integer.

DVI$_MULTIPATH

Returns a longword, interpreted as a Boolean. A value of 1 indicatesthe device is a member of a multipath set.

DVI$_NEXTDEVNAM

Returns the device name of the next volume in the volume set as a64-byte, zero-filled string. The node name is also returned. This itemcode is applicable only to disks.

DVI$_OPCNT

Returns the operation count of the device as an unsigned longword. Notethat the operation count may have been reset with the SETDEVICE/RESET=OPCNT command.

DVI$_OWNUIC

Returns the user identification code (UIC) of the owner of the deviceas a standard 4-byte UIC.

DVI$_PID

Returns the process identification (PID) of the owner of the device asan unsigned integer longword.

DVI$_PREFERRED_CPU

The return argument is a 32-bit CPU bit mask with a bit set indicatingthe preferred CPU. A return argument containing a bit mask of zeroindicates that no preferred CPU exists, either because Fast Path isdisabled or the device is not a Fast Path capable device. The returnargument serves as a CPU bit mask input argument to the$PROCESS_AFFINITY system service. The argument can be used to assign anapplication process to the optimal preferred CPU.

DVI$_RECSIZ

Returns the blocked record size as an unsigned integer longword.

DVI$_REFCNT

Returns the number of channels assigned to the device as an unsignedinteger longword.

DVI$_REMOTE_DEVICE

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device is a remote device; a value of 0 indicatesthat it is not a remote device. A remote device is a device that is notdirectly connected to the local node, but instead is visible throughthe OpenVMS Cluster system.

DVI$_ROOTDEVNAM

Returns the device name of the root volume in the volume set as a64-byte, zero-filled string. This item code is applicable only to disks.

DVI$_SECTORS

Returns the number of sectors per track as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_SERIALNUM

Returns the serial number of the volume as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_SERVED_DEVICE

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device is a served device; a value of 0 indicatesthat it is not a served device. A served device is one whose local nodemakes it available to other nodes in the OpenVMS Cluster system.

DVI$_SHDW_CATCHUP_COPYING

Returns a longword, which is interpreted as Boolean. The value 1indicates that the device is the target of a full copy operation.

DVI$_SHDW_COPIER_NODE

Returns the name of the node that is actively performing either thecopy or the merge operation, as a string.

DVI$_SHDW_DEVICE_COUNT

Returns the total number of devices in the virtual unit, includingdevices being added as copy targets, as a longword.

DVI$_SHDW_FAILED_MEMBER

Returns a longword, which is interpreted as Boolean. The value 1indicates that the device is a member that has been removed from theshadow set by the remote server. The DVI$_SHDW_FAILED_MEMBER item codeis for use only with VAX Volume Shadowing (phase I).

DVI$_SHDW_GENERATION

Returns the current, internal revision number of the virtual unit, as aquadword.

DVI$_SHDW_MASTER

Returns a longword, which is interpreted as Boolean. The value 1indicates that the device is a virtual unit named DSAnnnn:.

DVI$_SHDW_MASTER_MBR

Returns the name of the master member unit that is used for merge andcopy repair operations and for shadow set recovery operations, as astring.

DVI$_SHDW_MASTER_NAME

When the specified device is a shadow set member, $GETDVI returns thedevice name of the virtual unit (DSAnnnn:) that represents the shadowset of which the specified device is a member. $GETDVI returns a nullstring if the specified device is not a member or is itself a virtualunit (DSAnnnn:).

Note Shadow set members must have a nonzero allocation class to operate inan OpenVMS Cluster system. Refer to HP Volume Shadowing for OpenVMS for more information.

Because the shadow set virtual unit name can include up to 64characters, the buffer length field of the item descriptor shouldspecify 64 (bytes).

DVI$_SHDW_MBR_COPY_DONE

Returns the percentage of the copy operation that is complete on thecurrent member unit, as a longword.

DVI$_SHDW_MBR_COUNT

Returns the number of full source members in the virtual unit, as alongword. Devices added as copy targets are not full source members.

DVI$_SHDW_MBR_MERGE_DONE

Returns the percentage of the merge operation that has been completedon the member, as a longword.

DVI$_SHDW_MBR_READ_COST

Returns the current value set for the member unit, as a longword. Thisvalue can be modified to use a customer-specified value.

DVI$_SHDW_MEMBER

Returns a longword, which is interpreted as Boolean. The value 1indicates that the device is a shadow set member.

DVI$_SHDW_MERGE_COPYING

Returns a longword, which is interpreted as Boolean. The value 1indicates that the device is a merge member of the shadow set.

DVI$_SHDW_MINIMERGE_ENABLE

Returns a longword, which is interpreted as Boolean. The value 1indicates that the virtual unit will undergo a mini-merge and not afull merge, if a system in the cluster crashes.

DVI$_SHDW_NEXT_MBR_NAME

Returns the device name of the next member in the shadow set. If youspecify a virtual unit with the chan ordevnam argument, DVI$_SHDW_NEXT_MBR_NAME returns thedevice name of a member of a shadow set. If you specify the name of ashadow set member unit with the chan ordevnam argument, DVI$_SHDW_NEXT_MBR_NAME returns thename of the next member unit or a null string if there are no moremembers.

To determine all the members of a shadow set, first specify the virtualunit (DSAnnnn:) to $GETDVI. Then, on subsequent calls, specify themember name returned by the previous $GETDVI call until it returns anull member name.

When the shadow set members have a nonzero allocation class, the devicename returned by $GETDVI contains the allocation class; the name hasthe form $allocation-class$device. For example, if a shadowset has an allocation class of 255 and the device name is DUA42,$GETDVI returns the string $255$DUA42.

Note Shadow set members must have a nonzero allocation class to operate inan OpenVMS Cluster system. Refer to HP Volume Shadowing for OpenVMS for more information.

Because a device name can include up to 64 characters, the bufferlength field of the item descriptor should specify 64 (bytes).

DVI$_SHDW_READ_SOURCE

Returns the name of the member unit that is used for reads, at thispoint in time, as a longword. DVI$_SHDW_READ_SOURCE uses the unit thathas the lowest value of the sum of its queue length and read cost forreads. This is a dynamic value.

DVI$_SHDW_TIMEOUT

Returns the customer-specified timeout value set for the device, as along word. If you do not set a value by way of the SETSHOWSHADOWutility, the SYSGEN parameter SHADOW_MBR_TWO is used for member unitsand MVTIMEOUT is used for virtual units.

DVI$_STS

Returns the device unit status as a 4-byte bit vector. Each bit in thevector, when set, corresponds to a symbolic name that is defined by the$UCBDEF macro. The following table describes each name:

Symbol	Description
UCB$V_ALTBSY	Unit is busy via alternate startio path.
UCB$V_BSY	Unit is busy.
UCB$V_CANCEL	I/O on unit is canceled.
UCB$V_CLUTRAN	OpenVMS Cluster state transition in progress.
UCB$V_DEADMO	Deallocate at dismount.
UCB$V_DELETEUCB	Delete this UCB when reference count equals 0.
UCB$V_DISMOUNT	Dismount in progress.
UCB$V_ERLOGIP	Error log is in progress on unit.
UCB$V_EXFUNC_SUPP	Unit supports the EXFUNC bit.
UCB$V_FAST_PATH	Unit supports FAST PATH Affinity.
UCB$V_FP_HWINT	Unit supports FAST PATH hardware interrupt CPU Affinity.
UCB$V_INT	Interrupt is expected.
UCB$V_INTTYPE	Receiver interrupt.
UCB$V_IOPOST_LOCAL	Unit supports I/O post processing on the current CPU.
UCB$V_LCL_VALID	Volume is valid on the local node.
UCB$V_MNTVERIP	Mount verification is in progress.
UCB$V_MOUNTING	Device is being mounted.
UCB$V_MNTVERPND	Mount verification is pending on busy device.
UCB$V_NO_ASSIGN	Unit cannot have channels assigned to it.
UCB$V_ONLINE	Unit is on line.
UCB$V_PATHVERIP	Path verification is in progress for this device.
UCB$V_POWER	Power failed while unit busy.
UCB$V_SNAPSHOT	Restart validation is in progress.
UCB$V_SUPMVMSG	If set, suppress success type mount version messages.
UCB$V_SVPN_END	Last byte used from page mapped by system virtual page number (SVPN).
UCB$V_TEMPLATE	Template UCB from which other UCBs for this device type are made.
UCB$V_TIM	Timeout is enabled.
UCB$V_TIMOUT	Unit timed out.
UCB$V_UNLOAD	Unload volume at dismount.
UCB$V_VALID	Volume is software valid.
UCB$V_WRONGVOL	Wrong volume detected during mount verification.
UCB$V_WRTLOCKMV	Write-locked mount verification in progress.

DVI$_TRACKS

Returns the number of tracks per cylinder as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_TRANSCNT

Returns the transaction count for the volume as an unsigned integerlongword.

DVI$_QLEN

Returns the queue length for the device, as a long word. Note that thisvalue is the number of I/O requests already in the driver and not thedepth of the I/O pending queue.

DVI$_TT_ACCPORNAM

Returns the name of the remote access port associated with a channelnumber or with a physical or virtual terminal device number. If youspecify a device that is not a remote terminal or a remote type thatdoes not support this feature, $GETDVI returns a null string. The$GETDVI service returns the access port name as a 64-byte, zero-filledstring.

The $GETDVI service returns the name in the format of the remotesystem. If the remote system is a LAT terminal server, $GETDVI returnsthe name as server_name/port_name. The names are separated bythe slash (/) character. If the remote system is an X.29 terminal, thename is returned as network.remote_DTE.

When writing applications, you should use the string returned byDVI$_ACCPORNAM, instead of the physical device name, to identify remoteterminals.

DVI$_TT_CHARSET

Returns, as a 4-byte bit vector, the character sets supported by theterminal. Each bit in the vector, when set, corresponds to the name ofa coded character set. The $TTCDEF macro defines the following codedcharacter sets:

Symbol	Description
TTC$V_HANGUL	DEC Korean
TTC$V_HANYU	DEC Hanyu
TTC$V_HANZI	DEC Hanzi
TTC$V_KANA	DEC Kana
TTC$V_KANJI	DEC Kanji
TTC$V_THAI	DEC Thai

DVI$_TT_CS_HANGUL

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Korean coded character set;a value of 0 indicates that the device does not support the DEC Koreancoded character set.

DVI$_TT_CS_HANYU

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Hanyu coded character set; avalue of 0 indicates that the device does not support the DEC Hanyucoded character set.

DVI$_TT_CS_HANZI

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Hanzi coded character set; avalue of 0 indicates that the device does not support the DEC Hanzicoded character set.

DVI$_TT_CS_KANA

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Kana coded character set; avalue of 0 indicates that the device does not support the DEC Kanacoded character set.

DVI$_TT_CS_KANJI

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Kanji coded character set; avalue of 0 indicates that the device does not support the DEC Kanjicoded character set.

DVI$_TT_CS_THAI

Returns a longword, which is interpreted as Boolean. A value of 1indicates that the device supports the DEC Thai coded character set; avalue of 0 indicates that the device does not support the DEC Thaicoded character set.

DVI$_TT_PHYDEVNAM

Returns a string containing the physical device name of a terminal. Ifthe caller specifies a disconnected virtual terminal or a device thatis not a terminal, $GETDVI returns a null string. $GETDVI returns thephysical device name as a 64-byte, zero-filled string.

DVI$_UNIT

Returns the unit number as an unsigned integer longword.

DVI$_VOLCHAR

On Alpha systems, returns a 128-bit string (16 bytes) that representsthe volume characteristics or capabilities of the mounted device. If abit is set, the volume is capable of performing the function.

DVI$_VOLCOUNT

Returns the number of volumes in the volume set as an unsigned integerlongword. This item code is applicable only to disks.

DVI$_VOLNAM

Returns the volume name as a 12-byte, zero-filled string.

DVI$_VOLNUMBER

Returns the volume number of this volume in the volume set as anunsigned integer longword. This item code is applicable only to disks.

DVI$_VOLSETMEM

Returns a longword value, which is interpreted as Boolean. A value of 1indicates that the device is part of a volume set; a value of 0indicates that it is not. This item code is applicable only to disks.

DVI$_VOLSIZE

Returns the volume's current logical volume size.

DVI$_VPROT

Returns the volume protection mask as a standard 4-byte protection mask.

DVI$_TT_xxxx

DVI$_TT_xxxx is the format for a series of item codes that returninformation about terminals. This information consists of terminalcharacteristics. The xxxx portion of the item code namespecifies a single terminal characteristic.

Each of these item codes requires that the buffer specify a longwordinto which $GETDVI will write a 0 or 1: 0 if the terminal does not havethe specified characteristic, and 1 if the terminal does have it. Theone exception is the DVI$_TT_PAGE item code, which when specifiedcauses $GETDVI to return a decimal longword value that is the page sizeof the terminal.

You can also obtain this terminal-specific information by using theDVI$_DEVDEPEND and DVI$_DEVDEPEND2 item codes. Each of these two itemcodes specifies a longword bit vector wherein each bit corresponds to aterminal characteristic; $GETDVI sets the corresponding bit for eachcharacteristic possessed by the terminal.

Following is a list of the item codes that return information aboutterminal characteristics. For information about these characteristics,refer to the description of the F$GETDVI lexical function in theHP OpenVMS DCL Dictionary.

DVI$_TT_NOECHO	DVI$_TT_NOTYPEAHD
DVI$_TT_HOSTSYNC	DVI$_TT_TTSYNC
DVI$_TT_ESCAPE	DVI$_TT_LOWER
DVI$_TT_MECHTAB	DVI$_TT_WRAP
DVI$_TT_LFFILL	DVI$_TT_SCOPE
DVI$_TT_CRFILL	DVI$_TT_SETSPEED
DVI$_TT_EIGHTBIT	DVI$_TT_MBXDSABL
DVI$_TT_READSYNC	DVI$_TT_MECHFORM
DVI$_TT_NOBRDCST	DVI$_TT_HALFDUP
DVI$_TT_MODEM	DVI$_TT_OPER
DVI$_TT_LOCALECHO	DVI$_TT_AUTOBAUD
DVI$_TT_PAGE	DVI$_TT_HANGUP
DVI$_TT_MODHANGUP	DVI$_TT_BRDCSTMBX
DVI$_TT_DMA	DVI$_TT_ALTYPEAHD
DVI$_TT_ANSICRT	DVI$_TT_REGIS
DVI$_TT_AVO	DVI$_TT_EDIT
DVI$_TT_BLOCK	DVI$_TT_DECCRT
DVI$_TT_EDITING	DVI$_TT_INSERT
DVI$_TT_DIALUP	DVI$_TT_SECURE
DVI$_TT_FALLBACK	DVI$_TT_DISCONNECT
DVI$_TT_PASTHRU	DVI$_TT_SIXEL
DVI$_TT_PRINTER	DVI$_TT_APP_KEYPAD
DVI$_TT_DRCS	DVI$_TT_SYSPWD
DVI$_TT_DECCRT2
DVI$_TT_DECCRT3
DVI$_TT_DECCRT4

DVI$_WWID

Returns the World Wide Identifier (WWID) of Fibre Channel Disk and Tapedevices as a zero-filled string of indeterminate length.

The maximum length of this string may change with new devices;therefore, HP recommends that a 380-byte buffer be passed to thisfunction.

A return length address should also be passed with the call andexamined when the function completes. If the return length is equal tothe size of the buffer, then call $GETDVI again with a larger buffer toensure that the complete name has been read.

DVI$_yyyy

DVI$_yyyy is the format for a series of item codes that returndevice-independent characteristics of a device. There is an item codefor each device characteristic returned in the longword bit vectorspecified by the DVI$_DEVCHAR item code.

In the description of the DVI$_DEVCHAR item code is a list of symbolnames in which each symbol represents a device characteristic. Toconstruct the $GETDVI item code for each device characteristic,substitute for yyyy that portion of the symbol name thatfollows the underscore character. For example, the DVI$_REC item codereturns the same information as the DEV$V_REC bit in the DVI$_DEVCHARlongword bit vector.

The buffer for each of these item codes must specify a longword value,which is interpreted as Boolean. The $GETDVI service writes the value 1into the longword if the device has the specified characteristic andthe value 0 if it does not.

Description

The Get Device/Volume Information service returns primary and secondarydevice characteristics information about an I/O device. You can use thechan argument only if (1) the channel has already beenassigned, and (2) the caller's access mode is equal to or moreprivileged than the access mode from which the original channelassignment was made.

The caller of $GETDVI does not need to have a channel assigned to thedevice about which information is desired.

The $GETDVI service returns information about both primary devicecharacteristics and secondary device characteristics. By default,$GETDVI returns information about the primary device characteristicsonly.

To obtain information about secondary device characteristics, you mustperform a logical OR operation on the item code specifying theinformation desired with the code DVI$C_SECONDARY.

You can obtain information about primary and secondary devices in asingle call to $GETDVI.

In most cases, the two sets of characteristics (primary and secondary)returned by $GETDVI are identical. However, the two sets providedifferent information in the following cases:

• If the device has an associated mailbox, the primary characteristics are those of the assigned device and the secondary characteristics are those of the associated mailbox.
• If the device is a spooled device, the primary characteristics are those of the intermediate device (such as the disk) and the secondary characteristics are those of the spooled device (such as the printer).
• If the device represents a logical link on the network, the secondary characteristics contain information about the link.

Unless otherwise stated in the description of the item code, $GETDVIreturns information about the local node only.

Required Access or Privileges

None

Required Quota

Sufficient AST quota.

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The device name string descriptor, device name string, or itmlst argument cannot be read; or the buffer or return length longword cannot be written by the caller.
SS$_BADPARAM	The item list contains an invalid item code, or the buffer address field in an item descriptor specifies less than four bytes for the return length information.
SS$_EXASTLM	The process has exceeded its AST limit quota.
SS$_IVCHAN	You specified an invalid channel number, that is, a channel number larger than the number of channels.
SS$_IVDEVNAM	The device name string contains invalid characters, or neither the devnam nor chan argument was specified.
SS$_IVLOGNAM	The device name string has a length of 0 or has more than 63 characters.
SS$_NONLOCAL	The device is on a remote system.
SS$_NOPRIV	The specified channel is not assigned or was assigned from a more privileged access mode.
SS$_NOSUCHDEV	The specified device does not exist on the host system.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

Returns information about an I/O device; this information consists ofprimary and secondary device characteristics.

The $GETDVIW service completes synchronously; that is, it returns tothe caller with the requested information. HP recommends that you usean IOSB with this service. An IOSB prevents the service from completingprematurely. In addition, the IOSB contains additional statusinformation.

For asynchronous completion, use the Get Device/Volume Information($GETDVI) service; $GETDVI returns to the caller after queuing theinformation request, without waiting for the information to bereturned. In all other respects, $GETDVIW is identical to $GETDVI. Forall other information about the $GETDVIW service, refer to thedescription of $GETDVI.

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

Format

SYS$GETDVIW [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr] [,astprm][,nullarg]

C Prototype

int sys$getdviw (unsigned int efn, unsigned short int chan, void*devnam, void *itmlst, struct _iosb *iosb, void(*astadr)(__unknown_params), int astprm, unsigned __int64 *nullarg);

Returns the value(s) of the specified console environment variable(s).

Format

SYS$GETENV itmlst

C Prototype

int sys$getenv (void *itmlst);

Arguments

itmlst

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

The itmlst argument is the address of a list of itemdescriptors, each of which describes an item of information. The listof item descriptors is terminated by a longword of 0.

The service takes one argument as input, an item list. This item listhas the following format for a single item descriptor:

The following table defines the item descriptor fields:

Description

This system service will return the value(s) of the specified consoleenvironment variable(s).

Required Access or Privileges

None

Required Quota

None

Related Services

None

Condition Values Returned

SS$_NORMAL	Operation was successful; requested data was returned to caller.
SS$_ACCVIO	This status is returned if the caller does not have write access to the two input buffers or if the probe for read access to the item list fails.
SS$_BADPARAM	This status is returned if an empty item list is specified, or if the console callback to read the environment variable fails for any reason.

Returns information about one or more processes on the system or acrossthe OpenVMS Cluster system.

The $GETJPI service completes asynchronously. For synchronouscompletion, use the Get Job/Process Information and Wait ($GETJPIW)service.

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

Format

SYS$GETJPI [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr] ,[astprm]

C Prototype

int sys$getjpi (unsigned int efn, unsigned int *pidadr, void *prcnam,void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params),unsigned __int64 astprm);

Arguments

efn

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

Number of the event flag to be set when $GETJPI returns the requestedinformation. The efn argument is a quadword containingthis number; however, $GETJPI uses only the low-order byte.

Upon request initiation, $GETJPI clears the specified event flag (orevent flag 0 if efn was not specified). Then, when$GETJPI returns the requested information, it sets the specified eventflag (or event flag 0).

If you are not using event flags, you can specify this as EFN$C_ENF(this is defined in EFNDEF). Refer to the OpenVMS Programming Concepts Manual for additionalinformation.

pidadr

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Process identification (PID) of the process about which $GETJPI is toreturn information. The pidadr argument is the 32-bitaddress (on VAX systems) or the 32- or 64-bit address (on Alphasystems) of a longword containing the PID. The pidadrargument can refer to a process running on the local node or a processrunning on another node in the cluster.

If you give pidadr the value --1, $GETJPI assumes awildcard operation and returns the requested information for eachprocess on the system that it has the privilege to access, one processper call. To perform a wildcard operation, you must call $GETJPI in aloop, testing for the condition value SS$_NOMOREPROC after each calland exiting from the loop when SS$_NOMOREPROC is returned.

If you use $GETJPI with $PROCESS_SCAN, you can perform wildcardsearches across the cluster. In addition, with $PROCESS_SCAN you cansearch for specific processes based on many different selectioncriteria.

You cannot abbreviate a PID. All significant digits of a PID must bespecified; only leading zeros can be omitted.

prcnam

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

Name of the process about which $GETJPI is to return information. Theprcnam argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a character stringdescriptor pointing to this name string.

A process running on the local node can be identified with a 1- to15-character string. To identify a process on a cluster, you mustspecify the full process name, which includes the node name as well asthe process name. The full process name can contain up to 23 characters.

A local process name can look like a remote process name; therefore, ifyou specify ATHENS::SMITH, the system checks for a process namedATHENS::SMITH on the local node before checking node ATHENS for aprocess named SMITH.

You can use the prcnam argument only if the processidentified by prcnam has the same UIC group number asthe calling process. If the process has a different group number,$GETJPI returns no information. To obtain information about processesin other groups, you must use the pidadr 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 (Alpha)
mechanism:	by 32-bit reference (VAX)

Item list specifying which information about the process or processesis to be returned. The itmlst argument is the 32-bitaddress (on VAX systems) or the 32- or 64-bit address (on Alphasystems) of a list of item descriptors, each of which describes an itemof information. An item list in 32-bit format is terminated by alongword of 0; an item list in 64-bit format is terminated by aquadword of 0. All items in an item list must be of the sameformat---either 32-bit or 64-bit.

The following diagram depicts the 32-bit format of a single itemdescriptor:

The following table defines the item descriptor fields for 32-bit itemlist entries:

The following diagram depicts the 64-bit format of a single itemdescriptor:

The following table defines the item descriptor fields for 64-bit itemlist entries:

iosb

When you specify the iosb argument, $GETJPI sets thequadword to 0 upon request initiation. Upon request completion, acondition value is returned to the first longword; the second longwordis reserved for future use.

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 $GETJPI 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 $GETJPI, you must check the condition values returned in both R0 and the I/O status block.

astadr

If you specify astadr, the AST routine executes at thesame access mode as the caller of the $GETJPI service.

astprm

Item Codes

JPI$_ACCOUNT

Returns the account name of the process, which is an 8-byte string,filled with trailing blanks if necessary.

JPI$_APTCNT

Returns, in pages (on VAX systems) or pagelets (on Alpha systems), theactive page table count of the process, which is a longword integervalue.

JPI$_ASTACT

Returns the names of the access modes having active ASTs. Thisinformation is returned in a longword bit vector. When bit 0 is set, anactive kernel mode AST exists; bit 1, an executive mode AST; bit 2, asupervisor mode AST; and bit 3, a user mode AST.

JPI$_ASTCNT

Returns a count of the remaining AST quota, which is a longword integervalue.

JPI$_ASTEN

Returns a longword bit vector that indicates for each access modewhether ASTs are enabled for that mode. When bit 0 is set, Kernel modehas ASTs enabled; bit 1, Executive mode; bit 2, Supervisor mode; andbit 3, User mode.

JPI$_ASTLM

Returns the AST limit quota of the process, which is a longword integervalue.

JPI$_AUTHPRI

Returns the authorized base priority of the process, which is alongword integer value. The authorized base priority is the highestpriority a process without ALTPRI privilege can attain by means of the$SETPRI service.

JPI$_AUTHPRIV

Returns the privileges that the process is authorized to enable. Theseprivileges are returned in a quadword privilege mask and are defined bythe $PRVDEF macro.

JPI$_BIOCNT

Returns a count of the remaining buffered I/O quota, which is alongword integer value.

JPI$_BIOLM

Returns the buffered I/O limit quota of the process, which is alongword integer value.

JPI$_BUFIO

Returns a count of the buffered I/O operations of the process, which isa longword integer value.

JPI$_BYTCNT

Returns the remaining buffered I/O byte count quota of the process,which is a longword integer value.

JPI$_BYTLM

Returns the buffered I/O byte count limit quota of the process, whichis a longword integer value.

JPI$_CASE_LOOKUP_PERM

On Alpha systems, returns information about the file name lookup casesensitivity of a specified process. This value is set for the life ofthe process unless the style is set again. Values are 0(PPROP$K_CASE_BLIND) and 1 (PPROP$K_CASE_SENSITIVE).

Refer to the Guide to OpenVMS File Applications for additional information.

JPI$_CASE_LOOKUP_TEMP

On Alpha systems, returns information about the file name lookup casesensitivity of a specified process. This value is set only for the lifeof the image. Values are 0 (PPROP$K_CASE_BLIND) and 1(PPROP$K_CASE_SENSITIVE).

Refer to the Guide to OpenVMS File Applications for additional information.

JPI$_CHAIN

Processes another item list immediately after processing the currentone. The buffer address field in the item descriptor specifies theaddress of the next item list to be processed. You must specify theJPI$_CHAIN item code last in the item list.

You can chain together 32-bit and 64-bit item lists.

JPI$_CLASSIFICATION

On Alpha systems, returns, as a 20-byte padded string, the current MACclassification stored in the PSB.

JPI$_CLASS_NAME

Returns the name of the scheduling class (as a character string) thatthis process belongs to. Because the class name can include up to 16characters, the buffer length field of the item descriptor must specifyat least 16 bytes. If the process is not class scheduled, then a returnlength of 0 is returned to the caller.

JPI$_CLINAME

Returns the name of the command language interpreter that the processis currently using. Because the CLI name can include up to 39characters, the buffer length field in the item descriptor shouldspecify 39 bytes.

JPI$_CPU_ID

Returns, as a longword integer, the ID of the CPU on which the processis running or on which it last ran. This value is returned as --1 ifthe system is not a multiprocessor.

JPI$_CPULIM

Returns the CPU time limit of the process, which is a longword integervalue.

JPI$_CPUTIM

Returns the process's accumulated CPU time in 10-millisecond ticks,which is a longword integer value.

JPI$_CREPRC_FLAGS

Returns the flags specified by the stsflg argument inthe $CREPRC call that created the process. The flags are returned as alongword bit vector.

JPI$_CURPRIV

Returns the current privileges of the process. These privileges arereturned in a quadword privilege mask and are defined by the $PRVDEFmacro.

JPI$_CURRENT_AFFINITY_MASK

On Alpha systems, returns the current explicit affinity mask for theassociated kernel thread.

JPI$_CURRENT_USERCAP_MASK

On Alpha systems, returns the current user capability mask for theassociated kernel thread.

JPI$_DFMBC

Returns the default multibuffer count for a process as a longwordinteger value.

JPI$_DFPFC

Returns the default page fault cluster size of the process, which is alongword integer value measured in pages (on VAX systems) or pagelets(on Alpha systems).

JPI$_DFWSCNT

Returns, in pages (on VAX systems) or pagelets (on Alpha systems), thedefault working set size of the process, which is a longword integervalue.

JPI$_DIOCNT

Returns the remaining direct I/O quota of the process, which is alongword integer value.

JPI$_DIOLM

Returns the direct I/O quota limit of the process, which is a longwordinteger value.

JPI$_DIRIO

Returns a count of the direct I/O operations of the process, which is alongword integer value.

JPI$_EFCS

Returns the state of the process's local event flags 0 through 31 as alongword bit vector.

JPI$_EFCU

Returns the state of the process's local event flags 32 through 63 as alongword bit vector.

JPI$_EFWM

Returns the event flag wait mask of the process, which is a longwordbit vector.

JPI$_ENQCNT

Returns the remaining lock request quota of the process, which is alongword integer value.

JPI$_ENQLM

Returns the lock request quota of the process, which is a longwordinteger value.

JPI$_EXCVEC

Returns the address of a list of exception vectors for the process.Each exception vector in the list is a longword. There are eightvectors in the list: these are, in order, a primary and a secondaryvector for kernel mode access, for executive mode access, forsupervisor mode access, and for user mode access.

The $GETJPI service cannot return this information for any processother than the calling process; if you specify this item code and theprocess is not the calling process, $GETJPI returns the value 0 in thebuffer.

JPI$_FAST_VP_SWITCH

On VAX systems, returns an unsigned longword containing the number oftimes this process has issued a vector instruction that resulted in aninactive vector processor being enabled without the expense of a vectorcontext switch. In other words, this count reflects those instanceswhere the process has reenabled a vector processor on which theprocess's vector context has remained intact.

JPI$_FILCNT

Returns the remaining open file quota of the process, which is alongword integer value.

JPI$_FILLM

Returns the open file limit quota of the process, which is a longwordvalue.

JPI$_FINALEXC

Returns the address of a list of final exception vectors for theprocess. Each exception vector in the list is a longword. There arefour vectors in the list, one for each access mode, in this order:kernel, executive, supervisor, and user.

The $GETJPI service cannot return this information for any processother than the calling process; if you specify this item code and theprocess is not the calling process, $GETJPI returns the value 0 in thebuffer.

JPI$_FREP0VA

Returns the address of the first free page at the end of the programregion (P0 space) of the process.

JPI$_FREP1VA

Returns the address of the first free page at the end of the controlregion (P1 space) of the process.

JPI$_FREPTECNT

Returns the number of pages (on VAX systems) or pagelets (on Alphasystems) that the process has available for virtual memory expansion.

On VAX systems, the value returned is a longword integer. On Alphasystems, the value returned requires a quadword of storage. If thebuffer size supplied is not equal to 8 bytes, and the number of freepagelets exceeds the maximum value that can be represented in alongword, $GETJPI returns the largest positive 32-bit integer:2147483647.

JPI$_GETJPI_CONTROL_FLAGS

The JPI$_GETJPI_CONTROL_FLAGS item code, which is specified in the$GETJPI item list, provides additional control over $GETJPI; therefore,$GETJPI might be unable to retrieve all the data requested in an itemlist because JPI$_GETJPI_CONTROL_FLAGS requests that $GETJPI notperform certain actions that might be necessary to collect the data.For example, a $GETJPI control flag might instruct the calling programnot to retrieve a process that has been swapped out of the balance set.

If $GETJPI is unable to retrieve any data item because of therestrictions imposed by the control flags, it returns the data lengthas 0. To verify that $GETJPI received a data item, examine the datalength to be sure that it is not 0. To ensure the verification, be sureto specify the return length for each item in the $GETJPI item listwhen any of the JPI$_GETJPI_CONTROL_FLAGS flags is used.

Unlike other $GETJPI item codes, the JPI$_GETJPI_CONTROL_FLAGS item isan input item. The item list entry should specify a longword buffer.The desired control flags should be set in this buffer.

Because the JPI$_GETJPI_CONTROL_FLAGS item code tells $GETJPI how tointerpret the item list, it must be the first entry in the $GETJPI itemlist. The error code SS$_BADPARAM is returned if it is not the firstitem in the list.

The JPI$_GETJPI_CONTROL_FLAGS item code includes the following flags:

Flag	Description
JPI$M_NO_TARGET_INSWAP	Does not retrieve a process that has been swapped out of the balance set. This control flag is used to avoid adding the load of swapping processes into a system. By using this control flag and requesting information from a process that has been swapped out, the following occurs: Any data stored in the virtual address space of the process is not accessible. Any data stored in the process header (PHD) might not be accessible. Any data stored in resident data structures, such as the process control block (PCB) or the job information block (JIB), is accessible. You must examine the return length of an item to verify that the item was retrieved.
JPI$M_NO_TARGET_AST	Does not deliver a kernel mode AST to the target process. This control flag is used to avoid executing a target process to retrieve information. By using this control flag and not delivering an AST to a target process, the following occurs: Any data stored in the virtual address space of the process is not accessible. Any data stored in system data structures, such as the process header (PHD), the process control block (PCB), or the job information block (JIB), is accessible. You must examine the return length of an item to verify that the item was retrieved. The use of this control flag also implies that $GETJPI does not swap in a process, because $GETJPI would only bring a process into memory to deliver an AST to that process.
JPI$M_IGNORE_TARGET_STATUS	Attempts to retrieve as much information as possible, even though the process might be suspended or is being deleted. This control flag is used to retrieve all possible information from a process.
JPI$M_THREAD	Sets the wildcard mode to return information on all of the process's kernel threads beginning with the initial kernel thread.

JPI$_GPGCNT

Returns, in pages (on VAX systems) or pagelets (on Alpha systems), theprocess's global page count in the working set, which is a longwordinteger value.

JPI$_GRP

Returns, as a longword integer value, the group number of the process'sUIC.

JPI$_HOME_RAD

On Alpha systems, returns the home resource affinity domain (RAD).

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

JPI$_IMAGECOUNT

Returns, as a longword integer value, the number of images that havebeen run down for the process.

JPI$_IMAGE_AUTHPRIV

On Alpha systems, returns the authorized privilege mask of theinstalled image.

These privileges are returned in a quadword privilege mask and aredefined by the $PRVDEF macro.

JPI$_IMAGE_PERMPRIV

On Alpha systems, returns the permanent (default) privilege mask of theinstalled image.

These privileges are returned in a quadword privilege mask and aredefined by the $PRVDEF macro.

JPI$_IMAGE_RIGHTS

Returns the binary content of the image rights list as an array ofquadword identifiers. Each entry consists of a longword identifiervalue and longword identifier attributes, as shown in Table SYS-43.The image rights list is a set of identifiers associated with aprotected subsystem image. When a process runs a protected subsystem,the subsystem rights are automatically added to the process's imagerights list. These identifiers are subsequently removed during imagerundown. Allocate a buffer that is sufficient to hold the image rightslist, because $GETJPI returns only as much of the list as will fit inthe buffer.

Table SYS-43 Attributes of an Identifier

Symbolic Name	Description
KGB$M_DYNAMIC	Identifier can be enabled or disabled.
+KGB$M_NOACCESS	Rights of the identifier are null and void.
KGB$M_RESOURCE	Resources can be charged to the identifier.
+KGB$M_SUBSYSTEM	Identifier can be used to create protected subsystems.

JPI$_IMAGE_WORKPRIV

These privileges are returned in a quadword privilege mask and aredefined by the $PRVDEF macro.

JPI$_IMAGNAME

JPI$_IMAGPRIV

JPI$_INITIAL_THREAD_PID

JPI$_INSTALL_RIGHTS

JPI$_INSTALL_RIGHTS_SIZE

JPI$_JOBPRCCNT

JPI$_JOBTYPE

JPI$_KT_COUNT

JPI$_LAST_LOGIN_I

JPI$_LAST_LOGIN_N

JPI$_LOGIN_FAILURES

JPI$_LOGIN_FLAGS

JPI$_LOGINTIM

JPI$_MASTER_PID

JPI$_MAXDETACH

JPI$_MAXJOBS

JPI$_MEM

JPI$_MODE

JPI$_MSGMASK

JPI$_MULTITHREAD

JPI$_NODENAME

JPI$_NODE_CSID

JPI$_NODE_VERSION

JPI$_OWNER

JPI$_PAGEFLTS

JPI$_PAGFILCNT

JPI$_PAGFILLOC

JPI$_PARSE_STYLE_IMAGE

JPI$_PARSE_STYLE_PERM

JPI$_PERMANENT_AFFINITY_MASK

JPI$_PERMANENT_USERCAP_MASK

JPI$_PERSONA_AUTHPRIV

These privileges are returned in a quadword privilege mask and aredefined by the $PRVDEF macro.

JPI$_PERSONA_ID

JPI$_PERSONA_PERMPRIV

JPI$_PERSONA_RIGHTS

JPI$_PERSONA_RIGHTS_SIZE

JPI$_PERSONA_WORKPRIV

JPI$_PGFLQUOTA

JPI$_PHDFLAGS

JPI$_PID

JPI$_P0_FIRST_FREE_VA_64

Because this number is a quadword, the buffer length field in the itemdescriptor should specify 8 (bytes).

JPI$_P1_FIRST_FREE_VA_64

Because this number is a quadword, the buffer length field in the itemdescriptor should specify 8 (bytes).

JPI$_P2_FIRST_FREE_VA_64

Because this number is a quadword, the buffer length field in the itemdescriptor should specify 8 (bytes).

JPI$_PPGCNT

JPI$_PRCCNT

JPI$_PRCLM

JPI$_PRCNAM

JPI$_PRI

JPI$_PRIB

JPI$_PROCESS_RIGHTS

JPI$_PROC_INDEX

You can use the process index number as an index into system globalsections. Because the process index number is unique for each process,its use as an index into system global sections guarantees nocollisions with other system processes accessing those sections.

The process index is intended to serve users who formerly used thelow-order word of the PID as an index number.

JPI$_PROCPRIV

JPI$_RIGHTSLIST

JPI$_RIGHTS_SIZE

JPI$_RMS_DFMBC

JPI$_RMS_DFMBFIDX

JPI$_RMS_DFMBFREL

JPI$_RMS_DFMBFSDK

JPI$_RMS_DFMBFSMT

JPI$_RMS_DFMBFSUR

JPI$_RMS_DFNBC

JPI$_RMS_EXTEND_SIZE

JPI$_RMS_FILEPROT

JPI$_RMS_PROLOGUE

JPI$_SCHED_POLICY

JPI$_SHRFILLM

JPI$_SITESPEC

JPI$_SLOW_VP_SWITCH

JPI$_STATE

JPI$_STS

JPI$_STS2

JPI$_SUBSYSTEM_RIGHTS

When a process runs a protected subsystem, the subsystem rights areautomatically added to the process's image rights list. Theseidentifiers are subsequently removed during image rundown. Allocate abuffer that is sufficient to hold the subsystem rights list, because$GETJPI returns only as much of the list as will fit in the buffer.

JPI$_SUBSYSTEM_RIGHTS_SIZE

JPI$_SWPFILLOC

JPI$_SYSTEM_RIGHTS

JPI$_SYSTEM_RIGHTS_SIZE

JPI$_TABLENAME

JPI$_TERMINAL

JPI$_THREAD_INDEX

JPI$_TMBU

JPI$_TQCNT

JPI$_TQLM

JPI$_TT_ACCPORNAM

• If the terminal is on a terminal server, this item returns the terminal server name and the name of the line port on the server.
• If the terminal is a DECnet for OpenVMS remote terminal, this item returns the source system node name and the user name on the source system.
• If the terminal is on TELNET, this item returns the originating host address and port.
• If the terminal not on a terminal server, on DECnet, or on TELNET, this item returns a null string.

JPI$_TT_PHYDEVNAM

JPI$_UAF_FLAGS

JPI$_UIC

JPI$_USERNAME

JPI$_VIRTPEAK

On VAX systems, the value returned is a longword integer. On Alphasystems, the value returned requires a quadword of storage. If thebuffer size supplied is not equal to 8 bytes, and the virtual peakexceeds the maximum value that can be represented in a longword,$GETJPI returns the largest positive 32-bit integer: 2147483647.

JPI$_VOLUMES

JPI$_VP_CONSUMER

JPI$_VP_CPUTIM

JPI$_WSAUTH

JPI$_WSAUTHEXT

JPI$_WSEXTENT

JPI$_WSPEAK

JPI$_WSQUOTA

JPI$_WSSIZE

Description

The Get Job/Process Information service returns information about oneor more processes on the system or across the cluster. Using $GETJPIwith $PROCESS_SCAN, you can perform selective or clusterwide searches.

Getting information about another process is an asynchronous operationbecause the information might be contained in the virtual address spaceof the target process, and that process might be running at a lowerpriority, be outswapped, or be suspended in a miscellaneous or resourcewait state. To allow your program to overlap other functions with thetime needed to access the data in the other process, $GETJPI returnsimmediately after it has queued its information-gathering request tothe other process. You can use the JPI$_GETJPI item code to control theprocessing of the $GETJPI call and the information-gatheringinterprocess request itself.

When performing an asynchronous system service call such as $GETJPI,the specifications of the iosb argument and a uniqueevent flag are used in conjunction with mechanisms such as the $SYNCHsystem service to synchronize the final completion of the asynchronoussystem service call.

Required Access or Privileges

The calling process must have GROUP privilege to obtain informationabout other processes with the same group UIC number as the callingprocess. The calling process must have WORLD privilege to obtaininformation about other processes on the system that are not in thesame group as the calling process.

Required Quota

None

Related Services

$GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SYNCH

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read by the caller, or the buffer length or buffer cannot be written by the caller.
SS$_BADPARAM	The item list contains an invalid identifier. Or, an item list containing both 32-bit and 64-bit item list entries was found.
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$_NOMOREPROC	In a wildcard operation, $GETJPI found no more processes.
SS$_NOMORETHREAD	The search for kernel threads within a process is complete. This condition value is returned by $GETJPIW if you set the JPI$M_THREAD bit in JPI$_GETJPI_CONTROL_FLAGS.
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 obtain information about the specified process.
SS$_NOSUCHNODE	The specified node is not currently a member 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$_SUSPENDED	The specified process is suspended or in a miscellaneous wait state, and the requested information cannot be obtained.
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.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

Example

// Compile and link instructions:////    $ cc/decc getjpi_demo//    $ link getjpi_demo//    $ run getjpi_demo////#pragma module getjpi_demo "V1.0-000"// The various external definitions and prototypes...#include <descrip.h>           // static and dynamic string descriptor defs#include <efndef.h>            // for the No Event Flag Event Flag#include <jpidef.h>            // sys$getjpi item codes#include <lib$routines.h>      // run-time library function prototypes#include <pscandef.h>          // sys$process_scan item codes#include <ssdef.h>             // System service message codes#include <starlet.h>           // Function prototypes for system services#include <stdio.h>             // C standard I/O functions#include <stsdef.h>            // condition value definitions// Constants used in this module#define     MAX_ITEMLIST_IL3_ENTRIES  10#define     PROCESSNAME_LENGTH        16#define     USERNAME_LENGTH           12#define     IMAGE_LENGTH              255#define     TRIMAGE_LENGTH            38main()  {  char ImageBuf[IMAGE_LENGTH+1];  char ProcessBuf[PROCESSNAME_LENGTH+1];  char UsernameBuf[USERNAME_LENGTH+1];  int Count = 0;  int ProcessId;  int RetStat;  int i;  unsigned long int JpiCtx;  unsigned short int TrimageLength = TRIMAGE_LENGTH;  unsigned short int ImageLength;  unsigned short int ProcessLength;  unsigned short int UsernameLength;  unsigned short int iosb[4];  struct dsc$descriptor TrimageDsc = { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };  struct dsc$descriptor ImageDsc = { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL };  struct itemlist3    {    unsigned short int il_siz;    unsigned short int il_cod;    void *il_buf;    unsigned short int *il_rla;    } il3[MAX_ITEMLIST_IL3_ENTRIES];  char *CtlFmtT = "%-8.8s %-12s %-16s %-*.*s\n";  char *CtlFmtD = "%08X %-12s %-16s %-*.*s\n";  // Set up the static string descriptor...  ImageDsc.dsc$a_pointer = ImageBuf;  // Set up to scan only the interactive processes...  i = 0;  il3[i].il_siz   = 0;  il3[i].il_cod   = PSCAN$_MODE;  il3[i].il_buf   = (void *) JPI$K_INTERACTIVE;  il3[i++].il_rla = NULL;  il3[i].il_siz   = 0;  il3[i].il_cod   = 0;  il3[i].il_buf   = NULL;  il3[i++].il_rla = NULL;  // the sys$process_scan service sets up the sys$getjpi context...  RetStat = sys$process_scan( &JpiCtx, il3 );  if (!$VMS_STATUS_SUCCESS( RetStat ))    return RetStat;  i = 0;  il3[i].il_siz   = USERNAME_LENGTH;  il3[i].il_cod   = JPI$_USERNAME;  il3[i].il_buf   = UsernameBuf;  il3[i++].il_rla = &UsernameLength;  il3[i].il_siz   = PROCESSNAME_LENGTH;  il3[i].il_cod   = JPI$_PRCNAM;  il3[i].il_buf   = ProcessBuf;  il3[i++].il_rla = &ProcessLength;  il3[i].il_siz   = IMAGE_LENGTH;  il3[i].il_cod   = JPI$_IMAGNAME;  il3[i].il_buf   = ImageBuf;  il3[i++].il_rla = &ImageLength;  il3[i].il_siz   = sizeof( int );  il3[i].il_cod   = JPI$_PID;  il3[i].il_buf   = &ProcessId;  il3[i++].il_rla = NULL;  il3[i].il_siz   = 0;  il3[i].il_cod   = 0;  il3[i].il_buf   = NULL;  il3[i++].il_rla = NULL;  // Display the header...  printf( CtlFmtT, "PID","Username","Process name", 6, 6, "Image");  // Loop through the available processes...  while ( TRUE )    {    // Find the next process...    RetStat = sys$getjpiw( EFN$C_ENF, &JpiCtx, NULL,      il3, iosb, NULL, 0);    if ((RetStat == SS$_NOPRIV) || (RetStat == SS$_SUSPENDED))      continue;    if ( RetStat == SS$_NOMOREPROC )      break;    if (!$VMS_STATUS_SUCCESS( RetStat ))      return RetStat;    Count++;    // Zero-terminate the username, process and image name strings...    UsernameBuf[UsernameLength] = '\0';    ProcessBuf[ProcessLength] = '\0';    ImageBuf[ImageLength] = '\0';    // Trim the image filename to fit...    ImageDsc.dsc$w_length = ImageLength;    RetStat = lib$trim_filespec( &ImageDsc, &TrimageDsc, &TrimageLength );    if (!$VMS_STATUS_SUCCESS( RetStat ))      return RetStat;    printf( CtlFmtD, ProcessId, UsernameBuf, ProcessBuf,      TrimageDsc.dsc$w_length, TrimageDsc.dsc$w_length,      TrimageDsc.dsc$a_pointer );    }  printf("Interactive process count: %d\n", Count );  // Free up the dynamic descriptor allocated by lib$trim_filespec  RetStat = lib$sfree1_dd( &TrimageDsc );  if (!$VMS_STATUS_SUCCESS( RetStat ))    return RetStat;  return SS$_NORMAL;  }      

This is a simple program that demonstrates calling various OpenVMSsystem services and run-time library routines. This example uses theavailable process privileges to display as many interactive processesas it can---when the WORLD privilege is available, all of theinteractive processes will be displayed.

This example was built with OpenVMS (VAX and Alpha) V7.2, using the HPC V6.0 compiler.

Returns information about one or more processes on the system.

The $GETJPIW service completes synchronously; that is, it returns tothe caller with the requested information. HP recommends that you usean IOSB with this service. An IOSB prevents the service from completingprematurely. In addition, the IOSB contains status information.

For asynchronous completion, use the Get Job/Process Information($GETJPI) service; $GETJPI returns to the caller after queuing theinformation request, without waiting for the information to be returned.

In all other respects, $GETJPIW is identical to $GETJPI. For all otherinformation about the $GETJPIW service, refer to the description of$GETJPI in this manual.

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

Format

SYS$GETJPIW [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr],[astprm]

C Prototype

int sys$getjpiw (unsigned int efn, unsigned int *pidadr, void *prcnam,void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), intastprm);

Returns information about the lock database on a system.

The $GETLKI service completes asynchronously; for synchronouscompletion, use the Get Lock Information and Wait ($GETLKIW) service.

The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together providethe user interface to the Lock Management facility.

Format

SYS$GETLKI [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getlki (unsigned int efn, unsigned int *lkidadr, void *itmlst,struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm,unsigned int reserved);

Arguments

efn

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

Number of the event flag to be set when $GETLKI completes. Theefn argument is a longword containing this number;however, $GETLKI uses only the low-order byte. If you do not specifyefn, $GETLKI sets event flag 0.

lkidadr

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

Lock identification (lock ID) for the lock about which information isto be returned. The lock ID is the second longword in the lock statusblock, which was created when the lock was granted. Thelkidadr argument is the address of this longword.

If the value specified by lkidadr is 0 or --1, $GETLKIassumes a wildcard operation and returns information about each lock towhich the calling process has access, one lock per call.

To use the $GETLKI service, you must have read/write access to the lockID.

itmlst

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

Item list specifying the lock information that $GETLKI is to return.The itmlst argument is the address of a list of itemdescriptors, each of which describes an item of information. The listof item descriptors is terminated by a longword of 0.

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

The following table defines the item descriptor fields:

iosb

When $GETLKI is called, it sets the I/O status block to 0. When $GETLKIcompletes, it writes a condition value to the first longword in thequadword. The remaining two words in the quadword are unused.

Although 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 $GETLKI 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 $GETLKI, you must check the condition values returned in both R0 and the I/O status block.

astadr

If you specify this argument, the AST routine executes at the sameaccess mode as the caller of the $GETLKI service.

astprm

nullarg

Item Codes

LKI$_BLOCKEDBY

Returns information about all locks that are currently blocked by thelock specified by lkidadr. The $GETLKI service returnseight items of information about each blocked lock.

The $LKIDEF macro defines the following symbolic names that refer tothe eight items in the buffer:

Symbolic Name	Description
LKI$L_MSTLKID	Lock ID of the blocking lock on the system maintaining the resource (4 bytes)
LKI$L_PID	Process ID (PID) of the process that took out the blocked lock (4 bytes)
LKI$L_MSTCSID	OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocked lock (4 bytes)
LKI$B_RQMODE	Lock mode requested for the blocked lock; this lock mode was specified by the lkmode argument in the call to $ENQ (1 byte)
LKI$B_GRMODE	Lock mode granted to the blocked lock; this lock mode is written to the lock value block (1 byte)
LKI$B_QUEUE	Name of the queue on which the blocked lock currently resides (1 byte)
LKI$L_LKID	Lock ID of the lock on the system where the lock was requested (4 bytes)
LKI$L_CSID	OpenVMS Cluster system identifier (CSID) of the system where the lock was requested (4 bytes)

The values that $GETLKI can write into the LKI$B_RQMODE, LKI$B_GRMODE,and LKI$B_QUEUE items have symbolic names; these symbolic names specifythe six lock modes and the three types of queue in which a lock canreside. The Description section describes these names.

Thus, the buffer specified by the buffer address field in the itemdescriptor will contain the eight items of information, repeated insequence, for each blocked lock.

The length of the information returned for each blocked lock isreturned in bits 16 to 30 of the longword specified by the returnlength address field in the item descriptor, while the total length ofinformation returned for all blocked locks is returned in bits 0 to 15.Therefore, to determine the number of blocked locks, you divide thevalue of bits 16 to 30 into the value of bits 0 to 15.

LKI$_BLOCKING

Returns information about all locks that are currently blocking thelock specified by lkidadr. The $GETLKI service returnseight items of information about each blocking lock.

The $LKIDEF macro defines the following symbolic names that refer tothe eight items in the buffer:

Symbolic Name	Description
LKI$L_MSTLKID	Lock ID of the blocked lock on the system maintaining the resource (4 bytes)
LKI$L_PID	Process ID (PID) of the process that took out the blocking lock (4 bytes)
LKI$L_MSTCSID	OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocking lock (4 bytes)
LKI$B_RQMODE	Lock mode requested for the blocking lock; this lock mode was specified by the lkmode argument in the call to $ENQ (1 byte)
LKI$B_GRMODE	Lock mode granted to the blocking lock; this lock mode is written to the lock value block (1 byte)
LKI$B_QUEUE	Name of the queue on which the blocking lock currently resides (1 byte)
LKI$L_LKID	Lock ID of the lock on the system where the lock was requested (4 bytes)
LKI$L_CSID	OpenVMS Cluster system identifier (CSID) of the system where the lock was requested (4 bytes)

The values that $GETLKI can write into the LKI$B_RQMODE, LKI$B_GRMODE,and LKI$B_QUEUE items have symbolic names; these symbolic names specifythe six lock modes and the three types of queue in which a lock canreside. The Description section describes these names.

Thus, the buffer specified by the buffer address field in the itemdescriptor will contain the eight items of information, repeated insequence, for each blocking lock.

The length of the information returned for each blocking lock isreturned in bits 16 to 30 of the longword specified by the returnlength address field in the item descriptor, while the total length ofinformation returned for all blocking locks is returned in bits 0 to15. Therefore, to determine the number of blocking locks, you dividethe value of bits 16 to 30 into the value of bits 0 to 15.

LKI$_CSID

Returns the Cluster System ID (CSID) of the system where the processowning the lock resides. LKI$_CSID returns the CSID of the node wherethe $GETLKI system service is issued when the resource is mastered onthat node. When the processor is not part of a cluster, LKI$_CSIDreturns 0.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_CVTCOUNT

Returns the total number of locks that are currently on the conversionqueue of the resource associated with the lock. These locks are grantedat one mode and are waiting to be converted to another.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_GRANTCOUNT

Returns the total number of locks that are currently on the grant queueof the resource associated with the lock. Note that the total number ofgranted locks on the resource is equal to the sum of LKI$_CVTCOUNT andLKI$_GRANTCOUNT.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_LCKREFCNT

Returns the number of locks that have this lock as a parent lock. Whenthese locks were created, the parid argument in thecall to $ENQ or $ENQW specified the lock ID of this lock.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_LKID

Returns the lock ID of the lock on the system where the process owningthe lock resides. The lock ID returned by this item code is meaningfulonly on the system specified in the value returned by the LKI$_CSIDitem code.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_LOCKID

Returns the lock ID of the current lock. The current lock is the onespecified by the lkidadr argument unlesslkidadr is specified as --1 or 0, which indicates awildcard operation. Thus, this item code is usually specified only inwildcard operations where it is useful to know the lock IDs of thelocks that $GETLKI has discovered in the wildcard operation.

The lock ID is a longword value, so the buffer length field in the itemdescriptor should specify 4 (bytes).

LKI$_LOCKS

Returns information about all locks on the resource associated with thelock specified by lkidadr.

The $LKIDEF macro defines the following symbolic names that refer tothe eight items in the buffer:

Symbolic Name	Description
LKI$L_MSTLKID	Lock ID of the blocked lock on the system maintaining the resource (4 bytes)
LKI$L_PID	Process ID (PID) of the process that took out the lock (4 bytes)
LKI$L_MSTCSID	OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the lock (4 bytes)
LKI$B_RQMODE	Lock mode requested for the lock; this lock mode was specified by the lkmode argument in the call to $ENQ (1 byte)
LKI$B_GRMODE	Lock mode granted to the lock; this lock mode is written to the lock value block (1 byte)
LKI$B_QUEUE	Name of the queue on which the lock currently resides (1 byte)
LKI$L_LKID	Lock ID of the lock on the system where the lock was requested (4 bytes)
LKI$L_CSID	OpenVMS Cluster system identifier (CSID) of the system where the lock was requested (4 bytes)

The values that $GETLKI can write into the LKI$B_RQMODE, LKI$B_GRMODE,and LKI$B_QUEUE items have symbolic names; these symbolic names specifythe six lock modes and the three types of queue in which a lock canreside. The Description section describes these names.

Thus, the buffer specified by the buffer address field in the itemdescriptor will contain the eight items of information, repeated insequence, for each lock.

The length of the information returned for each lock is returned inbits 16 to 30 of the longword specified by the return length addressfield in the item descriptor, while the total length of informationreturned for all locks is returned in bits 0 to 15. Therefore, todetermine the number of locks, you divide the value of bits 16 to 30into the value of bits 0 to 15.

LKI$_MSTCSID

Returns the Cluster System ID (CSID) of the node currently masteringthe resource that is associated with the specified lock. Although theresource can be locked by processes on any node in the cluster, theresource itself is maintained on a single node. You can use the DCLcommand SHOW CLUSTER or the $GETSYI service to determine which node inthe OpenVMS Cluster is identified by the CSID that $GETLKI returns.

Because the processor mastering the lock can change at any time,multiple calls to $GETLKI for the same lock can produce differentvalues for this item code. LKI$_MSTCSID returns the CSID of the nodewhere the $GETLKI system service is issued when the resource ismastered on that node. When the processor where the $GETLKI was issuedis not part of an OpenVMS Cluster, this item code returns 0.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_MSTLKID

Returns the lock ID for the current master copy of the lock. Althoughthe resource can be locked by processes on any node in the cluster, theresource itself is maintained on a single node. Because lock IDs areunique to each processor on a cluster, the lock ID returned by thisitem code has meaning only on the processor that is specified in thevalue returned by the LKI$_MSTCSID item code.

Because the processor mastering the lock can change at any time,multiple calls to $GETLKI for the same lock can produce differentvalues for this item code. When the lock is mastered on the node wherethe $GETLKI system service is issued, or when the node is not a memberof a cluster, this item code returns the same information as LKI$_LKID.

The buffer length field in the item descriptor should specify 4 (bytes).

LKI$_NAMSPACE

Returns information about the resource name space. This information iscontained in a longword consisting of four bit fields; therefore, thebuffer length field in the item descriptor should specify 4 (bytes).

Each of the four bit fields can be referred to by its symbolic name;the $LKIDEF macro defines the symbolic names. The following tablelists, in order, the symbolic name of each bit field:

Symbolic Name	Description
LKI$W_GROUP	In this field (bits 0 to 15), $GETLKI writes the UIC group number of the process that took out the first lock on the resource, thereby creating the resource name. This process issued a call to $ENQ or $ENQW specifying the name of the resource in the resnam argument. However, if this process specified the LCK$_SYSTEM flag in the call to $ENQ or $ENQW, the resource name is systemwide. In this case, the UIC group number of the process is not associated with the resource name. Consequently, this field (bits 0 to 15) is significant only if the resource name is not systemwide. $GETLKI sets bit 31 if the resource name is systemwide.
LKI$B_RMOD	In this field (bits 16 to 23), $GETLKI writes the access mode associated with the first lock taken out on the resource.
LKI$B_STATUS	This field (bits 24 to 30) is not used. $GETLKI sets it to 0.
LKI$V_SYSNAM	This field (bit 31) indicates whether the resource name is systemwide. $GETLKI sets this bit if the resource name is systemwide and clears it if the resource name is qualified by the creating process's UIC group number. The state of this bit determines the interpretation of bits 0 to 15.

LKI$_PARENT

Returns the lock ID of the parent lock for the lock, if a parent lockwas specified in the call to $ENQ or $ENQW. If the lock does not have aparent lock, $GETLKI returns the value 0.

Because the parent lock ID is a longword, the buffer length field inthe item descriptor should specify 4 (bytes).

LKI$_PID

Returns the process identification (process ID) of the process thatowns the lock.

The process ID is a longword value, so the buffer length field in theitem descriptor should specify 4 (bytes).

LKI$_RESNAM

Returns the resource name string and its length, which must be from 1to 31 bytes. The resource name string was specified in theresnam argument in the initial call to $ENQ or $ENQW.

The $GETLKI service returns the length of the string in the returnlength address field in the item descriptor. However, in the call to$GETLKI, you do not know how long the string is; therefore, to avoidbuffer overflow, you should specify the maximum length (31 bytes) inthe buffer length field in the item descriptor.

LKI$_RSBREFCNT

Returns the number of subresources of the resource associated with thelock. A subresource has the resource as a parent resource. Note,however, that the number of subresources can differ from the number ofsublocks of the lock, because any number of processes can lock theresource. If any of these processes then locks another resource, and indoing so specifies the lock ID of the lock on the first resource as aparent lock, then the second resource becomes a subresource of thefirst resource.

Thus, the number of sublocks on a lock is limited to the number ofsublocks that a single process takes out, whereas the number ofsubresources on a resource is determined by (potentially) multipleprocesses.

The subresource reference count is a longword value, so the bufferlength field in the item descriptor should specify 4 (bytes).

LKI$_STATE

Returns the current state of the lock. The current state of the lock isdescribed by the following three 1-byte items (in the order specified):(1) the lock mode requested (in the call to $ENQ or $ENQW) for thelock, (2) the lock mode granted (by $ENQ or $ENQW) for the lock, and(3) the name of the queue on which the lock currently resides.

The buffer length field in the item descriptor shouldspecify 3 (bytes). The $LKIDEF macro defines the following symbolicnames that refer to the three 1-byte items in the buffer.

Symbolic Name	Description
LKI$B_STATE_RQMODE	Lock mode requested
LKI$B_STATE_GRMODE	Lock mode granted
LKI$B_STATE_QUEUE	Name of queue on which the lock resides

The values that $GETLKI can write into each 1-byte item have symbolicnames; these symbolic names specify the six lock modes and the threetypes of queue in which a lock can reside. The Description sectiondescribes these names.

LKI$_VALBLK

Returns the lock value block of the locked resource. This lock valueblock is the master copy that the lock manager maintains for theresource, not the process-private copy.

Because the lock value block is 16 bytes, the buffer length field inthe item descriptor should specify 16.

LKI$_WAITCOUNT

Returns the total number of locks that are currently on the wait queueof the resource associated with the lock. These locks are waiting to begranted.

The buffer length field in the item descriptor should specify 4 (bytes).

Description

The Get Lock Information service returns information about the lockdatabase on a system.

The access mode of the calling process must be equal to or moreprivileged than the access mode at which the lock was initially granted.

When locking on a resource is clusterwide, a single master copy of theresource is maintained on the node that owns the process that createdthe resource by taking out the first lock on it. When a process onanother node locks that same resource, a local copy of the resource iscopied to the node and the lock is identified by a lock ID that isunique to that node.

In a cluster environment, however, you cannot use $GETLKI to obtaindirectly information about locks on other nodes in the cluster; thatis, you cannot specify in a call to $GETLKI the lock ID of a lock heldby a process on another node. The $GETLKI service interprets thelkidadr argument as the lock ID of a lock on thecaller's node, even though the resource associated with a lock mighthave its master copy on the caller's node.

However, because a process on another node in the cluster can have alock on the same resource as the caller of $GETLKI, the caller, inobtaining information about the resource, can indirectly obtain someinformation about locks on the resource that are held by processes onother nodes. One example of information indirectly obtained about aresource is the contents of lock queues; these queues containinformation about all locks on the resource, and some of these lockscan be held by processes on other nodes.

Another example of information more directly obtained is the remotelock ID of a lock held by a process on another node. Specifically, ifthe caller of $GETLKI on node A specifies a lock (by means oflkidadr) and that lock is held by a process on node B,$GETLKI returns the lock ID of the lock from node B's lock database ifthe LKI$_REMLKID item code is specified in the call.

Item codes LKI$_BLOCKEDBY, LKI$_BLOCKING, LKI$_LOCKS, and LKI$_STATEspecify that $GETLKI return various items of information; some of theseitems are the names of lock modes or the names of lock queues.

The $LCKDEF macro defines the following symbolic names:

Symbolic Name	Lock Mode
LCK$K_NLMODE	Null mode
LCK$K_CRMODE	Concurrent read mode
LCK$K_CWMODE	Concurrent write mode
LCK$K_PRMODE	Protected read mode
LCK$K_PWMODE	Protected write mode
LCK$K_EXMODE	Exclusive mode

Symbolic Name	Queue Name
LKI$C_GRANTED	Granted queue, holding locks that have been granted
LKI$C_CONVERT	Converting queue, holding locks that are currently being converted to another lock mode
LKI$C_WAITING	Waiting queue, holding locks that are neither granted nor converting (for example, a blocked lock)

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing privileges to use $GETLKI:

• For locks held by other processes, you need to have joined the resource domain for lock access or hold WORLD privileges.
  You need WORLD privilege to obtain information about locks held by processes in other groups.
• To obtain information about system locks, either you need SYSLCK privilege or the process must be executing in executive or kernel access mode.

To establish a default resource domain, it is necessary to haveperformed either a call to $SET_RESOURCE_DOMAIN or a previous call to$ENQ[W].

Required Quota

The caller must have sufficient ASTLM or BYTLM quota.

Related Services

$DEQ, $ENQ, $ENQW, $GETLKIW, $SET_RESOURCE_DOMAIN

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read; the areas specified by the buffer address and return length address fields in the item descriptor cannot be written; or the location specified by the lkidadr argument cannot be written.
SS$_BADPARAM	You specified an invalid item code.
SS$_EXQUOTA	The caller has insufficient ASTLM or BYTLM quota.
SS$_ILLRSDM	The operation attempted is not allowed on the resource. Use SHOW SECURITY to verify the access allowed to the specified resource domain.
SS$_INSFMEM	The nonpaged dynamic memory is insufficient for the operation.
SS$_IVLOCKID	The lkidadr argument specified an invalid lock ID.
SS$_IVMODE	A more privileged access mode is required.
SS$_NOMORELOCK	The caller requested a wildcard operation by specifying a value of 0 or --1 for the lkidadr argument, and $GETLKI has exhausted the locks about which it can return information to the caller; or no lkidadr argument is specified. This is an alternate success status.
SS$_NOSYSLCK	The caller attempted to acquire information about a systemwide lock and did not have the required SYSLCK privilege.
SS$_NOWORLD	The caller attempted to acquire information about a lock held by a process in another group and did not have the required WORLD privilege.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

Returns information about the lock database on a system.

The $GETLKIW service completes synchronously; that is, it returns tothe caller with the requested information.

For asynchronous completion, use the Get Lock Information ($GETLKI)service; $GETLKI returns to the caller after queuing the informationrequest, without waiting for the information to be returned.

In all other respects, $GETLKIW is identical to $GETLKI. For all otherinformation about the $GETLKIW service, refer to the description of$GETLKI in this manual.

The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together providethe user interface to the Lock Management facility. Refer to thedescriptions of these other services for additional information aboutlock management.

Format

SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm][,nullarg]

C Prototype

int sys$getlkiw (unsigned int efn, unsigned int *lkidadr, void *itmlst,struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm,unsigned int reserved);

Returns message text associated with a given message identificationcode into the caller's buffer. The message can be from the systemmessage file or a user-defined message.

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

Format

SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]

C Prototype

int sys$getmsg (unsigned int msgid, unsigned short int *msglen, void*bufadr, unsigned int flags, unsigned char outadr [4]);

Arguments

msgid

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

Identification of the message to be retrieved. Themsgid argument is a longword value containing themessage identification. Each message has a unique identification,contained in bits 3 through 27 of system longword condition values.

msglen

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Length of the message string returned by $GETMSG. Themsglen argument is the 32- or 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of a word into which$GETMSG writes this length.

bufadr

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

Buffer to receive the message string. The bufadrargument is the 32- or 64-bit address (on Alpha systems) or the 32-bitaddress (on VAX systems) of a character string descriptor pointing tothe buffer into which $GETMSG writes the message string. The maximumsize of any message string is 256 bytes.

flags

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

Message components to be returned. The flags argumentis a longword bit vector wherein a bit, when set, specifies that themessage component is to be returned.

The following table describes the significant bits:

Bit	Value	Description
0	1	Include text of message
	0	Do not include text of message
1	1	Include message identifier
	0	Do not include message identifier
2	1	Include severity indicator
	0	Do not include severity indicator
3	1	Include facility name
	0	Do not include facility name

If you omit this argument in a VAX MACRO or BLISS-32 service call, itdefaults to a value of 15; that is, all flags are set and allcomponents of the message are returned. If you omit this argument in aFortran service call, it defaults to a value of 0; the value 0 causes$GETMSG to use the process default flags.

outadr

OpenVMS usage:	vector_byte_unsigned
type:	byte (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Optional information to be returned by $GETMSG. Theoutadr argument is the 32- or 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of a 4-byte array intowhich $GETMSG writes the following information:

Byte	Contents
0	Reserved
1	Count of FAO arguments associated with message
2	User-specified value in message, if any
3	Reserved

Description

The Get Message service locates and returns message text associatedwith a given message identification code into the caller's buffer. Themessage can be from the system message file or a user-defined message.The operating system uses this service to retrieve messages based onunique message identifications and to prepare to output the messages.

The message identifications correspond to the symbolic names forcondition values returned by system components; for example, SS$_codefrom system services, RMS$_code for RMS messages, and so on.

When you set all bits in the flags argument, $GETMSGreturns a string in the following format:

facility-severity-ident, message-text

where:

facility	Identifies the component of the operating system
severity	Is the severity code (the low-order three bits of the condition value)
ident	Is the unique message identifier
message-text	Is the text of the message

For example, if you specify the MSGID=#SS$_DUPLNAM argument, the$GETMSG service returns the following string:

%SYSTEM-F-DUPLNAM, duplicate process name

You can define your own messages with the Message utility. See theHP OpenVMS System Management Utilities Reference Manual for additional information.

The message text associated with a particular 32-bit messageidentification can be retrieved from one of several places. Thisservice takes the following steps to locate the message text:

1. All message sections linked into the currently executing image are searched for the associated information.
2. If the information is not found, the process-permanent message file is searched. (You can specify the process-permanent message file by using the SET MESSAGE command.)
3. If the information is not found, the systemwide message file is searched.
4. If the information is not found, the SS$_MSGNOTFND condition value is returned in R0 and a message in the following form is returned to the caller's buffer:

   %facility-severity-NONAME, message=xxxxxxxx[hex], (facility=n, message=n[dec])

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BUFFEROVF	The service completed successfully. The string returned overflowed the buffer provided and has been truncated.
SS$_INSFARG	The call arguments are insufficient.
SS$_MSGNOTFND	The service completed successfully; however, the message code cannot be found, and a default message has been returned.

Example

#include <stdio.h>#include <ssdef.h>#include <stsdef.h>#include <descrip.h>#include <starlet.h>int     status,                         /* Status of system calls */        msg_flag = 0x0001,              /* Text only */        msg_code = SS$_DUPLNAM;         /* Message code to retrieve */short int        outlen;                         /* Length of output string from $FAO */char    out_buffer[256],                /* Buffer for $FAO output */        msg_info[4];                    /* Buffer for message information */$DESCRIPTOR(out_desc, out_buffer);      /* VMS Descriptor for out_buffer */main(){    status = sys$getmsg(msg_code,       /* Error message number */                        &outlen,        /* Length of retrived message */                        &out_desc,      /* Descriptor for output buffer */                        msg_flag,       /* Message options flag */                        msg_info);      /* Return information area */    if ((status & STS$M_SUCCESS) != 0)    {        /* $GETMSG directive succeeded, output resultant string */        out_buffer[outlen] = '\0';      /* add string terminator to buffer */        puts(out_buffer);               /* output the result */    }    return (status);}      

This example shows a segment of a program used to obtain only the textportion of the message associated with the system message codeSS$_DUPLNAM. The $GETMSG service returns the following string:

duplicate process name

Returns information about queues and the jobs initiated from thosequeues.

The $GETQUI service completes asynchronously; for synchronouscompletion, use the Get Queue Information and Wait ($GETQUIW) service.

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

Format

SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]

C Prototype

int sys$getqui (unsigned int efn, unsigned short int func, unsigned int*context, void *itmlst, struct _iosb *iosb, void(*astadr)(__unknown_params), int astprm);

Arguments

efn

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

Number of the event flag to be set when $GETQUI completes. Theefn argument is a longword containing this number;however, $GETQUI uses only the low-order byte. The efnargument is optional.

When the request is queued, $GETQUI clears the specified event flag (orevent flag 0 if efn was not specified). Then, when theoperation completes, $GETQUI sets the specified event flag (or eventflag 0).

func

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

Function code specifying the function that $GETQUI is to perform. Thefunc argument is a word containing this function code.The $QUIDEF macro defines the names of each function code.

You can specify only one function code in a single call to $GETQUI.Most function codes require or allow for additional information to bepassed in the call. You pass this information by using theitmlst argument, which specifies a list of one or moreitem descriptors. Each item descriptor in turn specifies an item code,which either describes the specific information to be returned by$GETQUI, or otherwise affects the action designated by the functioncode.

You can use wildcard mode to make a sequence of calls to $GETQUI to getinformation about all characteristics, form definitions, queues, orjobs contained in the system job queue file. For information on usingwildcard mode, see the Description section.

context

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

Address of a longword containing the number of a context stream forthis call to the $GETQUI system service. If the argument is unspecifiedor 0, the service uses the default context stream (#0).

To generate a new context stream, the specified longword must contain--1. $GETQUI then modifies the longword to hold the context number forthat stream of operation. The context is marked with the caller's mode(user, supervisor, executive, or kernel). Any attempt to use thatcontext in successive calls is checked and no call from a mode outsidethe recorded mode is allowed access.

To clean up a context, make a $GETQUI call using theQUI$_CANCEL_OPERATION function code and specify the address of thecontext number as the context argument.

itmlst

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

Item list supplying information to be used in performing the functionspecified by the func argument. Theitmlst argument is the address of the item list. Theitem list consists of one or more item descriptors, each of whichcontains an item code. The item list is terminated by an item code of 0or by a longword of 0. The following diagram depicts the structure of asingle item descriptor:

The following table defines the item descriptor fields:

The item codes' symbolic names have the following format:

There are two types of item code:

• Input value item code. The $GETQUI service has only five input value item codes: QUI$_SEARCH_FLAGS, QUI$_SEARCH_JOB_NAME, QUI$_SEARCH_NAME, QUI$_SEARCH_NUMBER, and QUI$_SEARCH_USERNAME. These item codes specify the object name or number for which $GETQUI is to return information and the extent of $GETQUI's search for these objects. Most function codes require that you specify at least one input value item code. The function code or codes for which each item code is valid are shown in parentheses after the item code description.
  For input value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field must be zero. Specific buffer length requirements are given in the description of each item code.
• Output value item code. Output value item codes specify a buffer for information returned by $GETQUI. For output value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be zero or nonzero. Specific buffer length requirements are given in the description of each item code.

Several item codes specify a queue name, form name, or characteristicname to $GETQUI or request that $GETQUI return one of these names. Forthese item codes, the buffer must specify or be prepared to receive astring containing from 1 to 31 characters, exclusive of spaces, tabs,and null characters, which are ignored. Allowable characters in thestring are uppercase alphabetic characters, lowercase alphabeticcharacters (which are converted to uppercase), numeric characters, thedollar sign ($), and the underscore (_).

See the Item Codes section for a description of the $GETQUI item codes.

iosb

At request initiation, $GETQUI sets the value of the quadword I/Ostatus block to 0. When the requested operation has completed, $GETQUIwrites a condition value in the first longword of the I/O status block.It writes the value 0 into the second longword; this longword is unusedand reserved for future use.

The condition values returned by $GETQUI in the I/O status block arecondition values from the JBC facility, which are defined by the$JBCMSGDEF macro. The condition values returned from the JBC facilityare listed in the section Condition Values Returned in the I/O StatusBlock section.

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 $GETQUI 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 $GETQUI, you must check the condition values returned in both R0 and the I/O status block.

astadr

If specified, the AST routine executes at the same access mode as thecaller of $GETQUI.

astprm

QUI$_CANCEL_OPERATION

This request terminates a wildcard operation that might have beeninitiated by a previous call to $GETQUI by releasing the $GETQUIcontext block (GQC) associated with the specified context stream.

A specific context stream can be selected and other streams areunaffected.

QUI$_DISPLAY_CHARACTERISTIC

This request returns information about a specific characteristicdefinition, or the next characteristic definition in a wildcardoperation.

A successful QUI$_DISPLAY_CHARACTERISTIC wildcard operation terminateswhen the $GETQUI service has returned information about allcharacteristic definitions included in the wildcard sequence. The$GETQUI service indicates termination of this sequence by returning thecondition value JBC$_NOMORECHAR in the I/O status block. If the $GETQUIservice does not find any characteristic definitions, it returns thecondition value JBC$_NOSUCHCHAR in the I/O status block.

For more information on how to request information aboutcharacteristics, see the Description section.

You must specify one of the following input value item codes; you canspecify both:

QUI$_SEARCH_NAME
QUI$_SEARCH_NUMBER

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_CHARACTERISTIC_NAME
QUI$_CHARACTERISTIC_NUMBER

QUI$_DISPLAY_ENTRY

This request returns information about a specific job entry, or thenext job entry that matches the selection criteria in a wildcardoperation. You use the QUI$_SEARCH_NUMBER item code to specify the jobentry number.

In wildcard mode, the QUI$_DISPLAY_ENTRY operation also establishes ajob context for subsequent QUI$_DISPLAY_FILE operations. The jobcontext established remains in effect until you make another call tothe $GETQUI service that specifies either the QUI$_DISPLAY_ENTRY orQUI$_CANCEL_OPERATION function code.

A successful QUI$_DISPLAY_ENTRY wildcard operation terminates when the$GETQUI service has returned information about all job entries for thespecified user (or the current user name if the QUI$_SEARCH_USERNAMEitem code is not specified). The $GETQUI service signals termination ofthis sequence by returning the condition value JBC$_NOMOREENT in theI/O status block. If the $GETQUI service does not find a job with thespecified entry number, or does not find a job meeting the searchcriteria, it returns the condition value JBC$_NOSUCHENT in the firstlongword of the I/O status block.

You can specify the following input value item codes:

QUI$_SEARCH_FLAGS
QUI$_SEARCH_JOB_NAME
QUI$_SEARCH_NUMBER
QUI$_SEARCH_USERNAME

You can specify the following output value item codes:

QUI$_ACCOUNT_NAME
QUI$_AFTER_TIME
QUI$_ASSIGNED_QUEUE_NAME
QUI$_CHARACTERISTICS
QUI$_CHECKPOINT_DATA
QUI$_CLI
QUI$_COMPLETED_BLOCKS
QUI$_CONDITION_VECTOR
QUI$_CPU_LIMIT
QUI$_ENTRY_NUMBER
QUI$_FILE_COUNT
QUI$_FORM_NAME
QUI$_FORM_STOCK
QUI$_JOB_COMPLETION_QUEUE
QUI$_JOB_COMPLETION_TIME
QUI$_JOB_COPIES
QUI$_JOB_COPIES_DONE
QUI$_JOB_FLAGS
QUI$_JOB_NAME
QUI$_JOB_PID
QUI$_JOB_RETENTION_TIME
QUI$_JOB_SIZE
QUI$_JOB_STATUS
QUI$_LOG_QUEUE
QUI$_LOG_SPECIFICATION
QUI$_NOTE
QUI$_OPERATOR_REQUEST
QUI$_PARAMETER_1 through 8
QUI$_PENDING_JOB_REASON
QUI$_PRIORITY
QUI$_PROCESSOR
QUI$_QUEUE_FLAGS
QUI$_QUEUE_NAME
QUI$_QUEUE_STATUS
QUI$_RAD
QUI$_REQUEUE_QUEUE_NAME
QUI$_RESTART_QUEUE_NAME
QUI$_SUBMISSION_TIME
QUI$_UIC
QUI$_USERNAME
QUI$_WSDEFAULT
QUI$_WSEXTENT
QUI$_WSQUOTA

QUI$_DISPLAY_FILE

This request returns information about the next file defined for thecurrent job context. You normally make this request as part of a nestedwildcard sequence of queue-job-file operations or a nested wildcardsequence of entry-file operations; that is, before you make a call to$GETQUI to request file information, you have already made a call tothe $GETQUI service to establish the job context of the job thatcontains the files in which you are interested.

The $GETQUI service signals that it has returned information about allthe files defined for the current job context by returning thecondition value JBC$_NOMOREFILE in the I/O status block. If the currentjob context contains no files, $GETQUI returns the condition valueJBC$_NOSUCHFILE in the I/O status block.

A batch job can make a call to the $GETQUI service to requestinformation about the command file that is currently executing withoutfirst making calls to the service to establish a queue and job context.To do this, the batch job specifies the QUI$V_SEARCH_THIS_JOB option ofthe QUI$_SEARCH_FLAGS item code. The system does not save the queue orjob context established in such a call.

For more information about how to request file information, see theDescription section.

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_FILE_COPIES
QUI$_FILE_COPIES_DONE
QUI$_FILE_FLAGS
QUI$_FILE_IDENTIFICATION
QUI$_FILE_SETUP_MODULES
QUI$_FILE_SPECIFICATION
QUI$_FILE_STATUS
QUI$_FIRST_PAGE
QUI$_LAST_PAGE

QUI$_DISPLAY_FORM

This request returns information about a specific form definition, orthe next form definition in a wildcard operation.

A successful QUI$_DISPLAY_FORM wildcard operation terminates when the$GETQUI service has returned information about all form definitionsincluded in the wildcard sequence. The $GETQUI service signalstermination of this wildcard sequence by returning the condition valueJBC$_NOMOREFORM in the I/O status block. If the $GETQUI service findsno form definitions, it returns the condition value JBC$_NOSUCHFORM inthe I/O status block.

For more information on how to request information about forms, see theDescription section.

You must specify one of the following input value item codes. You canspecify both:

QUI$_SEARCH_NAME
QUI$_SEARCH_NUMBER

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_FORM_DESCRIPTION
QUI$_FORM_FLAGS
QUI$_FORM_LENGTH
QUI$_FORM_MARGIN_BOTTOM
QUI$_FORM_MARGIN_LEFT
QUI$_FORM_MARGIN_RIGHT
QUI$_FORM_MARGIN_TOP
QUI$_FORM_NAME
QUI$_FORM_NUMBER
QUI$_FORM_SETUP_MODULES
QUI$_FORM_STOCK
QUI$_FORM_WIDTH
QUI$_PAGE_SETUP_MODULES

QUI$_DISPLAY_JOB

This request returns information about the next job defined for thecurrent queue context. You normally make this request as part of anested wildcard queue-job sequence of operations; that is, before youmake a call to $GETQUI to request job information, you have alreadymade a call to the $GETQUI service to establish the queue context ofthe queue that contains the job in which you are interested.

In wildcard mode, the QUI$_DISPLAY_JOB operation also establishes a jobcontext for subsequent QUI$_DISPLAY_FILE operations. The job contextestablished remains in effect until another call is made to the $GETQUIservice that specifies the QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE, orQUI$_CANCEL_OPERATION function code.

The $GETQUI service signals that it has returned information about allthe jobs contained in the current queue context by returning thecondition value JBC$_NOMOREJOB in the I/O status block. If the currentqueue context contains no jobs, $GETQUI returns the condition valueJBC$_NOSUCHJOB in the first longword of the I/O status block.

A batch job can make a call to the $GETQUI service to requestinformation about itself without first making a call to the service toestablish a queue context. To do this, the batch job must specify theQUI$V_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code. Thesystem does not save the queue or job context established in such acall.

For more information about how to request job information, see theDescription section.

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_ACCOUNT_NAME
QUI$_AFTER_TIME
QUI$_CHARACTERISTICS
QUI$_CHECKPOINT_DATA
QUI$_CLI
QUI$_COMPLETED_BLOCKS
QUI$_CONDITION_VECTOR
QUI$_CPU_LIMIT
QUI$_ENTRY_NUMBER
QUI$_FILE_COUNT
QUI$_FORM_NAME
QUI$_FORM_STOCK
QUI$_INTERVENING_BLOCKS
QUI$_INTERVENING_JOBS
QUI$_JOB_COMPLETION_QUEUE
QUI$_JOB_COMPLETION_TIME
QUI$_JOB_COPIES
QUI$_JOB_COPIES_DONE
QUI$_JOB_FLAGS
QUI$_JOB_NAME
QUI$_JOB_PID
QUI$_JOB_RETENTION_TIME
QUI$_JOB_SIZE
QUI$_JOB_STATUS
QUI$_LOG_QUEUE
QUI$_LOG_SPECIFICATION
QUI$_NOTE
QUI$_OPERATOR_REQUEST
QUI$_PARAMETER_1 through 8
QUI$_PENDING_JOB_REASON
QUI$_PRIORITY
QUI$_QUEUE_NAME
QUI$_RAD
QUI$_REQUEUE_QUEUE_NAME
QUI$_RESTART_QUEUE_NAME
QUI$_SUBMISSION_TIME
QUI$_UIC
QUI$_USERNAME
QUI$_WSDEFAULT
QUI$_WSEXTENT
QUI$_WSQUOTA

QUI$_DISPLAY_MANAGER

This request returns information about a specific queue manager, or thenext queue manager in a wildcard operation.

The $GETQUI service indicates that it has returned information aboutall the queue managers contained in the current wildcard sequence byreturning the condition value JBC$_NOMOREQMGR in the I/O status block.If no queue manager matching the name string is found, $GETQUI returnsthe condition value JBC$_NOSUCHQMGR in the first longword of the I/Ostatus block.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_MANAGER_NAME
QUI$_MANAGER_NODES
QUI$_MANAGER_STATUS
QUI$_QUEUE_DIRECTORY
QUI$_SCSNODE_NAME

QUI$_DISPLAY_QUEUE

This request returns information about a specific queue definition, orthe next queue definition in a wildcard operation.

In wildcard mode, the QUI$_DISPLAY_QUEUE operation also establishes aqueue context for subsequent QUI$_DISPLAY_JOB operations. The queuecontext established remains in effect until another call is made to the$GETQUI service that specifies either the QUI$_DISPLAY_QUEUE orQUI$_CANCEL_OPERATION function code.

The $GETQUI service indicates that it has returned information aboutall the queues contained in the current wildcard sequence by returningthe condition value JBC$_NOMOREQUE in the I/O status block. If no queueis found, $GETQUI returns the condition value JBC$_NOSUCHQUE in thefirst longword of the I/O status block.

A batch job can make a call to the $GETQUI service to requestinformation about the queue in which it is contained without firstmaking a call to the service to establish a queue context. To do this,the batch job must specify the QUI$V_SEARCH_THIS_JOB option of theQUI$_SEARCH_FLAGS item code. The system does not save the queue contextestablished in such a call.

For more information about how to request queue information, see theDescription section.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following input value item code:

QUI$_SEARCH_FLAGS

You can specify the following output value item codes:

QUI$_ASSIGNED_QUEUE_NAME
QUI$_BASE_PRIORITY
QUI$_CHARACTERISTICS
QUI$_CPU_DEFAULT
QUI$_CPU_LIMIT
QUI$_DEFAULT_FORM_NAME
QUI$_DEFAULT_FORM_STOCK
QUI$_DEVICE_NAME
QUI$_EXECUTING_JOB_COUNT
QUI$_FORM_NAME
QUI$_FORM_STOCK
QUI$_GENERIC_TARGET
QUI$_HOLDING_JOB_COUNT
QUI$_JOB_LIMIT
QUI$_JOB_RESET_MODULES
QUI$_JOB_SIZE_MAXIMUM
QUI$_JOB_SIZE_MINIMUM
QUI$_LIBRARY_SPECIFICATION
QUI$_OWNER_UIC
QUI$_PENDING_JOB_BLOCK_COUNT
QUI$_PENDING_JOB_COUNT
QUI$_PROCESSOR
QUI$_PROTECTION
QUI$_QUEUE_DESCRIPTION
QUI$_QUEUE_FLAGS
QUI$_QUEUE_NAME
QUI$_QUEUE_STATUS
QUI$_RAD
QUI$_RETAINED_JOB_COUNT
QUI$_SCSNODE_NAME
QUI$_TIMED_RELEASE_JOB_COUNT
QUI$_WSDEFAULT
QUI$_WSEXTENT
QUI$_WSQUOTA

QUI$_TRANSLATE_QUEUE

This request translates a name for a logical queue to the executionname for the queue. The name for the logical queue is specified byQUI$_SEARCH_NAME.

The translation is performed iteratively until the equivalence stringis found or the number of translations allowed by the system has beenreached.

This item applies to logical queues only. For additional information,see the Description section.

You must specify the following input value item code:

QUI$_SEARCH_NAME

You can specify the following output value item code:

QUI$_QUEUE_NAME

Item Codes

QUI$_ACCOUNT_NAME

Returns, as a character string, the account name of the owner of thespecified job. Because the account name can include up to 8 characters,the buffer length field of the item descriptor should specify 8 (bytes).

(Valid for QUI$_DISPLAY_ENRY, QUI$_DISPLAY_JOB function codes)

QUI$_AFTER_TIME

Returns, as a quadword absolute time value, the system time at or afterwhich the specified job can execute; however, if the time specified atsubmission has passed, the job executes immediately and $GETQUI returnsthe system time at which the job was submitted.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_ASSIGNED_QUEUE_NAME

Returns, as a character string, the name of the execution queue towhich the logical queue specified in the call to $GETQUI is assigned.Because the queue name can include up to 31 characters, the bufferlength field of the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_AUTOSTART_ON

When you specify QUI$_AUTOSTART_ON for a batch queue, $GETQUI returns,as a character string in a comma-separated list, the names of the nodeson which the specified autostart queue can be run. Each node name isfollowed by a double colon (::).

When you specify QUI$_AUTOSTART_ON for an output queue, $GETQUIreturns, as a character string in a comma-separated list, the names ofthe nodes and devices to which the specified autostart queue's outputcan be sent. Each node name is followed by a double colon (::). Eachdevice name can be followed by the optional colon [:].

For more information on the autostart feature, refer to theHP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_BASE_PRIORITY

Returns, as a longword value in the range 0 to 15, the priority atwhich batch jobs are initiated from a batch execution queue or thepriority of a symbiont process that controls output execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_CHARACTERISTIC_NAME

Returns, as a character string, the name of the specifiedcharacteristic. Because the characteristic name can include up to 31characters, the buffer length field of the item descriptor shouldspecify 31 (bytes).

(Valid for QUI$_DISPLAY_CHARACTERISTIC function code)

QUI$_CHARACTERISTIC_NUMBER

Returns, as a longword value in the range 0 to 127, the number of thespecified characteristic.

(Valid for QUI$_DISPLAY_CHARACTERISTIC function code)

QUI$_CHARACTERISTICS

Returns, as a 128-bit string (16-byte field), the characteristicsassociated with the specified queue or job. Each bit set in the bitmask represents a characteristic number in the range 0 to 127.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

QUI$_CHECKPOINT_DATA

Returns, as a character string, the value of the DCL symbolBATCH$RESTART when the specified batch job is restarted. Because thevalue of the symbol can include up to 255 characters, the buffer lengthfield of the item descriptor should specify 255 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_CLI

Returns, as an OpenVMS RMS file name component, the name of the commandlanguage interpreter used to execute the specified batch job. The filespecification returned assumes the logical name SYS$SYSTEM and the filetype .EXE. Because a file name can include up to 39 characters, thebuffer length field in the item descriptor should specify 39 (bytes).This item code is applicable only to batch jobs.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_COMPLETED_BLOCKS

Returns, as a longword integer value, the number of blocks that thesymbiont has processed for the specified print job. This item code isapplicable only to print jobs.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_CONDITION_VECTOR

Returns the vector of three longwords. The first longword gives thecompletion status of the specified job. The second and third longwordsgive additional status about the print job.

(Valid for QUI$_DISPLAY ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_CPU_DEFAULT

Returns, as a longword integer value, the default CPU time limitspecified for the queue in 10-millisecond units. This item code isapplicable only to batch execution queues.

For more information about default forms, see the HP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_CPU_LIMIT

Returns, as a longword integer value, the maximum CPU time limitspecified for the specified job or queue in 10-millisecond units. Thisitem code is applicable only to batch jobs and batch execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

QUI$_DEFAULT_FORM_NAME

Returns, as a character string, the name of the default form associatedwith the specified output queue. Because the form name can include upto 31 characters, the buffer length field of the item descriptor shouldspecify 31 (bytes).

For more information about default forms, see the HP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_DEFAULT_FORM_STOCK

Returns, as a character string, the name of the paper stock on whichthe specified default form is to be printed. Because the name of thepaper stock can include up to 31 characters, the buffer length field ofthe item descriptor should specify 31 (bytes).

For more information on default forms, refer to the HP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_DEVICE_NAME

Returns, as a character string, the name of the device on which thespecified output execution queue is located. Because the device namecan include up to 255 characters, the buffer length field of the itemdescriptor should specify 255 (bytes).

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_ENTRY_NUMBER

Returns, as a longword integer value, the queue entry number of thespecified job.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_EXECUTING_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queuethat are currently executing.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_FILE_COPIES

Returns the number of times the specified file is to be processed,which is a longword integer value in the range 1 to 255. This item codeis applicable only to output execution queues.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_COPIES_DONE

Returns the number of times the specified file has been processed,which is a longword integer value in the range 1 to 255. This item codeis applicable only to output execution queues.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_COUNT

Returns, as a longword integer value, the number of files in aspecified job.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_FILE_FLAGS

Returns, as a longword bit vector, the processing options that havebeen selected for the specified file. Each processing option isrepresented by a bit. When $GETQUI sets a bit, the file is processedaccording to the corresponding processing option. Each bit in thevector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:

Symbolic Name	Description
QUI$V_FILE_BURST	Burst and flag pages are to be printed preceding the file.
QUI$V_FILE_DELETE	File is to be deleted after execution of request.
QUI$V_FILE_DOUBLE_SPACE	Symbiont formats the file with double spacing.
QUI$V_FILE_FLAG	Flag page is to be printed preceding the file.
QUI$V_FILE_TRAILER	Trailer page is to be printed following the file.
QUI$V_FILE_PAGE_HEADER	Page header is to be printed on each page of output.
QUI$V_FILE_PAGINATE	Symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUI$V_FILE_PASSALL	Symbiont prints the file in PASSALL mode.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_IDENTIFICATION

Returns, as a 28-byte string, the internal file-identification valuethat uniquely identifies the selected file. This string contains (inorder) the following three file-identification fields from the RMS NAMblock for the selected file: the 16-byte NAM$T_DVI field, the 6-byteNAM$W_FID field, and the 6-byte NAM$W_DID field.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_SETUP_MODULES

Returns, as a comma-separated list, the names of the text modules thatare to be extracted from the device control library and copied to theprinter before the specified file is printed. Because a text modulename can include up to 31 characters and is separated from the previoustext module name with a comma, the buffer length field of the itemdescriptor should specify 32 (bytes) for each possible text module.This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_SPECIFICATION

Returns the fully qualified OpenVMS RMS file specification of the fileabout which $GETQUI is returning information. Because a filespecification can include up to 255 characters, the buffer length fieldof the item descriptor should specify 255 (bytes).

Note The file specification is the result of an RMS file-passing operationthat occurs at the time you submit the job. If you renamed the file orcreated the job as a result of copying a file to a spooled device, thenyou cannot use this file specification to access the file through RMS.You use QUI$_FILE_IDENTIFICATION to obtain a unique identifier for thefile.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FILE_STATUS

Returns file status information as a longword bit vector. Each filestatus condition is represented by a bit. When $GETQUI sets the bit,the file status corresponds to the condition represented by the bit.Each bit in the vector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:

Symbolic Name	Description
QUI$V_FILE_CHECKPOINTED	File is checkpointed.
QUI$V_FILE_EXECUTING	File is being processed.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FIRST_PAGE

Returns, as a longword integer value, the page number at which theprinting of the specified file is to begin. This item code isapplicable only to output execution queues.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_FORM_DESCRIPTION

Returns, as a character string, the text string that describes thespecified form. Because the text string can include up to 255characters, the buffer length field in the item descriptor shouldspecify 255 (bytes).

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_FLAGS

Returns, as a longword bit vector, the processing options that havebeen selected for the specified form. Each processing option isrepresented by a bit. When $GETQUI sets a bit, the form is processedaccording to the corresponding processing option. Each bit in thevector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:

Symbolic Name	Description
QUI$V_FORM_SHEET_FEED	Symbiont pauses at the end of each physical page so that another sheet of paper can be inserted.
QUI$V_FORM_TRUNCATE	Printer discards any characters that exceed the specified right margin.
QUI$V_FORM_WRAP	Printer prints any characters that exceed the specified right margin on the following line.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_LENGTH

Returns, as a longword integer value, the physical length of thespecified form in lines. This item code is applicable only to outputexecution queues.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_MARGIN_BOTTOM

Returns, as a longword integer value, the bottom margin of thespecified form in lines.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_MARGIN_LEFT

Returns, as a longword integer value, the left margin of the specifiedform in characters.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_MARGIN_RIGHT

Returns, as a longword integer value, the right margin of the specifiedform in characters.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_MARGIN_TOP

Returns, as a longword integer value, the top margin of the specifiedform in lines.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_NAME

Returns, as a character string, the name of the specified form or themounted form associated with the specified job or queue. Because theform name can include up to 31 characters, the buffer length field ofthe item descriptor should specify 31 (bytes).

For more information about mounted forms, refer to the HP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_FORM, QUI$_DISPLAY_JOB,QUI$_DISPLAY_QUEUE function codes)

QUI$_FORM_NUMBER

Returns, as a longword integer value, the number of the specified form.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_SETUP_MODULES

Returns, as a comma-separated list, the names of the text modules thatare to be extracted from the device control library and copied to theprinter before a file is printed on the specified form. Because a textmodule name can include up to 31 characters and is separated from theprevious text module name by a comma, the buffer length field of theitem descriptor should specify 32 (bytes) for each possible textmodule. This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_FORM_STOCK

Returns, as a character string, the name of the paper stock on whichthe specified form is to be printed. Because the name of the paperstock can include up to 31 characters, the buffer length field of theitem descriptor should specify 31 (bytes).

For more information about forms, refer to the HP OpenVMS System Manager's Manual.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_FORM, QUI$_DISPLAY_JOB,QUI$_DISPLAY_QUEUE function codes)

QUI$_FORM_WIDTH

Returns, as a longword integer value, the width of the specified formin characters.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_GENERIC_TARGET

Returns, as a comma-separated list, the names of the execution queuesthat are enabled to accept work from the specified generic queue.Because a queue name can include up to 31 characters and is separatedfrom the previous queue name with a comma, the buffer length field ofthe item descriptor should specify 32 (bytes) for each possible queuename. A generic queue can send work to up to 124 execution queues. Thisitem code is meaningful only for generic queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_HOLDING_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queuebeing held until explicitly released.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_INTERVENING_BLOCKS

Returns, as a longword integer value, the size (in blocks) of filesassociated with pending jobs in the queue that were skipped during thecurrent call to $GETQUI. These jobs were not reported because they didnot match the selection criterion in effect for the call to $GETQUI.

The value of QUI$_INTERVENING_BLOCKS is 0 when (1) the job is not apending job, or (2) the job that matches the selection criterion is thefirst pending job in the queue, or (3) the preceding pending job in thequeue was reported in the previous call to $GETQUI.

This item code applies only to output queues.

In a wildcard sequence of calls to $GETQUI using the QUI$_DISPLAY_JOBfunction code, only information about jobs that match the $GETQUIselection criteria is returned.

(Valid for QUI$_DISPLAY_JOB function code)

QUI$_INTERVENING_JOBS

Returns, as a longword integer value, the number of pending jobs in thequeue that were skipped during the current call to $GETQUI. These jobswere not reported because they did not match the selection criterion ineffect for the call to $GETQUI.

The value of QUI$_INTERVENING_JOBS is 0 when (1) the job is not apending job, or (2) the job that matches the selection criterion is thefirst pending job in the queue, or (3) the preceding pending job in thequeue was reported in the previous call to $GETQUI.

This item code applies only to output queues.

In a wildcard sequence of calls to $GETQUI using the QUI$_DISPLAY_JOBfunction code, only information about jobs that match the $GETQUIselection criteria is returned.

(Valid for QUI$_DISPLAY_JOB function code)

QUI$_JOB_COMPLETION_QUEUE

Returns, as a character string, the name of the queue on which thespecified job executed. Because a queue name can include up to 31characters, the buffer length of the item descriptor should specify 31(bytes).

This item code has a value only if the QUI$_JOB_RETAINED bit is set inthe QUI$_JOB_STATUS longword item code.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_COMPLETION_TIME

Returns, as a quadword absolute time value, the system time at whichthe execution of the specified job completed.

This item code has a value only if the QUI$_JOB_RETAINED bit is set inthe QUI$_JOB_STATUS longword item code.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_COPIES

Returns, as a longword integer value, the number of times the specifiedprint job is to be repeated.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_COPIES_DONE

Returns, as a longword integer value, the number of times the specifiedprint job has been repeated.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_FLAGS

Returns, as a longword bit vector, the processing options that havebeen selected for the specified job. Each processing option isrepresented by a bit. When $GETQUI sets a bit, the job is processedaccording to the corresponding processing option. Each bit in thevector has a symbolic name.

The $QUIDEF macro defines the following symbolic names:

Symbolic Name	Description
QUI$V_JOB_CPU_LIMIT	CPU time limit for the job.
QUI$V_JOB_ERROR_RETENTION	The user requested that the job be retained in the queue, if the job completes unsuccessfully. If the queue is set to retain all jobs because the QUI$V_QUEUE_RETAIN_ALL bit of the QUI$_QUEUE_FLAGS item code is set, the job might be held in the queue even if it completes successfully. For more information about user-specified job retention, see the /RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.
QUI$V_JOB_FILE_BURST	Burst and flag pages precede each file in the job.
QUI$V_JOB_FILE_BURST_ONE	Burst and flag pages precede only the first copy of the first file in the job.
QUI$V_JOB_FILE_FLAG	Flag page precedes each file in the job.
QUI$V_JOB_FILE_FLAG_ONE	Flag page precedes only the first copy of the first file in the job.
QUI$V_JOB_FILE_PAGINATE	Symbiont paginates output by inserting a form feed whenever output reaches the bottom margin of the form.
QUI$V_JOB_FILE_TRAILER	Trailer page follows each file in the job.
QUI$V_JOB_FILE_TRAILER_ONE	Trailer page follows only the last copy of the last file in the job.
QUI$V_JOB_LOG_DELETE	Log file is deleted after it is printed.
QUI$V_JOB_LOG_NULL	No log file is created.
QUI$V_JOB_LOG_SPOOL	Job log file is queued for printing when job is complete.
QUI$V_JOB_LOWERCASE	Job is to be printed on printer that can print both uppercase and lowercase letters.
QUI$V_JOB_NOTIFY	Message is broadcast to terminal when job completes or aborts.
QUI$V_JOB_RAD (Alpha only)	Indicates if the job will use the RAD processing option. Supported only on AlphaServer GS series systems.
QUI$V_JOB_REQUEUE	Job will requeue after a system failure or can be requeued during execution.
QUI$V_JOB_RESTART	Job will restart after a system failure or can be requeued during execution.
QUI$V_JOB_RETENTION	The user requested that the job be retained in the queue regardless of the job's completion status. For more information about user-specified job retention, refer to the /RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.
QUI$V_JOB_WSDEFAULT	Default working set size is specified for the job.
QUI$V_JOB_WSEXTENT	Working set extent is specified for the job.
QUI$V_JOB_WSQUOTA	Working set quota is specified for the job.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_LIMIT

Returns the number of jobs that can execute simultaneously on thespecified queue, which is a longword integer value in the range 1 to255. This item code is applicable only to batch execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_JOB_NAME

Returns, as a character string, the name of the specified job. Becausethe job name can include up to 39 characters, the buffer length fieldof the item descriptor should specify 39 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_PID

Returns the process identification (PID) of the executing batch job instandard longword format.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_RESET_MODULES

Returns, as a comma-separated list, the names of the text modules thatare to be extracted from the device control library and copied to theprinter before each job in the specified queue is printed. Because atext module name can include up to 31 characters and is separated fromthe previous text module name by a comma, the buffer length field ofthe item descriptor should specify 32 (bytes) for each possible textmodule. This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_JOB_RETENTION_TIME

Returns, as a quadword time value, the system time until which the userrequested the job be retained in the queue. The system time can beexpressed in either an absolute or delta time format.

For more information, see the /RETAIN qualifier for PRINT or SUBMIT inthe HP OpenVMS DCL Dictionary.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_SIZE

Returns, as a longword integer value, the total number of disk blocksin the specified print job.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_JOB_SIZE_MAXIMUM

Returns, as a longword integer value, the maximum number of disk blocksthat a print job initiated from the specified queue can contain. Thisitem code is applicable only to output execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_JOB_SIZE_MINIMUM

Returns, as a longword integer value, the minimum number of disk blocksthat a print job initiated from the specified queue can contain. Thisitem code is applicable only to output execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_JOB_STATUS

Returns the specified job's status flags, which are contained in alongword bit vector. The $QUIDEF macro defines the following symbolicnames for these flags:

Symbol Name	Description
QUI$V_JOB_ABORTING	System is attempting to abort execution of job.
QUI$V_JOB_EXECUTING	Job is executing or printing.
QUI$V_JOB_HOLDING	Job will be held until it is explicitly released.
QUI$V_JOB_INACCESSIBLE	Caller does not have read access to the specific job and file information in the system queue file. Therefore, the QUI$_DISPLAY_JOB and QUI$_DISPLAY_FILE operations can return information for only the following output value item codes: QUI$_AFTER_TIME QUI$_COMPLETED_BLOCKS QUI$_ENTRY_NUMBER QUI$_INTEVENING_BLOCKS QUI$_INTEVENING_JOBS QUI$_JOB_SIZE QUI$_JOB_STATUS
QUI$V_JOB_PENDING	Job is pending. See QUI$_PENDING_JOB_REASON for the reason the job is in a pending state.
QUI$V_JOB_REFUSED	Job was refused by symbiont and is waiting for symbiont to accept it for processing.
QUI$V_JOB_RETAINED	Job has completed, but it is being retained in the queue.
QUI$V_JOB_STALLED	Execution of the job is stalled because the physical device on which the job is printing is stalled.
QUI$V_JOB_STARTING	The job has been scheduled for execution. Confirmation of execution has not been received.
QUI$V_JOB_SUSPENDED	Execution of the job is suspended because the queue on which it is executing is paused.
QUI$V_JOB_TIMED_RELEASE	Job is waiting for specified time to execute.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_LAST_PAGE

Returns, as a longword integer value, the page number at which theprinting of the specified file should end. This item code is applicableonly to output execution queues.

(Valid for QUI$_DISPLAY_FILE function code)

QUI$_LIBRARY_SPECIFICATION

Returns, as an OpenVMS RMS file name component, the name of the devicecontrol library for the specified queue. The library specificationassumes the device and directory name SYS$LIBRARY and a file type of.TLB. Because a file name can include up to 39 characters, the bufferlength field of the item descriptor should specify 39 (bytes). Thisitem code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_LOG_QUEUE

Returns, as a character string, the name of the queue into which thelog file produced for the specified batch job is to be entered forprinting. This item code is applicable only to batch jobs. Because aqueue name can contain up to 31 characters, the buffer length field ofthe item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_LOG_SPECIFICATION

Returns, as an OpenVMS RMS file specification, the name of the log fileto be produced for the specified job. Because a file specification caninclude up to 255 characters, the buffer length field of the itemdescriptor should specify 255 (bytes). This item code is meaningfulonly for batch jobs.

The string returned is the log file specification that was provided tothe $SNDJBC service to create the job. Therefore, to determine whethera log file is to be produced, testing this item code for a zero-lengthstring is insufficient; instead, you need to examine theQUI$V_JOB_LOG_NULL bit of the QUI$_JOB_FLAGS item code.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_MANAGER_NAME

Returns, as a character string, the queue manager name. Because a queuemanager name can include up to 31 characters, the buffer length fieldof the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_MANAGER_NODES

Returns, as a comma separated list, the names of the nodes on whichthis queue manager runs.

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_MANAGER_STATUS

Returns the specified queue manager's status flags, which are containedin a longword bit vector. The $QUIDEF macro defines the followingsymbolic names for these flags:

Symbolic Name	Description
QUI$V_MANAGER_FAILOVER	Queue manager is in the process of failing over to another node.
QUI$V_MANAGER_RUNNING	Queue manager is running.
QUI$V_MANAGER_START_PENDING	Queue manager can start up whenever a node on which it can run is booted.
QUI$V_MANAGER_STARTING	Queue manager is in the process of starting up.
QUI$V_MANAGER_STOPPING	Queue manager is in the process of shutting down.
QUI$V_MANAGER_STOPPED	Queue manager is stopped.

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_NOTE

Returns, as a character string, the note that is to be printed on thejob flag and file flag pages of the specified job. Because the note caninclude up to 255 characters, the buffer length field of the itemdescriptor should specify 255 (bytes). This item code is meaningful forbatch and output execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_OPERATOR_REQUEST

Returns, as a character string, the message that is to be sent to thequeue operator before the specified job begins to execute. Because themessage can include up to 255 characters, the buffer length field ofthe item descriptor should specify 255 (bytes). This item code ismeaningful only for output execution queues.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_OWNER_UIC

Returns the owner UIC as a longword value in standard UIC format.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PAGE_SETUP_MODULES

Returns, as a comma-separated list, the names of the text modules to beextracted from the device control library and copied to the printerbefore each page of the specified form is printed. Because a textmodule name can include up to 31 characters and is separated from theprevious text module name by a comma, the buffer length field of theitem descriptor should specify 32 (bytes) for each possible textmodule. This item code is meaningful only for output execution queues.

(Valid for QUI$_DISPLAY_FORM function code)

QUI$_PARAMETER_1 through QUI$_PARAMETER_8

Returns, as a character string, the value of the user-definedparameters that in batch jobs become the value of the DCL symbols P1through P8 respectively. Because these parameters can include up to 255characters, the buffer length field of the item descriptor shouldspecify 255 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PENDING_JOB_BLOCK_COUNT

Returns, as a longword integer value, the total number of blocks forall pending jobs in the queue (valid only for output execution queues).

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PENDING_JOB_COUNT

Returns, as a longword integer value, the number of jobs in the queuein a pending state.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_PENDING_JOB_REASON

Returns, as a longword bit vector, the reason that the job is in apending state. The $QUIDEF macro defines the following symbolic namesfor the flags:

Symbolic Name	Description
QUI$V_PEND_CHAR_MISMATCH	Job requires characteristics that are not available on the execution queue.
QUI$V_PEND_JOB_SIZE_MAX	Block size of job exceeds the upper block limit of the execution queue.
QUI$V_PEND_JOB_SIZE_MIN	Block size of job is less than the lower limit of the execution queue.
QUI$V_PEND_LOWERCASE_MISMATCH	Job requires lowercase printer.
QUI$V_PEND_NO_ACCESS	Owner of job does not have access to the execution queue.
QUI$V_PEND_QUEUE_BUSY	Job is pending because the number of jobs currently executing on the queue equals the job limit for the queue.
QUI$V_PEND_QUEUE_STATE	Job is pending because the execution queue is not in a running, open state as indicated by QUI$_QUEUE_STATUS.
QUI$V_PEND_STOCK_MISMATCH	Stock type required by the job's form does not match the stock type of the form mounted on the execution queue.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PRIORITY

Returns the scheduling priority of the specified job, which is alongword integer value in the range 0 through 255.

Scheduling priority affects the order in which jobs assigned to a queueare initiated; it has no effect on the base execution priority of ajob. The lowest scheduling priority value is 0, the highest is 255;that is, if a queue contains a job with a scheduling priority of 10 anda job with a scheduling priority of 2, the queue manager initiates thejob with the scheduling priority of 10 first.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_PROCESSOR

Returns, as an OpenVMS RMS file name component, the name of thesymbiont image that executes print jobs initiated from the specifiedqueue. The file name assumes the device and directory name SYS$SYSTEMand the file type .EXE. Because an RMS file name can include up to 39characters, the buffer length field of the item descriptor shouldspecify 39 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_PROTECTION

When you specify QUI$_PROTECTION, $GETQUI returns, as a word, thespecified queue's protection mask.

The following diagram illustrates the protection mask:

Bits 0 through 15 specify the protection value---the four types ofaccess (read, submit, manage, and delete) to be granted to the fourclasses of user (System, Owner, Group, World). Set bits deny access andclear bits allow access.

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_QUEUE_DESCRIPTION

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_QUEUE_DIRECTORY

(Valid for QUI$_DISPLAY_MANAGER function code)

QUI$_QUEUE_FLAGS

The $QUIDEF macro defines the following symbolic names:

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_QUEUE_NAME

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUE,QUI$_TRANSLATE_QUEUE function codes)

QUI$_QUEUE_STATUS

The $QUIDEF macro defines the following symbolic names for these flags:

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_QUEUE function codes)

QUI$_RAD (Alpha only)

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

QUI$_REQUEUE_QUEUE_NAME

Because a queue name can include up to 31 characters, the buffer lengthof the item descriptor should specify 31 (bytes).

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_RESTART_QUEUE_NAME

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_RETAINED_JOB_COUNT

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_SCSNODE_NAME

(Valid for QUI$_DISPLAY_QUEUE, QUI$_DISPLAY_MANAGER function codes)

QUI$_SEARCH_FLAGS

The following table contains the symbolic names for each option and thefunction code for which each flag is meaningful:

QUI$_SEARCH_JOB_NAME

(Valid for QUI$_DISPLAY_ENTRY function code)

QUI$_SEARCH_NAME

To direct $GETQUI to perform a wildcard search, you specifyQUI$_SEARCH_NAME as a string containing one or more of the wildcardcharacters (% or *).

(Valid for QUI$_DISPLAY_CHARACTERISTIC, QUI$_DISPLAY_FORM,QUI$_DISPLAY_MANAGER, QUI$_DISPLAY_QUEUE, QUI$_TRANSLATE_QUEUE functioncodes)

QUI$_SEARCH_NUMBER

(Valid for QUI$_DISPLAY_CHARACTERISTIC, QUI$_DISPLAY_ENTRY,QUI$_DISPLAY_FORM function codes)

QUI$_SEARCH_USERNAME

(Valid for QUI$_DISPLAY_ENTRY function code)

QUI$_SUBMISSION_TIME

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_TIMED_RELEASE_JOB_COUNT

(Valid for QUI$_DISPLAY_QUEUE function code)

QUI$_UIC

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_USERNAME

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB function codes)

QUI$_WSDEFAULT

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

QUI$_WSEXTENT

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

QUI$_WSQUOTA

(Valid for QUI$_DISPLAY_ENTRY, QUI$_DISPLAY_JOB, QUI$_DISPLAY_QUEUEfunction codes)

Description

The Get Queue Information service returns information about queues andthe jobs initiated from those queues. The $GETQUI and $SNDJBC servicestogether provide the user interface to the queue manager and jobcontroller processes. See the Description section of the $SNDJBCservice for a discussion of the different types of jobs and queues.

The $GETQUI service completes asynchronously; that is, it returns tothe caller after queuing the request, without waiting for the operationto complete. For synchronous completion, use the Get Queue Informationand Wait ($GETQUIW) service. The $GETQUIW service is identical to$GETQUI in every way except that $GETQUIW returns to the caller afterthe operation has completed.

Classes and Types of Queues

The $GETQUI item codes and function codes can be specific to the typeand class of the queue. For example, QUI$_LAST_PAGE applies only in thecontext of a printer or terminal execution queue, andQUI$_LOG_SPECIFICATION applies only to batch files.

The following information shows the two classes and the various typesof queues, while the descriptions of the individual $GETQUI item codesand function codes indicate the associated queue class and queue typerequirements:

• Execution queues---Queues that accept batch or print jobs for processing.
• Generic queues---Queues that hold jobs until an appropriate execution queue becomes available. The queue manager then requeues the job to the available execution queue.

The following table lists the Execution queue types:

Type	Description
Batch execution queues	Batch execution queues accept only batch jobs.
Output execution queues	Output execution queues accept jobs that a symbiont processes, and include the following types: Printer execution queue---Uses a symbiont to direct output to a printer. Terminal execution queue---Uses a symbiont to direct output to a terminal printer. Server execution queue---Uses a user-modified or user-written symbiont to process the files that belong to jobs in the queue.

The following table lists the Generic queue types:

Type	Description
Generic batch queues	Generic batch queues direct jobs only to batch execution queues.
Generic output queues	Generic output queues direct jobs to any of the three types of output execution queues: print, terminal, or server.
Logical queues	Logical queues are a special type of generic output queue that transfers jobs to another output execution queue.

For additional information, refer to the HP OpenVMS System Manager's Manual, Volume 1: Essentials.

You can specify the following function codes to return information forthe object types listed:

Function Code	Object Type
QUI$_DISPLAY_CHARACTERISTIC	Characteristic
QUI$_DISPLAY_FORM	Form
QUI$_DISPLAY_QUEUE	Queue
QUI$_DISPLAY_MANAGER	Queue manager
QUI$_DISPLAY_JOB	Job within a queue context
QUI$_DISPLAY_FILE	File within a job context
QUI$_DISPLAY_ENTRY	Job independent of queue

Maintaining Context Across $GETQUI Calls

When you call the $GETQUI service, the queue manager establishes aninternal GETQUI context block (GQC). The system uses the GQC to storeinformation temporarily and to keep track of its place in a wildcardsequence of operations. The system provides any number of GQC blocksper process.

To allow you to obtain information either about a particular object ina single call or about several objects in a sequence of calls, $GETQUIsupports three different search modes. The following search modesaffect the disposition of the GQC in different ways:

• Nonwildcard mode---$GETQUI returns information about a particular object in a single call. After the call completes, the system dissolves the GQC.
• Wildcard mode---$GETQUI returns information about several objects of the same type in a sequence of calls. The system saves the GQC between calls until the wildcard sequence completes.
• Nested wildcard mode---$GETQUI returns information about objects defined within another object. Specifically, this mode allows you to query jobs contained in a selected queue or files contained in a selected job in a sequence of calls. After each call, the system saves the GQC so that the GQC can provide the queue or job context necessary for subsequent calls.

The sections that follow describe how each of the three search methodsaffects $GETQUI's search for information; how you direct $GETQUI toundertake each method; and how each method affects the contents of theGQC.

Nonwildcard Mode

In nonwildcard mode, $GETQUI can return information about the followingobjects:

• A specific characteristic or form definition that you identify by name or number.
• A specific queue that you identify by name.
• A specific queue manager that you identify by name.
• A specific batch or print job that you identify by job entry number or by name.
• The queue, job, or executing command procedure file associated with the calling batch job. You invoke this special case of nonwildcard mode by specifying the QUI$_SEARCH_THIS_JOB option of the QUI$_SEARCH_FLAGS item code for a display queue, job, or file operation.

To obtain information about a specific characteristic or formdefinition, you call $GETQUI using the QUI$_DISPLAY_CHARACTERISTIC orQUI$_DISPLAY_FORM function code. You need to specify either the name ofthe characteristic or form in the QUI$_SEARCH_NAME item code or thenumber of the characteristic or form in the QUI$_SEARCH_NUMBER itemcode. The name string you specify cannot include either of the wildcardcharacters (* or %). You can specify both the QUI$_SEARCH_NAME andQUI$_SEARCH_NUMBER item codes, but the name and number you specify mustbe associated with the same characteristic or form definition.

To obtain information about a specific queue definition, you specifythe QUI$_DISPLAY_QUEUE function code and provide the name of the queuein the QUI$_SEARCH_NAME item code. The name string you specify cannotinclude the wildcard characters (* or %).

To obtain information about a specific queue manager, specify theQUI$_DISPLAY_MANAGER function code and provide the name of the queuemanager in the QUI$_SEARCH_NAME item code. The name string you specifycannot include the wildcard characters (* or %).

To obtain information about a specific batch or print job, specify theQUI$_DISPLAY_ENTRY function code and provide the entry number of thejob in the QUI$_SEARCH_NUMBER item code.

Finally, the $GETQUI service provides an option that allows a batch jobto obtain information about the queue, job, or command file that theassociated batch job is executing without first entering wildcard modeto establish a queue or job context. You can make a call from the batchjob that specifies the QUI$_DISPLAY_QUEUE function code to obtaininformation about the queue from which the batch job was initiated; theQUI$_DISPLAY_JOB function code to obtain information about the batchjob itself; or the QUI$_DISPLAY_FILE function code to obtaininformation about the command file for the batch job. For each of thesecalls, you must select the QUI$V_SEARCH_THIS_JOB option of theQUI$_SEARCH_FLAGS item code. When you select this option, $GETQUIignores all other options in the QUI$_SEARCH_FLAGS item code.

Wildcard Mode

In wildcard mode, the system saves the GQC between calls to $GETQUI sothat you can make a sequence of calls to $GETQUI to get informationabout all characteristics, forms, queues, jobs, or queue managerscontained in the queue database.

You can have several streams of operations open at one time. To use astream, specify a unique longword value for thecontext argument for every call associated with thatstream. If you do not specify the context argument,then context #0 will be used.

To set up a wildcard search for characteristic or form definitions,specify the QUI$_DISPLAY_CHARACTERISTIC or QUI$_DISPLAY_FORM functioncode and specify a name in the QUI$_SEARCH_NAME item code that includesone or more wildcard characters (* or %).

To set up a wildcard search for queues, use the QUI$_DISPLAY_QUEUEfunction code and specify a name in the QUI$_SEARCH_NAME item code thatincludes one or more wildcard characters (* or %). You can indicate thetype of the queue you want to search for by specifying any combinationof the following options for the QUI$_SEARCH_FLAGS item code:

QUI$V_SEARCH_BATCH
QUI$V_SEARCH_PRINTER
QUI$V_SEARCH_SERVER
QUI$V_SEARCH_TERMINAL
QUI$V_SEARCH_SYMBIONT
QUI$V_SEARCH_GENERIC

For example, if you select the QUI$V_SEARCH_BATCH option, $GETQUIreturns information only about batch queues; if you select theQUI$V_SEARCH_SYMBIONT option, $GETQUI returns information only aboutoutput queues (printer, terminal, and server queues). If you specifynone of the queue type options, $GETQUI searches all queues.

To set up a wildcard search for queue managers, specify theQUI$_DISPLAY_MANAGER function code and specify a name in theQUI$_SEARCH_NAME item code that includes one or more wildcardcharacters (* or %).

To set up a wildcard search for jobs, specify the QUI$_DISPLAY_ENTRYfunction code and the QUI$_SEARCH_WILDCARD option of theQUI$_SEARCH_FLAGS item code. When you specify this option, omit theQUI$_SEARCH_NUMBER item code. You can restrict the search to jobshaving particular status or to jobs residing in specific types ofqueues, or both, by including any combination of the following optionsfor the QUI$_SEARCH_FLAGS item code:

QUI$V_SEARCH_BATCH
QUI$V_SEARCH_EXECUTING_JOBS
QUI$V_SEARCH_HOLDING_JOBS
QUI$V_SEARCH_PENDING_JOBS
QUI$V_SEARCH_PRINTER
QUI$V_SEARCH_RETAINED_JOBS
QUI$V_SEARCH_SERVER
QUI$V_SEARCH_SYMBIONT
QUI$V_SEARCH_TERMINAL
QUI$V_SEARCH_TIMED_RELEASE_JOBS

You can also force wildcard mode for characteristic, form, or queuedisplay operations by specifying the QUI$V_SEARCH_WILDCARD option ofthe QUI$_SEARCH_FLAGS item code. If you specify this option, the systemsaves the GQC between calls, even if you specify a nonwildcard name inthe QUI$_SEARCH_NAME item code. Whether or not you specify a wildcardname in the QUI$_SEARCH_NAME item code, selecting theQUI$V_SEARCH_WILDCARD option ensures that wildcard mode is enabled.

Once established, wildcard mode remains in effect until one of thefollowing actions causes the GQC to be released:

• $GETQUI returns a JBC$_NOMORExxx or JBC$_NOSUCHxxx condition value on a call to display characteristic, form, queue, queue manager, or entry information, where xxx refers to CHAR, FORM, QUE, QMGR, or ENT.
• You explicitly cancel the wildcard operation by specifying the QUI$_CANCEL_OPERATION function code in a call to the $GETQUI service.
• Your process terminates.

Note that wildcard mode is a prerequisite for entering nested wildcardmode.

Nested Wildcard Mode

In nested wildcard mode, the system saves the GQC between calls to$GETQUI so that you can make a sequence of calls to $GETQUI to getinformation about jobs that are contained in a selected queue or filesof the selected job. Nested wildcard mode reflects the parent-childrelationship between queues and jobs and between jobs and files. The$GETQUI service can locate and return information about only one objectin a single call; however, queues are objects that contain jobs andjobs are objects that contain files. Therefore, to get informationabout an object contained within another object, you must first make acall to $GETQUI that specifies and locates the containing object andthen make a call to request information about the contained object. Thesystem saves the location of the containing object in the GQC alongwith the location of the contained object.

Note that the context number specified in the contextargument must remain the same for each level of nesting.

Two of $GETQUI's operations, QUI$_DISPLAY_JOB and QUI$_DISPLAY_FILE,can be used only in a nested wildcard mode, with one exception. Theexceptional use of these two operations involves calls made to $GETQUIfrom a batch job to find out more information about itself. Thisexceptional use is described at the end of the Nonwildcard Mode section.

You can enter nested wildcard mode from either wildcard display queuemode or from wildcard display entry mode. To obtain job and fileinformation in nested wildcard mode, you can use a combination ofQUI$_DISPLAY_QUEUE, QUI$_DISPLAY_JOB, and QUI$_DISPLAY_FILE operations.To obtain file information, you can use a combination ofQUI$_DISPLAY_ENTRY and QUI$_DISPLAY_FILE operations as an alternative.

To set up a nested wildcard search for job and file information, youfirst perform one or more QUI$_DISPLAY_QUEUE operations in wildcardmode to establish the queue context necessary for the nested displayjob and file operations. Next you specify the QUI$_DISPLAY_JOBoperation repetitively; these calls search the current queue until acall locates the job that contains the file or files you want. Thiscall establishes the job context. Having located the queue and the jobthat contain the file or files, you can now use the QUI$_DISPLAY_FILEoperation repetitively to request file information.

You can enter the nested wildcard mode for the display queue operationin two different ways: by specifying a wildcard name in theQUI$_SEARCH_NAME item code or by specifying a nonwildcard queue nameand selecting the QUI$V_SEARCH_WILDCARD option of the QUI$_SEARCH_FLAGitem code. The second method of entering wildcard mode is useful if youwant to obtain information about one or more jobs or files within jobsfor a specific queue and want to specify a nonwildcard queue name butstill want to save the GQC after the queue context is established.

When you make calls to $GETQUI that specify the QUI$_DISPLAY_JOBfunction code, by default $GETQUI locates all the jobs in the selectedqueue that have the same user name as the calling process. If you wantto obtain information about all the jobs in the selected queue, youselect the QUI$V_SEARCH_ALL_JOBS option of the QUI$_SEARCH_FLAGS itemcode.

After you establish a queue context, it remains in effect until youeither change the context by making another call to $GETQUI thatspecifies the QUI$_DISPLAY_QUEUE function code or until one of theactions listed at the end of the Wildcard Mode section causes the GQCto be released. An established job context remains in effect until youchange the context by making another call to $GETQUI that specifies theQUI$_DISPLAY_JOB function code or $GETQUI returns a JBC$_NOMOREJOB orJBC$_NOSUCHJOB condition value. While the return of either of these twocondition values releases the job context, the wildcard search remainsin effect because the GQC continues to maintain the queue context.Similarly, return of the JBC$_NOMOREFILE or JBC$_NOSUCHFILE conditionvalue signals that no more files remain in the current job context;however, these condition values do not cause the job context to bedissolved.

To set up a nested wildcard search for file information for aparticular entry, you first perform one or more QUI$_DISPLAY_ENTRYoperations in wildcard mode to establish the desired job context. Nextyou call $GETQUI iteratively with the QUI$_DISPLAY_FILE function codeto obtain file information for the selected job.

When you make calls to $GETQUI that specify the QUI$_DISPLAY_ENTRYfunction code, by default $GETQUI locates all jobs that have the sameuser name as the calling process. If you want to obtain informationabout jobs owned by another user, you specify the user name in theQUI$_SEARCH_USERNAME item code.

You can use the QUI$_SEARCH_FREEZE_CONTEXT option of theQUI$_SEARCH_FLAGS item code in any wildcard or nested wildcard call toprevent advancement of context to the next object on the list. Thisallows you to make successive calls for information about the samequeue, job, file, characteristic, or form.

Required Access or Privileges

The caller must have manage (M) access to the queue, read (R) access tothe job, or SYSPRV or OPER privilege to obtain job and file information.

If the caller does not have the privilege required to access a jobspecified in a QUI$_DISPLAY_JOB or QUI$_DISPLAY_FILE operation, $GETQUIreturns a successful condition value. However, it sets theQUI$V_JOB_INACCESSIBLE bit of the QUI$_JOB_STATUS item code and returnsinformation only for the following item codes:

QUI$_AFTER_TIME
QUI$_COMPLETED_BLOCKS
QUI$_ENTRY_NUMBER
QUI$_INTERVENING_BLOCKS
QUI$_INTERVENING_JOBS
QUI$_JOB_SIZE
QUI$_JOB_STATUS

Required Quota

AST limit quota must be sufficient.

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list or input buffer cannot be read by the caller; or the return length buffer, output buffer, or status block cannot be written by the caller.
SS$_BADCONTEXT	Context does not exist or must be called from a more privileged mode.
SS$_BADPARAM	The function code is invalid; the item list contains an invalid item code; a buffer descriptor has an invalid length; or the reserved parameter has a nonzero value.
SS$_DEVOFFLINE	The job controller process is not running.
SS$_EXASTLM	The astadr argument was specified, and the process has exceeded its ASTLM quota.
SS$_ILLEFC	The efn argument specifies an illegal event flag number.
SS$_INSFMEM	The space for completing the request is insufficient.
SS$_MBFULL	The job controller mailbox is full.
SS$_IVLOGNAM	The device name string has a length of 0 or has more than 63 characters.
SS$_MBTOOSML	The mailbox message is too large for the job controller mailbox.
SS$_UNASEFC	The efn argument specifies an unassociated event flag cluster.

Condition Values Returned in the I/O Status Block

JBC$_NORMAL	The service completed successfully.
JBC$_INVFUNCOD	The specified function code is invalid.
JBC$_INVITMCOD	The item list contains an invalid item code.
JBC$_INVPARLEN	The length of a specified string is outside the valid range for that item code.
JBC$_INVQUENAM	The queue name is not syntactically valid.
JBC$_JOBQUEDIS	The request cannot be executed because the system job queue manager has not been started.
JBC$_MISREQPAR	An item code that is required for the specified function code has not been specified.
JBC$_NOJOBCTX	No job context has been established for a QUI$_DISPLAY_FILE operation.
JBC$_NOMORECHAR	No more characteristics are defined, which indicates the termination of a QUI$_DISPLAY_CHARACTERISTIC wildcard operation.
JBC$_NOMOREENT	There are no more job entries for the specified user or current user name, which indicates termination of a QUI$_DISPLAY_ENTRY wildcard operation.
JBC$_NOMOREFILE	No more files are associated with the current job context, which indicates the termination of a QUI$_DISPLAY_FILE wildcard operation for the current job context.
JBC$_NOMOREFORM	No more forms are defined, which indicates the termination of a QUI$_DISPLAY_FORM wildcard operation.
JBC$_NOMOREJOB	No more jobs are associated with the current queue context, which indicates the termination of a QUI$_DISPLAY_JOB wildcard operation for the current queue context.
JBC$_NOMOREQMGR	No more queue managers are defined, which indicates the termination of a QUI$_DISPLAY_MANAGER wildcard operation.
JBC$_NOMOREQUE	No more queues are defined, which indicates the termination of a QUI$_DISPLAY_QUEUE wildcard operation.
JBC$_NOQUECTX	No queue context has been established for a QUI$_DISPLAY_JOB or QUI$_DISPLAY_FILE operation.
JBC$_NOSUCHCHAR	The specified characteristic does not exist.
JBC$_NOSUCHENT	There is no job with the specified entry number, or there is no job for the specified user or current user name.
JBC$_NOSUCHFILE	The specified file does not exist.
JBC$_NOSUCHFORM	The specified form does not exist.
JBC$_NOSUCHJOB	The specified job does not exist.
JBC$_NOSUCHQMGR	The specified queue manager does not exist.
JBC$_NOSUCHQUE	The specified queue does not exist.

Examples

! Declare system service related symbolsINTEGER*4       SYS$GETQUIW,2               LIB$MATCH_COND,2               STATUSINCLUDE         '($QUIDEF)'! Define item list structureSTRUCTURE       /ITMLST/  UNION    MAP      INTEGER*2 BUFLEN, ITMCOD      INTEGER*4 BUFADR, RETADR    END MAP    MAP      INTEGER*4 END_LIST    END MAP  END UNIONEND STRUCTURE! Define I/O status block structureSTRUCTURE       /IOSBLK/INTEGER*4       STS, ZEROEDEND STRUCTURE! Declare $GETQUIW item list and I/O status blockRECORD /ITMLST/ GETQUI_LIST(4)RECORD /IOSBLK/ IOSB! Declare variables used in $GETQUIW item listCHARACTER*31    QUEUE_NAMEINTEGER*2       QUEUE_NAME_LENINTEGER*4       SEARCH_FLAGS,2               ENTRY_NUMBER! Initialize item listGETQUI_LIST(1).BUFLEN = 4GETQUI_LIST(1).ITMCOD = QUI$_SEARCH_FLAGSGETQUI_LIST(1).BUFADR = %LOC(SEARCH_FLAGS)GETQUI_LIST(1).RETADR = 0GETQUI_LIST(2).BUFLEN = 4GETQUI_LIST(2).ITMCOD = QUI$_ENTRY_NUMBERGETQUI_LIST(2).BUFADR = %LOC(ENTRY_NUMBER)GETQUI_LIST(2).RETADR = 0GETQUI_LIST(3).BUFLEN = 31GETQUI_LIST(3).ITMCOD = QUI$_QUEUE_NAMEGETQUI_LIST(3).BUFADR = %LOC(QUEUE_NAME)GETQUI_LIST(3).RETADR = %LOC(QUEUE_NAME_LEN)GETQUI_LIST(4).END_LIST = 0SEARCH_FLAGS = QUI$M_SEARCH_THIS_JOB! Call $GETQUIW service to obtain job informationSTATUS = SYS$GETQUIW (,2               %VAL(QUI$_DISPLAY_JOB),,2               GETQUI_LIST,2               IOSB,,)IF (LIB$MATCH_COND (IOSB.STS, %LOC(JBC$_NOSUCHJOB))) THEN    ! The search_this_job option can be used only by    ! a batch job to obtain information about itself    TYPE *, '<<< this job is not being run in batch mode>>>'ENDIFIF (STATUS) STATUS = IOSB.STSIF (STATUS) THEN    ! Display information    TYPE *, 'Job entry number = ', ENTRY_NUMBER    TYPE *, 'Queue name = ', QUEUE_NAME(1:QUEUE_NAME_LEN)ELSE    ! Signal error condition    CALL LIB$SIGNAL (%VAL(STATUS))ENDIFEND      

This Fortran program demonstrates how a batch job can obtaininformation about itself from the system job queue file by using the$GETQUIW system service. Use of the QUI$M_SEARCH_THIS_JOB option in theQUI$_SEARCH_FLAGS input item requires that the calling program run as abatch job; otherwise, the $GETQUIW service returns a JBC$_NOSUCHJOBerror.

! Declare system service related symbolsINTEGER*4       SYS$GETQUIW,2               STATUS_Q,2               STATUS_J,2               NOACCESSINCLUDE         '($QUIDEF)'! Define item list structureSTRUCTURE       /ITMLST/  UNION    MAP      INTEGER*2 BUFLEN, ITMCOD      INTEGER*4 BUFADR, RETADR    END MAP    MAP      INTEGER*4 END_LIST    END MAP  END UNIONEND STRUCTURE! Define I/O status block structureSTRUCTURE       /IOSBLK/INTEGER*4       STS, ZEROEDEND STRUCTURE! Declare $GETQUIW item lists and I/O status blockRECORD /ITMLST/ QUEUE_LIST(4)RECORD /ITMLST/ JOB_LIST(6)RECORD /IOSBLK/ IOSB! Declare variables used in $GETQUIW item listsCHARACTER*31    SEARCH_NAMECHARACTER*31    QUEUE_NAMECHARACTER*39    JOB_NAMECHARACTER*12    USERNAMEINTEGER*2       SEARCH_NAME_LEN,2               QUEUE_NAME_LEN,2               JOB_NAME_LEN,2               USERNAME_LENINTEGER*4       SEARCH_FLAGS,2               JOB_SIZE,2               JOB_STATUS! Solicit queue name to search; it may be a wildcard nameTYPE 9000ACCEPT 9010, SEARCH_NAME_LEN, SEARCH_NAME! Initialize item list for the display queue operationQUEUE_LIST(1).BUFLEN =  SEARCH_NAME_LENQUEUE_LIST(1).ITMCOD =  QUI$_SEARCH_NAMEQUEUE_LIST(1).BUFADR =  %LOC(SEARCH_NAME)QUEUE_LIST(1).RETADR =  0QUEUE_LIST(2).BUFLEN =  4QUEUE_LIST(2).ITMCOD =  QUI$_SEARCH_FLAGSQUEUE_LIST(2).BUFADR =  %LOC(SEARCH_FLAGS)QUEUE_LIST(2).RETADR =  0QUEUE_LIST(3).BUFLEN =  31QUEUE_LIST(3).ITMCOD =  QUI$_QUEUE_NAMEQUEUE_LIST(3).BUFADR =  %LOC(QUEUE_NAME)QUEUE_LIST(3).RETADR =  %LOC(QUEUE_NAME_LEN)QUEUE_LIST(4).END_LIST = 0! Initialize item list for the display job operationJOB_LIST(1).BUFLEN =    4JOB_LIST(1).ITMCOD =    QUI$_SEARCH_FLAGSJOB_LIST(1).BUFADR =    %LOC(SEARCH_FLAGS)JOB_LIST(1).RETADR =    0JOB_LIST(2).BUFLEN =    4JOB_LIST(2).ITMCOD =    QUI$_JOB_SIZEJOB_LIST(2).BUFADR =    %LOC(JOB_SIZE)JOB_LIST(2).RETADR =    0JOB_LIST(3).BUFLEN =    39JOB_LIST(3).ITMCOD =    QUI$_JOB_NAMEJOB_LIST(3).BUFADR =    %LOC(JOB_NAME)JOB_LIST(3).RETADR =    %LOC(JOB_NAME_LEN)JOB_LIST(4).BUFLEN =    12JOB_LIST(4).ITMCOD =    QUI$_USERNAMEJOB_LIST(4).BUFADR =    %LOC(USERNAME)JOB_LIST(4).RETADR =    %LOC(USERNAME_LEN)JOB_LIST(5).BUFLEN =    4JOB_LIST(5).ITMCOD =    QUI$_JOB_STATUSJOB_LIST(5).BUFADR =    %LOC(JOB_STATUS)JOB_LIST(5).RETADR =    0JOB_LIST(6).END_LIST =  0! Request search of all jobs present in output queues; also force! wildcard mode to maintain the internal search context block after! the first call when a non-wild queue name is entered--this preserves! queue context for the subsequent display job operationSEARCH_FLAGS = (QUI$M_SEARCH_WILDCARD .OR.2               QUI$M_SEARCH_SYMBIONT .OR.2               QUI$M_SEARCH_ALL_JOBS)! Dissolve any internal search context block for the processSTATUS_Q = SYS$GETQUIW (,%VAL(QUI$_CANCEL_OPERATION),,,,,)! Locate next output queue; loop until an error status is returnedDO WHILE (STATUS_Q)   STATUS_Q = SYS$GETQUIW (,2                       %VAL(QUI$_DISPLAY_QUEUE),,2                       QUEUE_LIST,2                       IOSB,,)   IF (STATUS_Q) STATUS_Q = IOSB.STS   IF (STATUS_Q) TYPE 9020, QUEUE_NAME(1:QUEUE_NAME_LEN)   STATUS_J = 1   ! Get information on next job in queue; loop until error return   DO WHILE (STATUS_Q .AND. STATUS_J)       STATUS_J = SYS$GETQUIW (,2                       %VAL(QUI$_DISPLAY_JOB),,2                       JOB_LIST,2                       IOSB,,)       IF (STATUS_J) STATUS_J = IOSB.STS       IF ((STATUS_J) .AND. (JOB_SIZE .GE. 500)) THEN           NOACCESS = (JOB_STATUS .AND. QUI$M_JOB_INACCESSIBLE)           IF (NOACCESS .NE. 0) THEN               TYPE 9030, JOB_SIZE           ELSE               TYPE 9040, JOB_SIZE,2                   USERNAME(1:USERNAME_LEN),2                   JOB_NAME(1:JOB_NAME_LEN)           ENDIF       ENDIFENDDOENDDO9000    FORMAT (' Enter queue name to search: ', $)9010    FORMAT (Q, A31)9020    FORMAT ('0Queue name = ', A)9030    FORMAT ('   Job size = ', I5, '   <no read access privilege>')9040    FORMAT ('   Job size = ', I5,        2       '   Username = ', A, T46,        2       '   Job name = ', A)        END      

This Fortran program demonstrates how any job can obtain informationabout other jobs from the system job queue file by using the $GETQUIWsystem service. This program lists all print jobs in output queues witha job size of 500 blocks or more. It also displays queue name, jobsize, user name, and job name information for each job listed.