OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

Item Codes

All item codes that can be used with the $GETDVI system service may be used as the item-code argument to LIB$GETDVI. These codes have symbolic names beginning with DVI$_.

The use of a DVI$_ code by itself will return the primary device characteristic associated with that code. To obtain the secondary device characteristics, add 1 to the code. See the description of the $GETDVI system service for a list of the defined item codes. The symbolic names for these items are defined in Digital supplied symbol libraries in module $DVIDEF (where appropriate).

Value Formats

By using the longword-integer-value and resultant-string arguments to LIB$GETDVI, the information requested can be returned in two different fashions.

For each item described as a "string" in the table of Item Codes for the $GETDVI service, the value is returned in resultant-string.
For all other items---those that have numeric values---the numeric representation is returned in longword-integer-value (if specified), and a formatted string interpretation of the value is returned in resultant-string.

Each formatted item is written left-justified; resultant-length, if specified, gives the number of characters used. Table lib-4 lists the formats used for the string interpretations.

Table lib-4 Formats Used for LIB$GETDVI Strings
Item or Format Description

DVI$_ACPPID The string value is returned as an 8-digit hexadecimal number.

DVI$_PID The string value is returned as an 8-digit hexadecimal number.

DVI$_ACPTYPE The ACP type string is one of the following:

NONE No ACP

F11V1 Files-11 Level 1

F11V2 Files-11 Level 2

MTA Magnetic Tape

NET Networks

REM Remote I/O

DVI$_OWNUIC The standard UIC format [group,member] is used. If the format of a UIC includes identifiers from the access rights database in place of the octal group and member numbers, the UIC string returned will have these identifiers, if available.

DVI$_VPROT The volume protection string is in the following form:
SYSTEM=RWLP,OWNER=RWLP,GROUP=RWLP,WORLD=RWLP

If a category has no access, the equal sign is omitted. The string will not contain any embedded spaces.

Boolean The value string returned is TRUE if the low bit of the value is set, or FALSE if the low bit is clear.

All others The value string is returned in the form of an unsigned decimal integer.

Note

This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

Condition Values Returned

SS$_NORMAL Normal successful completion.

LIB$_STRTRU String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.

SS$_BADPARAM Unrecognized item code. The item-code argument was not recognized as valid by $GETDVI.

SS$_IVDEVNAM The device name string contains invalid characters, or neither the channel nor device-name arguments were specified.

LIB$_INSEF Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.

LIB$_INVARG Invalid arguments. The $GETDVI Item Code describes the item as a "string", and no resultant-string argument was specified.

LIB$_INVSTRDES Invalid string descriptor. The descriptor of the resultant-string argument is not a valid descriptor.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETDVI.

Any condition values returned by LIB$SCOPY_xxx, or the $GETDVI system service.

LIB$GETJPI

The Get Job/Process Information routine provides a simplified interface to the $GETJPI system service. It provides accounting, status, and identification information about a specified process.
LIB$GETJPI obtains only one item of information in a single call.

Format

LIB$GETJPI item-code [,process-id] [,process-name] [,resultant-value] [,resultant-string] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

item-code

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Item identifier code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. You may request only one item in each call to LIB$GETJPI.
LIB$GETJPI accepts all $GETJPI item codes. These names begin with JPI$_ and are defined in Digital supplied symbol libraries in module $JPIDEF.
process-id

OpenVMS usage: process_id

type: longword (unsigned)

access: modify

mechanism: by reference

Process identifier of the process for which you are requesting information. The process-id argument is the address of an unsigned longword containing the process identifier. If you do not specify process-id, process-name is used.
The process-id is updated to contain the process identifier actually used, which may be different from what you originally requested if you specified process-name or used wildcard process searching.

process-name

OpenVMS usage: process_name

type: character string

access: read only

mechanism: by descriptor

A 1- to 15-character string specifying the name of the process for which you are requesting information. The process-name argument is the address of a descriptor pointing to the process name string. The name must correspond exactly to the name of the process for which you are requesting information; LIB$GETJPI does not allow trailing blanks or abbreviations.
If you do not specify process-name, process-id is used. If you specify neither process-name nor process-id, the caller's process is used. Also, if you do not specify process-name and you specify zero for process-id, the caller's process is used. In this way, you can fetch the item you want and the caller's PID in a single call to LIB$GETJPI.
resultant-value

OpenVMS usage: varying_arg

type: unspecified

access: write only

mechanism: by reference

Numeric value of the information you request. The resultant-value argument is the address of a longword or quadword into which LIB$GETJPI writes the numeric value of this information. Refer to Table lib-5 for information on which items return longword values and which return quadword values. If the item you request returns only a string value, this argument is ignored.
resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String representation of the information you request. The resultant-string argument is the address of a character string into which LIB$GETJPI writes the string representation. Table lib-5 describes the string representation used for each item.
If you do not include resultant-string, but the item you request has only a string representation, the error status LIB$_INVARG is returned.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Number of significant characters written to resultant-string by LIB$GETJPI. The resultant-length argument is the address of an unsigned word integer into which LIB$GETJPI writes the number of characters.

