Conversion Functions

• Asc
• Base64DecodeText
• Base64EncodeBinary
• Base64EncodeFile
• Base64EncodeText
• CBool
• CByte
• CCur
• CDate
• CDbl
• Chr
• ChrW
• CInt
• CLng
• CSng
• CStr
• Hex
• IsNumeric
• Oct

Asc

Returns the number code of a character.

Syntax

Asc( string )

Arguments

• string
  • The character to return the number code for. If the string holds more than one character, the function returns the code of the first and ignores the rest.

Example

Asc("A")   ' Returns 65

Base64DecodeText

Decodes text encoded in Base64.

Webservice integrations often use it to decode a Base64 value that a service returns.

Syntax

Base64DecodeText( value )

Arguments

• value
  • The Base64 encoded value.

Example

' IMan-specific. The inverse of Base64EncodeText; UTF-8
' throughout. An empty input returns an empty string
' rather than erroring.
Base64DecodeText("QUNNRTAwMQ==")   ' Returns "ACME001"

Base64EncodeBinary

Base64 encodes a binary value, such as an image (png, jpg, gif) or a document (pdf).

Webservice integrations often use it when a service requires a Base64 value in the data you post.

Use it with the WebserviceGetBinary Function to encode that function's result in a usable form.

Syntax

Base64EncodeBinary( value )

Arguments

• value
  • The binary value.

Example

' IMan-specific. Takes a binary field's value, not text
' -- anything else raises a conversion error. Use it to
' put an attachment that is already in the dataset into
' a JSON or XML webservice payload.
Base64EncodeBinary(%DocumentImage)

Base64EncodeFile

Base64 encodes the contents of a file.

Webservice integrations often use it when a service requires a Base64 value in the data you post.

You can use it to upload images to a webservice that requires them Base64 encoded, such as the Shopify Product Image upload.

Syntax

Base64EncodeFile( [filesystem], file, [throwonerror] )

Arguments

• filesystem

  • Optional. The Id of a File System setup. The function resolves the path against that setup rather than the IMan server's own disk. See Naming a file system.

• file

  • The path to the file.

• throwonerror

  • Optional. When False, the function returns an empty string in place of raising an error if it cannot open or read the file. Once you name a file system, this argument is no longer optional. The function uses the number of arguments to decide which form you mean, so a read through a file system must pass all three.

Example

' IMan-specific. Reads a file and returns its Base64
' encoding. The second argument is throwOnError: leave
' it False and an unreadable file yields an empty
' string, so the integration continues.
Base64EncodeFile("C:\IMan\Outbound\SO-10432.pdf", False)

' A File System setup can be named FIRST, in which case
' the path is resolved through it -- Azure Blob, OneDrive
' or S3 -- rather than against the IMan server's own
' filesystem. The container comes from the setup, and
' throwOnError has to be given.
Base64EncodeFile("AZUREBLOB", "outbound/SO-10432.pdf", True)

Base64EncodeText

Base64 encodes a textual value.

Webservice integrations often use it when a service requires a Base64 value in the data you post.

Syntax

Base64EncodeText( value )

Arguments

• value
  • The textual value.

Example

' IMan-specific. UTF-8 in, Base64 out.
Base64EncodeText(%CustomerCode)   ' "ACME001" returns "QUNNRTAwMQ=="

CBool

Converts a value to a Boolean.

Syntax

CBool( expression )

Arguments

• expression
  • Any valid expression. If expression is zero, CBool returns False; otherwise it returns True. If expression cannot be interpreted as a number, a run-time error occurs.

Example

' Zero is False, every other number is True.
CBool(%Qty)   ' 10 returns True; 0 returns False

CByte

Converts a value to a byte, that is, a number between 0 and 255.

CByte converts any data type to the Byte subtype. For example, CByte forces byte arithmetic when currency, single-precision, double-precision, or integer arithmetic would normally occur.

CByte follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

Syntax

CByte( expression )

Arguments

• expression
  • Any valid expression. If expression lies outside the acceptable range for the byte subtype, an error occurs.

Example

' 0 to 255 only, and it rounds rather than truncating.
CByte(12.6)   ' Returns 13

CCur

CCur converts any data type to the Currency subtype. For example, CCur forces currency arithmetic when integer arithmetic would normally occur.

CCur follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

Description

Returns an expression that has been converted to a Variant of subtype Currency.

Syntax

CCur( expression )

Arguments

• expression
  • Any valid expression.

Example

' Fixes the value at four decimal places, which is what
' stops repeated arithmetic on a Double drifting a penny
' out over a long order.
CCur("948.00")   ' Returns 948

CDate

Use the IsDate function to check whether a value can be converted to a date or time. CDate recognises date literals and time literals, and some numbers that fall within the range of acceptable dates. When CDate converts a number, the whole-number part becomes the date and any fractional part becomes a time of day, counted from midnight.

CDate reads date formats according to your system's locale setting. If a date is in a format the locale does not recognise, CDate may get the order of day, month and year wrong. CDate does not recognise a long date format that includes the day of the week.

Description

Returns an expression that has been converted to a Variant of subtype Date.

Syntax

