 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$LOCK_IMAGE
Alpha and I64 Only
Locks the specified image in the process's working set.
Format
LIB$LOCK_IMAGE address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
address
| OpenVMS usage: |
address |
| type: |
quadword |
| access: |
read only |
| mechanism: |
by value |
Address of a byte within the image to be locked in the working set. If
the address argument is 0, the current image (which contains the call
to LIB$LOCK_IMAGE) is locked in the working set.
Description
LIB$LOCK_IMAGE locks the specified image in the process's working set.
This routine is typically used by a privileged user before the program,
executing in kernel mode, raises IPL above IPL 2. Above IPL 2, paging
is not allowed by the system. The program must access only pages valid
in the process's working set.
Condition Values Returned
|
SS$_WASSET
|
The specified image is locked in the working set and had previously
been locked in the working set.
|
|
SS$_WASCLR
|
The specified image is locked in the working set and had previously not
been locked in the working set.
|
Other status codes returned by sys$lkwset_64.
Examples
New example TBS?
LIB$LOOKUP_KEY
The Look Up Keyword in Table routine scans a table of keywords to find
one that matches the keyword or keyword abbreviation specified by
search-string.
Format
LIB$LOOKUP_KEY search-string ,key-table-array [,key-value]
[,keyword-string] [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
search-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String for which LIB$LOOKUP_KEY will search in the keyword table. The
search-string argument is the address of a descriptor
pointing to this string.
key-table-array
| OpenVMS usage: |
unspecified |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference, array reference |
Keyword table. The key-table-array argument contains
the address of an array that is this keyword table.
key-value
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Associated value of the keyword found by LIB$LOOKUP_KEY. The
key-value argument contains the address of an unsigned
longword into which LIB$LOOKUP_KEY writes the associated value of the
matched keyword.
keyword-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Full keyword string matched. The keyword-string
argument contains the address of a character-string descriptor.
LIB$LOOKUP_KEY writes the complete text of the matched keyword into the
character string.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters copied into the character-string pointed to by
keyword-string, not counting padding in the case of a
fixed-length string. The resultant-length argument is
the address of an unsigned word integer that contains the number of
characters in the matched keyword that were copied into the
character-string.
Description
LIB$LOOKUP_KEY is intended to help programmers to write utilities that
have command qualifiers with values.
LIB$LOOKUP_KEY locates a matching keyword or keyword abbreviation by
comparing the first n characters of each keyword in the keyword table
with the supplied string, where n is the length of the
supplied string.
When a keyword match is found, the following information is optionally
returned to the caller:
- The longword value associated with the matched keyword
- The full keyword string (any descriptor type)
An exact match is found if the length of the keyword found is equal to
the length of the supplied string.
If an exact keyword match is found, no further processing is performed,
and a normal return status is returned to the caller. Otherwise, after
a match has been found, the rest of the keyword table is scanned. If an
additional match is found, a "not enough characters" return
status is returned to the caller. If the keyword table contains a
keyword that is an abbreviation of another keyword in the table, an
exact match can occur for short abbreviations.
Figure lib-5 shows the structure of the keyword table, which the
calling program creates for this routine.
Figure lib-5 Keyword Table
Vector-count is the number of longwords that follow,
and counted-ASCII-string starts with a byte that is
the unsigned count of the number of ASCII characters that follow.
Because of the format of the keyword table, this routine cannot be
called easily from high-level languages. The examples that follow show
how to use a macro, $LIB_KEY_TABLE, to construct a keyword table from
MACRO or BLISS. A separate example shows how a table could be
constructed in Fortran.
Use of the $LIB_KEY_TABLE macro results in data that is not
position-independent code (PIC). If your application requires PIC data,
you must fill in the address of the keyword strings at execution time.
See the Fortran example (example 3) for a demonstration of this
technique.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. A unique keyword match was found.
|
|
LIB$_AMBKEY
|
Multiple keyword match found. Not enough characters were specified to
allow a unique match.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory to return keyword string. This is only
possible if
keyword-string is a dynamic string.
|
|
LIB$_INVARG
|
Invalid arguments, not enough arguments, and/or bad keyword table.
|
|
LIB$_STRTRU
|
String truncated.
|
|
LIB$_UNRKEY
|
The keyword you specified does not appear in the keyword table you
specified.
|
Examples
| #1 |
KEYTABLE:
$LIB_KEY_TABLE < -
<ADD, 1>, -
<DELETE, 2>, -
<EXIT, 3>>
|
This VAX MACRO fragment defines a keyword table named KEYTABLE
containing the three keywords ADD, DELETE, and EXIT with associated
keyword values of 1, 2, and 3, respectively.
The $LIB_KEY_TABLE macro is supplied in the default macro library
SYS$LIBRARY:STARLET.MLB. Because this library is automatically searched
by the assembler, you do not have to specify it in the DCL command
MACRO.
| #2 |
LIBRARY 'SYS$LIBRARY:STARLET.L32';
OWN
KEYTABLE: $LIB_KEY_TABLE (
(ADD, 1),
(DELETE, 2),
(EXIT, 3));
|
This BLISS code fragment specifies that SYS$LIBRARY:STARLET.L32 is to
be searched to resolve references. It defines a keyword table named
KEYTABLE containing the three keywords ADD, DELETE, and EXIT with
associated keyword values of 1, 2, and 3, respectively.
The $LIB_KEY_TABLE macro is supplied in the BLISS library
SYS$LIBRARY:STARLET.L32 and in the BLISS require file
SYS$LIBRARY:STARLET.REQ. BLISS does not automatically search either of
these files, so you must explicitly cause them to be searched by
including the appropriate LIBRARY or REQUIRE statement in your module.
You should use the precompiled library because it is more efficient for
the compiler.
| #3 |
PARAMETER (
1 MAXKEYSIZE = 6, ! Maximum keyword size
2 NKEYS = 3) ! Number of keywords
BYTE KEYWORDS (MAXKEYSIZE+1, NKEYS)
INTEGER*4 KEYTABLE (0:NKEYS*2)
DATA KEYWORDS /
1 3,'A','D','D',' ',' ',' ', ! Counted ASCII 'ADD'
2 6,'D','E','L','E','T','E', ! Counted ASCII 'DELETE'
3 4,'E','X','I','T',' ',' '/ ! Counted ASCII 'EXIT'
KEYTABLE(0) = NKEYS*2 ! Number of longwords to follow
KEYTABLE(1) = %LOC(KEYWORDS(1,1)) ! Address of keyword string
KEYTABLE(2) = 1 ! Keyword value for 'ADD'
KEYTABLE(3) = %LOC(KEYWORDS(1,2)) ! Address of keyword string
KEYTABLE(4) = 2 ! Keyword value for 'DELETE'
KEYTABLE(5) = %LOC(KEYWORDS(1,3)) ! Address of keyword string
KEYTABLE(6) = 3 ! Keyword value for 'EXIT'
|
This Fortran code fragment constructs a keyword table named KEYTABLE
containing the three keywords ADD, DELETE, and EXIT with associated
keyword values of 1, 2, and 3, respectively. This construction method
results in position-independent coded data, although the generated code
for the typical Fortran module contains other non-PIC values.
LIB$LOOKUP_TREE
The Look Up an Entry in a Balanced Binary Tree routine looks up an
entry in a balanced binary tree.
Note
No support for arguments passed by 64-bit address reference or for use
of 64-bit descriptors, if applicable, is planned for this routine.
|
Format
LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
treehead
| OpenVMS usage: |
address |
| type: |
address |
| access: |
read only |
| mechanism: |
by reference |
Tree head for the binary tree. The treehead argument
is the address of an unsigned longword that is this tree head.
symbol
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
unspecified |
| mechanism: |
unspecified |
Key to be looked up in the binary tree.
user-compare-routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied compare routine that LIB$LOOKUP_TREE calls to compare a
symbol with a node. The value returned by the compare routine indicates
the relationship between the symbol key and the current node.
For more information on the compare routine, see Call Format for a Compare Routine in the
Description section.
new-node
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Location where the new symbol was found. The new-node
argument is the address of an unsigned longword that is the new node
location.
Description
Call Format for a Compare Routine
The call format of a compare routine is as follows:
user-compare-routine symbol ,comparison-node [,user-data]
|
LIB$LOOKUP_TREE passes both the symbol and
comparison-node arguments to the compare routine,
using the same passing mechanism that was used to pass them to
LIB$LOOKUP_TREE. The user-data argument is passed in
the same way, but its use is optional.
The user-compare-routine argument in the call to
LIB$LOOKUP_TREE specifies the compare routine. This argument is
required. LIB$LOOKUP_TREE calls the compare routine for every node
except the first node in the tree.
The value returned by the compare routine is the result of comparing
the symbol key with the current node. The table below lists the
possible values returned by the compare routine:
| Return Value |
Meaning |
|
Negative
|
The
symbol argument is less than the current node.
|
|
Zero
|
The
symbol argument is equal to the current node.
|
|
Positive
|
The
symbol argument is greater than the current node.
|
For an example of a user-supplied compare routine written in C, see the
description of LIB$INSERT_TREE.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed. The key was found.
|
|
LIB$_KEYNOTFOU
|
Error. The key was not found.
|
Example
The C example provided in the description of LIB$INSERT_TREE also
demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for
assistance in using this routine.
LIB$LOOKUP_TREE_64 (Alpha and I64 Only)
The Look Up an Entry in a Balanced Binary Tree routine looks up an
entry in a balanced binary tree.
Format
LIB$LOOKUP_TREE_64 treehead ,symbol ,user-compare-routine ,new-node
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
treehead
| OpenVMS usage: |
address |
| type: |
address |
| access: |
read only |
| mechanism: |
by reference |
Tree head for the binary tree. The treehead argument
is the address of an unsigned quadword that is this tree head.
symbol
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
unspecified |
| mechanism: |
unspecified |
Key to be looked up in the binary tree.
user-compare-routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied compare routine that LIB$LOOKUP_TREE_64 calls to compare
a symbol with a node. The value returned by the compare routine
indicates the relationship between the symbol key and the current node.
For more information on the compare routine, see Call Format for a Compare Routine in the
Description section.
new-node
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Location where the new symbol was found. The new-node
argument is the address of an unsigned quadword that is the new node
location.
Description
Call Format for a Compare Routine
The call format of a compare routine is as follows:
user-compare-routine symbol ,comparison-node [,user-data]
|
LIB$LOOKUP_TREE_64 passes both the symbol and
comparison-node arguments to the compare routine,
using the same passing mechanism that was used to pass them to
LIB$LOOKUP_TREE_64. The user-data argument is passed
in the same way, but its use is optional.
The user-compare-routine argument in the call to
LIB$LOOKUP_TREE_64 specifies the compare routine. This argument is
required. LIB$LOOKUP_TREE_64 calls the compare routine for every node
except the first node in the tree.
The value returned by the compare routine is the result of comparing
the symbol key with the current node. The following table lists the
possible values returned by the compare routine:
| Return Value |
Meaning |
|
Negative
|
The
symbol argument is less than the current node.
|
|
Zero
|
The
symbol argument is equal to the current node.
|
|
Positive
|
The
symbol argument is greater than the current node.
|
For an example of a user-supplied compare routine written in C, see the
description of LIB$INSERT_TREE_64.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed. The key was found.
|
|
LIB$_KEYNOTFOU
|
Error. The key was not found.
|
Example
The C example provided in the description of LIB$INSERT_TREE also
demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for
assistance in using this routine.
LIB$LP_LINES
The Lines on Each Printer Page routine computes the default number of
lines on a printer page. This routine can be used by native-mode
OpenVMS utilities that produce listing files and paginate files.
Format
LIB$LP_LINES
RETURNS
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by value |
The default number of lines on a physical printer page. If the logical
name translation or conversion to binary fails, a default value of 66
is returned.
Arguments
None.
Description
LIB$LP_LINES computes the default number of lines on a printer page.
This routine can be used by native-mode OpenVMS utilities that produce
listing files and paginate files. The algorithm used by LIB$LP_LINES is:
- Translate the logical name SYS$LP_LINES.
- Convert the ASCII value obtained to a binary integer.
- Verify that the resulting value is in the range [30:255].
- If any of the prior steps fail, return the default paper size of 66
lines.
You can use LIB$LP_LINES to monitor the current default length of the
line printer page. You can also supply your own default length for the
current process. United States standard paper stock permits 66 lines on
each physical page.
If you are writing programs for a utility that formats a listing file
to be printed on a line printer, you can use LIB$LP_LINES to make your
utility independent of the default page length. Your program can use
LIB$LP_LINES to obtain the current length of the page. It can then
calculate the number of lines of text on each page by subtracting the
lines used for margins and headings.
The following is one suggested format:
- Three lines for the top margin
- Three lines for the bottom margin
- Three lines for listing heading information, consisting of:
- A language-processor identification line
- A source-program identification line
- One blank line
Condition Values Returned
None.
Examples
| #1 |
lplines = LIB$LP_LINES()
PRINT 10, lplines
10 Format (' Line printer page = ',I5,' lines.')
end
|
This Fortran program displays the current default length of the line
printer page.
| #2 |
100 EXTERNAL INTEGER FUNCTION LIB$LP_LINES
200 DECLARE INTEGER LPLINES
300 LPLINES = LIB$LP_LINES
400 PRINT "Line printer page = "; LPLINES
32767 END
|
This BASIC program displays the current default length of the line
printer page.
| #3 |
PROGRAM LINES(OUTPUT);
FUNCTION LIB$LP_LINES : INTEGER;
EXTERN;
BEGIN
WRITELN('Line printer page = ',LIB$LP_LINES,' lines.');
END.
|
This Pascal program displays the current default length of the line
printer page.
|