Description

LIB$GETJPI provides the following features in addition to those provided by the $GETJPI system service:

Instead of a list of item descriptors, which may be difficult to construct in high-level languages, the single item desired is specified as an integer code which is passed by reference. Results are written to separate arguments.
For items which return numeric values, LIB$GETJPI can optionally provide a formatted string interpretation of the value. For example, if the process UIC is requested, LIB$GETJPI can return the UIC formatted as [g,m].
For string arguments, all string classes supported by the Run-Time Library are understood.
Calls to LIB$GETJPI are synchronous. LIB$GETJPI calls LIB$GET_EF to allocate a local event flag number for synchronization.

See the description of the $GETJPI system service in the OpenVMS System Services Reference Manual for more information.
By using the resultant-value and resultant-string arguments to LIB$GETJPI, you can request that the information be returned in two ways. For each item described as a "string" in the table of Item Codes for the $GETJPI service, the value is returned in resultant-string. For all other items---those which have numeric values---the numeric representation is returned in resultant-value (if specified), and a formatted string interpretation of the value is returned in resultant-string.
Each formatted item is written left-justified; resultant-length, if specified, gives the number of characters used.
Table lib-5 lists the formats used for the string interpretations.

Table lib-5 Item Code Formats for LIB$GETJPI
Item or Format Description

JPI$_AUTHPRIV The string representation of these quadword privilege masks is a list of each privilege that is enabled. The privilege names are in uppercase, and are separated by commas.

JPI$_CURPRIV Same as for JPI$AUTHPRIV.

JPI$_IMAGPRIV Same as for JPI$AUTHPRIV.

JPI$_PROCPRIV Same as for JPI$AUTHPRIV.

JPI$_LOGINTIM The string representation of the quadword time is a standard absolute date-time string.

JPI$_PID The process identification string is an 8-digit hexadecimal number.

JPI$_STATE The process state string is one of the following:

CEF Common event flag wait

COM Computable

COMO Computable, outswapped

CUR Current process

COLPG Collided page wait

FPG Free page wait

HIB Hibernate wait

HIBO Hibernate wait, outswapped

LEF Local event flag wait

LEFO Local event flag wait, outswapped

MWAIT Mutex and miscellaneous resource wait

PFW Page fault wait

SUSP Suspended

SUSPO Suspended, outswapped

JPI$_UIC The standard UIC format [group,member] is used. If the format of a UIC includes identifiers from the access rights database in place of the octal group and member numbers, the UIC string returned will have these identifiers, if available.

JPI$_MODE The current mode string is one of the following: BATCH, INTERACTIVE or NETWORK.

All others The string value is returned as an unsigned decimal integer.

Note
This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_STRTRU String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.

SS$_BADPARAM Unrecognized item code. The item-code argument was not recognized as valid by $GETJPI.

LIB$_INSEF Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.

LIB$_INVARG Invalid arguments. The $GETJPI Item Code describes the item as a "string", and no resultant-string argument was specified.

LIB$_INVSTRDES Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETJPI.

Any condition value returned by LIB$SCOPY_xxx, or the $GETJPI system service.

LIB$GETQUI

The Get Queue Information routine provides a simplified interface to the $GETQUI system service. It provides queue, job, file, characteristic, and form information about a specified process.
LIB$GETQUI obtains only one item of information in a single call.

Format

LIB$GETQUI function-code [,item-code] [,search-number] [,search-name] [,search-flags] [,resultant-value] [,resultant-string] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

function-code

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Function code specifying the function that LIB$GETQUI is to perform. The function-code argument is the address of a signed longword containing the function code.
LIB$GETQUI accepts all $GETQUI function codes. These names begin with QUI$_ and are defined in Digital supplied symbol libraries in module $QUIDEF.
item-code

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Item identifier code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. You may request only one item in each call to LIB$GETQUI.
LIB$GETQUI accepts all $GETQUI item codes. These names begin with QUI$_ and are defined in Digital supplied symbol libraries in module $QUIDEF.

search-number

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Numeric value used to process your request. The search-number argument is the address of a signed longword integer containing the number needed to process your request. The search-number argument corresponds directly to QUI$_SEARCH_NUMBER as described by the $GETQUI system service.
search-name

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Character string used to process your request. The search-name argument is the address of a string descriptor that provides the name needed to process your request. The search-name argument corresponds directly to QUI$_SEARCH_NAME as described by the $GETQUI system service.
search-flags

OpenVMS usage: longword_unsigned

type: longword integer (unsigned)

access: read only

mechanism: by reference

Optional bit mask indicating request to be performed. The search-flags argument is the address of an unsigned longword integer containing the bit mask. The search-flags argument directly corresponds to $QUI_SEARCH_FLAGS as described by the $GETQUI system service.
resultant-value

OpenVMS usage: varying_arg

type: unspecified

access: write only

mechanism: by reference

