|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Get Previous Invocation Handle routine gets the previous invocation handle of any active procedure.A thread can obtain an invocation handle of the procedure context preceding that of a specified procedure context by using the following function format.
LIB$GET_PREV_INVO_HANDLE invo_handle
OpenVMS usage: invo_handle type: longword (unsigned) access: write only mechanism: by value
An invocation handle for the invocation context that is previous to that which was specified as the target.
invo_handle
OpenVMS usage: invo_handle type: longword (unsigned) access: read only mechanism: by value
An invocation handle that represents a target invocation context.
LIB$GET_PREV_INVO_HANDLE gets the previous invocation handle of any active procedure.See the HP OpenVMS Calling Standard manual for more information.
None.
The Get Value of CLI Symbol routine requests the calling process's command language interpreter (CLI) to return the value of a CLI symbol as a string. LIB$GET_SYMBOL then returns the string to the caller. Optionally, LIB$GET_SYMBOL can return the length of the returned value and the table in which the symbol was found.
LIB$GET_SYMBOL symbol ,resultant-string [,resultant-length] [,table-type-indicator]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
symbol
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Name of the symbol for which LIB$GET_SYMBOL searches. The symbol argument is the address of a descriptor pointing to the name of the symbol. LIB$GET_SYMBOL converts the symbol name to uppercase and removes trailing blanks before the search. The symbol argument must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters.resultant-string
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Value of the returned symbol. The resultant-string argument is the address of a descriptor pointing to a character string into which LIB$GET_SYMBOL writes the value of the symbol.resultant-length
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference
Length of the symbol value returned by LIB$GET_SYMBOL. The resultant-length argument is the address of an unsigned word integer into which LIB$GET_SYMBOL writes the length.table-type-indicator
OpenVMS usage: longword_signed type: longword integer (signed) access: write only mechanism: by reference
Indicator of which table contained the symbol. The table-type-indicator argument is the address of a signed longword integer into which LIB$GET_SYMBOL writes the table indicator.Possible values of the table indicator are listed below.
Symbolic Name Value Table LIB$K_CLI_LOCAL_SYM 1 Local symbol table LIB$K_CLI_GLOBAL_SYM 2 Global symbol table LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in symbol libraries supplied by HP (macro or module name $LIBCLIDEF) and as global symbols.
LIB$GET_SYMBOL first searches the local symbol table for the symbol name, then searches the global symbol table. Numeric values are converted to an ASCII representation of a signed decimal number before being returned.LIB$GET_SYMBOL is supported for use with the DCL command language interpreter. If used with the MCR CLI, the error status LIB$_NOCLI will be returned.
If an image is run directly as a subprocess or as a detached process, there is no CLI present to get the symbol. In that case, LIB$GET_SYMBOL returns the error status LIB$_NOCLI.
SS$_NORMAL Routine successfully completed. LIB$_STRTRU Routine successfully completed; string truncated. The destination string could not contain all the characters in the symbol value. LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your HP support representative. LIB$_INSCLIMEM Insufficient CLI memory. The CLI could not obtain enough virtual memory to perform the function. This may be caused by having too many symbols defined. Deleting some symbol definitions may relieve the situation. LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory. LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field. LIB$_INVSYMNAM Invalid symbol name. The symbol name contained more than 255 characters or did not begin with a letter or dollar sign ($). LIB$_NOCLI No CLI present. The calling process did not have a CLI to perform the function or the CLI did not support the request type. Note that an image run as a subprocess or detached process does not have a CLI. LIB$_NOSUCHSYM No such symbol. The symbol was not defined in either the local or global symbol table. LIB$_UNECLIERR Unexpected CLI error. The CLI returned an error status which was not recognized. This error may be caused by use of a nonstandard CLI. If this error occurs while using the DCL command language interpreter, please report the problem to your HP support representative.
Returns information from the unwind information block (UIB).
LIB$GET_UIB_INFO uib_va [,gp_value] [,uw_desc_va] [,uw_desc_len] [,handler_fv] [,ossd_va] [,lsda_va]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
uib_va
OpenVMS usage: address type: quadword (unsigned) access: read only mechanism: by reference
Address of a quadword that contains the virtual address of an unwind information block (UIB).gp_value
OpenVMS usage: address type: quadword (unsigned) access: read only mechanism: by reference
Address of a quadword that contains the GP value that must be added to the UIB condition handler value. Must be specified if handler_fv is specified.uw_desc_va
OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference
Address of a quadword to store the virtual address of the unwind descriptor area. If none is present, then zero is returned. This is an optional argument.un_desc_len
OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference
Address of a quadword to store the length (in bytes) of the unwind descriptor area. If none are present, then zero is returned. This is an optional argument.handler_fv
OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference
Address of a quadword to store the function value of the condition handler. If none is present, then zero is returned. This is an optional argument.ossd_va
OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference
Address of a quadword to store the address of the operating system-specific data area. If none is present, then zero is returned. This is an optional argument.lsda_va
OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference
Address of a quadword to store the address of the language-specific data area (LSDA). If none is present, then zero is returned. This is an optional argument.
Takes in the address of an uwind information block (UIB) and the GP value for a routine and returns the addresses of the start of the unwind descriptors (if any), the handler function descriptor (if any), and the operating system-specific data area (if any). The size in bytes of the unwind descriptors is also returned.SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE, SYS$GET_UNWIND_ENTRY_INFO,
SS$_NORMAL Routine completed successfully. LIB$_INVARG Bad UIB virtual address.
The Return the User's Language routine determines the user's choice of a natural language. The choice is determined by translating the logical SYS$LANGUAGE.
LIB$GET_USERS_LANGUAGE language
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
language
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Receives the translation of SYS$LANGUAGE. The language argument is the address of a descriptor pointing to this language name.
The LIB$GET_USERS_LANGUAGE routine translates the logical SYS$LANGUAGE and returns the user's choice of a natural language. If the logical SYS$LANGUAGE does not translate for some reason, then the language defaults to English and the status LIB$_ENGLUSED is returned.If a failure or truncation occurs while copying the language name to the language string argument, that error status overrides the LIB$_ENGLUSED or SS$_NORMAL status.
SS$_NORMAL Routine successfully completed. LIB$_ENGLUSED English used by default; unable to translate SYS$LANGUAGE.
Any condition value returned by LIB$SCOPY_R_DX.
The Allocate Virtual Memory routine allocates a specified number of contiguous bytes in the program region and returns the 32-bit virtual address of the first byte allocated.
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$GET_VM number-of-bytes, base-address [,zone-id]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
number-of-bytes
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Number of contiguous bytes that LIB$GET_VM allocates. The number-of-bytes argument is the address of a longword integer containing the number of bytes. LIB$GET_VM allocates enough memory to satisfy the request. Your program should not reference an address before the first byte address allocated (base-address) or beyond the last byte allocated (base-address + number-of-bytes - 1) since that space may be assigned to another routine. The value of number-of-bytes must be greater than zero.base-address
OpenVMS usage: address type: longword (unsigned) access: write only mechanism: by reference
First virtual address of the contiguous block of bytes allocated by LIB$GET_VM. The base-address argument is the address of an unsigned longword containing this base address.zone-id
OpenVMS usage: identifier type: longword (unsigned) access: read only mechanism: by reference
The zone-id argument is the address of a longword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE. This argument is optional. If zone-id is omitted or if the longword contains the value 0, the 32-bit default zone is used.
LIB$GET_VM satisfies an allocation request by reusing free memory in the zone, or by obtaining additional memory from the processwide 32-bit page pool managed by LIB$GET_VM_PAGE.LIB$GET_VM rounds up the value of number-of-bytes to a multiple of the block-size specified for the zone. The first byte allocated is aligned on the boundary specified by the alignment value for the zone.
If you specified allocation filling when you created the zone, LIB$GET_VM will fill each byte allocated. Otherwise, LIB$GET_VM does not initialize the memory and its contents are unpredictable.
All memory allocated by LIB$GET_VM has user mode read/write access, even if the call to LIB$GET_VM was made from a more privileged access mode.
The space allocated by successive calls to LIB$GET_VM may be noncontiguous because another routine can call LIB$GET_VM between your calls. If AST interrupts occur, LIB$GET_VM may allocate space to another routine between execution of any two statements in your program. Even if successive calls to LIB$GET_VM return two contiguous blocks, you must not combine them into one large block that is freed by a single call to LIB$FREE_VM.
LIB$GET_VM is fully reentrant, so it may be called by routines executing at AST level or in an Ada multitasking environment.
Your program must retain the address of the allocated area. This allows you to access or deallocate the space later.
If the zone you are getting was created using the LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate action routine for the get operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must have specified a user-get-routine.
SS$_NORMAL Routine successfully completed. LIB$_BADBLOADR Invalid zone-id or a corrupt zone. LIB$_BADBLOSIZ Bad block size. The value of number-of-bytes was less than or equal to 0. For the fixed-size blocks algorithm, LIB$_BADBLOSIZ can also be generated if the value of algorithm-argument specified in the call to LIB$CREATE_VM_ZONE is less than number-of-bytes. LIB$_INSVIRMEM Insufficient virtual memory. The request required more dynamic memory than was available from the operating system. No partial allocation is made in this case. LIB$_PAGLIMEXC Allocation exceeds the page-limit, set when the zone was create.
The Allocate Virtual Memory routine allocates a specified number of contiguous bytes in the program region and returns the 64-bit virtual address of the first byte allocated.
LIB$GET_VM_64 number-of-bytes, base-address [,zone-id]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
number-of-bytes
OpenVMS usage: quadword_signed type: quadword integer (signed) access: read only mechanism: by reference
Number of contiguous bytes that LIB$GET_VM_64 allocates. The number-of-bytes argument is the address of a quadword integer containing the number of bytes. LIB$GET_VM_64 allocates enough memory to satisfy the request. Your program should not reference an address before the first byte address allocated (base-address) or beyond the last byte allocated (base-address + number-of-bytes - 1) since that space may be assigned to another routine. The value of number-of-bytes must be greater than zero.base-address
OpenVMS usage: address type: quadword (unsigned) access: write only mechanism: by reference
First virtual address of the contiguous block of bytes allocated by LIB$GET_VM_64. The base-address argument is the address of an unsigned quadword containing this base address.zone-id
OpenVMS usage: identifier type: quadword (unsigned) access: read only mechanism: by reference
The zone-id argument is the address of a quadword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64. This argument is optional. If zone-id is omitted or if the quadword contains the value 0, the 64-bit default zone is used.
LIB$GET_VM_64 satisfies an allocation request by reusing free memory in the zone, or by obtaining additional memory from the processwide 64-bit page pool managed by LIB$GET_VM_PAGE_64.LIB$GET_VM_64 rounds up the value of number-of-bytes to a multiple of the block-size specified for the zone. The first byte allocated is aligned on the boundary specified by the alignment value for the zone.
If you specified allocation filling when you created the zone, LIB$GET_VM_64 will fill each byte allocated. Otherwise, LIB$GET_VM_64 does not initialize the memory and its contents are unpredictable.
All memory allocated by LIB$GET_VM_64 has user mode read/write access, even if the call to LIB$GET_VM_64 was made from a more privileged access mode.
The space allocated by successive calls to LIB$GET_VM_64 may be noncontiguous because another routine can call LIB$GET_VM_64 between your calls. If AST interrupts occur, LIB$GET_VM_64 may allocate space to another routine between execution of any two statements in your program. Even if successive calls to LIB$GET_VM_64 return two contiguous blocks, you must not combine them into one large block that is freed by a single call to LIB$FREE_VM_64.
LIB$GET_VM_64 is fully reentrant, so it may be called by routines executing at AST level or in an Ada multitasking environment.
Your program must retain the address of the allocated area. This allows you to access or deallocate the space later.
If the zone you are getting was created using the LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate action routine for the get operation. That is, in your call to LIB$CREATE_USER_VM_ZONE_64, you must have specified a user-get-routine.
SS$_NORMAL Routine successfully completed. LIB$_BADBLOADR Invalid zone-id or a corrupt zone. LIB$_BADBLOSIZ Bad block size. The value of number-of-bytes was less than or equal to 0. For the fixed-size blocks algorithm, LIB$_BADBLOSIZ can also be generated if the value of algorithm-argument specified in the call to LIB$CREATE_VM_ZONE_64 is less than number-of-bytes. LIB$_INSVIRMEM Insufficient virtual memory. The request required more dynamic memory than was available from the operating system. No partial allocation is made in this case. LIB$_PAGLIMEXC Allocation exceeds the page-limit, set when the zone was create.
| Previous | Next | Contents | Index |