|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Fit a Node Name Into an Output Field routine fits a node name into an output field. It attempts to compress the node name to fit the output field. If this fails, it trims the node name.
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$FIT_NODENAME nodename, output-buffer [,output-width][,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
nodename
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Node name to be fitted into the desired output field. The nodename argument contains the address of a descriptor pointing to this node-name string.The error LIB$_INVARG is returned if nodename contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename is an invalid descriptor.
output-buffer
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
The output buffer. The output-buffer argument contains the address of a descriptor pointing to the output buffer. LIB$FIT_NODENAME writes the final output node name into the buffer pointed to by output-buffer.The error LIB$_INVSTRDES is returned if output-buffer is an invalid descriptor.
The length field of the output-buffer descriptor is not updated unless output-buffer is a dynamic descriptor with a length less than the resulting fitted node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.
The output-buffer argument contains an unusable result when LIB$FIT_NODENAME returns in error.
output-width
OpenVMS usage: word_unsigned type: word (unsigned) access: read only mechanism: by reference
Field width desired for the fit operation. The output-width argument is the address of an unsigned word that contains this field width in bytes.If output-width is omitted, the current length of output-buffer is used. If output-buffer is not a fixed-length string, specify output-width to ensure that the desired width is used.
If the lengths of both output-buffer and output-width are specified, the length in output-width is used. In this case, if the current length of output-buffer is smaller than the length of output-width, the output node name is truncated at the end, and the alternate successful status LIB$_STRTRU is returned.
resultant-length
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference
Length of the output node name. The resultant-length argument is the address of an unsigned word that contains this length in bytes.The resultant-length argument contains an unusable result when LIB$FIT_NODENAME returns in error.
This routine fits the input node name into the desired output field for display purposes. It first attempts to get the usable short form of the input node name by calling LIB$COMPRESS_NODENAME. If that fails, the input node name is expanded by LIB$EXPAND_NODENAME and then trimmed by LIB$TRIM_FULLNAME to fit the desired output width.The input is validated against the supported form of input node names. The error LIB$_INVARG is returned if the input node name is invalid.
Node-name compression is always attempted even if the length of the input node name is less than or equal to the desired output width. This is to ensure that the short form of a full name is always chosen for display purposes.
When the compressed node name is too long to fit the desired output width, the input node name is expanded using LIB$EXPAND_NODENAME and trimmed using LIB$TRIM_FULLNAME. In this case, the alternate success status LIB$_STRTRU is returned.
When LIB$FIT_NODENAME encounters errors from the underlying network services, it tries to return the string-truncated compressed node name. If it is the compression operation that fails, LIB$FIT_NODENAME returns the string-truncated input node name. The alternate successful status LIB$_STRTRU is returned.
Note that the returned node name can be either a compressed usable short form of the input node name or an unusable trimmed or truncated node name. The caller should always assume an unusable node name is returned when it finds the alternate success return status LIB$_STRTRU. On the other hand, the SS$_NORMAL return status means that a usable form of a node name is returned.
LIB$FIT_NODENAME adds padding spaces to the end of the output buffer if the output node name is shorter than the size of the output buffer. The argument resultant-length, if supplied, is set to the length of the output node name, excluding any padding spaces.
SS$_NORMAL Routine successfully completed. LIB$_STRTRU Routine successfully completed. Characters are truncated in the output buffer pointed to by output-buffer. LIB$_INVARG Invalid argument:
- nodename is invalid.
- nodename points to a null string.
- The length of the node name is more than 1024 characters.
LIB$_INVSTRDES Invalid string descriptor. LIB$_WRONUMARG Wrong number of arguments.
Any condition value returned by LIB$SCOPY_R_DX.
The Fix Floating Reserved Operand routine finds the reserved operand of any F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) after a reserved operand fault has been signaled.+ LIB$FIXUP_FLT changes the reserved operand from --0.0 to the value of the new-operand argument, if present; or to +0.0 if new-operand is absent.
This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only.
LIB$FIXUP_FLT signal-arguments ,mechanism-arguments [,new-operand]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
signal-arguments
OpenVMS usage: vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument is the address of an array of unsigned longwords containing the signal argument vector.mechanism-arguments
OpenVMS usage: vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument is the address of an array of unsigned longwords containing the mechanism argument vector.new-operand
OpenVMS usage: floating-point type: F_floating access: read only mechanism: by reference
An F-floating value to replace the reserved operand. The new-operand argument is the address of an F-floating number containing the new operand. This is an optional argument. If omitted, the default value is +0.0.
LIB$FIXUP_FLT finds the reserved operand of any F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) after a reserved operand fault has been signaled. LIB$FIXUP_FLT changes the reserved operand from --0.0 to the value of the new-operand argument, if present; or to +0.0 if new-operand is absent. LIB$FIXUP_FLT cannot handle the following cases and will return a status of SS$_RESIGNAL if any of them occur:
- The currently active signaled condition is not SS$_ROPRAND.
- The reserved operand's data type is not F-floating, D-floating, G-floating, or H-floating.
- The reserved operand is an element in the coefficient table for one of the VAX POLYx instructions.
If the status value returned from LIB$FIXUP_FLT is seen by the condition handling facility (as would be the case if LIB$FIXUP_FLT was the handler), any success value is equivalent to SS$_CONTINUE, which causes the instruction to be restarted. Any failure value is equivalent to SS$_RESIGNAL, which causes the condition to be resignaled to the next handler. This resignal status is because the condition handler (LIB$FIXUP_FLT) was unable to handle the condition correctly.
LIB$FIXUP_FLT can be enabled directly as a condition handler. The signal-arguments and mechanism-arguments arguments are passed to the condition handler by OpenVMS exception dispatching.
SS$_NORMAL Routine successfully completed. The reserved operand was found and has been fixed. SS$_ACCVIO Access violation. An argument to LIB$FIXUP_FLT or an operand of the faulting instruction could not be read or written. SS$_RESIGNAL The signaled condition was not SS$_ROPRAND, or the reserved operand was not a floating-point value or was an element in a POLY x table. SS$_ROPRAND Reserved operand fault. The optional argument new-operand was supplied but was itself an F-floating reserved operand. LIB$_BADSTA Bad stack. The stack frame linkage has been corrupted since the time of the reserved operand exception.
+ No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine. |
The Floating-Point Underflow Detection routine enables or disables floating-point underflow detection for the calling routine activation. The previous setting is returned as a function value.
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.
This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only.
LIB$FLT_UNDER new-setting
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
The old floating-point underflow enable setting (the previous contents of the SF$W_PSW[PSW$V_FU] in the caller's frame).
new-setting
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
New floating-point underflow enable setting. The new-setting argument is the address of an unsigned byte containing the new setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable.
LIB$FLT_UNDER affects only the current routine activation and does not affect any of its callers or any routines that it may call. However, the setting does remain in effect for any routines entered through a JSB entry point.The caller's stack frame will be modified by this routine.
None.
C+
C This Fortran example program shows
C the use of LIB$FLT_UNDER.
C-
INTEGER*4 NEW_SETTING
REAL*4 X , Y , Z
NEW_SETTING = 0
X = 1E-20
Y = 1E20
CALL LIB$FLT_UNDER( NEW_SETTING )
TYPE *,'First Case: This should not have an underflow exception'
Z = X / Y
TYPE *, 'If this lines prints then the underflow exception
1 was disabled.'
TYPE *
NEW_SETTING = 1
X = 1E-20
Y = 1E20
CALL LIB$FLT_UNDER( NEW_SETTING )
TYPE * , 'Second Case: This should have an underflow exception
1 and then stop.'
Z = X / Y
TYPE * , 'If this line prints, then the underflow exception
1 was disabled.'
END
|
In this Fortran example, floating-point underflow detection is disabled the first time X is divided by Y. The second time, underflow detection is enabled, and the program stops because of the error generated.
The Format Date and/or Time routine allows the user to select at run time a specific output language and format for a date or time, or both.
LIB$FORMAT_DATE_TIME date-string [,date] [,user-context] [,date-length] [,flags]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
date-string
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Receives the requested date or time, or both, that has been formatted for output according to the currently selected format and language. The date-string argument is the address of a descriptor pointing to this string.date
OpenVMS usage: date_time type: quadword (unsigned) access: read only mechanism: by reference
The date or time, or both, to be formatted for output. The date argument is the address of an unsigned quadword that contains the absolute date or time, or both to be formatted. If you omit this argument, or if you supply a zero passed by value, then the current system time is used. Note that the date argument must represent an absolute time, not a delta time.user-context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
User context that retains the translation context over multiple calls to this routine. The user-context argument is the address of an unsigned longword that contains this context. The initial value of the context variable must be zero. Thereafter, the user program must not write to the cell.The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$FORMAT_DATE_TIME may abort if two threads of execution attempt to manipulate the context area concurrently. Therefore, when calling this routine in situations where reentrancy might occur, such as from AST level, HP recommends that users specify a different context cell for each calling thread.
date-length
OpenVMS usage: longword_signed type: longword (signed) access: write only mechanism: by reference
Number of bytes of text written to the date-string argument. The date-length argument is the address of a signed longword that receives this string length. Note that date-length specifies the number of bytes of text, not the number of characters, written to date-string.flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by reference
Bit mask that allows the user to specify whether the date, time, or both are output. The flags argument is the address of an unsigned bit mask containing the specified values. Valid values are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS.Default values are determined as follows:
- If the flags argument is omitted, LIB$FORMAT_DATE_TIME determines which fields to format according to the current definition of LIB$DT_FORMAT.
- If the flags argument is specified, LIB$FORMAT_DATE_TIME uses the flags value to determine which fields to format. That is, the flags argument can be used to override the definition of LIB$DT_FORMAT when specifying which fields should be formatted for output. If the field specified by flags was not assigned a format through the definition of LIB$DT_FORMAT, the standard OpenVMS format is used.
The LIB$FORMAT_DATE_TIME routine formats an OpenVMS internal format date-time quadword into a textual string of some predefined format. The language to be used and the format in which to output the information are programmable using either of the following methods.
- The language and format are programmable at compile time through the use of the routine LIB$INIT_DATE_TIME_CONTEXT.
- The language and format are determined at run time through the translation of the logical names SYS$LANGUAGE and LIB$DT_FORMAT.
In general, if an application is formatting text for internal storage or transmission, the language and format should be specified at compile time. If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and format of your choice.
If an application is formatting text for presentation to a user, the logical name method of specifying language and format should be used. In this method, the user assigns equivalence names to the logical names SYS$LANGUAGE and LIB$DT_FORMAT, thereby selecting the language and format of the date and time at run time.
If the logical name method is used, the translations of the logical names SYS$LANGUAGE and LIB$DT_FORMAT specify one or more executive mode logicals, which in turn must be translated to determine the actual format string. These additional logicals supply such things as the names of the days of the week and the months in the selected language (determined by SYS$LANGUAGE). All of these logicals are predefined, so that a non-privileged user can select any one of these languages and formats. A user can create his or her own languages and formats; however, the CMEXEC, SYSNAME, and SYSPRV privileges are required.
With the exception of SYS$LANGUAGE and LIB$DT_FORMAT, all logical names used by this routine must be defined from the executive mode.
See the HP OpenVMS Programming Concepts Manual for a description of system date and time operations as well as a detailed description of the format mnemonics used in these routines.
SS$_NORMAL Routine successfully completed. LIB$_ABSTIMREQ Absolute time required. LIB$_DEFFORUSE Default format used; unable to determine the desired format. LIB$_ENGLUSED English used; unable to determine or use the specified language. LIB$_REENTRANCY Reentrant invocation with same context variable. LIB$_STRTRU Output string truncated. LIB$_UNRFORCOD Unrecognized format code.
Any condition values returned by the $NUMTIM system service, or RTL routines LIB$GET_VM, LIB$GET_VM_64, LIB$ANALYZE_SDESC, or LIB$ANALYZE_SDESC_64.
| Previous | Next | Contents | Index |