|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
Alpha and I64 Only
Locks the specified image in the process's working set.
LIB$LOCK_IMAGE address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
New example TBS?
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.
LIB$LOOKUP_KEY search-string ,key-table-array [,key-value] [,keyword-string] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
| #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.
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.
LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
LIB$_NORMAL Routine successfully completed. The key was found. LIB$_KEYNOTFOU Error. The key was not found.
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.
The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a balanced binary tree.
LIB$LOOKUP_TREE_64 treehead ,symbol ,user-compare-routine ,new-node
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
LIB$_NORMAL Routine successfully completed. The key was found. LIB$_KEYNOTFOU Error. The key was not found.
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.
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.
LIB$LP_LINES
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.
None.
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
None.
| #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.
| Previous | Next | Contents | Index |