 |
HP OpenVMS RTL Library (LIB$) Manual
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 HP 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
HP.
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 HP.
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 HP 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.
|
Table lib-6 lists the formats used for the string interpretations.
Table lib-6 Item Code Formats for LIB$GETQUI
| Item or Format |
Description |
|
QUI$_AFTER_TIME
|
Returns a quadword
resultant-value as well as a
resultant-string.
|
|
QUI$_CHARACTERISTICS
|
Returns an octaword
resultant-value as well as a comma-separated list that
lists all the characteristic numbers, output as a
resultant-string.
|
|
QUI$_SUBMISSION_TIME
|
Returns a quadword
resultant-value as well as a
resultant-string.
|
|
QUI$_UIC
|
Returns a formatted
resultant-string as well as a longword.
|
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
$GETQUI.
|
|
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 $GETQUI 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$GETQUI.
|
Any condition value returned by LIB$SCOPY_xxx, or the $GETQUI
system service.
LIB$GETSYI
The Get Systemwide Information routine provides a simplified interface
to the $GETSYI system service. The $GETSYI system service obtains
status and identification information about the system. LIB$GETSYI
returns only one item of information in a single call.
Format
LIB$GETSYI item-code [,resultant-value] [,resultant-string]
[,resultant-length] [,cluster-system-id] [,node-name]
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 code specifying the desired item of information. The
item-code argument is the address of a signed longword
containing this item code. All valid $GETSYI item codes are accepted.
resultant-value
| OpenVMS usage: |
varying_arg |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference |
Numeric value returned by LIB$GETSYI. The
resultant-value argument is the address of a longword
or quadword containing this value. If an item is listed as returning
only a string value, this argument is ignored.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Information returned by LIB$GETSYI. The
resultant-string argument is the address of a
descriptor pointing to the character string that will receive this
information.
See the Description section for more information about value formats.
If resultant-string is not specified and if the
returned value 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, not including blank padding or
truncated characters. The resultant-length argument is
the address of an unsigned word into which LIB$GETSYI returns this
number.
cluster-system-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Cluster system identification (CSID) of the node for which information
is to be returned. The cluster-system-id argument is
the address of this CSID. If cluster-system-id is
specified and is nonzero, node-name is not used. If
cluster-system-id is specified as zero, LIB$GETSYI
uses node-name and writes into the
cluster-system-id argument the CSID corresponding to
the node identified by node-name.
The cluster-system-id of an OpenVMS node is assigned
by the cluster-connection software and may be obtained by the DCL
command SHOW CLUSTER. The value of the
cluster-system-id for an OpenVMS node is not
permanent; a new value is assigned to an OpenVMS node whenever it joins
or rejoins the OpenVMS Cluster.
If cluster-system-id is specified as --1, LIB$GETSYI
assumes a wildcard operation and returns the requested information for
each OpenVMS node in the cluster, one node per call.
If cluster-system-id is not specified,
node-name is used.
node-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the node for which information is to be returned. The
node-name argument is the address of a descriptor
pointing to the node name string. If cluster-system-id
is not specified or is specified as zero, node-name is
used. If neither node-name nor
cluster-system-id is specified, the caller's node is
used. See the cluster-system-id argument for more
information.
The node name string must contain from 1 to 15 characters and must
correspond exactly to the OpenVMS node name; no trailing blanks nor
abbreviations are permitted.
Description
LIB$GETSYI provides the following features in addition to those
provided by the $GETSYI 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$GETSYI can optionally
provide a formatted string interpretation of the value.
- For string arguments, all string classes supported by the Run-Time
Library are understood.
- Calls to LIB$GETSYI are synchronous. LIB$GETSYI calls LIB$GET_EF to
allocate a local event flag number for synchronization.
All item codes that can be used with the $GETSYI system service may be
used as the item-code argument to LIB$GETSYI. See the
description of the $GETSYI system service for a list of the defined
item codes. Note that the symbolic names for these items are defined in
symbol libraries in module $SYIDEF (where appropriate) supplied by HP.
Value Formats
By using the resultant-value and
resultant-string arguments to LIB$GETSYI, 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
$GETSYI 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 an unsigned
decimal integer representation is stored in
resultant-string.
Each formatted item is written left-justified;
resultant-length, if specified, gives the number of
characters used.
See the HP OpenVMS System Services Reference Manual: A--GETUAI for a description of the $GETSYI system service.
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.
|
|
SS$_BADPARAM
|
Unrecognized item code. The
item-code argument was not recognized as valid by
$GETSYI.
|
|
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 $GETSYI 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$_STRTRU
|
String truncated. This is an alternate success return status. The
resultant-string argument could not contain all the
characters of the returned item.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments. An incorrect number of arguments was passed
to LIB$GETSYI.
|
|