CDate( date )

Arguments

• date
  • Any valid date expression.

Example

' Parsed using the IMan server's locale, so "12/03/2026"
' is 12 March on a UK server and 3 December on a US one.
' Test IsDate first if the source cannot be trusted.
CDate("12/03/2026")   ' Returns 12/03/2026 on a UK server

CDbl

CDbl converts any data type to the Double subtype. For example, CDbl forces double-precision arithmetic when currency or integer arithmetic would normally occur.

CDbl follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

Description

Returns an expression that has been converted to a Variant of subtype Double.

Syntax

CDbl( expression )

Arguments

• expression
  • Any valid expression.

Example

' Prices arriving as text from a CSV or webservice need
' this before arithmetic, or "35.00" & 1 concatenates
' instead of adding.
CDbl(%UnitPrice) * %Qty   ' "35.00" and 10 return 350

Chr

Description

Returns the character for a number code.

Syntax

Chr( number_code )

Arguments

• number_code
  • The number of the character to return.

Example

' Chr(9) is a tab, Chr(13) & Chr(10) a Windows line
' break.
Chr(65)   ' Returns "A"

ChrW

Description

Returns the Unicode character for a number code.

Some Unicode characters are hard to type or display, and some are invisible. ChrW returns any Unicode character from its decimal value.

Syntax

ChrW( number_code )

Arguments

• number_code
  • The Unicode decimal number of the character to return.

Example

ChrW(2032)

' Returns the Unicode Prime (′) character.

ChrW(8206)

' Returns the non-printable Unicode Left-To-Right Mark.

ChrW(39277)

' Returns the chinese symbol 饭.

CInt

CInt converts any other data type to the Integer subtype. For example, CInt forces integer arithmetic when currency, single-precision, or double-precision arithmetic would normally occur.

CInt follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

If expression lies outside the acceptable range for the Integer subtype, an error occurs.

Description

Returns an expression that has been converted to a Variant of subtype Integer.

Syntax

CInt( expression )

Arguments

• expression
  • Any valid expression.

Example

' -32,768 to 32,767, and it uses banker's rounding:
' exact halves go to the nearest EVEN number.
CInt(%Qty)   ' "10" returns 10
CInt(2.5)    ' Returns 2
CInt(3.5)    ' Returns 4

CLng

CLng converts any data type to the Long subtype. For example, CLng forces integer arithmetic when currency, single-precision, or double-precision arithmetic would normally occur.

CLng follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

If expression lies outside the acceptable range for the Long subtype, an error occurs.

Description

Returns an expression that has been converted to a Variant of subtype Long.

Syntax

CLng( expression )

Arguments

• expression
  • Any valid expression.

Example

' Same rounding as CInt, but the full 32-bit range.
CLng(35000.6)   ' Returns 35001

CSng

CSng converts any data type to the Single subtype. For example, CSng forces single-precision arithmetic when currency or integer arithmetic would normally occur.

CSng follows your system's locale setting, and recognises the decimal and thousand separators that locale uses.

If expression lies outside the acceptable range for the Single subtype, an error occurs.

Description

Returns an expression that has been converted to a Variant of subtype Single.

Syntax

CSng( expression )

Arguments

• expression
  • Any valid expression.

Example

' Single precision. Prefer CDbl or CCur for money --
' Single carries roughly seven significant digits, which
' a large order total exceeds.
CSng(%UnitPrice)   ' "35.00" returns 35

CStr

CStr converts any data type to the String subtype.

CStr follows your system's locale setting, and recognises the decimal separator that locale uses.

What CStr returns depends on the data in expression:

Description

Returns an expression that has been converted to a Variant of subtype String.

• Boolean
  • A String containing True or False.
• Date
  • A String containing a date in the short-date format of your system.
• Null
  • A run-time error.
• Empty
  • A zero-length String ("").
• Error
  • A String containing the word Error followed by the error number.
• Other numeric
  • A String containing the number.

Syntax

CStr( expression )

Arguments

• expression
  • Any valid expression.

Example

' Forces a number to text, so & concatenates rather than
' adding.
CStr(%Qty) & " x " & %ItemCode   ' Returns "10 x ACME-4471-BLU"

Hex

Description

Returns a string representing the hexadecimal value of a number.

Syntax

Hex(number)

Arguments

• number
  • Any valid expression. If number is not a whole number, Hex first rounds it to the nearest whole number.

Example

Hex(255)   ' Returns "FF"

IsNumeric

Description

Returns a Boolean value indicating whether an expression can be evaluated as a number.

Syntax

IsNumeric(expression)

Arguments

• expression
  • Any valid expression.

Example

' Test before casting: CDbl on non-numeric text raises a
' type mismatch and fails the record.
Dim Price
Price = 0
If IsNumeric(%UnitPrice) Then Price = CDbl(%UnitPrice)
Price   ' "35.00" returns 35; "N/A" returns 0

Oct

Description

Returns a string representing the octal value of a number.

Syntax

Oct(number)

Arguments

• number
  • Any valid expression. If number is not already a whole number, Oct first rounds it to the nearest whole number.

Example

Oct(8)   ' Returns "10"