Miscellaneous Functions

• CreateObject
• EncryptString
• GetLocale
• GetObject
• GetRegisteredValue
• IIf
• IsEmpty
• IsNull
• IsObject
• RegisterValue
• SetLocale
• TypeName
• VarType
• WriteToLog

CreateObject

Description

Creates and returns a reference to an object.

Syntax

CreateObject(typename [, location])

Arguments

• typename
  • The type or class of the object to create.
• location
  • Optional. The name of the network server to create the object on.

Example

' Instantiates a COM object. The component must be
' registered ON THE IMAN SERVER and reachable by the
' Scheduler service account -- an object that works in
' the Designer and fails on a schedule is normally
' registration or permissions, not the script.
Dim fso
Set fso = CreateObject("Scripting.FileSystemObject")
fso.FolderExists("C:\IMan\Outbound")   ' Returns True or False

EncryptString

Description

Encrypts any string.

Deprecated

EncryptString is deprecated, and a future version of IMan will remove it. It encrypts with a fixed key that is the same in every IMan installation, and anyone with IMan can reverse it. IMan writes a warning to the log each time an integration calls it. The RealisableData.EncDencUtils object is deprecated for the same reason.

To keep a password out of an integration, store it in a Setup item, such as a system connector or a database connection. IMan protects those with its own keys. See Secrets.

Syntax

EncryptString

Arguments

• string
  • The string to encrypt.

Example

' Reversible encryption, not a hash. To store a
' password for comparison, use the one-way
' HashString.
'
' An empty input returns an empty string.
EncryptString(%CustomerCode)

GetLocale

Description

Returns the current locale ID value.

A locale is a set of preferences for a language, a country or region, and its cultural conventions.

The locale decides such things as keyboard layout, alphabetical sort order, and date, time, number and currency formats.

Syntax

GetLocale

Arguments

• None

Example

' The current locale id (LCID). 2057 is English (United
' Kingdom), 1033 English (United States).
GetLocale()   ' Returns e.g. 2057

GetObject

Description

Returns a reference to an object from a file.

Syntax

GetObject([pathname] [, class])

Arguments

• pathname
  • Optional. Full path and name of the file containing the object to retrieve. If pathname is omitted, class is required.
• class
  • Optional. The class of the object, as a string.

Example

' Binds to an ALREADY-RUNNING COM object, or loads one
' from a file -- where CreateObject starts a new one.
' Same server-registration requirement as CreateObject.
Dim app
Set app = GetObject(, "Excel.Application")

GetRegisteredValue

Description

Returns a value saved earlier with RegisterValue. If no key matches, GetRegisteredValue returns an empty string.

Syntax

GetRegisteredValue(key)

Arguments

• key
  • The key the value is stored under. It can be a single value or an array of values.

Example

' Reads back what RegisterValue stored. Returns an empty
' string when the key was never set, so it does not
' error on a first pass.
GetRegisteredValue("RunningTotal")

' Keys can be composite -- pass an array and the parts
' are combined:
GetRegisteredValue(Array("LineNo", %WarehouseCode))

IIf

Description

An inline If statement. It returns one of two values, depending on how an expression evaluates.

IIf evaluates both truepart and falsepart, whatever the result of the expression.

Use an If...Then...Else statement if only the part the condition selects should be evaluated.

Syntax

IIf( expression, truepart, falsepart )

Arguments

• expression
  • Any valid Boolean expression.
• truepart
  • Returned when expression evaluates to True.
• falsepart
  • Returned when expression evaluates to False.

Example

Return "Turtle" when the Customer field is ABC001, and "Horse" otherwise.

IIf(%Customer = "ABC001", "Turtle", "Horse")

Multiply the Price field by 1 when the Qty field is less than 1, and by the Qty field otherwise. A line with no quantity is then charged as one unit.

%Price * IIf(%Qty < 1, 1, %Qty)

Return HARDWARE if the EquipmentType field is empty, and the value from the PRODUCTCODE lookup otherwise. IIf evaluates both parts, so the Lookup always runs. That is a problem if the Lookup raises an error on an empty value, as it would here.

IIf(%EquipmentType = "", "HARDWARE", Lookup("PRODUCTCODE", "LKUPRESULT", %EquipmentType, True))

IsEmpty

Description

Returns a Boolean that shows whether a variable has been initialised.

Syntax

IsEmpty(expression)

