Skip to main content

$SCONVERT (ObjectScript)

Converts a binary encoded value to a number.

Synopsis

$SCONVERT(s,format,endian,position)
$SC(s,format,endian,position)

Arguments

Argument Description
s A string of 8-bit bytes which encode for a number. Limitations on valid values are imposed by the format selected.
format One of the following format codes, specified as a quoted string: S1, S2, S4, S8, U1, U2, U4, F4, or F8.
endian Optional — A boolean value, where 0 = little-endian and 1 = big-endian. The default is 0.
position Optional — The character position in the string of 8-bit bytes at which to begin conversion. Character positions are counted from 1. The default value is 1. If you specify position, you must either specify endian or a placeholder comma.

Description

$SCONVERT converts s from an encoded string of 8-bit bytes to a numeric value, using the specified format.

The following are the supported format codes:

Code Description
S1 Signed integer encoded into a string of one 8-bit bytes. The value must be in the range -128 through 127, inclusive.
S2 Signed integer encoded into a string of two 8-bit bytes. The value must be in the range -32768 through 32767, inclusive.
S4 Signed integer encoded into a string of four 8-bit bytes. The value must be in the range -2147483648 through 2147483647, inclusive.
S8 Signed integer encoded into a string of eight 8-bit bytes. The value must be in the range -9223372036854775808 through 9223372036854775807, inclusive.
U1 Unsigned integer encoded into a string of one 8-bit bytes. The maximum value is 256.
U2 Unsigned integer encoded into a string of two 8-bit bytes. The maximum value is 65535.
U4 Unsigned integer encoded into a string of four 8-bit bytes. The maximum value is 4294967295.
F4 IEEE floating point number encoded into a string of four 8-bit bytes.
F8 IEEE floating point number encoded into a string of eight 8-bit bytes.

String s must contain sufficient characters starting at and following the specified character position to satisfy the number of 8-bit bytes required by the format code. For example, $SCONVERT(s,"S4",0,9) requires that the length of s be at least 12 characters because the decoded result comes from the character positions 9, 10, 11 and 12. Values beyond this range result in a <VALUE OUT OF RANGE> error.

$SCONVERT is intended only for use on 8-bit byte strings.

If argument s is a numeric value, it is converted to a string containing its canonical numeric form before it is decoded.

You can use the IsBigEndian()Opens in a new tab class method to determine which bit ordering is used on your operating system platform: 1=big-endian bit order; 0=little-endian bit order.

  WRITE $SYSTEM.Version.IsBigEndian()

$SCONVERT provides the inverse of the $NCONVERT operation.

Examples

In the following example, $SCONVERT converts a two-byte binary encoded value to a number:

  SET x=$NCONVERT(258,"U2")
  ZZDUMP x 
  SET y=$SCONVERT(x,"U2")
  WRITE !,y

The following example, $SCONVERT converts a two-byte binary encoded value in big-endian order to a number:

  SET x=$NCONVERT(258,"U2",1)
  ZZDUMP x 
  SET y=$SCONVERT(x,"U2",1)
  WRITE !,y

See Also

FeedbackOpens in a new tab