View source for F$CVSI()

'''F$CVSI''' is a [[Lexical functions|lexical function]] that converts the specified bits in the specified character string to a signed number. It returns the integer equivalent of the extracted bit field, converted as a signed value.

=Syntax=

F$CVSI(start-bit,number-of-bits,string)

==start-bit==

Specifies the offset of the first bit to be extracted. The low-order (rightmost) bit of a string is position number 0 for determining the offset. Specify the offset as an integer expression.

If you specify an expression with a negative value, or with a value that exceeds the number of bits in the string, then DCL displays the INVRANGE error message.

==number-of-bits==

Specifies the length of the bit string to be extracted, which must be less than or equal to the number of bits in the string.

If you specify an expression with a negative value, or with a value that is invalid when added to the bit position offset, then DCL displays the INVRANGE error message.

==string==

Specifies the string from which the bits are taken. Specify the string as a character string expression.

=Examples=

 $ A[0,32] = %X2B
 $ SHOW SYMBOL A
 A = "+..."
 $ X = F$CVSI(0,4,A)
 $ SHOW SYMBOL X
 X = -5   Hex = FFFFFFFB  Octal = 37777777773

This example uses an arithmetic overlay to assign the hexadecimal value 2B to all 32 bits of the symbol A. For more information on arithmetic overlays, see the description of the assignment statement (=).

The symbol A has a string value after the overlay because it was previously undefined. (If a symbol is undefined, it has astring value as a result of an arithmetic overlay. If a symbol was previously defined, it retains the same data type afterthe overlay.) The hexadecimal value 2B corresponds to the ASCII value of the plus sign (+).

Next, the F$CVSI function extracts the low-order 4 bits from the symbol A; the low-order 4 bits contain the binary representation of the hexadecimal value B. These bits are converted, as a signed value, to an integer. The converted value, -5, is assigned to the symbol X.

 $ SYM[0,32] = %X2A
 $ SHOW SYMBOL SYM 
  SYM = "*..."
 $ Y = F$CVSI(0,33,SYM)
  %DCL-W-INVRANGE, field specification is out of bounds - check sign and size
 $ SHOW SYMBOL Y
  %DCL-W-UNDSYM, undefined symbol - check spelling

In this example, the width argument specified with the F$CVSI function is too large. Therefore, DCL issues an error message and the symbol Y is not assigned a value.

[[Category:Lexical Functions]]