|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
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.
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.
LIB$GETQUI function-code [,item-code] [,search-number] [,search-name] [,search-flags] [,resultant-value] [,resultant-string] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$GETSYI item-code [,resultant-value] [,resultant-string] [,resultant-length] [,cluster-system-id] [,node-name]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
| Previous | Next | Contents | Index |