Numeric value of the information you requested. The resultant-value argument is the address of a longword, quadword or octaword into which LIB$GETQUI writes the numeric value of this information. Refer to Table lib-6 for information on which items return values other than longwords.
If the item you requested returns only a string value, this argument is ignored.
resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String representation of the information you requested. The resultant-string argument is the address of a character string into which LIB$GETQUI writes the string representation. Table lib-6 describes the string representation used for each item.
If you do not include resultant-string, but the item you request has only a string representation, the error status LIB$_INVARG is returned.
resultant-length

OpenVMS usage: word_signed

type: word integer (signed)

access: write only

mechanism: by reference

Number of significant characters written to resultant-string by LIB$GETQUI. The resultant-length argument is the address of a signed word integer into which LIB$GETQUI writes the number of characters.

Description

LIB$GETQUI provides a simplified interface to the $GETQUI system service. It provides queue, job, file, characteristic, and form information about a specified process. This routine obtains only one item of information in a single call.
LIB$GETQUI provides the following features in addition to those provided by the $GETQUI system service.

Instead of a list of item descriptors that may be difficult to construct in high-level languages, the single item desired is specified as an integer code which is passed by reference. Results are written to separate arguments.
For items that return numeric values, LIB$GETQUI optionally can provide a formatted string interpretation of the value. For example, if you request the characteristics of a queue, LIB$GETQUI can return the list of characteristics as "23,42,76,98,125".
For string arguments, all string classes supported by the Run-Time Library are understood.
Calls to LIB$GETQUI are synchronous. LIB$GETQUI calls $GETQUIW to force the synchronization.

LIB$GETQUI retains context. This means that previous calls to LIB$GETQUI affect current calls to LIB$GETQUI.
See the description of the $GETQUI system service in the OpenVMS System Services Reference Manual for more information.
By using the resultant-value and resultant-string arguments to LIB$GETQUI, you can request that the information be returned in two ways. For items that have numeric values, the numeric representation is returned in resultant-value (if specified), and a formatted string interpretation of the value is returned in resultant-string. For each item described as a "string" in the table of Item Codes for the $GETQUI service, the value is returned in resultant-string.
Each formatted item is written left-justified; resultant-length, if specified, gives the number of characters used.
The $GETQUI system service requires some item codes. LIB$GETQUI provides those item codes for you by corresponding your input to LIB$GETQUI directly to the required input codes.
The following table describes all of the required and optional input needed to perform your task with LIB$GETQUI:

Function Input Description

QUI$_CANCEL Accepts no input.

QUI$_DISPLAY_CHARACTERISTIC A characteristic name or number, or both. Optionally, a search flags number.

QUI$_DISPLAY_ENTRY Optionally, an entry number, user name, and search flags number. The default user name is that of the calling process.

QUI$_DISPLAY_FILE Optionally, a search flags number.

QUI$_DISPLAY_FORM A form name or number, or both. Optionally, a search flags number.

QUI$_DISPLAY_JOB Optionally, a search flags number.

QUI$_DISPLAY_QUEUE A queue name. Optionally, a search flags number.

QUI$_TRANSLATE_QUEUE A queue name.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

5932PRO_020.HTML

SS$_NORMAL	Normal successful completion.
LIB$_STRTRU	String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.
SS$_BADPARAM	Unrecognized item code. The item-code argument was not recognized as valid by $GETDVI.
SS$_IVDEVNAM	The device name string contains invalid characters, or neither the channel nor device-name arguments were specified.
LIB$_INSEF	Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.
LIB$_INVARG	Invalid arguments. The $GETDVI Item Code describes the item as a "string", and no resultant-string argument was specified.
LIB$_INVSTRDES	Invalid string descriptor. The descriptor of the resultant-string argument is not a valid descriptor.
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETDVI.

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

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

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

OpenVMS usage:	process_name
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	varying_arg
type:	unspecified
access:	write only
mechanism:	by reference

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

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

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.
SS$_BADPARAM	Unrecognized item code. The item-code argument was not recognized as valid by $GETJPI.
LIB$_INSEF	Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.
LIB$_INVARG	Invalid arguments. The $GETJPI Item Code describes the item as a "string", and no resultant-string argument was specified.
LIB$_INVSTRDES	Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETJPI.

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

OpenVMS usage:	word_signed
type:	word integer (signed)
access:	write only
mechanism:	by reference

Function	Input Description
QUI$_CANCEL	Accepts no input.
QUI$_DISPLAY_CHARACTERISTIC	A characteristic name or number, or both. Optionally, a search flags number.
QUI$_DISPLAY_ENTRY	Optionally, an entry number, user name, and search flags number. The default user name is that of the calling process.
QUI$_DISPLAY_FILE	Optionally, a search flags number.
QUI$_DISPLAY_FORM	A form name or number, or both. Optionally, a search flags number.
QUI$_DISPLAY_JOB	Optionally, a search flags number.
QUI$_DISPLAY_QUEUE	A queue name. Optionally, a search flags number.
QUI$_TRANSLATE_QUEUE	A queue name.