 |
OpenVMS RTL Library (LIB$) Manual
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 Compaq 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 symbol libraries in module $JPIDEF supplied by
Compaq.
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 the
descriptor for 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: A--GETUAI
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 symbol libraries in module $QUIDEF supplied by
Compaq.
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 symbol libraries in module $QUIDEF supplied by
Compaq.
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 the
descriptor for 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: A--GETUAI
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.
|
|