Arguments

• expression
  • Any expression. Because IsEmpty tests whether a variable is initialised, the argument is usually a single variable name.

Example

' True for a variable that has never been assigned. NOT
' the same as IsNull, which is about a value that is
' explicitly nothing, and not the same as an empty
' string.
Dim v
IsEmpty(v)    ' Returns True -- declared but never assigned
v = ""
IsEmpty(v)    ' Returns False -- assigned, even though it is blank

IsNull

Description

Returns a Boolean that shows whether an expression contains no valid data (Null).

Syntax

IsNull(expression)

Arguments

• expression
  • Any expression.

Example

' True when a value is Null -- in IMan, a database
' lookup that found a row whose column is NULL. A field
' reference is never Null: test a field with no value
' with IsFieldNull on the Field functions page. IsEmpty
' is about an unassigned variable.
Dim Terms
Terms = Lookup("CUSTTERMS", "TERMSCODE", %CustomerCode, False)
IsNull(Terms)   ' True when the customer's TERMSCODE is NULL

IsObject

Description

Returns a Boolean that shows whether an expression references a valid object.

Syntax

IsObject(expression)

Arguments

• expression
  • Any expression.

Example

Dim fso
Set fso = CreateObject("Scripting.FileSystemObject")
IsObject(fso)   ' Returns True

RegisterValue

Description

Stores a value under a key. The value lasts for the rest of a single transform. Use GetRegisteredValue to read it back.

Syntax

RegisterValue(key, value)

Arguments

• key
  • The key to store the value under. It can be a single value or an array of values.
• value
  • The value to store.

Example

' IMan-specific. Stores a value under a key so a later
' expression can read it back with GetRegisteredValue --
' the way to carry a running total or a line counter
' across records, which a local variable cannot do
' because it does not survive the record.
'
' It returns an empty string, so it must not be the last
' line of an expression. Store, then return the value
' you want.
RegisterValue("RunningTotal", GetRegisteredValue("RunningTotal") + %LineTotal)
GetRegisteredValue("RunningTotal")   ' 350, then 490, then 790

' Composite keys: pass an array and the parts are
' combined into one key.
RegisterValue(Array("Total", %WarehouseCode), %LineTotal)

SetLocale

Description

Sets the global locale and returns the previous locale.

Syntax

SetLocale(lcid)

Arguments

• lcid
  • Any valid 32-bit value or short string that identifies a geographical locale. The Locale ID chart lists the recognised values.
  • If lcid is zero, SetLocale sets the locale to match the current system setting.

Example

' Changes the locale used by date and number formatting
' for the rest of the expression. Returns the PREVIOUS
' locale, so it can be restored.
Dim prev
prev = SetLocale(1033)      ' Switch to US English
Dim d
d = CDate("03/12/2026")     ' Parsed as 3 December
SetLocale(prev)             ' Put it back
d

TypeName

Description

Returns a string that names the Variant subtype of a variable.

Syntax

TypeName(varname)

Arguments

• varname
  • Any variable.

Example

' The name of a value's type -- the readable counterpart
' to VarType.
TypeName(%Qty)           ' Returns e.g. "Long"
TypeName(%UnitPrice)     ' Returns e.g. "Double"
TypeName(%ItemCode)      ' Returns "String"

VarType

Description

Returns a number for the subtype of a variable.

Syntax

VarType(varname)

Arguments

• varname
  • Any variable.

Example

' The type as a number: 0 Empty, 1 Null, 2 Integer, 3
' Long, 5 Double, 7 Date, 8 String, 11 Boolean.
VarType(%ItemCode)   ' Returns 8

WriteToLog

Description

Writes an entry to the detail area of the log.

Syntax

WriteToLog code, message

Arguments

WriteToLog is a procedure (a Sub), so do not put brackets around its arguments.

• code
  • The number or code to write to the log's ResultCode field.
• message
  • The message to write to the log's ResultReason field.

Example

' IMan-specific. Writes an entry to the integration's
' detail audit log, visible in the Audit Log Query
' screen. Takes a result code and a message, in that
' order.
'
' It does not stop the record -- use Check for that.
' This is for leaving a trail when something is unusual
' but not wrong.
If %LineTotal <> %UnitPrice * %Qty Then
  WriteToLog "PRICE", "Line total does not match price x qty for " & %ItemCode
End If
%LineTotal