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 where the object is to be created.

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.

Syntax

EncryptString

Arguments

• string
  • The string to be encrypted.

Example

' IMan-specific, and REVERSIBLE -- it is symmetric
' encryption, not a hash. Use it to keep a value from
' being readable in transit or at rest, not to store a
' password for comparison; for that use HashString,
' which is one-way.
'
' An empty input returns an empty string.
EncryptString(%CustomerCode)

GetLocale

Description

Returns the current locale ID value.

A locale is a set of user preference information related to the user's language, country/region, and cultural conventions.

The locale determines 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 string being the class of the object.

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

Retrieves a value previously saved with RegisterValue. If no matching key is found an empty string is returned.

Syntax

GetRegisteredValue(key)

Arguments

• key
  • Value used to address or store the value. The key value may be either 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, returning one of two values, depending on the evaluation of an expression.

Both the truepart and falsepart are eagerly evaluated. This means they are evaluated irrespective of the expression result.

Use a traditional "if then else statement" if you require the truepart or falsepart to be evaluated only on the result of the condition.

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 has a value of ABC001 otherwise return "Horse".

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

Multiply the Price field with either 1, when the Qty field is less than 1, otherwise for all values of Qty where the multiply the Price field with the Qty field.

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

Return HARDWARE if the EquipmentType field is empty, otherwise return the value from the PRODUCTCODE lookup. Since IIf function eagerly evaluates, the Lookup method will always be evaluated. This may present an issue if the Lookup would raise an error on an empty value (as would happen here).

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

IsEmpty

Description

Returns a Boolean value indicating whether a variable has been initialized.

Syntax

IsEmpty(expression)

Arguments

• expression
  • Can be any expression. However, because IsEmpty is used to determine if individual variables are initialized, the expression argument is most often 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 value that indicates whether an expression contains no valid data (Null).

Syntax

IsNull(expression)

Arguments

• expression
  • Can be any expression.

Example

' True when a value is explicitly Null -- typically a
' database column with no value. Contrast IsEmpty, which
' is about an unassigned variable, and IsFieldNull on
' the Field functions page, which is about an IMan field
' not being set.
IsNull(%Description)   ' True when the source column was NULL

IsObject

Description

Returns a Boolean value indicating whether an expression references a valid object.

Syntax

IsObject(expression)

Arguments

• expression
  • Can be any expression.

Example

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

RegisterValue

Description

Stores a value which is persisted during a single transform by its key. The function is used in conjunction with GetRegisteredValue to retrieve the stored value.

Syntax

RegisterValue(key, value)

Arguments

• key
  • The value used to address or store the value. The key value may be either 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 uniquely identifies a geographical locale. Recognized values can be found in the Locale ID chart.
  • If lcid is zero, the locale is set 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 provides Variant subtype information about 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 value indicating 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

Note this is a procedure (or sub) and there should NOT be any parentheses placed around the arguments.

• code
  • The number or code to be written to the ResultCode field of the log.
• message
  • The message to be written to the ResultReason field of the log.

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