IBM Optim: Optim Basic Language Reference - Internodebdavis/Optim/Docs/OptimBasic.pdf · x IBM...
Transcript of IBM Optim: Optim Basic Language Reference - Internodebdavis/Optim/Docs/OptimBasic.pdf · x IBM...
IBM Optim
Optim Basic Language ReferenceVersion 7 Release 3
���
IBM Optim
Optim Basic Language ReferenceVersion 7 Release 3
���
NoteBefore using this information and the product it supports, read the information in “Notices” on page 111.
Version 7 Release 3 (September 2010)
This edition applies to version 7, release 3 of IBM Optim and to all subsequent releases and modifications untilotherwise indicated in new editions.
© Copyright IBM Corporation 1994, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . vii
About this publication . . . . . . . . ix
Chapter 1. Introduction to Optim Basic 1Adding Column Map Procedures To A Column Map 1
General Functions, Statements, and ReservedWords . . . . . . . . . . . . . . . 3Functions, Statements, and Reserved Words byType . . . . . . . . . . . . . . . . 4Object Properties and Global Functions by Type . 7Operators . . . . . . . . . . . . . . 9
Chapter 2. Elements . . . . . . . . . 13Comments. . . . . . . . . . . . . . . 13Statement Terminator . . . . . . . . . . . 13Line Continuation Character. . . . . . . . . 13Numbers . . . . . . . . . . . . . . . 13Variables . . . . . . . . . . . . . . . 14
Variable and Constant Names . . . . . . . 14Declaration of Variables . . . . . . . . . 14Data Types . . . . . . . . . . . . . 14Variant Data Type . . . . . . . . . . . 15Variants and Concatenation . . . . . . . . 15
Control Structures . . . . . . . . . . . . 15Do Loop . . . . . . . . . . . . . . 16While Loop . . . . . . . . . . . . . 16For...Next Loop . . . . . . . . . . . . 16If and Select Statements . . . . . . . . . 16GoTo . . . . . . . . . . . . . . . 17
Subroutines and Functions . . . . . . . . . 17ByRef and ByVal . . . . . . . . . . . . 18Calling Procedures in DLLs . . . . . . . . . 19File Input/Output . . . . . . . . . . . . 20Arrays . . . . . . . . . . . . . . . . 21
Single Arrays . . . . . . . . . . . . . 21Multi-Dimensional Arrays . . . . . . . . 22
User-Defined Types. . . . . . . . . . . . 22OLE Fundamentals . . . . . . . . . . . . 23
OLE Objects . . . . . . . . . . . . . 24OLE Automation . . . . . . . . . . . 25Making Applications Work Together . . . . . 26
Chapter 3. Functions and Statements 29Abs Function . . . . . . . . . . . . . . 29AppActivate Statement . . . . . . . . . . 29Asc Function . . . . . . . . . . . . . . 30Atn Function . . . . . . . . . . . . . . 30Call Statement . . . . . . . . . . . . . 30CBool Function . . . . . . . . . . . . . 30CDate Function . . . . . . . . . . . . . 31CDbl Function . . . . . . . . . . . . . 31ChDir Statement. . . . . . . . . . . . . 31ChDrive Statement . . . . . . . . . . . . 32
Choose Function. . . . . . . . . . . . . 32Chr Function . . . . . . . . . . . . . . 32CInt Function. . . . . . . . . . . . . . 33CLng Function . . . . . . . . . . . . . 33Close Statement . . . . . . . . . . . . . 33Const Statement . . . . . . . . . . . . . 34Cos Function . . . . . . . . . . . . . . 34CreateObject Function . . . . . . . . . . . 34CSng Function . . . . . . . . . . . . . 35CStr Function. . . . . . . . . . . . . . 35CurDir Function . . . . . . . . . . . . . 36CVar Function . . . . . . . . . . . . . 36Date Function . . . . . . . . . . . . . 36DateSerial Function. . . . . . . . . . . . 37DateValue Function. . . . . . . . . . . . 37Day Function . . . . . . . . . . . . . . 37Declare Statement . . . . . . . . . . . . 38Dim Statement . . . . . . . . . . . . . 38Dir Function . . . . . . . . . . . . . . 39Do...Loop Statement . . . . . . . . . . . 39End Statement . . . . . . . . . . . . . 40EOF Function. . . . . . . . . . . . . . 40Erase Statement . . . . . . . . . . . . . 40Exit Statement . . . . . . . . . . . . . 41Exp Function . . . . . . . . . . . . . . 41FileCopy Statement . . . . . . . . . . . . 41FileLen Function. . . . . . . . . . . . . 42Fix Function . . . . . . . . . . . . . . 42For Each...Next Statement . . . . . . . . . 42For...Next Statement . . . . . . . . . . . 42Format Function . . . . . . . . . . . . . 43FreeFile Function . . . . . . . . . . . . 48Function Statement . . . . . . . . . . . . 48Get Statement . . . . . . . . . . . . . 49GetObject Function . . . . . . . . . . . . 49Global Statement . . . . . . . . . . . . 49GoTo Statement . . . . . . . . . . . . . 49Hex Function . . . . . . . . . . . . . . 49Hour Function . . . . . . . . . . . . . 50If...Then...Else Statement . . . . . . . . . . 50Input # Statement . . . . . . . . . . . . 51Input Function . . . . . . . . . . . . . 51InStr Function . . . . . . . . . . . . . 52Int Function . . . . . . . . . . . . . . 52IsArray Function . . . . . . . . . . . . 52IsDate Function . . . . . . . . . . . . . 52IsEmpty Function . . . . . . . . . . . . 53IsNull Function . . . . . . . . . . . . . 53IsNumeric Function . . . . . . . . . . . 53IsObject Function . . . . . . . . . . . . 53Kill Statement . . . . . . . . . . . . . 54LBound Function . . . . . . . . . . . . 54LCase Function . . . . . . . . . . . . . 54Left Function . . . . . . . . . . . . . . 55Len Function . . . . . . . . . . . . . . 55Let Statement. . . . . . . . . . . . . . 55
© Copyright IBM Corp. 1994, 2010 iii
Line Input # Statement . . . . . . . . . . 55LOF Function. . . . . . . . . . . . . . 56Log Function . . . . . . . . . . . . . . 56Mid Function . . . . . . . . . . . . . . 56Minute Function. . . . . . . . . . . . . 56MkDir Statement . . . . . . . . . . . . 57Month Function . . . . . . . . . . . . . 57Name Statement . . . . . . . . . . . . . 57Now Function . . . . . . . . . . . . . 57Oct Function . . . . . . . . . . . . . . 58On Error Statement . . . . . . . . . . . . 58Open Statement . . . . . . . . . . . . . 61Option Base Statement. . . . . . . . . . . 62Option Explicit Statement . . . . . . . . . 62Print Method . . . . . . . . . . . . . . 62Print # Statement . . . . . . . . . . . . 63Randomize Statement . . . . . . . . . . . 64ReDim Statement . . . . . . . . . . . . 64Rem Statement . . . . . . . . . . . . . 64Right Function . . . . . . . . . . . . . 65RmDir Statement . . . . . . . . . . . . 65Rnd Function . . . . . . . . . . . . . . 65Second Function . . . . . . . . . . . . . 66Seek Function . . . . . . . . . . . . . 66Seek Statement . . . . . . . . . . . . . 66Select Case Statement . . . . . . . . . . . 67SendKeys Function . . . . . . . . . . . . 67Set Statement . . . . . . . . . . . . . . 68Shell Function . . . . . . . . . . . . . 68Sin Function . . . . . . . . . . . . . . 69Space Function . . . . . . . . . . . . . 69Sqr Function . . . . . . . . . . . . . . 69Static Statement . . . . . . . . . . . . . 69Str Function . . . . . . . . . . . . . . 70StrComp Function . . . . . . . . . . . . 70String Function . . . . . . . . . . . . . 70Sub Statement . . . . . . . . . . . . . 70Tan Function . . . . . . . . . . . . . . 71Time Function . . . . . . . . . . . . . 71Timer Function . . . . . . . . . . . . . 71TimeSerial Function . . . . . . . . . . . 72TimeValue Function . . . . . . . . . . . 72Trim, LTrim, RTrim Functions . . . . . . . . 72Type Statement . . . . . . . . . . . . . 73UBound Function . . . . . . . . . . . . 74UCase Function . . . . . . . . . . . . . 74Val Function . . . . . . . . . . . . . . 74VarType Function . . . . . . . . . . . . 75Weekday Function . . . . . . . . . . . . 75While...Wend Statement . . . . . . . . . . 75With Statement . . . . . . . . . . . . . 76Write # Statement . . . . . . . . . . . . 76Year Function. . . . . . . . . . . . . . 77
Chapter 4. Object Properties andGlobal Functions . . . . . . . . . . 79Properties for App Object. . . . . . . . . . 81
ArchBrowseIdxDir . . . . . . . . . . . 82ArchDir . . . . . . . . . . . . . . 82ArchIdxDir . . . . . . . . . . . . . 82Arg . . . . . . . . . . . . . . . . 82
ArgCount . . . . . . . . . . . . . . 82CompanyName . . . . . . . . . . . . 82ComputerName . . . . . . . . . . . . 83DataDir. . . . . . . . . . . . . . . 83Environ. . . . . . . . . . . . . . . 83Error . . . . . . . . . . . . . . . 83Instance . . . . . . . . . . . . . . 83LogEvent . . . . . . . . . . . . . . 83OpSys . . . . . . . . . . . . . . . 84OpSysBuild . . . . . . . . . . . . . 84OpSysCSD. . . . . . . . . . . . . . 84OpSysRelease. . . . . . . . . . . . . 84Request. . . . . . . . . . . . . . . 84RequestList . . . . . . . . . . . . . 85RtBuild . . . . . . . . . . . . . . . 85RtRelease . . . . . . . . . . . . . . 85Script . . . . . . . . . . . . . . . 85ServerUserId . . . . . . . . . . . . . 85StartLogging . . . . . . . . . . . . . 85TempDir . . . . . . . . . . . . . . 86ThreadHandle . . . . . . . . . . . . 86ThreadId . . . . . . . . . . . . . . 87
Properties for Source Object . . . . . . . . . 87Column (source object) . . . . . . . . . 87ColumnList . . . . . . . . . . . . . 87CreateFile . . . . . . . . . . . . . . 88CreatorId . . . . . . . . . . . . . . 88DBAlias . . . . . . . . . . . . . . 88IsColumn . . . . . . . . . . . . . . 88OwnerId . . . . . . . . . . . . . . 89Table . . . . . . . . . . . . . . . 89
Properties for Target Object . . . . . . . . . 89Column (target object) . . . . . . . . . . 89SetFromFile . . . . . . . . . . . . . 89Value (target object) . . . . . . . . . . 90
Properties for a Column Instance . . . . . . . 90Available . . . . . . . . . . . . . . 90IsNull . . . . . . . . . . . . . . . 90Length . . . . . . . . . . . . . . . 91Name . . . . . . . . . . . . . . . 91Nullable . . . . . . . . . . . . . . 91Precision . . . . . . . . . . . . . . 91Scale. . . . . . . . . . . . . . . . 91Type. . . . . . . . . . . . . . . . 91Value (column instance) . . . . . . . . . 91
Global Functions . . . . . . . . . . . . 92GetAllSettings . . . . . . . . . . . . 92GetAsBinary . . . . . . . . . . . . . 93GetAsDate. . . . . . . . . . . . . . 93GetAsDecimalChar . . . . . . . . . . . 94GetAsDecimalCharSz . . . . . . . . . . 94GetAsOracleDate . . . . . . . . . . . 94GetAsSybaseDateTime . . . . . . . . . . 95GetAsSybaseDecimal . . . . . . . . . . 96GetAsSybaseMoney. . . . . . . . . . . 96GetAsSybaseSmallDateTime . . . . . . . . 97GetAsSybaseSmallMoney . . . . . . . . . 97GetAsTime . . . . . . . . . . . . . 98GetAsVarBinary . . . . . . . . . . . . 98GetAsVarChar . . . . . . . . . . . . 99GetAsVarCharSz. . . . . . . . . . . . 99
iv IBM Optim: Optim Basic Language Reference
GetGlobalWork . . . . . . . . . . . . 99GetSetting . . . . . . . . . . . . . 100PutAsBinary. . . . . . . . . . . . . 101PutAsDate . . . . . . . . . . . . . 101PutAsDecimalChar . . . . . . . . . . 101PutAsDecimalCharSz . . . . . . . . . . 102PutAsOracleDate . . . . . . . . . . . 102PutAsSybaseDateTime . . . . . . . . . 103PutAsSybaseDecimal . . . . . . . . . . 103PutAsSybaseMoney . . . . . . . . . . 104PutAsSybaseSmallDateTime . . . . . . . 104PutAsSybaseSmallMoney . . . . . . . . 105PutAsTime . . . . . . . . . . . . . 105
PutAsVarBinary . . . . . . . . . . . 106PutAsVarChar . . . . . . . . . . . . 106PutAsVarCharSz . . . . . . . . . . . 106SaveSetting . . . . . . . . . . . . . 107SetGlobalWork . . . . . . . . . . . . 108Global Function Return Codes. . . . . . . 108
Notices . . . . . . . . . . . . . . 111Trademarks . . . . . . . . . . . . . . 113
Index . . . . . . . . . . . . . . . 115
Contents v
vi IBM Optim: Optim Basic Language Reference
Tables
1. Names of Optim Basic functions, statements,and reserved words in alphabetical order . . . 3
2. Names of Optim Basic functions, statements,and reserved words of type Flow of Control . . 5
3. Names of Optim Basic functions, statements,and reserved words of type Conversion . . . 5
4. Names of Optim Basic functions, statements,and reserved words of type File I/O . . . . 5
5. Names of Optim Basic functions, statements,and reserved words of type Math . . . . . 5
6. Names of Optim Basic functions, statements,and reserved words of type Procedures . . . 5
7. Names of Optim Basic functions, statements,and reserved words of type Strings . . . . . 6
8. Names of Optim Basic functions, statements,and reserved words of type Variables andConstants . . . . . . . . . . . . . 6
9. Names of Optim Basic functions, statements,and reserved words of type Error Trapping . . 6
10. Names of Optim Basic functions, statements,and reserved words of type Date/Time . . . 6
11. Names of Optim Basic functions, statements,and reserved words of type DDE. . . . . . 6
12. Names of Optim Basic functions, statements,and reserved words of type Arrays . . . . . 6
13. Names of Optim Basic functions, statements,and reserved words of type Miscellaneous . . 6
14. Names of Optim Basic Application Object (App)properties . . . . . . . . . . . . . 7
15. Names of Optim Basic Source Object (Source)properties . . . . . . . . . . . . . 7
16. Names of Optim Basic Target Object (Target)properties . . . . . . . . . . . . . 7
17. Names of Optim Basic Column Instanceproperties . . . . . . . . . . . . . 7
18. Arithmetic operators in Optim Basic . . . . 919. Relational operators in Optim Basic . . . . 1020. Logical operators in Optim Basic . . . . . 1021. Operator precedence in Optim Basic . . . . 1022. Data Types used in Optim Basic . . . . . 1423. VarType return values . . . . . . . . . 75
© Copyright IBM Corp. 1994, 2010 vii
viii IBM Optim: Optim Basic Language Reference
About this publication
This reference document describes the syntax used by the Optim™ Basic programming language.
Use Optim Basic to write Column Map Procedures. A Column Map Procedure is a custom program thatis referenced by a Column Map. Column Map Procedures allow you to perform special processing orchange data in ways that you could not do using native Column Map functions.
© Copyright IBM Corp. 1994, 2010 ix
x IBM Optim: Optim Basic Language Reference
Chapter 1. Introduction to Optim Basic
Use Optim Basic to write Column Map Procedures. A Column Map Procedure is a custom program thatis referenced by a Column Map. Column Map Procedures allow you to perform special processing orchange data in ways that you could not do using native Column Map functions.
You can use a Column Map Procedure in any process that requires a Column Map (in other words, aConvert, Insert, Load, or Restore Process). If you specify a Column Map Procedure as a source columnwithin a Column Map, Optim runs the Column Map Procedure whenever you use the Column Map in aprocess on a Windows computer. If the process is delegated to an Optim Server on a Windows computer,Optim Server can also run the Column Map Procedure.
Note: You can use a Column Map Procedure only if Optim runs on a Microsoft Windows computer. Ifthe process is delegated to an Optim Server, the Optim Server must be on a Windows computer. Youcannot use a Column Map Procedure if either Optim or Optim Server runs on a UNIX computer.
Because Column Map Procedures derive values that could not be generated using native Column Mapfunctions, they help you manage data according to site-specific rules. For example, you might want toround Year-to-Date Sales amounts before restoring data for analysis or reporting. In a similar example,you might want to use conditional processing to round off Year-to-Date Sales, but only for the state ofPennsylvania.
The function of a Column Map Procedure is generally the same as that of an exit routine. Exit routines,however, are written outside Optim and must be externally compiled and linked. Column MapProcedures, on the other hand, do not require an external compile and link, and complicated callingconventions.
One function of a Column Map Procedure is to generate values that could not otherwise be defined forthe destination column—useful for handling special processing and data manipulation according tosite�defined rules. During processing, the Column Map Procedure, a program that derives values for thecorresponding destination column, runs. Column Map Procedures are not limited to data transformation,however. You can also use a Column Map Procedure to reject rows on the basis of custom processing, tocreate a report tailored to the needs of your site, or to implement conditional data transformations.
Before you begin writing a Column Map Procedure, see the Common Elements Manual for detailedinformation on the use of Table Maps and Column Maps and referencing Column Map Procedures inprocess requests.
Adding Column Map Procedures To A Column MapTo add a Column Map Procedure to a Column Map, first create the Column Map Procedure using theColumn Map Procedure Editor. After you create the Column Map Procedure, you can reference theColumn Map Procedure from a Column Map.
Predefined Functions and subroutine
The purpose of the Column Map Procedure is to supply data values for destination columns. To effectthis, Move and Archive call certain functions and subroutines, pre-defined in the Column Map Procedure.They are:
© Copyright IBM Corp. 1994, 2010 1
Sub Load.........End Sub
This optional subroutine is called before any tables areprocessed. You can use this subroutine for initialization orother tasks that apply generally in the procedure.
Function CmStartTable () As Integer.........End Function
This optional function is called before each table isprocessed. You can use this function for initialization tasksthat affect or apply to each table processed in theprocedure.
Function CmTransform () As Integer.........End Function
This required function is called for each row that isprocessed and provides instructions for the datatransformation to be performed.
Function CmEndTable.........End Function
This optional function is called after each table isprocessed. You can use this function for tasks requiredafter each table is processed.
Sub Unload().........End Sub
This optional subroutine is called after all tables areprocessed. You can use this subroutine for tasks requiredbefore termination of the procedure.
Of the native functions, only the CmTransform function is required; others are optional. You can add yourown functions to be called by one or more native functions or otherwise edit the functions to generatedestination values or reports that meet your requirements.
Return Codes
The CmStartTable and CmTransform functions must return one of the following codes:
ReturnCode Mnemonic Explanation
0 PST_CM_EXIT_SUCCESS Procedure executed successfully
1 PST_CM_EXIT_REJECT_ROW Procedure rejected row
2 PST_CM_EXIT_ABORT_PROCESS Procedure detected abort condition
Naming Conventions
Once written, a Column Map Procedure can be saved and stored in the Optim Directory—available foruse with other Column Maps or in other processes. The naming convention is as follows:
identifierIdentifier assigned to the Column Map Procedure (1 to 8 characters).
name Name assigned to the Column Map Procedure (1 to 12 characters).
A Local Column Map (unnamed) Procedure is stored as part of the Column Map and is not otherwiseavailable. Include the name of the Column Map Procedure in print output for a process to automaticallygenerate a name for any local Column Map Procedure. The format is: tablename.columnname.n.
2 IBM Optim: Optim Basic Language Reference
Referencing a Named Procedure in a Column Map
To reference a named procedure in a Column Map, use the following syntax for the appropriate sourcecolumn:
PROC identifier.name [ ( ["parm1" [,"parmn"] ] ) ], where:
identifierIdentifier assigned to the Column Map Procedure (1 to 8 characters).
name Name assigned to the Column Map Procedure (1 to 12 characters).
parm1, parmnAs many as 8 optional string or numeric constants, separated by commas that are passed to theprocedure when it is called.
Referencing a Local Procedure in a Column Map
To reference a local procedure in a Column Map, use the following syntax for the appropriate sourcecolumn:
PROC LOCAL [ ( ["parm1" [,"parmn"] ] ) ], where:
parm1, parmnAs many as 8 optional string or numeric constants, separated by commas that are passed to theprocedure when it is called.
General Functions, Statements, and Reserved WordsThis topic lists in alphabetical order the names of the functions, statements, and reserved words that areavailable in Optim Basic.
For a detailed description of each language element, refer to Chapter 3, “Functions and Statements,” onpage 29.
Table 1. Names of Optim Basic functions, statements, and reserved words in alphabetical order
Abs Access Alias And
Any App AppActivate Asc
As Atn Base Begin
Binary ByVal Call Case
CBool CDate CDbl ChDir
ChDrive Choose Chr CInt
CLng Close Const Cos
CreateObject CSng CStr CVar
CurDir Date DateSerial DateValue
Day DDEInitiate DDEExecute Declare
Dim Dir Do...Loop Double
Else ElseIf Empty End
End If EOF Eqv Erase
Err Error Exit Exp
Explicit False FileCopy FileLen
Fix For For Each...Next For...Next
Format FreeFile Function Get Object
Chapter 1. Introduction to Optim Basic 3
Table 1. Names of Optim Basic functions, statements, and reserved words in alphabetical order (continued)
Get GetAttr Global GoTo
Hex Hour If...Then...Else Imp
Input Input # InputBox Int
Integer InStr Is IsArray
IsNull IsNumeric IsDate IsEmpty
IsObject Kill LBound LCase
Left Len Let Line Input #
LOF Log Long Loop
LTrim Mid Minute MkDir
Mod Month Name Next
Not Now Object Oct
On On Error Open Option
Option Base Option Explicit Optional Or
Print Print # Put Randomize
ReDim Rem Right RmDir
Rnd Rtrim Second Seek
Select Select Case SendKeys Set
SetAttr Shell Sin Single
Sng Space Sqr Static
Step Str StrComp String
Sub Tan Then Time
Timer TimeSerial TimeValue To
Trim True Type UBound
UCase Until Val Variant
VarType Weekday While...Wend With
Write # Xor Year
Functions, Statements, and Reserved Words by TypeThis topic lists by type the names of the functions, statements, and reserved words that are available inOptim Basic.
The types of functions, statements, and reserved words are:v “Flow of Control” on page 5v “Conversion” on page 5v “File I/O” on page 5v “Math” on page 5v “Procedures” on page 5v “Strings” on page 6v “Variables and Constants” on page 6v “Error Trapping” on page 6v “Date/Time” on page 6v “DDE” on page 6
4 IBM Optim: Optim Basic Language Reference
v “Arrays” on page 6v “Miscellaneous” on page 6
For a detailed description of each language element, refer to Chapter 3, “Functions and Statements,” onpage 29.
Flow of Control
Table 2. Names of Optim Basic functions, statements, and reserved words of type Flow of Control
Do...Loop End End If Exit For
Exit Loop For Each...Next For...Next GoTo
If...Then...Else OnError Select Case While...Wend
Conversion
Table 3. Names of Optim Basic functions, statements, and reserved words of type Conversion
Asc CBool CDate CDbl
Chr CInt Clng CSngr
CStr CVar Date DateSerial
DateValue Day Fix Format
Hex Hour Int Minute
Month Oct Second Str
TimeSerial TimeValue Val Weekday
Year
File I/O
Table 4. Names of Optim Basic functions, statements, and reserved words of type File I/O
ChDir ChDrive Close CurDir
Dir EOF FileCopy FileLen
FreeFile Get GetAttr Input
Kill Line Input LOF MkDir
Name Open Print # Put
RmDir Seek SetAttr Write #
Math
Table 5. Names of Optim Basic functions, statements, and reserved words of type Math
Abs Atn Cos Exp
Fix Int Log Rnd
Sgn Sin Sqr Tan
Procedures
Table 6. Names of Optim Basic functions, statements, and reserved words of type Procedures
Call Declare End Function End Sub
Exit Function Global Sub
Chapter 1. Introduction to Optim Basic 5
Strings
Table 7. Names of Optim Basic functions, statements, and reserved words of type Strings
Asc Chr InStr LCase
Left Len Let LTrim
Mid Option Compare Right RTrim
Space StrComp Format String Trim
UCase
Variables and Constants
Table 8. Names of Optim Basic functions, statements, and reserved words of type Variables and Constants
Const Dim Global IsDate
IsEmpty IsNull IsNumeric Option Explicit
Static VarType
Error Trapping
Table 9. Names of Optim Basic functions, statements, and reserved words of type Error Trapping
On Error Resume
Date/Time
Table 10. Names of Optim Basic functions, statements, and reserved words of type Date/Time
Date Now Time Timer
DDE
Table 11. Names of Optim Basic functions, statements, and reserved words of type DDE
DDEExecute DDEInitiate DDETerminate
Arrays
Table 12. Names of Optim Basic functions, statements, and reserved words of type Arrays
Dim Erase Global Lbound
Option Base Option Explicit ReDim Static
Ubound
Miscellaneous
Table 13. Names of Optim Basic functions, statements, and reserved words of type Miscellaneous
AppActivate CreateObject GetObject Randomize
Rem SendKeys Shell
6 IBM Optim: Optim Basic Language Reference
Object Properties and Global Functions by TypeThis topic lists by type the names of the object properties and global functions that are available in OptimBasic.
The types of object properties and global functions are:v “Application Object Properties”v “Source Object Properties”v “Target Object Properties”v “Column Instance Properties”v “Global Functions”
For a detailed description of each object property or global function, see Chapter 4, “Object Propertiesand Global Functions,” on page 79.
Application Object Properties
Table 14. Names of Optim Basic Application Object (App) properties
ArchBrowseIdxDir ArchDir ArchIdxDir Arg
ArgCount CompanyName ComputerName DataDir
Environ Error Instance LogEvent
Opsys OpsysBuild OpsysCSD OpsysRelease
Request RequestList RtBuild RtRelease
Script ServerUserId StartLogging TempDir
ThreadHandle ThreadId
Source Object Properties
Table 15. Names of Optim Basic Source Object (Source) properties
Column ColumnList CreateFile CreatorId
DBAlias IsColumn OwnerId Table
Target Object Properties
Table 16. Names of Optim Basic Target Object (Target) properties
Column SetFromFile Value
Column Instance Properties
Table 17. Names of Optim Basic Column Instance properties
Available IsNull Length Name
Nullable Precision Scale Type
Value
Global Functions
FunctionSyntax
Chapter 1. Introduction to Optim Basic 7
GetAllSettingsGetAllSettings("appname","section")
GetAsBinaryGetAsBinary(column,length)
GetAsDateGetAsDate(column,pointer)
GetAsDecimalCharGetAsDecimalChar(column,precision[,scale])
GetAsDecimalCharSzGetAsDecimalCharSz(column,precision,scale)
GetAsOracleDateGetAsOracleDate(column,pointer)
GetAsSybaseDateTimeGetAsSybaseDateTime(column,pointer)
GetAsSybaseDecimalGetAsSybaseDecimal(column,pointer)
GetAsSybaseMoneyGetAsSybaseMoney(column,pointer)
GetAsSybaseSmallDateTimeGetAsSybaseSmallDateTime(column,pointer)
GetAsSybaseSmallMoneyGetAsSybaseSmallMoney(column,pointer)
GetAsTimeGetAsTime(column,pointer)
GetAsVarBinaryGetAsVarBinary(column,pointer)
GetAsVarCharGetAsVarChar(column,pointer)
GetAsVarCharSzGetAsVarCharSz(column,pointer)
GetGlobalWorkGetGlobalWork(area,length)
GetSettingGetSetting("appname","section","key"[,"default"])
PutAsBinaryPutAsBinary(column,length)
PutAsDatePutAsDate(column,pointer)
PutAsDecimalCharPutAsDecimalChar(pointer)
PutAsDecimalCharSzPutAsDecimalCharSz(pointer)
PutAsOracleDatePutAsOracleDate(column,pointer)
8 IBM Optim: Optim Basic Language Reference
PutAsSybaseDateTimePutAsSybaseDateTime(column,pointer)
PutAsSybaseDecimalPutAsSybaseDecimal(column,pointer)
PutAsSybaseMoneyPutAsSybaseMoney(column,pointer)
PutAsSybaseSmallDateTimePutAsSybaseSmallDateTime(column,pointer)
PutAsSybaseSmallMoneyPutAsSybaseSmallMoney(column,pointer)
PutAsTimePutAsTime(column,pointer)
PutAsVarBinaryPutAsVarBinary(column,pointer)
PutAsVarCharPutAsVarChar(column,pointer)
PutAsVarCharSzPutAsVarCharSz(column,pointer)
SaveSettingSaveSetting "appname","section","key",value
SetGlobalWorkSetGlobalWork(pointer,length)
OperatorsYou can use operators within Optim Basic expressions to signify arithmetic, relational, and logicaloperations within the expression. You can also use operators to indicate the order (or precedence) inwhich Optim Basic is to resolve the operations within each expression.
Arithmetic Operators
The following table lists the arithmetic operators that are available in Optim Basic. Arithmetic operatorsfollow mathematical rules of precedence. Either + or & can be used for string concatenation.
Table 18. Arithmetic operators in Optim Basic
Operator Function Usage
^ exponentiation x = y^2
- negation x = -2
* multiplication x% = 2 * 3
/ division x = 10/2
Mod modulo x = y Mod z
+ addition x = 2 + 3
- subtraction x = 6 - 4
Chapter 1. Introduction to Optim Basic 9
Relational Operators
The following table lists the relational operators that are available in Optim Basic.
Table 19. Relational operators in Optim Basic
Operator Function Usage
< less than x < Y
<= less than or equal to x <= Y
= equals x = Y
>= greater than or equal to x >= Y
> greater than x > Y
<> not equal to x <> Y
Logical Operators
The following table lists the logical operators that are available in Optim Basic.
Table 20. Logical operators in Optim Basic
Operator Function Usage
Not logical negation If Not (x)
And logical and (true only if botharguments are true)
If (x>y) And (x<z)
Or logical or (true if at least oneargument is true)
If (x=y) Or (x=z)
Xor logical exclusion (true only if exactlyone argument is true)
If (x>y) Xor (x<z)
Eqv logical equivalence (true if botharguments are true or if botharguments are false)
If (x=y) Eqv (x=z)
Imp logical implication (true if botharguments are true or if the firstargument is false)
If (x=y) Imp (x=z)
Operator Precedence
The following table indicates the order in which Optim Basic resolves operations in an expression.Operators with equal precedence are resolved from left to right in the expression. For example, in theexpression 5/9*(F-32), the operation F-32 is resolved first, the operation 5/9 is resolved next, and thethird operation multiplies the results of the first two operations together.
Table 21. Operator precedence in Optim Basic
Operator Description Order
() parentheses first
10 IBM Optim: Optim Basic Language Reference
Table 21. Operator precedence in Optim Basic (continued)
Operator Description Order
^ exponentiation
- negation (for example, -x)
/ * division, multiplication
Mod modulo
+ - & addition, subtraction, concatenation
= <> < > <= >= relational
Not logical negation
And logical conjunction
Or logical disjunction
Xor logical exclusion
Eqv logical equivalence
Imp logical implication last
Chapter 1. Introduction to Optim Basic 11
12 IBM Optim: Optim Basic Language Reference
Chapter 2. Elements
In an Optim Basic program, you can include elements such as comments, functions, and statements.Optim Basic also supports decimal, octal, and hexadecimal representations of numbers, twelve variabledata types, and multiple flow of control structures.
A program can be composed of many files. Each file can contain many subroutines and functions.Variables can be local (within a subroutine or function) or global (shared by all subroutines and functionswithin the program).
CommentsComments are nonexecutable lines of code that are included in a program. Any text that follows anapostrophe or the word rem is treated as a comment and is ignored. The word rem, all other keywords,and most names are not case sensitive.
For example:' This whole line is a commentrem This whole line is a commentREM This whole line is a commentRem This whole line is a comment
You can also include a comment on the same line with executable code. The text that follows theapostrophe in the following example is a comment.x=x+1 Msg ' Display message.
Statement TerminatorStatements in Optim Basic implicitly terminate at the end of the line, unless the statement is continued bya line continuation character. To include more than one statement on a line, use a colon to separate thestatements.
For example:X.AddPoint ( 25, 100) : X.AddPoint ( 0, 75)
This line is equivalent to the following lines:X.AddPoint ( 25, 100)X.AddPoint ( 0, 75)
Line Continuation CharacterTo continue a line of code to the next line, end the line with an underscore _, with a space before andafter the underscore.
For example:X.AddPoint _( 25, 100)
NumbersOptim Basic supports decimal, octal and hexadecimal number representations. To use octal (base 8)numbers, prefix the number with &O. To use hexadecimal (base 16) numbers, prefix the number with &H.
© Copyright IBM Corp. 1994, 2010 13
VariablesA variable is a representation of a changeable value.
Variable and Constant NamesVariable and constant names are a maximum of 40 characters. Names are not case sensitive and caninclude the letters A to Z and a to z, the underscore “_”, and the digits 0 to 9. However, each name mustbegin with a letter and cannot be a reserved word.
Note: One exception to this rule is that object member names and property names can be reservedwords.
Declaration of VariablesVariables can be local or global. Declare a variable with the Dim statement.
To declare a variable other than a variant, use an As phrase in the Dim statement, or append a typespecifier character to the variable name. (For example, you can append a percent sign % to the end of avariable name to declare a type of Integer.)
For example:Sub Main
Dim X As IntegerDim Y As DoubleDim Name$, Age% ' declaration of string variable Name$ and integer variable Age%
End Sub
Data TypesVariables in Optim Basic can use the same data types as the data types that are used in your database.
In some cases, you can use type specifiers in the name of a variable to indicate the data type of thevariable. For example, if you specify variable name Star$, Optim Basic assumes that the variable is astring and allocates memory for variable Star$ accordingly. To enable better memory management and toclarify the data type used by each variable, use the Dim statement to define the data types of yourvariables formally.
The following table lists the data types used in Optim Basic, the type specifiers and type declarations thatyou can use to specify these data types, and the amount of memory reserved for each variable of eachdata type.
Table 22. Data Types used in Optim Basic
Variable Type Specifier Type Declaration Size
Boolean Dim x As Boolean True or False
Byte Dim x As Byte 0 to 225
Currency Dim x As Currency 8 bytes
Date Dim x As Date 8 bytes
Double # Dim x As Double 8 bytes
Integer % Dim x As Integer 2 bytes
Long & Dim x As Long 4 bytes
Object Dim x As Object 4 bytes
Single ! Dim x As Single 4 bytes
String $ Dim x As String 0 to 65 500 char
14 IBM Optim: Optim Basic Language Reference
Table 22. Data Types used in Optim Basic (continued)
Variable Type Specifier Type Declaration Size
Variant Dim x As Any
user-defined Types size of each element
Variant Data TypeA variable with the variant data type can contain any type of value, and can change the type of valuethat it contains without having to convert the variable from one data type to another.
When a variable is used but not declared, it is implicitly declared as a variant data type. You do not haveto declare a variable before using it, unless the Option Explicit statement is used.
Note: You can explicitly declare a variant by using the As Variant phrase in a Dim statement. Forexample: Dim x As Variant.
You can use the variant data type to store numbers, strings, dates, and times. When using a variant, youdo not have to explicitly convert a variable from one data type to another. This data type conversion ishandled automatically. For example:Sub Main
Dim x ' variant variablex = 10x = x + 8x = "F" & xPrint x ' prints F18
End Sub
A variant variable can readily change its data type. To determine the internal representation of a variant,use the function VarType. VarType returns a value that corresponds to the explicit data type. For possiblereturn values, see “VarType Function” on page 75.
For numbers in variant variables, the most compact data type possible is used. For example, if you firstassign a small number to a variant it will be stored as an integer. If you subsequently assign the variantto a number with a fractional component, it will be stored as a double.
For numeric operations on a variant variable, you might need to determine if the value stored is a validnumeric in order to avoid an error. Use the IsNumeric function to determine if the stored value is a validnumeric. For more information, see “IsNumeric Function” on page 53.
Variants and ConcatenationIf a string and a number are concatenated, the result is a string. To ensure that a concatenation worksregardless of data type, use the ampersand operator (&). The ampersand operator is not an arithmeticoperator; it will simply concatenate the values as if they were strings.
You can use the IsEmpty function to determine if a variant variable has been previously assigned. Formore information, see “IsEmpty Function” on page 53.
Control StructuresControl structures direct the execution of blocks of statements. Available control structures are Do loops,While loops, For loops, Select Case, If Then, If Then Else, and the branching statement: GoTo.
Chapter 2. Elements 15
Do LoopThe Do loop allows you to execute a block of statements an indefinite number of times. Variations of theDo loop are Do While, Do Until, Do Loop While, and Do Loop Until.
Examples are:Do While condition
statement(s)...Exit Dostatement(s)...
LoopDo Until condition
statement(s)...LoopDo
statement(s)...Loop While conditionDo
statement(s)...Loop Until condition
Do While and Do Until check the condition before entering the loop, thus the block of statements insidethe loop are executed only when those conditions are met. Do Loop While and Do Loop Until check thecondition after executing the block of statements, thereby guaranteeing that the block of statements isexecuted at least once.
While LoopThe While...Wend loop is similar to the Do While loop. The condition is checked before the block ofstatements comprising the loop is executed.
For example:While condition
statements...Wend
For...Next LoopThe For...Next loop has a counter variable and repeats a block of statements a set number of times. Thecounter variable is checked at the beginning of the loop and increases or decreases with each repetitionthrough the loop. The counter default is one if the Step variation is not used.
For example:For counter = beginningvalue To endingvalue [Step increment]
statements...Next
If and Select StatementsThe condition of an If statement can be a comparison or an expression, but it must evaluate to True orFalse. The If...Then block has single line and multiple line syntax.
For example:If condition Then statements... ' single line syntaxIf condition Then
statements... ' multiple line syntaxEnd If
A variation on the If statement is the If...Then...Else statement. Use this statement when differentstatement blocks are to be executed depending on the condition. The If...Then...ElseIf... variationcan become very long. If so, consider using the Select statement.
16 IBM Optim: Optim Basic Language Reference
If condition Thenstatements...
ElseIf condition Thenstatements...
Elsestatements...
End If
The Select Case statement tests one variable for many different values. This statement tends to be easierto read and should be used in place of a complicated If...Then...ElseIf statement.Select Case variable to test
Case 1statements...
Case 2statements...
Case 3statements...
Case Elsestatements...
End Select
GoToThe GoTo statement branches to the label specified in the GoTo statement.
For example:GoTo label1
.
.
.label1:
The program execution jumps to the area that begins with label label1:.
Subroutines and FunctionsA subroutine is a series of statements (enclosed between a Sub statement and an End Sub statement) thatperform actions but do not return a value. A function is a series of statements (enclosed between aFunction statement and an End Function statement) that perform actions and can also return a value.
A subroutine can take arguments (constants, variables, or expressions that are passed by a callingprocedure). For subroutines without arguments, include an empty set of parentheses () with the Substatement.
Similar to a subroutine, a function can take arguments (constants, variables, or expressions that arepassed to it by a calling procedure). For functions without arguments, include an empty set ofparentheses () with the Function statement. A function returns a value by assigning a value to its namein one or more statements of the procedure. The return type of a function is always a variant.
Naming conventions
Subroutine and function names can contain a maximum of 40 characters. Each name can include theletters A to Z and a to z, the underscore “_”, and the digits 0 to 9. However, each name must begin witha letter and cannot be a reserved word.
You can create your own functions or subroutines in Optim Basic or call external DLLs.
To create a subroutine, use the following syntax.
Chapter 2. Elements 17
Sub subname...End Sub
To create a function, use the following syntax .Function funcname As type...funcname = value...End Function
Declare functions in DLLs using the Declare statement.
ByRef and ByValWhen you pass a variable to a function or subroutine, use ByVal or ByRef to specify whether the functionor subroutine has permission to change the value of the passed variable.
If you want to... Then...
prevent the function or subroutine from changing thevalue of the passed variable and to keep the parameterfrom being reassigned outside the local procedure
enter ByVal before the variable name in the statement.
permit the function or subroutine to change the value ofthe passed variable
enter ByRef before the variable name in the statement.
ByRef is the Optim Basic default and needs not be used explicitly. Because ByRef is the default, allvariables passed to other functions or subroutines can be changed unless you use the ByVal keyword toprotect the variable or use parentheses to indicate that the variable is ByVal.
In the next example, the parameter var3 is passed by value and cannot be changed by the subroutineSubOne.SubOne var1, var2, (var3)
In another example, the function R is receiving two parameters, X and n. The second parameter n ispassed by value and the contents cannot be changed from within the function R.Function R( X As String, ByVal n As Integer)
In the following examples, scalar variables are passed by reference and user-defined types are passed byvalue.
Scalar VariablesSub Main
Dim x(5) As IntegerDim i As Integerfor i = 0 to 5
x(i) = inext iPrint iJoe (i), x ' The parentheses around the variable i turn it into an
' expression which passes by valueprint "should be 6: "; x(2), i
End SubSub Joe( ByRef j As Integer, ByRef y() As Integer )
print "Joe: "; j, y(2)j = 345for i = 0 to 5
18 IBM Optim: Optim Basic Language Reference
print "i: "; i; "y(i): "; y(i)next iy(2) = 3 * y(2)
End Sub
Passing user-defined Types by Val to DLLs and functions' This example shows how a native Windows API (OpenFile)' can be defined and used.' OpenFile() StructureType OFSTRUCT
cBytes As String * 1fFixedDisk As String * 1nErrCode As Integerreserved As String * 4szPathName As String * 128
End Type' OpenFile() FlagsGlobal Const OF_READ = &H0Global Const OF_WRITE = &H1Global Const OF_READWRITE = &H2Global Const OF_SHARE_COMPAT = &H0Global Const OF_SHARE_EXCLUSIVE = &H10Global Const OF_SHARE_DENY_WRITE = &H20Global Const OF_SHARE_DENY_READ = &H30Global Const OF_SHARE_DENY_NONE = &H40Global Const OF_PARSE = &H100Global Const OF_DELETE = &H200Global Const OF_VERIFY = &H400Global Const OF_CANCEL = &H800Global Const OF_CREATE = &H1000Global Const OF_PROMPT = &H2000Global Const OF_EXIST = &H4000Global Const OF_REOPEN = &H8000Declare Function OpenFile Lib "Kernel" (ByVal lpFileName As _String, lpReOpenBuff As OFSTRUCT, ByVal wStyle As Integer) _As IntegerSub Main
Dim ofs As OFSTRUCT' Print OF_READWRITEofs.szPathName = "c:\Program Files\Softech\RT\Bin\Default.bas"print ofs.szPathNameofs.nErrCode = 5print ofs.nErrCodeOpenFile "t.bas", ofsprint ofs.szPathNameprint ofs.nErrCode
End Sub
Calling Procedures in DLLsThere are two main ways that Optim Basic can be extended. One way is to call functions and subroutinesin DLLs, and the other way is to call functions and subroutines in Optim.
The mechanisms used for calling either type of procedure is similar. (See “Declare Statement” on page 38for more details.)
To declare a DLL procedure or a procedure in Optim, place a declare statement in your declares file oroutside the code area. All declarations are Global to the run and accessible by all subroutines andfunctions. If the procedure does not return a value, declare it as a subroutine. If the procedure has areturn value, declare it as a function.Declare Sub InvertRect Lib “User”
(ByVal hDC AS Integer, _aRect As Rectangle)
Chapter 2. Elements 19
Declare Function GetPrivateProfileString Lib "Kernel32" _(ByVal lpApplicationName As String, _ByVal lpKeyName As String, _ByVal lpDefault As String, _ByVal lpReturnedString As String, _ByVal nSize As Integer, _ByVal lpFileName As String) As Integer
Note the continuation character, the underscore “ _ ”, that is used in the previous Declare statements.
After a procedure is declared, you can call it as you would another function.
Note: Optim cannot verify that you are passing correct values to a DLL procedure. If you pass incorrectvalues, the procedure might fail or produce unpredictable results.
File Input/OutputOptim Basic supports full sequential and binary file I/O.
The following functions and statements apply to file access:
Dir EOF FileCopy FileLen
Seek Open Close Input
Line Input Print Write
File I/O examples are:Sub Main
Open "TESTFILE" For Input As #1 ' Open file.Do While Not EOF(1) ' Loop until end of file.
Line Input #1, TextLine ' Read into variable.Print TextLine ' Print .
LoopClose #1 ' Close file.
End SubSub test
Open "MYFILE" For Input As #1 ' Open file for input.Do While Not EOF(1) ' Check for end of file.
Line Input #1, InputData ' Read line of data.Print InputData
LoopClose #1 ' Close file.
End SubSub FileIO_Example()
Dim Msg ' Declare variable.Call Make3Files( ) ' Create data files.Msg = "Several test files have been created on your disk."Msg = Msg & "Choose OK to remove the test files."Print MsgFor I = 1 To 3
Kill "TEST" & I ' Remove data files.Next I
End SubSub Make3Files ( )
Dim I, FNum, FName ' Declare variables.For I = 1 To 3
FNum = FreeFile ' Determine next file #.FName = "TEST" & FNumOpen FName For Output As FNum ' Open file.Print #I, "This is test #" & I ' Write to file.
20 IBM Optim: Optim Basic Language Reference
Print #I, "Here is another "; "line"; INext IClose ' Close all files.
End Sub
ArraysOptim Basic supports single and multi-dimensional arrays. Using arrays, you can refer to a series ofvariables by the same name, each with a separate index.
All arrays have upper and lower bounds. Optim Basic allocates space for each index number in the array.To avoid wasting memory, declare arrays so that they are only as large as you need.
All elements in an array must have the same data type. You can use the following data types in an array:v Byte
v Boolean
v Long
v Integer
v Single
v Double
v String
v Variant
You can also define a type and define the array in terms of the user-defined data type.
Generally, to declare a fixed-size array, complete one of the following:v Create a global array by using the Dim statement outside the procedure section of a code module.v Create a local array by using the Dim statement inside a procedure.
Single ArraysTo declare an array, follow the array name with the upper bound in parentheses. The upper bound mustbe an integer.
For example:Dim ArrayName (10) As IntegerDim Sum (20) As Double
To create a global array, simply declare the array outside the procedure:Dim Counters (12) As IntegerDim Sums (22) As DoubleSub Main ( ) ...
The same declarations within a procedure use Static or Dim:Static Counters (12) As IntegerStatic Sums (22) As Double
The first declaration creates an array with 12 elements, and index numbers running from 0 to 11. Thesecond creates an array with 22 elements. To change the default lower bound to 1, place an Option Basestatement in the Declarations section of a module:Option Base 1
Another way to specify the lower bound is to provide it explicitly (as an integer, in the range -32 768 to32 767) using the To keyword:
Chapter 2. Elements 21
Dim Counters (1 To 13) As IntegerDim Sums (100 To 126) As String
In the preceding declarations, the index numbers of Counters run from 1 to 13, and the index numbers ofSums run from 100 to 126.
Note: You must declare an array before using it.
Loops often provide an efficient way to manipulate arrays. For example, the following For loop initializesall elements in the array to 5:Static Counters (1 To 20) As IntegerDim I As Integer
For I = 1 To 20Counter ( I ) = 5
Next I...
Multi-Dimensional ArraysOptim Basic supports arrays with any number of dimensions.
The following example declares a two-dimensional array within a procedure:Static Mat(20, 20) As Double
Either or both dimensions can be declared with explicit lower bounds:Static Mat(1 to 10, 1 to 10) As Double
You can efficiently process a multidimensional array with the use of For loops. In the followingstatements, the elements in a multidimensional array are set to a value:Dim L As Integer, J As Integer
Static TestArray(1 To 10, 1 to 10) As DoubleFor L = 1 to 10
For J = 1 to 10TestArray(L,J) = I * 10 + J
Next JNext L
The following is an example of a three-dimensional array.Dim ArrTest(5, 3, 2)
This declaration creates an array that has three dimensions with sizes 6 by 4 by 3, unless Option Base 1is set previously in the code. The use of Option Base 1 sets the lower bound of all arrays to 1 instead of0.
User-Defined TypesYou can define types that are composites of other built-in or user-defined types. Variables of these newcomposite types can be declared; then, member variables of the new type can be accessed using dotnotation. Only variables of user-defined types that contain simple data types can be passed to DLLfunctions expecting ‘C' structures.
You create user-defined types using the Type statement, which must be placed outside the procedure inyour code. User-defined types are global; however, variables declared as user-defined types can be eitherglobal or local. User-defined types in Optim Basic cannot contain arrays.Type type1
a As Integerd As Doubles As String
22 IBM Optim: Optim Basic Language Reference
End TypeType type2
a As Integero As type1
End TypeDim type2a As type2Dim type1a As type1Sub TypeExample ()
a = 5type1a.a = 7472type1a.d = 23.1415type1a.s = "YES"type2a.a = 43type2a.o.s = "Hello There"Print type1a.aPrint type1a.dPrint type1a.sPrint type2a.aPrint type2a.o.sPrint a
End Sub
OLE FundamentalsObject Linking and Embedding (OLE) is a technology that allows a programmer of Windows-basedapplications to create an application that can display data from many different applications. OLE lets youedit the data within the source applications or edit the data within your own application.
OLE Objects
An OLE object is a discrete unit of data supplied by an OLE application. An application can expose manytypes of objects. For example, a spreadsheet application can expose a worksheet, macro sheet, chart, cell,or range of cells, each as a different type of object. You use the OLE control to create linked andembedded objects. After a linked or embedded object is created, the object contains the name of theapplication that supplied the object, its data (or, in the case of a linked object, a reference to the data),and an image of the data.
OLE Automation
Some applications provide objects that support OLE Automation. You can use Optim Basic toprogrammatically manipulate the data in these objects. Some objects that support OLE Automation alsosupport linking and embedding. You can create an OLE Automation object by using the CreateObjectfunction.
Class
The class of an object determines the application that provides the data and the type of data the objectcontains. The class names of some commonly used Microsoft applications include MSGraph, MSDraw,WordDocument, and Excel spreadsheet.
OLE Automation and Microsoft Word exampleSub OLEexample( )
Dim word As ObjectDim myData As StringmyData = 4 * Atn(1) ' Demonstrates Automatic type conversionSet word = CreateObject("Word.Basic")Word.AppShowword.FileNewDefaultword.Insert "The following was computed in RT for Servers: "word.Bold 1 ' Show value in boldface
Chapter 2. Elements 23
word.Insert myDataword.Bold 0Print "Done"
End Sub
OLE ObjectsAn OLE Automation Object is an instance of a class within your application that you wish to manipulateprogrammatically, as with a Column Map Procedure. These might be new classes whose sole purpose isto collect and expose data and functions in a way that makes sense to your end users.
An OLE Object becomes programmable when you expose those member functions. OLE Automationdefines two types of members that you can expose for an object:v Methods are member functions that perform an action on an object. For example, a Document object
might provide a Save method.v Properties are member function pairs that set or return information about the state of an object. For
example, a Drawing object might have a style property.
The following objects can be exposed by implementing the listed methods and properties for each object:
OLE Automation Object Methods Properties
Application Help ActiveDocument
Quit Application
Add Data Caption
Repeat DefaultFilePath
Undo Documents
Height
Name
Parent
Path
Printers
StatusBar
Top
Value
Visible
Width
24 IBM Optim: Optim Basic Language Reference
OLE Automation Object Methods Properties
Document Activate Application
Close Author
NewWindow Comments
Print FullName
PrintPreview Keywords
RevertToSaved Name
Save Parent
SaveAs Path
ReadOnly
Saved
Subject
Title
Value
To provide access to more than one instance of an object, expose a collection object. A collection objectmanages other objects. All collection objects support iteration over the objects they manage. For example,an application with a multiple document interface (MDI) might expose a Documents collection objectwith the following methods and properties:
Collection Object Methods Properties
Documents Add Application
Close Count
Item Parent
Open
OLE AutomationOLE Automation is a standard that applications use to expose OLE objects to development tools andcontainers that support OLE Automation.
For example, a spreadsheet application might expose a worksheet, chart, cell, or range of cells, each as adifferent type of object. A word processor might expose objects such as application, paragraph, sentence,bookmark, or selection.
When an application supports OLE Automation, the objects it exposes can be accessed by a Column MapProcedure. You can manipulate these objects by invoking methods on the object, or by getting and settingthe properties, just as you would with the objects in Optim.
For example, if you created an OLE Automation object named MyObj, you might write the following codeto manipulate the object:Sub Main
Dim MyObj As ObjectSet MyObj = CreateObject ("Word.Basic")MyObj.FileNewDefaultMyObj.Insert "Hello, world."MyObj.Bold 1
End Sub
Chapter 2. Elements 25
The following syntax is supported for the GetObject function, where class is the parameter representingthe class of the object to retrieve. The first parameter must be an empty string.Set MyObj = GetObject ("", class)
Note: The properties and methods an object supports are defined by the application that created theobject. See application documentation for details on the properties and methods it supports.
Accessing an OLE object
The following functions and properties allow you to access an OLE Automation object:v The CreateObject Function creates a new object of a specified type.v The GetObject Function retrieves an object pointer to a running application.
Making Applications Work TogetherMany operations, such as linking and object embedding, need applications to work together in acoordinated fashion. However, there is no way that Windows can be set up, in advance, to accommodateall applications and dynamic link libraries that can be installed. Even within an application, the user hasthe ability to select various components to install.
As part of the installation process, Windows requires that applications supporting DDE/OLE featuresregister the support by storing information in several locations. The most important of these is theregistration database.
Registration DatabaseEach Windows system maintains a Registration Database file (REG.DAT) that records details about the DDEand OLE functions supported by the installed applications. The registration database is a file calledREG.DAT in the \WINDOWS directory.
The REG.DAT database contains information that controls a variety of activities relating to data integrationusing DDE and OLE. The information in the registration database can be divided into four basiccategories.v Associations
Information in this table associates files with specific extensions to particular applications. Thisfunction is essentially the same as that performed by the Extensions section of the WIN.INI file.
v Shell OperationsTwo Windows programs are referred to as Shell programs, or programs that organize basic operatingsystem tasks, like running applications, opening files, and sending files to the printer. Shell programsuse lists, windows, menus, and dialog boxes to perform these operations. In contrast, a commandsystem, like DOS, requires the entry of explicit command lines to accomplish these tasks.
v OLE Object ServersREG.DAT maintains a highly structured database of details needed by programs that operate as objectservers. This is by far the most complex task performed by REG.DAT. There is no WIN.INI equivalent forthis function.
v DDE/OLE AutomationREG.DAT contains the details and applications that support various types of DDE/OLE Automationoperations.
Differences between WIN.INI and REG.DAT
The key difference between the WIN.INI file and the REG.DAT database is that WIN.INI is an unstructuredtext document and REG.DAT is a tree-like, structured database. The WIN.INI file uses no special structuresother than headings (simply titles enclosed in brackets) to organize the information. If you want to locatean item in the WIN.INI file, you must search the file for the specific item. REG.DAT is a tree-like, structured
26 IBM Optim: Optim Basic Language Reference
database used for storing information relating to program and file operations that, in particular, involvethe use of DDE or OLE. The tree structure organizes the complex set of instructions needed to implementDDE and OLE operations, and makes them accessible to the applications that need to use them. Thisorganization is not possible with a text document like WIN.INI. The WIN.INI file records informationabout the Windows system in a simple sequential listing.
Chapter 2. Elements 27
28 IBM Optim: Optim Basic Language Reference
Chapter 3. Functions and Statements
This section describes the functions and statements in Optim Basic that you can use when writingprograms. The functions and statements are listed alphabetically.
The syntax used to describe the functions and statements is as follows:
text Variable text is shown in lowercase italics.
( ) Argument lists (in other words, variables, constants, or expressions) passed as parameters to afunction or statement are enclosed in parentheses. Separate multiple parameters with commas.
" Strings and literals are enclosed in double quotation marks.
[ ] Indicates an optional parameter. (Square brackets are not actually used in the command line.)
{ } Indicates a choice of two or more settings from which one (and only one) must be selected.(Brackets are not actually used in the command line.)
| Separates options. (The pipe symbol is not actually used in the command line.)
Abs FunctionThe Abs function returns the absolute value of a number.Abs (number)
The data type of the return value is the same as that of the number argument. However, if the numberargument is a Variant of VarType (String) and can be converted to a number, the return value will be aVariant of VarType (Double). If the numeric argument results in Null, the return is Null.
ExampleSub Main
Dim Msg X, YX = InputBox ("Enter a Number:")Y = Abs (X)Msg = “The number you entered is " & XMsg = Msg + " . The absolute value of " & X & " is " & YPrint Msg ' Print Message.
End Sub
AppActivate StatementThe AppActivate statement activates an application.AppActivate "appname"
The argument appname is the name in the title bar of the activated application window.
ExampleSub Main ( )
AppActivate "Microsoft Word"SendKeys "%F, %N, RT for Servers", TrueMsg = "Click OK to close Word"Print MsgAppActivate "Microsoft Word"SendKeys "%F, %C, N", True
End Sub
© Copyright IBM Corp. 1994, 2010 29
Asc FunctionReturns the ASCII code for the first character in a string as a numeric value.Asc (str)
ExampleSub Main ( )
Dim I, Msg ' Declare variables.For I = Asc ("A") To Asc ("Z") ' From A through Z.
Msg = Msg & Chr ( I ) ' Create a string.Next IPrint Msg ' Print results.
End Sub
Atn FunctionThe Atn function returns the arc tangent of a number in radians.Atn (rad)
The argument rad can be any numeric expression.
ExampleSub AtnExample ( )
Dim Msg, Pi ' Declare variables.Pi = 4 * Atn ( 1 ) ' Calculate Pi.Msg = "Pi is equal to " & Str (Pi)Print Msg ' Print results.
End Sub
Call StatementThe Call statement activates a subroutine or a DLL function.
Syntax 1Call name [(argument list)]
Syntax 2name [argument list]
The argument name is the name of the subroutine or DLL function. The argument argument list is the listof arguments passed to the called function or subroutine.
You are not required to use the Call statement when calling a subroutine or a DLL function. If you usethe Call statement, parentheses are required when using argument list. If you omit the Call statement,you also must omit the parentheses around argument list.
CBool FunctionThe CBool function converts a valid string or numeric expression to Boolean.CBool (expression)
ExampleSub Main
Dim A, B, CheckA = 5: B = 5Check = CBool (A = B)Print Check
30 IBM Optim: Optim Basic Language Reference
A = 0Check = CBool (A)Print Check
End Sub
CDate FunctionThe CDate function converts any valid expression to a Date variable with a VarType of 7.CDate (expression)
The argument expression must be a valid string or numeric date that represents a date from January 1,0030 through December 31, 9999.
ExampleSub Main
Dim MyDate, MDate, MTime, MSTimeMyDate = "May 29, 1959" ' Define date.MDate = CDate (MyDate) ' Convert to Date data type.MTime = "10:32:27 PM" ' Define time.MSTime = CDate(MTime) ' Convert to Date data type.Print MDatePrint MSTime
End Sub
CDbl FunctionThe CDbl function converts a valid string or numeric expression to double.CDbl (expression)
ExampleSub Main ( )
Dim y As Integery = 25555 ' The integer expression allows 5 digits.If VarType ( y ) = 2 Then
Print yx = CDbl ( y ) ' Converts the integer value of y to a double
' value in x.x = x * 100000 ' y is now 10 digits in the form of x.Print x
End IfEnd Sub
ChDir StatementThe ChDir statement changes the default directory.ChDir pathname
The argument pathname is a variable or a literal string limited to fewer than 128 characters with thefollowing format:
[drive:] [ \ ] dir[\dir]...
The drive parameter is optional. The dir parameter is a directory name. ChDir changes the defaultdirectory on the current drive, if the drive is omitted.
ExampleSub Main ( )
Dim Answer, Msg, NL ' Declare variables.NL = Chr (10) ' Define newline.
Chapter 3. Functions and Statements 31
CurPath = CurDir ( ) ' Get current path.ChDir " \ "Msg = "The current directory has been changed to"Msg = Msg & CurDir ( ) & NL & NL & "Press OK to change back"Msg = Msg & "to your previous default directory."Answer = Print (Msg) ' Get user response.ChDir CurPath ' Change back to user default.Msg = "Directory changed back to " & CurPath & "."Print Msg ' Print results.
End Sub
ChDrive StatementThe ChDrive statement changes the default drive.ChDrive drivename
The argument drivename is a string that corresponds to an existing drive. If drivename is more than onecharacter, the first character is used.
ExampleSub Main ( )
Dim Msg NL ' Declare variable.NL = Chr (10) ' Define newline.CurPath = CurDir ( ) ' Get current path.ChDir " \ "ChDrive "C:"Msg = "The current directory has been changed to"Msg = Msg & CurDir ( ) & NL & NL & "Press ok to change back"Msg = Msg & "to your previous default directory."Print Msg ' Get user response.ChDir CurPath ' Change back to user default.Msg = "Directory changed back to" % CurPath & "."Print Msg ' Print results.
End Sub
Choose FunctionThe Choose function returns a value from a list of arguments.Choose (number, choice1[, choice2][, choice3]...)
Choose will return a Null value if number is less than one or greater than the number of choices in the list.If number is not an integer it will be rounded to the nearest integer.
ExampleSub Main
number = 2GetChoice = Choose (number, "Choice1", "Choice2", "Choice3")Print GetChoice
End Sub
Chr FunctionThe Chr function returns a one-character string whose ASCII number is the argument.Chr (int)
ExampleSub ChrExample ( )
Dim X, Y, Msg, NLNL = Chr (10)For X = 1 to 2
32 IBM Optim: Optim Basic Language Reference
For Y = Asc ("A") To Asc ("Z")Msg = Msg & Chr (Y)
Next YMsg = Msg & NL
Next XPrint Msg
End Sub
CInt FunctionThe Clnt function converts any valid expression to an integer.CInt (expression)
ExampleSub Main ( )
Dim y As Longy = 25Print VarType (y)If VarType (y) = 3 Then
Print yx = CInt (y) ' Converts the long value of y to an integer
' value in x.Print xPrint VarType (x)
End IfEnd Sub
CLng FunctionConverts any valid expression to a long integer data type.CLng (expression)
ExampleSub Main ( )
Dim y As Integery = 25000 ' The integer expression can hold only five
' digits.If VarType (y) = 2 Then
Print yx = CLng (y) ' Converts the integer value of x to a long
' value in x.x = x * 10000 ' y is now ten digits in the form of x.Print x
End IfEnd Sub
Close StatementCloses the designated file (or closes all open files, if no argument is specified).Close [ [ # ] filenumber ] [, [ # ] filenumber ]...
The filenumber argument is the number used to open the file with the Open statement. Use Close with noarguments to close all open files.
ExampleSub Main
Open "c:\test.txt" For Input As #1Do While Not EOF (1)
My Str = Input (10, #1)Print MyStr
Chapter 3. Functions and Statements 33
LoopClose #1
End SubSub Make3Files ( )
Dim I, FNum, FName ' Declare variables.For I = 1 to 3
FNum = FreeFile ' Determine next file number.FName = "TEST" & FNumOpen FName For Output As FNum ' Open file.Print #I, "This is test #" & IPrint #I, "Here is another"; "line"; I
Next IClose ' Close all files.
End Sub
Const StatementAssigns a symbolic name to a constant value. A constant must be defined before it is used.Const name = expression
The definition of a Const in Optim Basic outside the procedure or at the module level is global. A typedeclaration character may be used; however, if none is used, one of the following data types will beassigned to the constant:v Long (if it is a long or integer)v Double (if a decimal place is present)v String (if it is a string)
ExampleGlobal Const Height = 14.4357
Cos FunctionReturns the cosine of an angle.Cos (rad)
The argument rad is a valid numeric expression in radians. Cos returns a double unless the return valueis specified as a single or integer.
ExampleSub Main ( )
Dim J As DoubleDim I As Single ' Declare variables.Dim K As IntegerFor I =1 to 10
Msg = Msg & Cos ( I ) & "," ' Cos function call.J = Cos ( I )Print JK = Cos ( I )Print K
Next IPrint Msg ' Print results.Print Msg1
End Sub
CreateObject FunctionCreates an OLE automation object.CreateObject (class)
34 IBM Optim: Optim Basic Language Reference
ExampleSub Command1_Click ( )
Dim word6 As objectSet word6 = CreateObject ("Word.Basic")word6.FileNewDefaultword6.InsertParaword6.Insert "Attn:"word6.InsertParaword6.InsertParaword6.InsertParaword6.Insert "Table Name:"word6.Bold 0name = "Some Body"word6.Insert nameword6.Bold 0word6.InsertParaword6.InsertParaword6.InsertParaword6.InsertParaword6.Insert "text of letter"word6.InsertParaword6.InsertPara
End Sub
CSng FunctionConverts any valid expression to a single.CSng (expression)
ExampleSub Main ( )
Dim y As Integery = 25If VarType(y) = 2 Then
Print yx = CSng(y) ' Converts the integer value of y to a single
' value in x.Print x
End IfEnd Sub
CStr FunctionConverts any valid expression to a string.CStr (expression)
ExampleSub Main
Dim Y As IntegerY = 25Print YIf VarType (Y) = 2 Then
X = CStr (Y) ' Converts Y To a Str.X = X + "hello" ' It is now possible to combine Y with strings.Print X
End IfEnd Sub
Chapter 3. Functions and Statements 35
CurDir FunctionReturns the current path for the specified drive.CurDir[$] ([drive])
CurDir returns a variant; CurDir$ returns a string.
Example' Declare Function CurDir Lib "NewFuns.dll" ( ) As StringSub Form_Click ( )
Dim Msg, NL ' Declare variable.NL = Chr (10) ' Define newline.Msg = "The current directory is: "Msg = Msg & NL & CurDir ( )Print Msg ' Print message.
End Sub
CVar FunctionConverts any valid expression to a variant.CVar (expression)
ExampleSub Main
Dim MyInt As IntegerMyInt = 4534Print MyIntMyVar = CVar (MyInt & "0.23") ' Makes MyInt a Variant + 0.23.Print MyVar
End Sub
Date FunctionReturns the current system date.Date [( )]
Date returns a string variant containing a date.
ExampleSub Main
x = Date ( )Print DatePrint xPrint "VarType: " & VarType (Date)MyTime = "08:04:23 PM"MyDate = "03/03/95"MyDate = "January 27, 1993"SysDate = DatePrint Sysdate, 0, "System Date"Print Now, 0, "Now"Print MyTime, 0, "MyTime"Print Second ( MyTime ) & "Seconds"Print Minute ( MyTime ) & "Minutes"Print Hour ( MyTime ) & "Hours"Print Day ( MyDate ) & "Days"Print Month ( MyDate ) & "Months"Print Year ( MyDate ) & "Years"' Returns current system time in the system-defined long time' format.Print Format (Time, "Short Time") & "Short Time"
36 IBM Optim: Optim Basic Language Reference
Print Format (Time, "Long Time") & "Long Time"' Returns current system date in the system-defined long date' format.Print Format (Date, "Short Date") & "Short Date"Print Format (Date, "Long Date") & "Long Date"MyDate = "30 December 91" ' use of European date.Print MyDatePrint MyDate, 0, "MyDate International..."Print Day (MyDate), 0, "day"Print Month (MyDate), 0, "month"Print Year (MyDate), 0, "year"Print = "30-December-91" ' another European date usage.Print MyDatePrint MyDate, 0, "MyDate International..."Print Day (MyDate), 0, "day"Print Month (MyDate), 0, "month"Print Year (MyDate), 0, "year"Print Format ("This is it", ">") ' Returns "THIS IS IT".
End Sub
DateSerial FunctionReturns a Date variant corresponding to the year, month and day that were passed in.DateSerial (year, month, day)
All three parameters are required and must be valid.
ExampleSub Main
Dim MDateMDate = DateSerial(1959, 5, 29)Print MDate
End Sub
DateValue FunctionReturns a Date variant corresponding to the string date expression that was passed in.DateValue (dateexpression)
The argument dateexpression can be a string or any expression that can represent a date, a time, or both.
ExampleSub Main( )
Dim v As VariantDim d As Doubled = NowPrint dv = DateValue("1999/05/29")Print (VarType(v))Print (v)
End Sub
Day FunctionReturns a Date variant corresponding to the string date expression that was passed in.Day (dateexpression)
The argument dateexpression can be a string or any expression that can represent a date.
Chapter 3. Functions and Statements 37
ExampleSub Main
Dim MDate, MDayMDate = #May 29, 1959#MDay = Day(MDate)Print "The Day listed is the " & MDay
End Sub
Declare StatementRefers to an external procedure in a Dynamic Link Library (DLL).
Syntax 1Declare Sub procname Lib libname [Alias aliasname][(argument list)]
Syntax 2Declare Function procname Lib libname [Alias aliasname][(argument list)][As type]
The argument procname is the name of the function or subroutine being called. The argument libname isthe name of the DLL that contains the procedure.
Use the optional Alias aliasname clause to supply the procedure name in the DLL if it is different fromthe name specified on the procedure parameter. To pass the optional argument list, use the followingformat:([ByVal] variable [As type] [,ByVal] variable [As type]...)
The optional ByVal parameter specifies that the variable is passed by value instead of by reference. Theoptional As type parameter is used to specify the data type. Valid data types are string, integer, double,long, and variant.
If a procedure has no arguments, use only double parentheses ( ) to ensure that no arguments arepassed. For example:Declare Sub OntTime Lib “Check” ( )
ExampleDeclare Function GetFocus Lib "User" () As IntegerDeclare Function GetWindowText Lib "User" (ByVal hWnd%, _
ByVal Mess$, ByVal cbMax%) As IntegerSub Main
Dim hWindow%Dim str1 As String *51Dim str2 As String * 25hWindow% = GetFocus()print "GetWindowText returned: ", GetWindowText _
( hWindow%, str1,51 )print "GetWindowText2 returned: ", GetWindowText _
( hWindow%, str2, 25)print str1print str2
End Sub
Dim StatementAllocates storage for and declares variables and arrays in a module.Dim variablename [([subscripts])] [As type] [,variablename [([subscripts])] [As type] ]...
The argument variablename is the name of the variable being declared. The optional subscriptsargument declares the dimensions of an array. The optional As type argument specifies the data type.
38 IBM Optim: Optim Basic Language Reference
Supported data types are:v Bytev Booleanv Currencyv Datev Doublev Integerv Longv Objectv Singlev Stringv Variant
ExampleSub Main
Dim x As LongDim y As IntegerDim z As SingleDim a As DoubleDim s As StringDim v As Variant ' This is the same as Dim x or Dim x as any
End Sub
Dir FunctionReturns a file/directory name that matches the given path and attributes.Dir[(path [,attributes])]
ExamplePrint Dir( "c:\Windows\*.bmp" )
Do...Loop StatementRepeats a group of statements while a condition is true or until a condition is met.
Syntax 1Do [{While|Until} condition]
[statements][Exit Do][statements]
Loop
Syntax 2Do
[statements][Exit Do][statements]
Loop [{While|Until} condition]
ExampleSub Main ( )
Dim Value, Msg ' Declare variables.Do
Value = InputBox("Enter a value from 5 to 10.")If Value >= 5 And Value <= 10 Then
Chapter 3. Functions and Statements 39
Exit Do ' Exit Do...Loop.Else
Msg = “Not in range” ' Msg if not in range.Print Msg
End IfLoop
End Sub
End StatementEnds a program or a block of statements, such as a function or a subroutine.End [{Function | If | Select | Type | With | Sub }]
ExampleSub Main()
Dim Var1 as StringVar1 = "hello"Print "Calling Test"Test Var1Print Var1
End SubSub Test (wvar1 as string)
wvar1 = "goodbye"Print "Use of End Statement"End
End Sub
EOF FunctionReturns a value during file input that indicates whether the end of a file has been reached.EOF(Filenumber)
Example' This example uses the Input function to read 10 characters at a' time from a file and print them. This example assumes that' TESTFILE is a text file with a few lines of sample data.Sub Main
Open "TESTFILE" For Input As #1 ' Open file.Do While Not EOF(1) ' Loop until end of file.
MyStr = Input(10, #1) ' Get ten characters.Print MyStr
LoopClose #1 ' Close file.
End Sub
Erase StatementReinitializes the elements of a fixed array.Erase arrayname [,arrayname ]
Example' This example demonstrates some of the features of arrays. The' lower bound for an array is 0 unless it is specified or option base' sets it as in this example.Option Base 1Sub Main
' Declare array variables.Dim Num(10) As Integer ' Integer array.Dim StrVarArray(10) As String ' Variable-string array.Dim StrFixArray(10) As String * 10 ' Fixed-string array.Dim VarArray(10) As Variant ' Variant array.
40 IBM Optim: Optim Basic Language Reference
Dim DynamicArray() As Integer ' Dynamic array.ReDim DynamicArray(10) ' Allocate storage space.Erase Num ' Each element set to 0.Erase StrVarArray ' Each element set to
' zero-length string ("").Erase StrFixArray ' Each element set to 0.Erase VarArray ' Each element set to Empty.Erase DynamicArray ' Free memory used by array.
End Sub
Exit StatementExits a loop or procedure.Exit {Do | For | Function | Sub}
Example' This sample shows Do ... Loop with Exit Do to get out.Sub Main ( )
Dim Value, Msg ' Declare variables.Do
Value = InputBox("Enter a value from 5 to 10.")If Value >= 5 And Value <= 10 Then ' Check range.
Exit Do ' Exit Do...Loop.Else
Msg = "Not in range"Print Msg ' Print message.
End IfLoop
End Sub
Exp FunctionReturns the base of the natural log raised to a power (e ^ num). The value of the constant e isapproximately 2.71828.Exp (num)
ExampleSub ExpExample ()
' Exp(x) is e ^x so Exp(1) is e ^1 or e.Dim Msg, ValueOfE ' Declare variables.ValueOfE = Exp(1) ' Calculate value of e.Msg = "The value of e is " & ValueOfEPrint Msg ' Print message.
End Sub
FileCopy StatementCopies a file from a source to a destination.FileCopy (sourcefile, destinationfile)
The sourcefile and destinationfile arguments are valid string expressions. The argument sourcefile isthe name of the file to copy. The argument destinationfile is the target file name.
ExampleDim SourceFile, DestinationFileSourceFile = "SRCFILE" ' Define source file name.DestinationFile = "DESTFILE" ' Define target file name.FileCopy SourceFile, DestinationFile ' Copy source to target.
Chapter 3. Functions and Statements 41
FileLen FunctionReturns a Long integer that is the length of the file in bytes.FileLen (filename)
ExampleSub Main
Dim MySizeMySize = FileLen("C:\TESTFILE") ' Returns file length (bytes).Print MySize
End Sub
Fix FunctionReturns the integer portion of a number.Fix (number)
ExampleSub Main
Dim MySizeMySize = Fix(4.345)Print MySize
End Sub
For Each...Next StatementExecutes the group of statements for each element in an array of a collection. For Each...Next statementscan be nested if each loop element is unique.For Each element in group
[statements][Exit For][statements]
Next [element]
Note: The For Each...Next statement cannot be used with an array of user-defined types.
ExampleSub Main
dim z(1 to 4) as doublez(1) = 1.11z(2) = 2.22z(3) = 3.33For Each v In z
Print vNext v
End Sub
For...Next StatementExecutes a block of statements for a specified number of times.For counter = expression1 to expression2 [Step increment]
[statements]Next [counter]
ExampleSub Main ( )
Dim x,y,zFor x = 1 to 5
42 IBM Optim: Optim Basic Language Reference
For y = 1 to 5For z = 1 to 5
Print "Looping" ,z,y,xNext z
Next yNext x
End Sub
Format FunctionFormats a string, number, or variant data type to a format expression.Format[$] (expression [,fmt ] )
expressionExpression to be formatted.
fmt A string of characters that specify how the expression is to be displayed. Do not mix formatexpressions with different types in a single fmt parameter.
If the fmt parameter is omitted or is zero-length, and the expression is numeric, Format[$] converts thenumeric value to the appropriate return data type. Positive numbers converted to strings using Format[$]lack the leading space reserved for the sign of the value; however, those converted using Str[$] retainthe leading space.
To format numbers, you can use formats that have been predefined in Optim Basic. You can also createformats with standard characters that have special meaning when used in a format expression.
Predefined Numeric Formats
The following are predefined numeric format names:
General NumberFormat the number as it is, with no 000 separators.
Fixed Format at least one digit to the left and two digits to the right of the decimal separator.
StandardFormat the number with 000 separator, if appropriate. Include two digits to the right of thedecimal separator.
PercentFormat number multiplied by 100 with a percent sign (%) appended to the right. Include twodigits to the right of the decimal separator.
ScientificUse standard scientific notation.
True/FalseFalse if number is 0; otherwise, True.
User-Defined Numeric Formats
The following list shows the characters you can use to create user-defined numeric formats:
CharacterMeaning
Null stringNo formatting.
0 Digit placeholder for a digit or a zero.
Chapter 3. Functions and Statements 43
Notes:
v If a number has fewer digits than zeros (on either side of the decimal) in the format expression,leading or trailing zeros are added.
v If a number has more digits to the right of the decimal separator than zeros in the formatexpression, the number is rounded to the number of decimal places for which there are zeros.
v If a number has more digits to left of the decimal separator than zeros in the formatexpression, the extra digits are displayed without modification.
# Digit placeholder. Displays a digit or nothing. If a digit is in the position where the # appears inthe format string, it is displayed. Otherwise, nothing is displayed.
. Decimal placeholder. Determines the number of digits displayed to the left and right of thedecimal separator.
% Percentage placeholder. Multiplies the expression by 100.
, 000 separator. Separates thousands from hundreds within a number that has four or more placesto the left of the decimal separator.
To use this separator in the format statement, specify a comma surrounded by digit placeholders(0 or #). Two adjacent commas or a comma immediately to the left of the decimal separator(whether or not a decimal is specified) means “scale the number by dividing it by 1000, roundingas needed.”
E-E+e-e+Scientific format. If the format expression contains at least one digit placeholder (0 or #) to theright of E-, E+, e- or e+, the number is displayed in scientific format with E or e inserted betweenthe number and its exponent. The number of digit placeholders to the right determines thenumber of digits in the exponent. Use E- or e- to place a minus sign next to negative exponents.Use E+ or e+ to place a plus sign next to positive exponents.
: Time separator. The actual character used as the time separator depends on the Time Formatspecified in the International section of the Control Panel.
/ Date separator. The actual character used as the date separator depends on the Date Formatspecified in the International section of the Control Panel.
- + $ () spaceA literal character. To include a character other than one listed, precede it with a backslash (\).
\ Include the next character in the format string. The backslash is not included. To include abackslash, use two backslashes (\\).
Examples of characters that cannot be literal characters are the date- and time-formattingcharacters (a, c, d, h, m, n, p, q, s, t, w, y, and /:), the numeric-formatting characters (#, 0, %, E, e,comma, and period), and the string-formatting characters (@, &, <, >, and !).
“String”Include the string inside double quotation marks. To include a string in fmt, use the ANSI codefor a double quotation mark Chr(34) to enclose the text.
* Use the next character as the fill character. Any empty space in a field is filled with the characterfollowing the asterisk.
Multiple Formats
Unless the fmt argument contains a predefined format, an expression can include from one to fourformats separated by semicolons. If you use:v One format only—the expression applies to all values.v Two formats—the first format applies to positive values. The second applies to negative values.
44 IBM Optim: Optim Basic Language Reference
v Three formats—the first format applies to positive values, the second applies to negative values, andthe third applies to zeros.
v Four formats—the first format applies to positive values, the second applies to negative values, thethird applies to zeros, and the fourth applies to Null values.
The following example has two formats: the first is the format for positive values and zeros; the second isthe format for negative values.
“$#,##0; ($#,##0)”
You can include semicolons with nothing between them as place holders. For example, the followingformat displays positive and negative values using the first format and displays “Zero” if the value iszero.
“$#,##0;;\Z\e\r\o”
Sample Numeric Formats
The following examples assume that, in the International section of the Control Panel, the Country is setto United States. The first column shows the format strings. The remaining columns show the result if theformatted data has the value shown in the column headings.
Format (fmt) Positive 3 Negative 3 Decimal .3 Null
Null string 3 -3 0.3
0 3 -3 1
0.00 3.00 -3.00 0.30
#,##0 3 -3 1
#,##0.00;;;Nil 3.00 -3.00 0.30 Nil
$#,##0;($#,##0) $3 ($3) $1
0% 300% -300% 30%
0.00% 300.00% -300.00% 30.00%
0.00E+00 3.00E+00 -3.00E+00 3.00E-01
Predefined Date/Time Formats
You can also use numbers to represent date and time information. You can format date and time serialnumbers using date and time formats or using number formats because date/time serial numbers arestored as floating-point values.
To format dates and times, you can use either a commonly used format that has been predefined orcreate a time format. The following list shows the names of predefined date formats you can use, anddescribes each format.
Format NameDescription
GeneralA date and/or time (for example, 4/3/93 03:34 PM). If there is no fractional part, display only adate (for example, 4/3/93). If there is no integer part, display time only (for example, 03:34 PM).
Long DateA Long Date, as defined in the International section of the Control Panel.
Chapter 3. Functions and Statements 45
MediumA date in the form of the Short Date, as defined in the International section of the Control Panel,but spell out the month abbreviation.
Short DateA Short Date, as defined in the International section of the Control Panel.
Long TimeA Long Time, as defined in the International section of the Control Panel. Long Time includeshours, minutes, seconds.
Medium TimeTime in 12-hour format using hours and minutes, and the AM/PM designator.
Short TimeTime using 24-hour format (for example, 17:45).
User-Defined Date/Time Formats
The following list shows the characters you can use to define custom date/time formats.
CharacterMeaning
c Date as dddd and the time as tttt.
d Day as a number with no leading zero (1-31).
dd Day as a number with a leading zero (01-31).
ddd Day as an abbreviation (Sun-Sat).
dddddDate serial number as a complete date (including day, month, and year).
w Day of the week as a number (1-7).
ww Week of the year as a number (1-53).
m Month as a number with no leading zero (1-12). If m immediately follows h or hh, the minuterather than the month is displayed.
mm Month as a number with a leading zero (01-12). If mm immediately follows h or hh, the minuterather than the month is displayed.
mmm Month as an abbreviation (Jan-Dec).
mmmmMonth as a full name (January-December).
q Quarter of the year as a number (1-4).
y Day as a number (1-366).
yy Year as a two-digit number (00-99).
yyyy Year as a four-digit number (100-9999).
h Hour as a number without leading zeros (0-23).
hh Hour as a number with leading zeros (00-23).
n Minute as a number without leading zeros (0-59).
nn Minute as a number with leading zeros (00-59).
s Second as a number without leading zeros (0-59).
ss Second as a number with leading zeros (00-59).
46 IBM Optim: Optim Basic Language Reference
ttttt Time serial number as a complete time (including hour, minute, and second) using the timeseparator defined by the Time Format in the International section of the Control Panel. A leadingzero is added if the Leading Zero option is selected and the time is before 10:00 AM or PM. Thedefault time format is h:mm:ss.
AM/PM12-hour time with an uppercase AM/PM.
am/pm12-hour time with a lowercase am/pm.
A/P 12-hour time with an uppercase A/P.
a/p 12-hour time with a lowercase a/p.
AMPM12-hour time showing the contents of the 11:59 string (s1159) in the WIN.INI file for any hourbefore noon, or the contents of the 2359 string (s2359) for any hour between noon and 11:59 PM.AMPM is either uppercase or lowercase, but the case of the string must match the string in theWIN.INI file. The default format is AM/PM.
Sample Date/Time Formats
The following list shows how 6:45 PM on February 26, 1965 would be formatted using the indicateddate/time formats.
m/d/y 2/26/65
d-mmmm-yy26-February-65
d-mmmm26-February
mmmm-yyFebruary-65
hh:nn AM/PM06:45 PM
h:nn:ss a/p6:45:15 p
h:nn:ss18:45:15
m/d/yy/h:nn2/26/65/18:45
String Formats
Strings also can be formatted with Format[$]. An expression for strings can have one or two formats,separated by a semicolon. If you use:v One format only—the format applies to all string data.v Two formats—the first applies to string data, and the second applies to values and zero-length strings.
The following characters can be used to create a format expression for strings:
CharacterMeaning
@ Character placeholder. Displays a character or a space. Placeholders are filled from right to leftunless there is an ! character in the format string.
Chapter 3. Functions and Statements 47
& Character placeholder. Display a character or nothing.
< Force lowercase.
> Force uppercase.
! Force placeholders to fill from left to right instead of right to left.
FreeFile FunctionReturns an integer that is the next available file handle to be used by the Open Statement.FreeFile
ExampleSub Main
Dim Mx, FileNumberFor Mx = 1 To 3
FileNumber = FreeFileOpen "c:\e1\TEST" & Mx For Output As #FileNumberWrite #FileNumber, "This is a sample."Close #FileNumber
Next MxOpen "c:\e1\test1" For Input As #1Do While Not EOF(1)
MyStr = Input(10, #1)Print MyStr
LoopClose #1
End Sub
Function StatementDeclares and defines a procedure that can receive arguments and return a value of a specified data type.Function Functionname [(argument list)] [As type]
[statements]Functionname = expression[statements]Functionname = expression
End Function
When the optional argument list must be passed, the format is as follows:([ByVal] variable [As type] [,ByVal] variable [As type]...)
The optional ByVal parameter specifies that the variable is passed by value instead of by reference. Theoptional As type parameter specifies the data type. Valid data types are String, Integer, Double, Long,and Variant.
ExampleSub Main
Dim I as integerFor I = 1 to 10
Print GetColor2(I)Next I
End SubFunction GetColor2( c% ) As Long
GetColor2 = c% * 25If c% > 2 Then
GetColor2 = 255 ' 0x0000FF - RedEnd IfIf c% > 5 Then
GetColor2 = 65280 ' 0x00FF00 - GreenEnd If
48 IBM Optim: Optim Basic Language Reference
If c% > 8 ThenGetColor2 = 16711680 ' 0xFF0000 - Blue
End IfEnd Function
Get StatementReads from a disk file into a variable.Get [ # ] filenumber, [recordnumber,] variablename
The argument filenumber is the number used to open the file. The argument recordnumber is the byteposition in which reading starts, for files opened in Binary mode. The argument variablename is thename of the variable used to receive the data from the file.
GetObject FunctionRetrieves an object.GetObject (pathname [,class])
The argument pathname is the name of the file containing the object to retrieve. The argument class is astring representing the class of the object to retrieve. If pathname is an empty string, class is required.
Global StatementA Global statement must be outside the procedure section of the script. Global variables are available toall functions and subroutines in your program.Global Const constant
GoTo StatementBranches unconditionally and without return to a specified label in a procedure.GoTo label
ExampleSub Main ( )
Dim x,y,zFor x = 1 to 5
For y = 1 to 5For z = 1 to 5
Print "Looping" ,z,y,xIf y > 3 Then
GoTo Label1End If
Next zNext y
Next xLabel1:End Sub
Hex FunctionReturns the hexadecimal value of a decimal parameter.Hex (num)
Hex returns a string. The argument num can be any valid number. The number is rounded to nearestwhole number before evaluation.
Chapter 3. Functions and Statements 49
ExampleSub Main ()
Dim Msg As String, x%x% = 10Msg =Str( x%) & " decimal is "Msg = Msg & Hex(x%) & " in hex "Print Msg
End Sub
Hour FunctionReturns an integer between 0 and 23 that is the hour of the day indicated in a specified date and time.Hour (Date)
The argument Date is any number (expressed as a string) that can represent a date and time from January1, 1980 through December 31, 9999.
ExampleSub Main
MyTime = "08:04:23 PM"MyDate = "03/03/95"MyDate = "January 27, 1993"Print NowPrint MyTimePrint Second( MyTime ) & " Seconds"Print Minute( MyTime ) & " Minutes"Print Hour( MyTime ) & " Hours"Print Day( MyDate ) & " Days"Print Month( MyDate ) & " Months"Print Year( MyDate ) & " Years"' Returns current system time in the system-defined long time' format.Print Format(Time, "Short Time")MyStr = Format(Time, "Long Time")' Returns current system date in the system-defined long date' format.Print Format(Date, "Short Date")Print Format(Date, "Long Date")' If format is not supplied, a string is returned.Print Format(23) ' Returns "23".' User-defined formats.Print Format(5459.4, "##,##0.00") ' Returns "5,459.40".Print Format(334.9, "###0.00") ' Returns "334.90".Print Format(5, "0.00%") ' Returns "500.00%".Print Format("HELLO", "<") ' Returns "hello".Print Format("This is it", ">") ' Returns "THIS IS IT".
End Sub
If...Then...Else StatementAllows conditional statements in the code.
Syntax 1If condition Then thenpart [Else elsepart]
Syntax 2If condition Then
.[statement(s)].
ElseIf condition Then
50 IBM Optim: Optim Basic Language Reference
.[statement(s)].
Else.[statement(s)].
End If
ExampleSub IfTest
' demo If...Then...ElseDim msg as StringDim nl as StringDim someInt as Integernl = Chr(10)msg = "Less"someInt = 4If 5 > someInt Then msg = "Greater"
Print “” & msgIf 3 > someInt Then
msg = "Greater"Else
msg = "Less"End IfPrint “” & msgIf someInt = 1 Then
msg = "Spring"ElseIf someInt = 2 Then
msg = "Summer"ElseIf someInt = 3 Then
msg = "Fall"ElseIf someInt = 4 Then
msg = "Winter"Else
msg = "Salt"End IfPrint " " & msg
End Sub
Input # StatementReads data from a sequential file and assigns the data to variables.Input # filenumber, variablelist
The argument filenumber is the number used in the open statement when the file is opened. Theargument variablelist is a comma-delimited list of variables that are assigned when read from the file.
ExampleDim MyString, MyNumberOpen "c:\TESTFILE" For Input As #1 ' Open file for input.Do While Not EOF(1) ' Loop until end of file.
Input #1, MyString, MyNumber ' Read data into two variables.LoopClose #1 ' Close file.
Input FunctionReturns characters from a sequential file.Input ( n, [#] filenumber )
Chapter 3. Functions and Statements 51
The argument n is the number of bytes to be read from a file. The argument filenumber is the numberused in the open statement.
ExampleSub Main
Open "TESTFILE" For Input As #1 ' Open file.Do While Not EOF(1) ' Loop until end of file.
MyStr = Input(10, #1) ' Get ten characters.Print MyStr
LoopClose #1 ' Close file.
End Sub
InStr FunctionReturns the character position of the first occurrence of one string within another string (or 0 if the stringis not found).InStr (numbegin, string1, string2)
The argument numbegin, a valid positive integer no greater than 65 535, is required and sets the startingpoint for the search.
The argument string1 is the string that is searched, and the argument string2 is the string for which thefunction searches.
ExampleSub Main ()
B$ = "Good Bye"A% = InStr(2, B$, "Bye")C% = Instr(3, B$, "Bye")
End Sub
Int FunctionReturns the integer portion of a number.Int (number)
IsArray FunctionReturns a Boolean True or False to indicate if the variable identified by variablename is an array.IsArray (variablename)
ExampleSub Main
Dim MArray(1 To 5) As Integer, MCheckMCheck = IsArray(MArray)Print MCheck
End Sub
IsDate FunctionReturns a Boolean True or False to indicate if a parameter can be converted to a date.IsDate (variant)
52 IBM Optim: Optim Basic Language Reference
ExampleSub Main
Dim x As StringDim MArray As Integer, MCheckMArray = 345x = "January 1, 2001"MCheck = IsDate(MArray)MChekk = IsDate(x)MArray1 = CStr(MArray)MCheck1 = CStr(MCheck)Print MArray1 & " is a date " & Chr(10) & MCheckPrint x & " is a date" & Chr(10) & MChekk
End Sub
IsEmpty FunctionReturns a Boolean True or False to indicate if the parameter has been initialized.IsEmpty (variant)
Example' This sample explores the concept of an empty variant.Sub Main
Dim x ' Emptyx = 5 ' Not Empty - Longx = Empty ' Emptyy = x ' Both EmptyPrint “x” & " IsEmpty: " & IsEmpty(x)
End Sub
IsNull FunctionReturns a Boolean True or False to indicate if the parameter contains the Null value.IsNull (variant)
Note: The Null value indicates that variant contains no data. The Null value differs from a null-string(which is a zero length string) and an empty string (which has not yet been initialized).
IsNumeric FunctionReturns a Boolean True or False to indicate if the parameter can be converted to a numeric data type.IsNumeric (v)
The argument v can be any variant, numeric value, date or string (if the string can be interpreted asnumeric).
IsObject FunctionReturns a Boolean True or False to indicate whether the parameter is an object.IsObject (objectname)
ExampleSub Main
Dim MyInt As Integer, MyCheckDim MyObject As ObjectDim YourObject As ObjectSet MyObject = CreateObject("Word.Basic")
Chapter 3. Functions and Statements 53
Set YourObject = MyObjectMyCheck = IsObject(YourObject)Print MyCheck
End Sub
Kill StatementDeletes the specified file. To remove a directory, use the RmDir statement.Kill pathname
ExampleConst NumberOfFiles = 3Sub Main ( )
Dim Msg ' Declare variable.Call MakeFiles( ) ' Create data files.Msg = "Several test files have been created on your disk. You"Msg = Msg & "may see them by switching tasks. Choose OK to"Msg = Msg & "remove the test files."Print MsgFor I = 1 To NumberOfFiles
Kill "TEST" & I ' Remove data files from disk.Next I
End SubSub MakeFiles ( )
Dim I, FNum, FName ' Declare variables.For I = 1 To NumberOfFiles
FNum = FreeFile ' Determine next file number.FName = "TEST" & IOpen FName For Output As FNum ' Open file.Print #FNum, "This is test #" & I ' Write string to file.Print #FNum, "Here is another "; "line"; I
Next IClose ' Close all files.
End Sub
LBound FunctionReturns the smallest available subscript for the dimension of the indicated array.LBound (array [,dimension])
Example' This example demonstrates some of the features of arrays. The' lower bound for an array is 0 unless it is specified or option base' has set as in this example.Option Base 1Sub Main
Dim a(10) As DoublePrint "LBound: " & LBound(a) & " UBound: " & UBound(a)Dim i As IntegerFor i = 0 to 3
a(i) = 2 + i * 3.1Next iPrint a(0),a(1),a(2), a(3)
End Sub
LCase FunctionReturns a string in which all uppercase letters of a string parameter have been converted to lowercase.LCase[$](string)
54 IBM Optim: Optim Basic Language Reference
Example' This example uses the LTrim and RTrim functions to strip leading' and trailing spaces, respectively, from a string variable. It' uses the Trim function alone to strip both types of spaces.' LCase and UCase are also shown in this example as well as the' use of nested function calls.Sub Main
MyString = " <-Trim-> " ' Initialize string.TrimString = LTrim(MyString) ' TrimString = "<-Trim-> ".Print "|" & TrimString & "|"TrimString = LCase(RTrim(MyString)) ' TrimString = " <-trim->".Print "|" & TrimString & "|"TrimString = LTrim(RTrim(MyString)) ' TrimString = "<-Trim->".Print "|" & TrimString & "|"' Using the Trim function alone achieves the same result.TrimString = UCase(Trim(MyString)) ' TrimString = "<-TRIM->".Print "|" & TrimString & "|"
End Sub
Left FunctionReturns the left-most characters of a string parameter.Left[$] (string)
The function Left returns a variant. The function Left$ returns a string.
Len FunctionReturns the number of characters in a string.Len (string)
ExampleSub Main ( )
A$ = "RT for Servers"StrLen% = Len(A$) ' The value of StrLen is 14.Print StrLen%
End Sub
Let StatementAssigns a value to a variable.[Let] variablename = expression
Line Input # StatementReads a line from a sequential file into a string or variant variable.Line Input # filenumber, variablename
The argument filenumber is used in the open statement to open the file.
Example' Line Input # Statement Example:' This example uses the Line Input # statement to read a line from a' sequential file and assign it to a variable. This example assumes' that TESTFILE is a text file with a few lines of sample data.Sub Main
Open "TESTFILE" For Input As #1 ' Open file.Do While Not EOF(1) ' Loop until end of file.
Line Input #1, TextLine ' Read line into variable.
Chapter 3. Functions and Statements 55
Print TextLine ' Print to Debug window.LoopClose #1 ' Close file.
End Sub
LOF FunctionReturns a long number for the number of bytes in the open file.LOF (filenumber)
The argument filenumber is required and must be an integer.
ExampleSub Main
Dim FileLengthOpen "TESTFILE" For Input As #1FileLength = LOF(1)Print FileLengthClose #1
End Sub
Log FunctionReturns the natural log of a number.Log(num)
The argument num must be a valid number greater than zero.
ExampleSub Form_Click ( )
Dim I, Msg, NLNL = Chr(13) & Chr(10)Msg = Exp(1) & NLFor I = 1 to 3
Msg = Msg & Log(Exp(1) ^ I ) & NLNext IPrint Msg
End Sub
Mid FunctionReturns a substring within a string.Mid (strgvar, begin, length)
Minute FunctionReturns an integer from 0 through 59 that represents the minute of the hour contained in the parameter.Minute (date)
ExampleSub Main
MyTime = "08:04:23 PM"MyDate = "03/03/95"MyDate = "January 27, 1993"Print NowPrint MyTimePrint Second(MyTime) & " Seconds"Print Minute(MyTime) & " Minutes"Print Hour(MyTime) & " Hours"
56 IBM Optim: Optim Basic Language Reference
Print Day(MyDate) & " Days"Print Month(MyDate) & " Months"Print Year(MyDate) & " Years"
End Sub
MkDir StatementCreates a new directory.MkDir path
The argument path is a string expression that must contain fewer than 128 characters.
ExampleSub Main
Dim DST As StringDST = "t1"mkdir DSTmkdir "t2"
End Sub
Month FunctionReturns an integer from 1 through 12 that represents the month of the year.Month (date)
ExampleSub Main
MyDate = "03/03/96"print MyDatex = Month(MyDate)print x
End Sub
Name StatementChanges the name of a directory or a file.Name oldname As newname
The arguments oldname and newname are strings that can optionally contain a path.
Now FunctionReturns a date that represents the current date and time according to the system date and time setting.Now
The Now function returns a variant data type containing a date and time that are stored internally as adouble. The number is a date and time from January 1, 100 through December 31, 9999, where January 1,1900 is 2. Numbers to the left of the decimal point represent the date, and numbers to the right representthe time.
ExampleSub Main ( )
Dim TodayToday = Now
End Sub
Chapter 3. Functions and Statements 57
Oct FunctionReturns the octal value of the parameter as a string.Oct (num)
The argument num must be a valid numeric or string expression.
ExampleSub Main ( )
Dim Msg, Num ' Declare variables.Num = InputBox("Enter a number.") ' Get user input.Msg = Num & " decimal is &O"Msg = Msg & Oct(Num) & " in octal notation."Print Msg ' Print results.
End Sub
On Error StatementEnables error-handling routine and specifies the line label of the routine.On Error { GoTo label | Resume Next | GoTo 0 }
The argument label must be present in the code or an error is generated.
The error number can be used to determine the error that has occurred; the error description provides acharacter description of the error.
Errors can be raised using the syntax:
Err.Raise x
ExampleSub Main
On Error GoTo dudeDim x as objectx.draw ' Object not setjpe ' Undefined function callprint 1/0 ' Division by zeroErr.Raise 6 ' Generate an "Overflow" errorPrint "Back"Print "Jack"Exit Sub
dude:Print "HELLO"Print Err.Number, Err.DescriptionResume NextPrint "Should not get here!"Print "What?"
End Sub
Error Descriptions
The following list shows the descriptions that correspond to defined errors:
5: "Invalid procedure call";
6: "Overflow";
7: "Out of memory";
58 IBM Optim: Optim Basic Language Reference
9: "Subscript out of range";
10: "Array is fixed or temporarily locked";
11: "Division by zero";
13: "Type mismatch";
14: "Out of string space";
16: "Expression too complex";
17: "Can't perform requested operation";
18: "User interrupt occurred";
20: "Resume without error";
28: "Out of stack space";
35: "Sub, Function, or Property not defined";
47: "Too many DLL application clients";
48: "Error in loading DLL";
49: "Bad DLL calling convention";
51: "Internal error";
52: "Bad file name or number";
53: "File not found";
54: "Bad file mode";
55: "File already open";
57: "Device I/O error";
58: "File already exists";
59: "Bad record length";
60: "Disk full";
62: "Input past end of file";
63: "Bad record number";
67: "Too many files";
68: "Device unavailable";
70: "Permission denied";
Chapter 3. Functions and Statements 59
71: "Disk not ready";
74: "Can't rename with different drive";
75: "Path/File access error";
76: "Path not found";
91: "Object variable or With block variable not set";
92: "For loop not initialized";
93: "Invalid pattern string";
94: "Invalid use of Null";
// OLE Automation Messages
429: "OLE Automation server cannot create object";
430: "Class doesn't support OLE Automation";
432: "File name or class name not found during OLE Automation operation";
438: "Object doesn't support this property or method";
440: "OLE Automation error";
443: "OLE Automation object does not have a default value";
445: "Object doesn't support this action";
446: "Object doesn't support named arguments";
447: "Object doesn't support current local setting";
448: "Named argument not found";
449: "Argument not optional";
450: "Wrong number of arguments";
451: "Object not a collection";
// Miscellaneous Messages
444: "Method not applicable in this context";
452: "Invalid ordinal";
453: "Specified DLL function not found";
457: "Duplicate Key";
460: "Invalid Clipboard format";
60 IBM Optim: Optim Basic Language Reference
461: "Specified format doesn't match format of data";
480: "Can't create AutoRedraw image";
481: "Invalid picture";
482: "Printer error";
483: "Printer driver does not support specified property";
484: "Problem getting printer information from the system. Make sure the printer is set up correctly.";
485: "invalid picture type";
520: "Can't empty Clipboard";
521: "Can't open Clipboard";
Open StatementOpens a file for input and output operations.Open pathname [For mode] [Access access] As [#]filenumber
You must open a file before performing any I/O operation. The Open statement consists of:
pathnameFile name or path.
mode Reserved word that specifies the file mode: Append, Binary Input, Output.
access Reserved word that specifies the operations that are permitted on the open file: Read, Write.
filenumberInteger expression with a value from 1 through 255. When an Open statement is executed,filenumber is associated with the file as long as it is open. Other I/O statements can use thenumber to refer to the file.
Note: If a file doesn't exist, it is created when opened for Append, Binary Input, or Output modes.
Mode
The argument mode is a reserved word that specifies one of the following file modes:
Input Sequential input mode.
OutputSequential output mode.
AppendSequential output mode. Sets the file pointer to the end of the file. A Print # or Write #statement extends (appends to) the file.
Access
The argument access is a reserved word that indicates the operations that can be performed on theopened file. If the file is already open and the indicated access is not allowed, the Open operation failsand a Permission Denied error occurs.
The argument access can be one of the following reserved words:
Chapter 3. Functions and Statements 61
Read Opens the file for reading only.
Write Opens the file for writing only.
Read WriteOpens the file for both reading and writing. This mode is valid only for Random and Binary filesand for files opened for Append mode.
Option Base StatementDeclares the default lower bound for array subscripts. The default base is 0.Option Base {0 | 1}
The Option Base statement is not required. If used, the statement can appear only once in a module (onlyin the Declarations section), and it must be used before you declare the dimensions of any arrays.
Note: The To clause in the Dim, Global, and Static statements provides a more flexible way to control therange of array subscripts. However, if you do not explicitly set the lower bound with a To clause, you canuse Option Base to change the default lower bound to 1.
ExampleOption Base 1 ' Module level statement.Sub Main
Dim A( ), Msg, NL ' Declare variables.NL = Chr(10) ' Define newline.ReDim A(20) ' Create an array.Msg = "The lower bound of the A array is " & LBound(A) & "."Msg = Msg & NL & "The upper bound is " & UBound(A) & "."Print Msg ' Print message.
End Sub
Option Explicit StatementRequires explicit declaration of all variables.Option Explicit
The Option Explicit statement is used outside the script in the Declarations section. If this statement iscontained in the middle of a file, the rest of the compile is affected.
ExampleOption ExplicitSub Main
Print y ' Because y is not explicitly dimmed an error will occur.End Sub
Print MethodPrints a string to the process report.Print [expr, expr...]
ExampleSub PrintExample ( )
Dim Msg, Pi ' Declare variables.Let Pi = 4 * _Atn(1) ' Calculate Pi.Msg = "Pi is equal to " & Str(Pi)Print Msg ' Print results.Print Pi ' Prints the results in the compiler
' messages window.End Sub
62 IBM Optim: Optim Basic Language Reference
Print # StatementWrites data to a sequential file.Print # filenumber, [ [{Spc(n) | Tab(n)}] [expression] [{; | ,}] ]
filenumberNumber used in an Open statement to open a sequential file. It can be any number of an openfile. Note that you must include the number sign (#) preceding the file number.
Spc(n) Name of the function optionally used to insert n spaces into the printed output. Multiple use ispermitted.
Tab(n) Name of the function optionally used to tab to the nth column before printing expression list.Multiple use is permitted.
expressionNumeric and/or string expression to be written to the file.
; | , Character that determines the position of the next character that is printed. A semicolon indicatesthat the next character is printed immediately after the last character; a comma indicates that thenext character is printed at the beginning of the next print zone. Print zones occur every 14columns. If neither character is specified, the next character is printed on the next line.
Notes:
v You must include a comma after filenumber. If you omit expression, the Print # statement prints ablank line in the file. Because Print # writes an image of the data to the file, you must delimit the dataso it is printed correctly. If you use commas as delimiters, Print # also writes the blanks between printfields.
v The Print # statement usually writes Variant data to a file the same way it writes any other data type.However, there are some exceptions:– If the data being written is a Variant of VarType 0 (Empty), Print # writes nothing to the file for
that data item.– If the data being written is a Variant of VarType 1 (Null), Print # writes the literal #NULL# to the
file.– If the data being written is a Variant of VarType 7 (Date), Print # writes the date to the file using
the Short Date format defined in the win.ini file. When either the date or the time component ismissing or zero, Print # writes only the part provided to the file.
Examples
The following example writes data to a test file:Sub Main
Dim I, FNum, FName ' Declare variables.For I = 1 To 3
FNum = FreeFile ' Determine next file #.FName = "TEST" & FNumOpen FName For Output As FNum ' Open file.Print #I, "This is test #" & I ' Write string to file.Print #I, "Here is another "; "line"; I
Next IClose ' Close all files.
End Sub
This example writes data to a test file and reads the data back:Sub Main ( )
Dim FileData, Msg, NL ' Declare variables.NL = Chr(10) ' Define newline.Open "TESTFILE" For Output As #1 ' Open to write file.Print #1, "This is a test of the Print # statement."
Chapter 3. Functions and Statements 63
Print #2, ' Print blank line.Print #2, "Zone 1", "Zone 2" ' Print in two zones.Print #2, "With no space between" ; "." ' Print two strings
' together.CloseOpen "TESTFILE" for Input As #2 ' Open to read file.Do While Not EOF(2)
Line Input #2, FileData ' Read a line of data.Msg = Msg & FileData & NL ' Construct message.Print Msg
LoopClose ' Close all open files.Print "Testing Print Statement" ' Print message.Kill "TESTFILE" ' Remove file from disk.
End Sub
Randomize StatementInitializes the random number generator.Randomize [number]
The argument number is any valid number and is used to initialize the random number generator. If youomit number, the value returned by the Timer function is used.
ExampleSub Main
Dim MValueRandomize ' Initialize random-number generator.MValue = Int((6 * Rnd) + 1)Print MValue
End Sub
ReDim StatementDeclares dynamic arrays and reallocates storage space.ReDim variablename (subscripts) [As type] [,variablename (subscripts) [As type] ]
The ReDim statement is used to size or resize a dynamic array that has already been declared using a Dimstatement with empty parentheses.
The parameter variablename is the name of the array variable being declared. You can use the subscriptsparameter to change the number of elements and dimensions in the array. If the array was declaredpreviously as a variant data type, you can use the optional As type parameter to change the data type ofthe elements.
ExampleSub Main
Dim TestArray( ) As IntegerDim IReDim TestArray(10)For I = 1 To 10
TestArray(I) = I + 10Print TestArray(I)
Next IEnd Sub
Rem StatementIncludes explanatory remarks in a program.
64 IBM Optim: Optim Basic Language Reference
Syntax 1Rem comment
Syntax 2'comment
The variable comment is the text of any comment you wish to include in the code.
Right FunctionReturns a specified number of characters from the end of a string. For example, this function can returnthe last five characters in a string.Right (stringexpression, n)
The argument n is the number of characters returned and must be a long integer.
RmDir StatementRemoves an existing directory.RmDir path
The argument path is the name of the directory to be removed.
Example' This sample shows the functions mkdir (Make Directory)' and rmdir (Remove Directory).Sub Main
Dim dirName As StringdirName = "t1"mkdir dirNamemkdir "t2"Print "Directories: t1 and t2 created. Press OK to remove them"rmdir "t1"rmdir "t2"
End Sub
Rnd FunctionReturns a random number.Rnd (number)
The argument number must be a valid numeric expression.
Example' The example uses the Rnd function to simulate rolling a pair of' dice by generating random values from 1 to 6.Sub Main ( )
Dim Dice1, Dice2, Msg ' Declare variables.Dice1 = CInt(6 * Rnd() + 1) ' Generate first die value.Dice2 = CInt(6 * Rnd() + 1) ' Generate second die value.Msg = "You rolled a " & Dice1Msg = Msg & " and a " & Dice2Msg = Msg & " for a total of "Msg = Msg & Str(Dice1 + Dice2) & "."Print Msg ' Print message.
End Sub
Chapter 3. Functions and Statements 65
Second FunctionReturns an integer that is the seconds portion time specified in a string.Second (time)
The argument time is any number (expressed as a string) that can represent a date and time from January1, 1980 through December 31, 9999.
ExampleSub Main
MyTime = "08:04:23 PM"MyDate = "03/03/95"MyDate = "January 27, 1993"Print NowPrint MyTimePrint Second(MyTime) & " Seconds"Print Minute(MyTime) & " Minutes"Print Hour(MyTime) & " Hours"Print Day(MyDate) & " Days"Print Month(MyDate) & " Months"Print Year(MyDate) & " Years"' Returns current system time in the system-defined long time' format.Print Format(Time, "Short Time")MyStr = Format(Time, "Long Time")' Returns current system date in the system-defined long date' format.Print Format(Date, "Short Date")Print Format(Date, "Long Date")' User-defined formats.Print Format(5459.4, "##,##0.00") ' Returns "5,459.40".Print Format(334.9, "###0.00") ' Returns "334.90".Print Format(5, "0.00%") ' Returns "500.00%".Print Format("HELLO", "<") ' Returns "hello".Print Format("This is it", ">") ' Returns "THIS IS IT".
End Sub
Seek FunctionReturns a number that represents the byte position for the next operation. The first byte in the file is atposition 1.Seek (filenumber)
The argument filenumber is used in the open statement and must be a valid numeric expression.
ExampleSub Main
Open "TESTFILE" For Input As #1 ' Open file for reading.Do While Not EOF(1) ' Loop until end of file.
MyChar = Input(1, #1) ' Read next character of data.Print Seek(1) ' Print byte position.
LoopClose #1 ' Close file.
End Sub
Seek StatementSets the byte position in a file for the next I/O operation.Seek [#]filenumber, position
66 IBM Optim: Optim Basic Language Reference
The argument filenumber is used in the open statement and must be a valid numeric expression. Theargument position is a number that indicates where the next read or write is to occur, relative to thebeginning of the file.
ExampleSub Main
Open "TESTFILE" For Input As #1 ' Open file for reading.For i = 1 To 24 Step 3 ' Loop until end of file.
Seek #1, i ' Seek to byte positionMyChar = Input(1, #1) ' Read next character of data.Print MyChar ' Print character of data
Next iClose #1 ' Close file.
End Sub
Select Case StatementExecutes statements in the case based on the test variable.Select Case testvariable
Case var1statements
Case var2statements
Case Elsestatements
End Select
Note: The Select Case statement supports the following syntax: the “To” keyword, a comma delimitedlist, and a constant or variable.
ExampleSub Test ()
For x = 1 to 5print xSelect Case x
Case 2Print "Outer Case Two"
Case 3Print "Outer Case Three"
' Exit ForSelect Case x
Case 2Print "Inner Case Two"
Case 3Print "Inner Case Three"
' Exit ForCase Else ' Must be something else.
Print "Inner Case Else:", xEnd SelectPrint "Done with Inner Select Case"
Case Else ' Must be something else.Print "Outer Case Else:",x
End SelectNext xPrint "Done with For Loop"
End Sub
SendKeys FunctionSends one or more keystrokes to the active window as if entered at the keyboard.SendKeys (keys [,wait])
Chapter 3. Functions and Statements 67
The argument keys is a string representing the desired keystrokes. The argument wait is an optionalBoolean True or False. If omitted, wait is assumed to be false. If wait is true, the keystrokes must beprocessed before control is returned to the calling procedure.
ExampleSub Main ( )
Dim I, X, Msg ' Declare variables.X = Shell("Calc.exe", 1) ' Shell Calculator.For I = 1 To 5 ' Set up counting loop.
SendKeys I & "{+}", True ' Send keystrokes to Calculator.Next I ' to add each value of I.AppActivate "Calculator" ' Return focus to Calculator.SendKeys "%{F4}", True ' Alt+F4 to close Calculator.
End Sub
Set StatementAssigns an object to an object variable.Set objectvariable = {[New] objectexpression | Nothing}
The argument objectvariable is the name of the variable.
Shell FunctionRuns an executable program.Shell ( app [,style])
The argument app is the name of the program to be executed. An error occurs if the name of the programdoes not have a .PIF, .COM, .BAT, or .EXE extension. The argument style is a number corresponding tothe style of the window. The argument style is optional; if omitted, the program is opened minimizedwith focus.
Window Styles
The argument style can have the following values:
1,5,9 Normal with focus
2 (Default) Minimized with focus
3 Maximized with focus
4,8 Normal without focus
6,7 Minimized without focus
Return Value
If the Shell function successfully executes the named file, it returns the task ID of the started program.The task ID is a unique number that identifies the running program. If the Shell function can't start thenamed program, an error occurs.
Example' This example uses Shell to leave the current application and run' the Calculator program included with Microsoft Windows; it then' uses the SendKeys statement to send keystrokes to add some' numbers.Sub Main ( )
Dim I, X, Msg ' Declare variables.X = Shell("Calc.exe", 1) ' Shell Calculator.
68 IBM Optim: Optim Basic Language Reference
For I = 1 To 5 ' Set up counting loop.SendKeys I & "{+}", True ' Send keystrokes to Calculator.
Next I ' to add each value of I.AppActivate "Calculator" ' Return focus to Calculator.SendKeys "%{F4}", True ' Alt+F4 to close Calculator.
End Sub
Sin FunctionReturns the sine of an angle expressed in radians.Sin (rad)
ExampleSub Main ( )
pi = 4 * Atn(1)rad = 90 * (pi/180)x = Sin(rad)print x
End Sub
Space FunctionSkips a specified number of spaces in a Print # statement.Space (number)
The argument number is any valid integer and determines the number of blank spaces.
Example' This sample shows the space functionSub Main
Print "Hello" & Space(20) & "There"End Sub
Sqr FunctionReturns the square root of a number.Sqr (num)
The argument num is a valid number greater than or equal to zero.
Static StatementDeclares variables and allocates storage space.Static variable
The variables retain their values through the program execution.
Example' This example shows how to use the Static keyword to retain the' value of the variable i in sub Joe. If Dim is used instead of Static,' then i is empty when printed on the second call as well as the first.Sub Main
For i = 1 to 2Joe 2
Next iEnd SubSub Joe( j as integer )
Static i
Chapter 3. Functions and Statements 69
print ii = i + 5print i
End Sub
Str FunctionReturns the value of a numeric expression. Str returns a string.Str (numericexpr)
ExampleSub Main ( )
Dim msga = -1Print "Num = " & Str(a)Print "Abs(Num) =" & Str(Abs(a))
End Sub
StrComp FunctionReturns a variant that is the result of the comparison of two strings.StrComp (string1,string2 [,compare])
ExampleSub Main
Dim MStr1, MStr2, MCompMStr1 = "ABCD": MStr2 = "today" ' Define variables.print MStr1, MStr2MComp = StrComp(MStr1, MStr2) ' Returns -1.print MCompMComp = StrComp(MStr1, MStr2) ' Returns -1.print MCompMComp = StrComp(MStr2, MStr1) ' Returns 1.print MComp
End Sub
String FunctionReturns a string that consists of one character repeated for a specified number of times.String (numeric, charcode)
If charcode contains more than one character, the first character in charcode is repeated.
ExampleSub Main
Dim MStringMString = String(5, "*") ' Returns "*****".MString = String(5, 42) ' Returns "44444".MString = String(10, "Today") ' Returns "TTTTTTTTTT".Print MString
End Sub
Sub StatementDeclares and defines a subroutine procedure name, parameters and code.Sub subname [(argument list)]
[statements]End Sub
70 IBM Optim: Optim Basic Language Reference
To pass the optional argument list, use the following format:([ByVal] variable [As type] [,ByVal] variable [As type]...)
ExampleSub Main
Dim DST As StringDST = "t1"mkdir DSTmkdir "t2"
End Sub
Tan FunctionReturns the tangent of an angle as a double.Tan (angle)
The argument angle must be expressed in radians.
Example' This sample program shows the use of the Tan function.Sub Main ()
Dim Msg, Pi ' Declare variables.Pi = 4 * Atn(1) ' Calculate Pi.Msg = "Pi is equal to " & PiPrint Msg ' Print results.x = Tan(Pi/4)Print x & " is the tangent of Pi/4"
End Sub
Time FunctionReturns the current system time from a date variable.Time[()]
Example
In the example below, the Time function uses the Now function to obtain the current date and time. (Forinformation about the Now function, see “Now Function” on page 57.Sub Main
x = Time(Now)Print x
End Sub
Timer FunctionTracks elapsed time.Timer
The returned value is the number of seconds elapsed since midnight.
ExampleSub Main
Dim TS As SingleDim TE As SingleDim TEL As SingleTS = TimerPrint "Starting Timer"
Chapter 3. Functions and Statements 71
TE = TimerTT = TE - TSPrint TT
End Sub
TimeSerial FunctionReturns the time serial for the given hour, minute, and second.TimeSerial (hour, minute, second)
ExampleSub Main
Dim MTimeMTime = TimeSerial(12, 25, 27)Print MTime
End Sub
TimeValue FunctionReturns a double-precision serial number based on the time indicated by an input string.TimeValue (timestring)
Midnight = TimeValue (“23:59:59”)
ExampleSub Main
Dim MTimeMTime = TimeValue("12:25:27 PM")Print MTime
End Sub
Trim, LTrim, RTrim FunctionsReturns a copy of a string.[{L| R}]Trim (string)
LTrim removes leading spaces from the string. RTrim removes trailing spaces from the string. Trimremoves both leading and trailing spaces from the string.
Example' This example uses the LTrim and RTrim functions to strip leading' and trailing spaces, respectively, from a string variable. It' uses the Trim function alone to strip both types of spaces.' LCase and UCase are also shown in this example as well as' the use of nested function calls.Sub Main
MyString = " <-Trim-> " ' Initialize string.TrimString = LTrim(MyString) ' TrimString = "<-Trim-> ".Print "|" & TrimString & "|"TrimString = LCase(RTrim(MyString)) ' TrimString = " <-trim->".Print "|" & TrimString & "|"TrimString = LTrim(RTrim(MyString)) ' TrimString = "<-Trim->".Print "|" & TrimString & "|"' Using the Trim function alone achieves the same result.TrimString = UCase(Trim(MyString)) ' TrimString = "<-TRIM->".Print "|" & TrimString & "|"
End Sub
72 IBM Optim: Optim Basic Language Reference
Type StatementDefines a user-defined data type containing one or more elements.Type variablename
[variablename As type][variablename As type]...
End Type
User-defined types are often used with data records that consist of a number of related elements ofdifferent data types. An array cannot be an element of a user-defined type.v The value variablename is the name of the user-defined data type using standard variable naming
conventions.v The value type is one of the following data types: long, single, double, string (for variable-length
strings), string * length (for fixed-length strings), variant, or another user-defined type. (Type cannot bean object data type.)
After declaring a user-defined type using the Type statement, you can declare a variable of that typeanywhere in your script. Use Dim or Static to declare a variable of a user-defined type. Line numbersand line labels are not allowed in Type...End Type blocks.
Example' This sample shows some of the features of user-defined types.Type type1
a As Integerd As Doubles As String
End TypeType type2
a As Stringo As type1
End TypeType type3
b As Integerc As type2
End TypeDim type2a As type2Dim type2b As type2Dim type1a As type1Dim type3a As type3Sub Form_Click ()
a = 5type1a.a = 7472type1a.d = 23.1415type1a.s = "YES"type2a.a = "43 - forty three"type2a.o.s = "Yaba Daba Doo"type3a.c.o.s = "COS"type2b.a = "943 - nine hundred and forty three"type2b.o.s = "Yogi"Print type1a.aPrint type1a.dPrint type1a.sPrint type2a.aPrint type2a.o.sPrint type2b.aPrint type2b.o.sPrint type3a.c.o.sPrint a
End Sub
Chapter 3. Functions and Statements 73
UBound FunctionReturns the value of the largest usable subscript for the specified dimension of an array.UBound (arrayname [,dimension])
If no dimension is given, 1 is assumed.
Example' This example demonstrates some of the features of arrays. The' lower bound for an array is 0 unless it is specified or option base' is set it as is done in this example.Option Base 1Sub Main
Dim a(10) As DoublePrint "LBound: " & LBound(a) & " UBound: " & UBound(a)Dim i As IntegerFor i = 1 to 3
a(i) = 2 + iNext iPrint a(1),a(1),a(2), a(3)
End Sub
UCase FunctionConverts all lowercase letters to uppercase.UCase (string)
Example' This example uses the LTrim and RTrim functions to strip leading' and trailing spaces, respectively, from a string variable. It' uses the Trim function alone to strip both types of spaces.' LCase and UCase are also shown in this example as well as the' use of nested function calls.Sub Main
MyString = " <-Trim-> " ' Initialize string.TrimString = LTrim(MyString) ' TrimString = "<-Trim-> ".Print "|" & TrimString & "|"TrimString = LCase(RTrim(MyString)) ' TrimString = " <-trim->".Print "|" & TrimString & "|"TrimString = LTrim(RTrim(MyString)) ' TrimString = "<-Trim->".Print "|" & TrimString & "|"' Using the Trim function alone achieves the same result.TrimString = UCase(Trim(MyString)) ' TrimString = "<-TRIM->".Print "|" & TrimString & "|"
End Sub
Val FunctionReturns the numeric value of a string of characters.Val (string)
ExampleSub Main
Dim MsgDim YourVal As DoubleYourVal = Val(InputBox$("Enter a number"))Msg = "The number you entered is: " & YourValPrint Msg
End Sub
74 IBM Optim: Optim Basic Language Reference
VarType FunctionReturns a value that indicates the type of the given variable.VarType (varname)
The argument varname is a variant data type. The following are return values:
Table 23. VarType return values
VarType return value Variable type
0 Empty
1 Null
2 Integer
3 Long
4 Single
5 Double
7 Date/Time
8 String
ExampleIf VarType(x) = 5 Then Print "Vartype is Double" ' Print variable type
Weekday FunctionReturns an integer containing the whole number for the weekday it is representing.Weekday (date[, firstdayofweek])
ExampleSub Main
x = Weekday(#5/29/1959#)Print x
End Sub
While...Wend StatementExecutes a block of statements while a given condition is true.While condition
.
.
.[statements]...
Wend
The argument condition is any numeric or expression that evaluates to a Boolean True or False.
ExampleSub Main
Const Max = 5Dim A(5) As StringA(1) = "Programmer"A(2) = "Engineer"A(3) = "President"
Chapter 3. Functions and Statements 75
A(4) = "Tech Support"A(5) = "Sales"Exchange = TrueWhile Exchange
Exchange = FalseFor I = 1 To Max
Print A(I)Next I
WendEnd Sub
With StatementExecutes a block of commands or statements on a given object without referring again to the name ofthat object.With object
[statements]End With
With statements can be nested. You must fully qualify any object in an inner With block to any member ofan object in an outer With block.
ExampleType type1
a As Integerd As Doubles As String
End TypeType type2
a As Stringo As type1
End TypeDim type1a As type1Dim type2a As type2Sub Main ( )
With type1a.a = 65.d = 3.14
End WithWith type2a
.a = "Hello, world"With .o
.s = "Goodbye"End With
End Withtype1a.s = "YES"Print type1a.aPrint type1a.dPrint type1a.sPrint type2a.aPrint type2a.o.s
End Sub
Write # StatementWrites and formats data to a sequential file that must be opened in output or append mode.Write #filenumber [,parameterlist]
A comma-delimited list of the supplied parameters is written to the indicated file. If no parameters arepresent, only the newline character will be written to the file.
76 IBM Optim: Optim Basic Language Reference
ExampleSub Main ( )
Open "TESTFILE" For Output As #1 ' Open to write file.userData1$ = InputBox("Enter your own text here")userData2$ = InputBox("Enter more of your own text here")Write #1, "This is a test of the Write # statement."Write #1,userData1$, userData2Close #1Open "TESTFILE" for Input As #2 ' Open to read file.Do While Not EOF(2)
Line Input #2, FileData ' Read a line of data.PRint FileData ' Construct message.
LoopClose #2 ' Close all open files.Print "Testing Print Statement" ' Print message.Kill "TESTFILE" ' Remove file from disk.
End Sub
Year FunctionReturns an integer representing a year from 1930 through 2029.Year (serial)
The returned integer represents the year of the argument serial. The argument serial is a string thatrepresents a date. If serial is Null, the return is Null.
ExampleSub Main
MyDate = "11/11/11"x = Year(MyDate)Print x
End Sub
Chapter 3. Functions and Statements 77
78 IBM Optim: Optim Basic Language Reference
Chapter 4. Object Properties and Global Functions
You can use predefined object property functions and global functions within an Optim Basic program.These functions allow you to get or set information about the Optim operating environment and thesource and target objects that are used in an Optim Basic program. For example, there is a predefinedproperty function that returns True or False based upon whether a value in a column is null.
The supported objects, object properties, and global functions are:
Object Name Property
Optim Application App
“ArchBrowseIdxDir” on page 82
“ArchDir” on page 82
“ArchIdxDir” on page 82
“Arg” on page 82
“ArgCount” on page 82
“CompanyName” on page 82
“ComputerName” on page 83
“DataDir” on page 83
“Environ” on page 83
“Error” on page 83
“Instance” on page 83
“LogEvent” on page 83
“OpSys” on page 84
“OpSysBuild” on page 84
“OpSysCSD” on page 84
“OpSysRelease” on page 84
“Request” on page 84
“RequestList” on page 85
“RtBuild” on page 85
“RtRelease” on page 85
“Script” on page 85
“ServerUserId” on page 85
“StartLogging” on page 85
“TempDir” on page 86
“ThreadHandle” on page 86
“ThreadId” on page 87
Source File Source
“Column (source object)” on page 87
“ColumnList” on page 87
“CreateFile” on page 88
“CreatorId” on page 88
© Copyright IBM Corp. 1994, 2010 79
Object Name Property
“DBAlias” on page 88
“IsColumn” on page 88
“OwnerId” on page 89
“Table” on page 89
Target Table Target
“Column (target object)” on page 89
“SetFromFile” on page 89
“Value (target object)” on page 90
Column Instance (Source or Target Object)
“Available” on page 90
“IsNull” on page 90
“Length” on page 91
“Name” on page 91
“Nullable” on page 91
“Precision” on page 91
“Scale” on page 91
“Type” on page 91
“Value (column instance)” on page 91
Global Functions (No Qualifiers)
“GetAllSettings” on page 92
“GetAsBinary” on page 93
“GetAsDate” on page 93
“GetAsDecimalChar” on page 94
“GetAsDecimalCharSz” on page 94
“GetAsOracleDate” on page 94
“GetAsSybaseDateTime” on page 95
“GetAsSybaseDecimal” on page 96
“GetAsSybaseMoney” on page 96
“GetAsSybaseSmallDateTime” on page 97
“GetAsSybaseSmallMoney” on page 97
“GetAsTime” on page 98
“GetAsVarBinary” on page 98
“GetAsVarChar” on page 99
“GetAsVarCharSz” on page 99
“GetGlobalWork” on page 99
“GetSetting” on page 100
“PutAsBinary” on page 101
“PutAsDate” on page 101
“PutAsDecimalChar” on page 101
“PutAsDecimalCharSz” on page 102
“PutAsOracleDate” on page 102
80 IBM Optim: Optim Basic Language Reference
Object Name Property
“PutAsSybaseDateTime” on page 103
“PutAsSybaseDecimal” on page 103
“PutAsSybaseMoney” on page 104
“PutAsSybaseSmallDateTime” on page 104
“PutAsSybaseSmallMoney” on page 105
“PutAsTime” on page 105
“PutAsVarBinary” on page 106
“PutAsVarChar” on page 106
“PutAsVarCharSz” on page 106
“SaveSetting” on page 107
“SetGlobalWork” on page 108
Properties for App ObjectYou can use properties to get or set values specific to Optim.
Properties for app objects are:v ArchBrowseIdxDir
v ArchDir
v ArchIdxDir
v Arg
v ArgCount
v CompanyName
v ComputerName
v DataDir
v Environ
v Error
v Instance
v LogEvent
v OpSys
v OpSysBuild
v OpSysCSD
v OpSysRelease
v Request
v RequestList
v RtBuild
v RtRelease
v Script
v ServerUserId
v StartLogging
v TempDir
v ThreadHandle
v ThreadId
Chapter 4. Object Properties and Global Functions 81
ArchBrowseIdxDirReturns the Archive Browse Index path.App.ArchBrowseIdxDir()
ExamplePrint " Archive Browse Index Path: " & App.ArchBrowseIdxDir()
ArchDirReturns the Archive path.App.ArchDir()
ExamplePrint " Archive Path: " & App.ArchDir()
ArchIdxDirReturns the Archive Index path.App.ArchIdxDir()
ExamplePrint " Archive Index Path: " & App.ArchIdxDir()
ArgReturns, as a string, the argument for the nth parameter, passed to the procedure as long.App.Arg(n)
ExampleDim ArgNum As LongArgNum=1Do While ArgNum<=App.ArgCount()
Print #ReportFile,'' Argument'', _ArgNum,''.......'',App.Arg(ArgNum)
Print '' Argument '' & ArgNum&''.......''&App.Arg(ArgNum)ArgNum=ArgNum+1
Loop
ArgCountReturns, as long, the number of parameters passed to the procedure.App.ArgCount
ExamplePrint " Max Argument: "&App.ArgCount
CompanyNameReturns, as a string, the company name specified when Optim was configured.App.CompanyName
ExamplePrint " Optim CompanyName - "&App.CompanyName
82 IBM Optim: Optim Basic Language Reference
ComputerNameReturns, as a string, the name of the machine.App.ComputerName
ExamplePrint " Computer Name - "&App.ComputerName
DataDirReturns, as a string, the data directory drive and path for Optim.App.DataDir
ExamplePrint " Optim Data Directory - "&App.DataDir
EnvironReturns or sets an environment variable.App.Environ ("variable")
ExampleApp.Environ("EnvironVar") = "Environment variables "&App.Script
ErrorReturns, as a string, the last error message generated by the Optim application.App.Error
ExamplePrint " Rt Error............."&App.Error
InstanceReturns, as long, the thread instance handle.App.Instance
ExamplePrint " Instance............."&App.Instance
LogEventWrites an event to the Windows log or to a file, as defined by the App.StartLogging property.App.LogEvent eventtype,"messagetext",
The following are valid eventtype values:
0x1 RtLogEventTypeError Error
0x2 RtLogEventTypeWarning Warning
0x4 RtLogEventTypeInformation Information
ExampleApp.LogEvent RtLogEventTypeInformation, _
"Write this as an Info:"& Format(Now, "dddd mmm d yyyy")
Chapter 4. Object Properties and Global Functions 83
OpSysReturns a short numeric value that indicates the operating system.App.OpSys
The numeric values that can be returned are as follows:
0 RtOpsysWindowsUnknown Operating system is unknown.
1 RtOpsysWindows95 Operating system is Microsoft Windows 95.
2 RtOpsysWindows98 Operating system is Microsoft Windows 98.
3 RtOpsysWindowNT Operating system is Microsoft Windows NT.
ExampleDim Platform As String
Select Case App.OpSysCase RtOpsysWindows95
Platform = "Windows95"Case RtOpsysWindows98
Platform = "Windows98"Case RtOpsysWindowsNT
Platform = "WindowsNT"Case Else
Platform = "Unknown"End Select
OpSysBuildReturns a float value that indicates the build number for the operating system.App.OpSysBuild
ExamplePrint " Operating SysBuild - "&App.OpSysBuild
OpSysCSDReturns, as a formatted string, the operating system service pack description.App.OpSysCSD
ExamplePrint " Operating ServPack - "&App.OpSysCSD
OpSysReleaseReturns a float value that indicates the operating system release.App.OpSysRelease
ExamplePrint " Operating SysRel - "&App.OpSysRelease
RequestReturns a string value that corresponds to the supplied request variable name.App.Request(variablename)
84 IBM Optim: Optim Basic Language Reference
ExampleDim ReqList As VariantReqList = App.RequestListDim ReqData As String
For Each ReqData In ReqListPrint #ReportFile," ",ReqData,".....",App.Request(ReqData)Print " " & ReqData & "....." & App.Request(ReqData)
Next ReqData
RequestListReturns a list of variable names, as strings, that can be queried using App.Request.App.RequestList
ExampleDim ReqList As VariantReqList = App.RequestListDim ReqData As String
For Each ReqData In ReqListPrint #ReportFile," ",ReqData,".....",App.Request(ReqData)Print " " & ReqData & "....." & App.Request(ReqData)
Next ReqData
RtBuildReturns the current build of Optim.App.RtBuild
ExamplePrint " Rt Build - "&App.RtBuild
RtReleaseReturns the current release of Optim.App.RtRelease
ExamplePrint " RT Release - "&App.RtRelease
ScriptReturns, as a string, the name of the Column Map Procedure that is currently executing.App.Script
ExamplePrint " Rt Script Name - "&App.Script
ServerUserIdReturns the User Id for the server.App.ServerUserId
ExamplePrint " Server UserId - "&App.ServerUserId
StartLoggingSets destination and mode for the log.App.StartLogging(mode, "path")
Chapter 4. Object Properties and Global Functions 85
The default path is \PROC.log in the temporary directory for the Optim application. The following arevalid modes:
0 RtLogAuto If running on Windows NT, directs log records to the Window Eventmanager. If not on NT, directs logs records to a specified file.
1 RtLogOff Turns RT logging off.
2 RtLogToFile Directs log records to a specified file.
3 RtLogToNT Directs log records to the Windows Event manager.
0x10 RtLogOverwrite Recreates the log file each time the application starts.
0x20 RtLogThreadId Prefixes ThreadId to all log entries.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' Load' Example of Event Logging.'--------------------------------------------------------------------Sub Load()
If (App.Arg(1) = "File") Then' Direct Log Records to a specified file, Prefix ThreadId to all' event entries, and ensure an empty log file at Load of this' CM Proc.App.StartLogging _
RtLogToFile+RtLogThreadID+RtLogOverwrite,_"c:\rtwin.log"
ElseIf (App.Arg(1) = "Windows") Then' Direct Log Records to Window's Event manager and DONT' Prefix ThreadId.App.StartLogging RtLogToNT,""
Else' If NT log to Event manager, if not NT log to specified file.App.StartLogging RtLogAuto+RtLogThreadID,"c:\rtwin.log"
End IfApp.LogEvent RtLogEventTypeInformation, _
"Write this as an Info: " & Format _(Now, "dddd mmm d yyyy")
App.StartLogging RtLogOff,"" ' Turn Rt Logging offEnd Sub
TempDirReturns, as a string, the temporary directory drive and path for Optim.App.TempDir
ExamplePrint " Rt Temp Directory - "&App.TempDir
ThreadHandleReturns, as long, the thread handle.App.ThreadHandle
ExamplePrint " ThreadHandle - "&App.ThreadHandle
86 IBM Optim: Optim Basic Language Reference
ThreadIdReturns, as long, the thread ID.App.ThreadId
ExamplePrint " ThreadId - "&App.ThreadId
Properties for Source ObjectYou can use properties to get information about a source table and its columns. For example, you canobtain a list of columns in the source table or the source table name.
Properties for a source table or its columns are:v Column
v ColumnList
v CreateFile
v CreatorId
v DBAlias
v IsColumn
v OwnerId
v Table
Column (source object)Returns the column object for the specified column.Source.Column("columnname")
ExampleDim ColInstance As Object
Set ColInstance = Source.Column("CUST_ID") ' Faster to' keep instance
statements...
ColumnListReturns a variant list of columns in the source table.Source.ColumnList
ExampleDim ColList As VariantColList = Source.ColumnListDim col As StringDim NullAttr As StringDim Part1 As StringDim Part2 As StringDim Part3 As StringFor Each col In ColList
NullAttr = ""Set ColInstance = Source.Column(col) ' Faster to keep instanceIf ColInstance.Nullable Then NullAttr = "(N)"Part2 = "Name: " & ColInstance.Name & NullAttrPart1 = Pad(Part2,25) & " Type:" & ColInstance.TypePart2 = "Length:" & ColInstance.Length & " Precision:" & _
ColInstance.PrecisionPart3 = " Scale:" & ColInstance.Scale & " Available:" & _
ColInstance.Available'Print " " & Part1
Chapter 4. Object Properties and Global Functions 87
Print Part2 & Part3Print #ReportFile,Part1,Part2,Part3SData.ColumnCnt = SData.ColumnCnt + 1
Next col
CreateFileWrites column data to a destination file.Source.CreateFile({True | False} [,"pathname"])
The destination file is specified by pathname. If pathname is not specified, a unique file name is generatedand placed in the Optim data directory. True indicates that the destination file will be overlaid; Falseindicates that the column data is appended to the destination file.
Example'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
Dim ColInstance As Object' Speed access up to the object
Set ColInstance = Source.Column(Target.Column)
' Have the file deleted, then' write the column data to a file named c:\DATA.LOB
ColInstance.CreateFile(TRUE,"c:\DATA.LOB")Target.SetFromFile("") ' Set Target To Null
End Function
CreatorIdReturns, as a string, the Creator ID for the source table.Source.CreatorId
ExamplePrint " Source Table : " & Source.DBAlias & "." & _
Source.CreatorId & "." & Source.Table
DBAliasReturns, as a string, the DBAlias for the source table.Source.DBAlias
ExamplePrint " Source Table : " & Source.DBAlias & "." & _
Source.CreatorId & "." & Source.Table
IsColumnReturns a Boolean True or False to indicate whether named column is in the table.Source.IsColumn("columnname")
ExamplePrint " Source Table : " & Source.DBAlias & "." & Source.OwnerId _
& "." & Source.Table
88 IBM Optim: Optim Basic Language Reference
OwnerIdReturns, as a string, the Owner Id for the table.Source.OwnerId
ExamplePrint " Source Table : " & Source.DBAlias & "." & _
Source.CreatorId & "." & Source.Table
TableReturns, as a string, the table name.Source.Table
ExamplePrint " Source Table : " & Source.DBAlias & "." & _
Source.CreatorId & "." & Source.Table
Properties for Target ObjectYou can use properties to return the name of a column and to set values for a column in a destinationtable.
Properties for a target object are:v Column
v SetFromFile
v Value
Column (target object)Returns the name of the target column as a string.Target.Column
ExampleFunction CmTransform() As Integer
Target.Value = Source.Column(Target.Column).ValueEnd Function
SetFromFileSets the target column with the data contained in a specified file.Target.SetFromFile("[pathname]")
The file is specified by pathname. If pathname is not specified or the file is empty, the target column is setto Null.
Example'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
Dim ColInstance As Object' Speed access up to the object
Set ColInstance = Source.Column(Target.Column)
' Have the file deleted, then' write the column data to a file named c:\DATA.LOB
Chapter 4. Object Properties and Global Functions 89
ColInstance.CreateFile(TRUE,"c:\DATA.LOB")Target.SetFromFile("") ' Set Target To Null
End Function
Value (target object)Sets the value for a column according to the value on the right side of the “=” sign.Target.Value
ExampleFunction CmTransform() As Integer
Target.Value = "New Value"End Function
Properties for a Column InstanceYou can use several properties to get values for a column instance in a Source or Target object.
Properties for a column instance are:v Available
v IsNull
v Length
v Name
v Nullable
v Precision
v Scale
v Type
v Value
AvailableReturns a Boolean True or False to indicate whether column is available.colinstance.Available
Each column is processed in the order listed in the Column Map. A column is available unless its value isdetermined by a Column Map Exit or Column Map Procedure that has not yet executed.
ExamplePrint " Column Available : " & ColInstance.Available
IsNullReturns a Boolean True or False to indicate whether value in column instance is Null.colinstance.IsNull
ExamplePrint " Column IsNull : " & ColInstance.IsNull
To set a column to null you can use SetFromFile with an empty file name or the name of a file with asize of zero. You can also use the reserved word Empty, as in the following example:Function CmTransform() As IntegerIf (Source.Column("STATE").Value = "PA") Then
Target.Value = Empty
90 IBM Optim: Optim Basic Language Reference
ElseTarget.Value = Source.Column(Target.Column).Value
End IfEnd Function
LengthReturns column data length, as long.colinstance.Length
ExamplePart2 = "Length:" & ColInstance.Length & " Precision:" & _
ColInstance.Precision
NameReturns column name, as a string.
ExamplePart2 = "Name: " & ColInstance.Name & NullAttr
NullableReturns a Boolean True or False to indicate whether column instance is Null eligible.colinstance.Nullable
ExampleIf ColInstance.Nullable Then NullAttr = "(N)"
PrecisionReturns column precision, as short.colinstance.Precision
ExamplePart2 = "Length:" & ColInstance.Length & " Precision:" & _
ColInstance.Precision
ScaleReturns column scale, as short.colinstance.Scale
ExamplePart3 = " Scale:" & ColInstance.Scale & " Available:" & _
ColInstance.Available'
TypeReturns column type, as short.colinstance.Type
ExamplePart1 = Pad(Part2,25) & " Type:" & ColInstance.Type
Value (column instance)Returns the value for a column instance.colinstance.Value
Chapter 4. Object Properties and Global Functions 91
ExampleFunction CmTransform() As Integer
Target.Value = Source.Column(Target.Column).ValueEnd Function
Global FunctionsUse global functions to return or set values for a column to match a specific DBMS format.
The global functions that are available with Optim Basic are:v GetAllSettings
v GetAsBinary
v GetAsDate
v GetAsDecimalChar
v GetAsDecimalCharSz
v GetAsOracleDate
v GetAsSybaseDateTime
v GetAsSybaseDecimal
v GetAsSybaseMoney
v GetAsSybaseSmallDateTime
v GetAsSybaseSmallMoney
v GetAsTime
v GetAsVarBinary
v GetAsVarChar
v GetAsVarCharSz
v GetGlobalWork
v GetSetting
v PutAsBinary
v PutAsDate
v PutAsDecimalChar
v PutAsDecimalCharSz
v PutAsOracleDate
v PutAsSybaseDateTime
v PutAsSybaseDecimal
v PutAsSybaseMoney
v PutAsSybaseSmallDateTime
v PutAsSybaseSmallMoney
v PutAsTime
v PutAsVarBinary
v PutAsVarChar
v PutAsVarCharSz
v SaveSetting
v SetGlobalWork
GetAllSettingsReturns a two-dimensional array of the key settings and their corresponding values contained in theapplication node and section node.
92 IBM Optim: Optim Basic Language Reference
GetAllSettings("appname","section")
The application node and section node are specified by appname and section.
Note: If appname starts with a "\", the user must supply the entire key. If appname does not start with a"\", the following is used as the first part of the key: Software\Princeton Softech\Scripting
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' Load' Called before any tables processed'--------------------------------------------------------------------Sub Load()
Dim RegEntries As VariantDim RegNum As IntegerDim RC As LongRegEntries = GetAllSettings("Default","MyData")If IsArray(RegEntries) Then
RegNum = LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,1) & " Lower:" & _
LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,2) & " Lower:" & _
LBound(RegEntries,2)Do While RegNum <= UBound(RegEntries,1)
Print RegEntries(RegNum,LBound(RegEntries,2)) & " " _& RegEntries(RegNum,LBound(RegEntries,2)+1)
RegNum = RegNum + 1Loop
ElsePrint "RegEntriesis not a table " & VarType(RegEntries)Exit Sub
End IfRC = SaveSetting("Default","MyData","Entry1", _
"Update with string")Print GetSetting("Default","MyData","Entry1", _
"Did SaveSetting fail?")End Sub
GetAsBinaryReturns Binary Column value.GetAsBinary(column,length)
The length is the area to copy to the target. A short return code indicates success or failure.
ExampleDim buffer As ByteDim rc As Integerrc = GetAsBinary(Source.Column(Target.Column),buffer,1)If (rc = 1) Then
Print "Retrieved a single byte"ElseIf (rc = 0) Then
Print "Column is Null"Else
Print "Expected rc from RT:" & rcEnd If
GetAsDateReturns Date Column value.GetAsDate(column,pointer)
Chapter 4. Object Properties and Global Functions 93
The pointer points to a PST_STRUCT_DATE structure in which Year, Month, and Day are integers. Ashort return code indicates success or failure.
ExampleDim RtDate As PST_STRUCT_DATEIf (GetAsDate(Source.Column(Target.Column),RtDate)) Then
Print RtDate.Month & "/" & RtDate.Day & "/"& RtDate.YearElse
Print "Unable to Convert date for customer: " & _Source.Column("CUST_ID").Value
End If
GetAsDecimalCharReturns a Decimal Character value with the specified precision and scale.GetAsDecimalChar(column,precision[,scale])
A short return code indicates success or failure.
ExamplePrint GetAsDecimalChar(Source.Column(Target.Column),0,0)
GetAsDecimalCharSzReturns a Decimal Character value.GetAsDecimalCharSz(column,precision,scale)
A short return code indicates success or failure.
ExamplePrint GetAsDecimalCharSz(Source.Column(Target.Column))
GetAsOracleDateReturns an Oracle Date value.GetAsOracleDate(column,pointer)
The pointer points to a PST_RT_STRUCT_ORA_DATE structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtOraDate As PST_RT_STRUCT_ORA_DATE
If (GetAsOracleDate(Source.Column(Target.Column), _RtOraDate)) Then
Print RtOraDate.Century &"-"& RtOraDate.Year &"-"& _RtOraDate.Month &"-"& RtOraDate.Day &"-"& _
RtOraDate.Hour &"-"& RtOraDate.Minute &"-"& _RtOraDate.Second
RtOraDate.Century = Mid(RtOraDate.Century,2,2)
94 IBM Optim: Optim Basic Language Reference
RtOraDate.Year = Mid(RtOraDate.Year,2,2)Print "Oracle Date = " & RtOraDate.Month & "/" & _
RtOraDate.Day & "/" & RtOraDate.Century & _RtOraDate.Year
Print ""Else
Print "Unable to Convert RtOraDate"End If
End Function
GetAsSybaseDateTimeReturns a Sybase Adaptive Server Enterprise (ASE) Date value.GetAsSybaseDateTime(column,pointer)
The pointer points to a PST_STRUCT_SYB_DATETIME structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
Target.Value = Source.Column(Target.Column).ValueDim RtSybDateTime As PST_STRUCT_SYB_DATETIMEIf (GetAsSybaseDateTime(Source.Column(Target.Column), _
RtSybDateTime)) ThenPrint "Data Value : " & _
Source.Column(Target.Column).ValuePrint "RtSybDateTime.Date : " & RtSybDateTime.DatePrint "RtSybDateTime.Time : " & RtSybDateTime.TimePrint "Converted Date : " & _
SybaseDateToStr(RtSybDateTime)Print ""
ElsePrint "Unable to Convert RtSybDateTime"
End If
End FunctionFunction SybaseDateToStr(ByRef SybDate As _
PST_STRUCT_SYB_DATETIME) As StringDim j As Long,jx4m1 As Long,dx4p3 As Long, dx5m3 As LongDim Year As LongDim Day As LongDim Month As LongDim TempTS As datetimej = SybDate.Date + 693902jX4m1 = (j * 4) - 1Year = Int(jX4m1 / 146097)j = jX4m1 - (Year * 146097)Day = Int(j / 4)dX4p3 = Day * 4 + 3j = Int(dX4p3 / 1461)Day = dX4p3 - (j * 1461)Day = Int((Day + 4) / 4)dX5m3 = Day * 5 - 3Month = Int(dX5m3 / 153)Day = dX5m3 - Month * 153Day = (Day + 5) / 5Year = Year * 100 + jIf Month < 10 Then
Month = Month + 3
Chapter 4. Object Properties and Global Functions 95
ElseMonth = Month - 9Year = Year +1
End IfSybaseDateToStr = Year & " " & Month & " " & Day
End Function
GetAsSybaseDecimalReturns a Sybase ASE Decimal value.GetAsSybaseDecimal(column,pointer)
The pointer points to a PST_RT_STRUCT_SYB_DEC structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtSybDecimal As PST_RT_STRUCT_SYB_DECIf (GetAsSybaseDecimal(Source.Column(Target.Column), _
RtSybDecimal)) ThenPrint "RtSybDecimal.Precision : " & _
RtSybDecimal.PrecisionPrint "RtSybDecimal.Scale : " & RtSybDecimal.ScalePrint ""
ElsePrint "Unable to Convert RtSybDecimal"
End If
End Function
GetAsSybaseMoneyReturns a Sybase ASE Money value.GetAsSybaseMoney(column,pointer)
The pointer points to a PST_STRUCT_SYB_MONEY structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtSybMoney As PST_STRUCT_SYB_MONEY
If (GetAsSybaseMoney(Source.Column(Target.Column), _RtSybMoney)) ThenPrint "Data Value : " & _
96 IBM Optim: Optim Basic Language Reference
Source.Column(Target.Column).ValuePrint "RtSybMoney.High : " & RtSybMoney.HighPrint "RtSybMoney.Low : " & RtSybMoney.LowPrint ""
ElsePrint "Unable to Convert RtSybMoney"
End If
End Function
GetAsSybaseSmallDateTimeReturns a Sybase ASE Small Date value.GetAsSybaseSmallDateTime(column,pointer)
The pointer points to a PST_STRUCT_SYB_SMALLDATETIME structure. A short return code indicatessuccess or failure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtSybSmallDateTime As _
PST_STRUCT_SYB_SMALLDATETIME
If (GetAsSybaseSmallDateTime(Source.Column _(Target.Column), RtSybSmallDateTime)) Then
Print "Data Value : " & _Source.Column(Target.Column).Value
Print "RtSybSmallDateTime.Date : " & _RtSybSmallDateTime.Date
Print "RtSybSmallDateTime.Time : " & _RtSybSmallDateTime.Time
Print ""Else
Print "Unable to Convert RtSybSmallDateTime"End If
End Function
GetAsSybaseSmallMoneyReturns a Sybase ASE Small Money value.GetAsSybaseSmallMoney(column,pointer)
The pointer points to a PST_STRUCT_SYB_SMALLMONEY structure. A short return code indicatessuccess or failure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
Chapter 4. Object Properties and Global Functions 97
' Following instruction copies source value to target value' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtSybSmallMoney As PST_STRUCT_SYB_SMALLMONEYRtSybSmallMoney.Money = 0
If (GetAsSybaseSmallMoney(Source.Column(Target.Column), _RtSybSmallMoney)) Then
Print "Data Value : " & _Source.Column(Target.Column).Value
Print "RtSybSmallMoney.Money : " & _RtSybSmallMoney.Money
Print ""Else
Print "Unable to Convert RtSybSmallMoney"End If
End Function
GetAsTimeReturns a Time value.GetAsTime(column,pointer)
The pointer points to a PST_STRUCT_TIME structure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value.' It should be replaced by your code.Target.Value = Source.Column(Target.Column).ValueDim RtTime As PST_STRUCT_TIME
If (GetAsTime(Source.Column(Target.Column),RtTime)) ThenPrint "Data Value : " & _
Source.Column(Target.Column).ValuePrint "RtTime.Hour : " & RtTime.Hour
Print "RtTime.Minute : " & RtTime.MinutePrint "RtTime.Second : " & RtTime.SecondPrint ""
ElsePrint "Unable to Convert time for customer: " & _
Source.Column("CUST_ID").ValueEnd If
End Function
GetAsVarBinaryReturns a Variable column value in binary format.GetAsVarBinary(column,pointer)
The pointer points to a PST_STRUCT_VARBIN structure. A short return code indicates success or failure.
ExampleDim RtVarBin As PST_STRUCT_VARBINIf (GetAsVarBinary(Source.Column(Target.Column),RtVarBin))Then
Print "Data Value : " & Source.Column(Target.Column).Value
98 IBM Optim: Optim Basic Language Reference
Print "RtVarBin.Length : " & RtVarBin.LengthPrint ""
ElsePrint "Unable to Convert RtVarBin"
End If
GetAsVarCharReturns a Variable column value in character format.GetAsVarChar(column,pointer)
The pointer points to a PST_STRUCT_VARCHAR structure. A short return code indicates success orfailure.
ExampleDim RtVarChar As PST_STRUCT_VARCHARIf (GetAsVarChar(Source.Column(Target.Column),RtVarChar)) Then
' Print RtVarChar.Length & " " & Len(RtVarChar.Data)Print "Column Data Value : " & _
Source.Column(Target.Column).ValuePrint "RtVarChar.Length : " & RtVarChar.Length & " _
RtVarChar.Data : " & RtVarChar.DataPrint ""
ElsePrint "Unable to Convert RtVarChar"
End If
GetAsVarCharSzReturns a Variable column value with Null delimiter in character format.GetAsVarCharSz(column,pointer)
The pointer points to a PST_STRUCT_VARCHAR structure. A short return code indicates success orfailure.
ExampleDim RtVarCharSz As PST_STRUCT_VARCHARIf (GetAsVarCharSz(Source.Column(Target.Column), _
RtVarCharSz)) ThenPrint "Data Value : " & Source.Column(Target.Column).ValuePrint "RtVarCharSz.Length : " & RtVarCharSz.LengthPrint "RtVarCharSz.Data : " & RtVarCharSz.DataPrint ""
ElsePrint "Unable to Convert RtVarCharSz"
End If
GetGlobalWorkRetrieves information that was previously saved in the Global Work area by SetGlobalWork.GetGlobalWork(area,length)
The area argument points to the work area; length indicates, as short, the length of the area to beupdated.
For more information on SetGlobalWork, see “SetGlobalWork” on page 108.
ExampleType GlobalArea
FileOpen As BooleanSysInfo As Boolean
Chapter 4. Object Properties and Global Functions 99
TableCnt As LongColumnCnt As LongCurTable As String
End TypeSub Load()
Dim GData As GlobalArea' Get copy of current information
Call GetGlobalWork(GData,Len(GData))If GData.SysInfo = false Then
SysInfoEnd If
GData.SysInfo = trueGData.FileOpen = trueGData.TableCnt = 0GData.ColumnCnt = 0
statements...Exit Sub
End Sub
GetSettingReturns a variant of the key setting value for the specified key, which is found in the application nodeand section node.GetSetting("appname","section","key"[,"default"])
The application node and section node are specified by appname and section. The optional default is anexpression containing the value to return if no value is set for the specified key.
Note: If appname starts with a "\", the user must supply the entire key. If appname does not start with a"\", the following is used as the first part of the key: Software\Princeton Softech\Scripting
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' Load' Called before any tables processed'--------------------------------------------------------------------Sub Load()
Dim RegEntries As VariantDim RegNum As IntegerDim RC As LongRegEntries = GetAllSettings("Default","MyData")If IsArray(RegEntries) Then
RegNum = LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,1) & " Lower:" & _
LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,2) & " Lower:" & _
LBound(RegEntries,2)Do While RegNum <= UBound(RegEntries,1)
Print RegEntries(RegNum,LBound(RegEntries,2)) & " " _& RegEntries(RegNum,LBound(RegEntries,2)+1)
RegNum = RegNum + 1Loop
ElsePrint "RegEntries is not a table " & VarType(RegEntries)Exit Sub
End IfRC = SaveSetting("Default","MyData","Entry1", _
"Update with string")Print GetSetting("Default","MyData","Entry1", _
"Did SaveSetting fail?")End Sub
100 IBM Optim: Optim Basic Language Reference
PutAsBinaryReturns Binary Column value.PutAsBinary(column,length)
The length is the length of the area to copy to the target. A short return code indicates success or failure.
ExampleDim buffer As ByteDim rc As Integerbuffer = ''A''rc = PutAsBinary,buffer,1)If (rc = PST_EXIT_SUCCESS) Then
Print "Single byte successfully set"Else
Print "Unexpected rc from RT:" & rcEnd If
PutAsDateSets Date column value.PutAsDate(column,pointer)
The pointer points to a PST_STRUCT_DATE structure in which Year, Month, and Day are integers. Ashort return code indicates success or failure.
ExampleFunction CmTransform() As Integer
Dim NewDate As PST_STRUCT_DATEDim RtDate As PST_STRUCT_DATETarget.Value = Source.Column(Target.Column).Value
If (GetAsDate(Source.Column(Target.Column),RtDate)) ThenNewDate.Year = RtDate.Year - 50NewDate.Month = RtDate.MonthNewDate.Day = RtDate.DayPrint "Old Date = " & RtDate.Month & "/" & RtDate.Day _
& "/" & RtDate.YearPrint "New Date = " & NewDate.Month & "/" & NewDate.Day _
& "/" & NewDate.YearIf (PutAsDate(NewDate) = PSTEXIT_SUCCESS) Then
Print "PutAsDate(NewDate) " & NewDate.Month & "/" & _NewDate.Day & "/" & NewDate.Year & _" was successful"
Print ""Else
Print "PutAsDate(NewDate) FAILED"CmTransform = PST_CM_EXIT_ABORT_PROCESSPrint ""
End IfElse
Print "Unable to calculate NewDate.Year"End If
End Function
PutAsDecimalCharSets Decimal Character column value.PutAsDecimalChar(pointer)
The pointer points to a string value. A short return code indicates success or failure.
Chapter 4. Object Properties and Global Functions 101
ExampleFunction CmTransform() As Integer
' Following instruction copies source value to target valueDim NewDecimalChar As StringNewDecimalChar = 250
If (PutAsDecimalChar(NewDecimalChar ) _= PSTEXIT_SUCCESS) Then
Print "PutAsDecimalChar worked - Data Value = " & _NewDecimalChar
Print ""Else
Print "PutAsDecimalChar FAILED"Print ""CmTransform = PST_CM_EXIT_ABORT_PROCESS
End IfEnd Function
PutAsDecimalCharSzSets Decimal Character column value.PutAsDecimalCharSz(pointer)
The pointer points to a string value. A short return code indicates success or failure.
ExampleFunction CmTransform() As Integer
' Following instruction copies source value to target valueDim NewDecimalCharSz As IntegerNewDecimalCharSz = 333.333
If (PutAsDecimalCharSz(NewDecimalCharSz) = _PSTEXIT_SUCCESS) Then
Print "PutAsDecimalCharSz worked - Data Value = " _& NewDecimalCharSz
Print ""Else
Print "PutAsDecimalCharSz FAILED"Print "PST_CM_EXIT_ABORT_PROCESS = " & _
PST_CM_EXIT_ABORT_PROCESSCmTransform = PST_CM_EXIT_ABORT_PROCESS
End IfEnd Function
PutAsOracleDateSets Oracle Date column value.PutAsOracleDate(column,pointer)
The pointer points to a PST_STRUCT_ORA_DATE structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Dim RtOraDate As PST_RT_STRUCT_ORA_DATE
102 IBM Optim: Optim Basic Language Reference
RtOraDate.Century = 120RtOraDate.Year = 101RtOraDate.Month = 3RtOraDate.Day = 17RtOraDate.Hour = 1RtOraDate.Minute = 1RtOraDate.Second = 1If PutAsOracleDate(RtOraDate) = PSTEXIT_SUCCESS Then
Print "Put as Date 03/17/2001-00:00:00 AM"Else
Print "PutAsDate failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End If
End Function
PutAsSybaseDateTimeSets a Sybase ASE Date column value.PutAsSybaseDateTime(column,pointer)
The pointer points to a PST_STRUCT_SYB_DATETIME structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
Dim NewTime As PST_STRUCT_SYB_DATETIMENewTime.Date = 37130NewTime.Time = 10230642If (PutAsSybaseDateTime(NewTime) = PSTEXIT_SUCCESS) _
ThenPrint "Put as Date worked (08/29/2001-9:28:22.042 AM)"Print ""
ElsePrint "PutAsDate failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End If
End Function
PutAsSybaseDecimalSets a Sybase ASE Decimal column value.PutAsSybaseDecimal(column,pointer)
The pointer points to a PST_RT_STRUCT_SYB_DEC structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value
Chapter 4. Object Properties and Global Functions 103
' It should be replaced by your code.Dim NewSybDecimal As PST_RT_STRUCT_SYB_DECNewSybDecimal.Precision = 5NewSybDecimal.Scale = 2NewSybDecimal.Array = 77If (PutAsSybaseDecimal(NewSybDecimal) _
= PSTEXIT_SUCCESS) ThenPrint "Put as Date worked"
ElsePrint "RtSybDecimal failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End IfEnd Function
PutAsSybaseMoneySets a Sybase ASE Money column value.PutAsSybaseMoney(column,pointer)
The pointer points to a PST_STRUCT_SYB_MONEY structure. A short return code indicates success orfailure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Dim RtSybMoney As PST_STRUCT_SYB_MONEYRtSybMoney.High = 0RtSybMoney.Low = 457236000
If (PutAsSybaseMoney (RtSybMoney) = PSTEXIT_SUCCESS) _Then
Print "PutAsSybaseMoney worked"Else
Print "PutAsSybaseMoney failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End If
End Function
PutAsSybaseSmallDateTimeSets a Sybase ASE Small Date column value.PutAsSybaseSmallDateTime(column,pointer)
The pointer points to a PST_STRUCT_SYB_SMALLDATETIME structure. A short return code indicatessuccess or failure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value
104 IBM Optim: Optim Basic Language Reference
' It should be replaced by your code.Dim RtSybSmallDateTime As _
PST_STRUCT_SYB_SMALLDATETIMERtSybSmallDateTime.Date = 39RtSybSmallDateTime.Time = 105' NewTime.Date = 37130' NewTime.Time = 10230642
If (PutAsSybaseSmallDateTime(RtSybSmallDateTime) _= PSTEXIT_SUCCESS) Then
Print "PutAsSybaseSmallDateTime (02/09/1900-01:45 AM)"Print ""
ElsePrint "PutAsSybaseSmallDateTime failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End If
End Function
PutAsSybaseSmallMoneySets a Sybase ASE Small Money column value.PutAsSybaseSmallMoney(column,pointer)
The pointer points to a PST_STRUCT_SYB_SMALLMONEY structure. A short return code indicatessuccess or failure.
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' CmTransform' Called for each row being processed'--------------------------------------------------------------------Function CmTransform() As Integer
' Following instruction copies source value to target value' It should be replaced by your code.Dim RtSybSmallMoney As PST_STRUCT_SYB_SMALLMONEYRtSybSmallMoney.Money = 500000
If (PutAsSybaseSmallMoney (RtSybSmallMoney) _= PSTEXIT_SUCCESS) Then
Print "PutAsSybaseSmallMoney (50.00) worked"Else
Print "PutAsSybaseSmallMoney failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End IfEnd Function
PutAsTimeSets a Time column value.PutAsTime(column,pointer)
The pointer points to a PST_STRUCT_TIME structure. A short return code indicates success or failure.
ExampleOption ExplicitOption Base 1' CmTransform' Called for each row being processedFunction CmTransform() As Integer
' Following instruction copies source value to target value
Chapter 4. Object Properties and Global Functions 105
' It should be replaced by your code.Dim RtTime As PST_STRUCT_TIMERtTime.Hour = 12RtTime.Minute = 24RtTime.Second = 36
If (PutAsTime(RtTime) = PSTEXIT_SUCCESS) ThenPrint "PutAsTime 12:24:36 PM worked"
ElsePrint "PutAsTime failed"CmTransform = PST_CM_EXIT_ABORT_PROCESS
End IfEnd Function
PutAsVarBinarySets a Variable column value in binary format.PutAsVarBinary(column,pointer)
The pointer points to a PST_STRUCT_VARBIN structure. A short return code indicates success or failure.
ExampleDim RtVarBin As PST_STRUCT_VARBINIf (PutAsVarBinary(Source.Column(Target.Column),RtVarBin))Then
Print "Data Value : " & Source.Column(Target.Column).ValuePrint "RtVarBin.Length : " & RtVarBin.LengthPrint ""
ElsePrint "Unable to Convert RtVarBin"
End If
PutAsVarCharSets a Variable column value in character format.PutAsVarChar(column,pointer)
The pointer points to a PST_STRUCT_VARCHAR structure. A short return code indicates success orfailure.
ExampleFunction CmTransform() As Integer
' Following instruction copies source value to target valueDim NewVarChar As PST_STRUCT_VARCHARNewVarChar.Length = 75NewVarChar.Data = "Test of PutAsVarChar"If (PutAsVarChar(NewVarChar) = PSTEXIT_SUCCESS) Then
Print "PutAsVarChar data = [Test of PutAsVarChar]"Print ""
ElsePrint "PutAsVarChar(NewVarChar) FAILED"CmTransform = PST_CM_EXIT_ABORT_PROCESSPrint ""
End If
End Function
PutAsVarCharSzSets a Variable column value with Null delimiter in character format.PutAsVarCharSz(column,pointer)
106 IBM Optim: Optim Basic Language Reference
The pointer points to a PST_STRUCT_VARCHAR structure. A short return code indicates success orfailure.
ExampleFunction CmTransform() As Integer
' Following instruction copies source value to target valueDim NewVarCharSz As PST_STRUCT_VARCHARNewVarCharSz.Length = 255NewVarCharSz.Data = "PutAsVarCharSz PutAsVarCharSz _
PutAsVarCharSz PutAsVarCharSz PutAsVarCharSz _PutAsVarCharSz"
If (PutAsVarCharSz(NewVarCharSz) = PSTEXIT_SUCCESS)Then
Print "PutAsVarCharSz data = [PutAsVarCharSz _PutAsVarCharSz PutAsVarCharSz PutAsVarCharSz _PutAsVarCharSz PutAsVarCharSz]"
Print ""Else
Print "PutAsVarCharSz(NewVarCharSz) FAILED"CmTransform = PST_CM_EXIT_ABORT_PROCESSPrint ""
End IfEnd Function
SaveSettingSets the value of the key setting in the application node and section nodeSaveSetting "appname","section","key",value
The application node and section node are specified by appname and section, where the key setting isbeing saved. The argument key is the name of the key setting being saved. The argument value is anexpression containing the value to which key will be set.
Note: If appname starts with a "\", the user must supply the entire key. If appname does not start with a"\", the following is used as the first part of the key: Software\Princeton Softech\Scripting
ExampleOption ExplicitOption Base 1'--------------------------------------------------------------------' Load' Called before any tables processed'--------------------------------------------------------------------Sub Load()
Dim RegEntries As VariantDim RegNum As IntegerDim RC As LongRegEntries = GetAllSettings("Default","MyData")If IsArray(RegEntries) Then
RegNum = LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,1) & " Lower:" & _
LBound(RegEntries,1)Print "Upper: " & UBound(RegEntries,2) & " Lower:" & _
LBound(RegEntries,2)Do While RegNum <= UBound(RegEntries,1)
Print RegEntries(RegNum,LBound(RegEntries,2)) & " " _& RegEntries(RegNum,LBound(RegEntries,2)+1)
RegNum = RegNum + 1Loop
ElsePrint "RegEntries is not a table " & VarType(RegEntries)Exit Sub
End If
Chapter 4. Object Properties and Global Functions 107
RC = SaveSetting("Default","MyData","Entry1", _"Update with string")
Print GetSetting("Default","MyData","Entry1", _"Did SaveSetting fail?")
End Sub
SetGlobalWorkSaves data for later reference.SetGlobalWork(pointer,length)
The pointer points to a work area and length is the length of the area. A short return code indicatessuccess or failure.
ExampleOption ExplicitOption Base 1Type GlobalWork
Test As String * 30End TypeSub Load
statementsDim GlblWork As GlobalWork' Test global workCall SetGlobalWork(GlblWork, Len(GlblWork))GlblWork.Test = "TESTGLBL"statements
End Load
Global Function Return CodesA return code indicates the success or failure of a global function.
Return Codes— Get
For global functions beginning with Get (for example, GetAsBinary), one of the following three returncodes indicates success or failure:
Return Code Mnemonic Description
0 TRUE Column data is not null
1 FALSE Column data is null
255 PSTEXIT_INVALID_PRECISION Column is unknown
Note: All other conditions cause the script to be aborted.
Return Codes— Put
For global functions beginning with Put (for example, PutAsBinary), one of the following return codesindicates success or failure:
Return Code Mnemonic Description
0 PSTEXIT_SUCCESS Process executed successfully
2 PSTEXIT_INVALID_LENGTH Invalid length
3 PSTEXIT_INVALID_PRECISION Invalid precision
4 PSTEXIT_INVALID_SCALE Invalid Scale
6 PSTEXIT_COL_NOT_NULLABLE Column is not Null eligible
108 IBM Optim: Optim Basic Language Reference
Return Code Mnemonic Description
7 PSTEXIT_INCOMPATIBLE_TYPE Type is incompatible
8 PSTEXIT_TRUNC_WARNING Truncation warning
9 PSTEXIT_CONVERSION_ERROR Conversion error
13 PSTEXIT_COL_NOT_AVAILABLE Column is not available
14 PSTEXIT_COL_NOT_UPDATABLE Column is not updatable
15 PSTEXIT_COL_NOT_LOB Column is not a LOB
16 PSTEXIT_INVALID_LOB_SEG_OFFSET
Invalid offset for LOB segment
17 PSTEXIT_INVALID_LOB_SEG_LENGTH
Invalid length for LOB segment
18 PSTEXIT_INVALID_FILE_NAME Invalid file name
19 PSTEXIT_LOB_FILE_OPEN_ERROR Error opening LOB file
20 PSTEXIT_LOB_FILE_IO_ERROR I/O error on LOB file
21 PSTEXIT_LOB_FILE_TOO_LARGE LOB file is too large
255 PSTEXIT_UNKNOWN_COLUMN Column is unknown
Chapter 4. Object Properties and Global Functions 109
110 IBM Optim: Optim Basic Language Reference
Notices
This information was developed for products and services offered in the U.S.A.
IBM® may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply thatonly that IBM product, program, or service may be used. Any functionally equivalent product, program,or service that does not infringe any IBM intellectual property right may be used instead. However, it isthe user's responsibility to evaluate and verify the operation of any non-IBM product, program, orservice.
IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:
IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:
IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Somestates do not allow disclaimer of express or implied warranties in certain transactions, therefore, thisstatement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:
© Copyright IBM Corp. 1994, 2010 111
IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.
The licensed program described in this information and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, orany equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimated throughextrapolation. Actual results may vary. Users of this document should verify the applicable data for theirspecific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to change before theproducts described become available.
This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms.
Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©Copyright IBM Corp. _enter the year or years_. All rights reserved.
112 IBM Optim: Optim Basic Language Reference
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
TrademarksIBM, Optim, the IBM logo, and ibm.com® are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both. If these and other IBMtrademarked terms are marked on their first occurrence in this information with a trademark symbol (®
or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time thisinformation was published. Such trademarks may also be registered or common law trademarks in othercountries. A current list of IBM trademarks is available on the Web at “Copyright and trademarkinformation” at www.ibm.com/legal/copytrade.shtml.
Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States,other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.
Notices 113
114 IBM Optim: Optim Basic Language Reference
Index
AAbs Function 29App object properties 81, 87
ArchBrowseIdxDir 82ArchDir 82ArchIdxDir 82Arg 82ArgCount 82CompanyName 82ComputerName 83DataDir 83Environ 83Error 83Instance 83LogEvent 83OpSys 84OpSysBuild 84OpSysCSD 84OpSysRelease 84Request 84RequestList 85RtBuild 85RtRelease 85Script 85ServerUserId 85StartLogging 85TempDir 86ThreadHandle 86ThreadId 87
AppActivate Statement 29ArchBrowseIdxDir
App object property 82ArchDir
App object property 82ArchIdxDir
App object property 82Arg
App object property 82ArgCount
App object property 82Arrays 21, 22
Dim statement 21Fixed-size 21For...Next statement 22Multi-dimensional arrays 22Option Base statement 21, 22Single arrays 21Static statement 21To keyword 21
Asc Function 30Atn Function 30Available
Column Instance property 90
BByRef 18
Default 18ByVal 18
CCall Statement 30Calling Procedures in DLLs 19
Declare statement 19Function 19Subroutine 19
CBool Function 30CDate Function 31CDbl Function 31ChDir Statement 31ChDrive Statement 32Choose Function 32Chr Function 32CInt Function 33Class
object 23CLng Function 33Close Statement 33CmStartTable Function 2CmTransform function 2Collection object, OLE 25Column
Source object property 87Target object property 89
Column Instance properties 90Available 90IsNull 90Length 91Name 91Nullable 91Precision 91Scale 91Type 91Value 91
Column Map Procedure Editor 1Column Map Procedures 1, 3
Column Map Procedure Editor 1Definition 1Naming conventions 2Reference procedure in Column
Map 3Return codes 2Sample 1, 2
ColumnListSource object property 87
Comments 13CompanyName
App object property 82ComputerName
App object property 83Concatenation and variants 15Const Statement 34Control Structures 16, 17
Do loop 16For...Next loop 16GoTo statement 17If...Then statement 16If...Then...Else statement 16If...Then...ElseIf statement 16Select Case statement 16While loop 16
Cos Function 34CreateFile
Source object property 88CreateObject Function 34
Access an OLE Automation object 26CreatorId
Source object property 88CSng Function 35CStr Function 35CurDir Function 36CVar Function 36
DData types, variables 14DataDir
App object property 83Date Function 36DateSerial Function 37DateValue Function 37Day Function 37DBAlias
Source object property 88Declare Statement 38
Calling procedures 19Dim Statement 38
Declare fixed-size arrays 21Dir Function 39Do...Loop Statement 39
Control structure 16
EElements of Optim Basic 13, 29End Statement 40Environ
App object property 83EOF Function 40Erase Statement 40Error
App object property 83Eventtypes
for App.LogEvent 83Exit Statement 41Exp Function 41
FFile Input/Output 20
Examples 20Functions and statements 20
FileCopy Statement 41FileLen Function 42Fix Function 42For Each...Next Statement 42For...Next Statement 42
Control structure 16Manipulate arrays 22
Format Function 43, 48Multiple formats 44, 45
© Copyright IBM Corp. 1994, 2010 115
Format Function (continued)Examples 45
Predefined date/time formats 45, 46Predefined numeric formats 43Sample date/time formats 47Sample numeric formats 45String formats 47, 48User-defined date/time formats 46,
47User-defined numeric formats 43, 44
FreeFile Function 48Function Statement 48Functions
Abs 29Asc 30Atn 30CBool 30CDate 31CDbl 31Choose 32Chr 32CInt 33CLng 33Cos 34CreateObject 34CSng 35CStr 35CurDir 36CVar 36Date 36DateSerial 37DateValue 37Day 37Dir 39EOF 40Exp 41FileLen 42Fix 42Format 43, 48FreeFile 48GetObject 49Hex 49Hour 50Input 51InStr 52Int 52IsArray 52IsDate 52IsEmpty 53IsNull 53IsNumeric 53IsObject 53LBound 54LCase 54Left 55Len 55LOF 56Log 56LTrim 72Mid 56Minute 56Month 57Now 57Oct 58Right 65Rnd 65RTrim 72
Functions (continued)Second 66Seek 66SendKeys 67Shell 68Sin 69Space 69Sqr 69Str 70StrComp 70String 70Tan 71Time 71Timer 71TimeSerial 72TimeValue 72Trim 72UBound 74UCase 74Val 74VarType 75Weekday 75Year 77
Functions and Statements 29Listed by type 4Quick reference 3Syntax 29
GGet Statement 49GetAllSettings
global function 93GetAsBinary
global function 93GetAsDate
global function 93GetAsDecimalChar
global function 94GetAsDecimalCharSz
global function 94GetAsOracleDate
global function 94GetAsSybaseDateTime
global function 95GetAsSybaseDecimal
global function 96GetAsSybaseMoney
global function 96GetAsSybaseSmallDateTime
global function 97GetAsSybaseSmallMoney
global function 97GetAsTime
global function 98GetAsVarBinary
global function 98GetAsVarChar
global function 99GetAsVarCharSz
global function 99GetGlobalWork
global function 99GetObject Function 49
Access an OLE Automation object 26GetSetting
global function 100
Global functions 92GetAllSettings 93GetAsBinary 93GetAsDate 93GetAsDecimalChar 94GetAsDecimalCharSz 94GetAsOracleDate 94GetAsSybaseDateTime 95GetAsSybaseDecimal 96GetAsSybaseMoney 96GetAsSybaseSmallDateTime 97GetAsSybaseSmallMoney 97GetAsTime 98GetAsVarBinary 98GetAsVarChar 99GetAsVarCharSz 99GetGlobalWork 99GetSetting 100PutAsBinary 101PutAsDate 101PutAsDecimalChar 101PutAsDecimalCharSz 102PutAsOracleDate 102PutAsSybaseDateTime 103PutAsSybaseDecimal 103PutAsSybaseMoney 104PutAsSybaseSmallDateTime 104PutAsSybaseSmallMoney 105PutAsTime 105PutAsVarBinary 106PutAsVarChar 106PutAsVarCharSz 106Return codes, Get 108Return codes, Put 108SaveSetting 107SetGlobalWork 108
Global Statement 49GoTo Statement 49
Control structure 17
HHex Function 49Hour Function 50
IIf...Then Statement, Control structure 16If...Then...Else Statement 16, 50
Control structure 16If...Then...ElseIf Statement
Control structure 16Input # Statement 51Input Function 51Instance
App object property 83InStr Function 52Int Function 52IsArray Function 52IsColumn
Source object property 88IsDate Function 52IsEmpty Function 53
Determine if variant has beenassigned 15
116 IBM Optim: Optim Basic Language Reference
IsNullColumn Instance property 90
IsNull Function 53IsNumeric Function 53
For numeric operations on avariant 15
IsObject Function 53
KKill Statement 54
LLBound Function 54LCase Function 54Left Function 55Len Function 55Length
Column Instance property 91Let Statement 55Line continuation character 13Line Input # Statement 55LOF Function 56Log Function 56LogEvent
App object property 83Eventtypes 83
LTrim Function 72
MMake Applications Work Together
OLE 26, 29Method, Print 62Methods, OLE 24Mid Function 56Minute Function 56MkDir Statement 57Month Function 57
NName
Column Instance property 91Name Statement 57Now Function 57Null
Setting a column to null 89, 90Value, defined 53
NullableColumn Instance property 91
Numbers 14
OObject Linking and Embedding (OLE)
See OLE Fundamentals 23Objects
List of properties 7Oct Function 58OLE Automation 23, 25, 26
Accessing an object 26CreateObject Function 26GetObject Function 26
OLE Fundamentals 23, 29Class 23Making Applications Work
Together 26, 29Installation 26REG.DAT 26REG.DAT and WIN.INI 26
OLE Automation 23, 25, 26Accessing an object 26
OLE Objects 23, 24Application 24Collection object 25Methods 24Properties 24
REG.DATAssociations 26DDE/OLE Automation 26OLE Object Servers 26Shell Operations 26
OLE Objects 23, 25Collection object 25Methods 24Properties 24
On Error Statement 58, 61Descriptions 58, 61
Miscellaneous messages 60OLE Automation messages 60
Syntax to raise errors 58Open Statement 61, 62
Access, argument 61Mode, argument 61Syntax 61
Operators 9Arithmetic operators 9Logical operators 9Precedence 9Relational operators 9
OpSysApp object property 84
Return values 84OpSysBuild
App object property 84OpSysCSD
App object property 84OpSysRelease
App object property 84Optim Basic
elements of 13, 29Option Base Statement 62
Set lower bound of an array 21, 22Option Explicit Statement 62OwnerId
Source object property 89
PPrecision
Column Instance property 91Print # Statement 63
Date 63Empty 63Null 63Syntax 63
Print Method 62Properties 79
App object 81, 87See App object properties
Properties (continued)Column Instance 80, 90
See also Column Instanceproperties 90
Global functions 92See also Global functions 92
Listed by object 7Source object 79, 89Target object 80, 89
See also Target objectproperties 89
Properties, OLE 24PutAsBinary
global function 101PutAsDate
global function 101PutAsDecimalChar
global function 101PutAsDecimalCharSz
global function 102PutAsOracleDate
global function 102PutAsSybaseDateTime
global function 103PutAsSybaseDecimal
global function 103PutAsSybaseMoney
global function 104PutAsSybaseSmallDateTime
global function 104PutAsSybaseSmallMoney
global function 105PutAsTime
global function 105PutAsVarBinary
global function 106PutAsVarChar
global function 106PutAsVarCharSz
global function 106
RRandomize Statement 64ReDim Statement 64REG.DAT 26
Associations 26DDE/OLE Automation 26OLE Object Servers 26Shell Operations 26WIN.INI differences 26
Registration DatabaseSee REG.DAT
Rem Statement 65Request
App object property 84RequestList
App object property 85Right Function 65RmDir Statement 65Rnd Function 65RtBuild
App object property 85RtRelease
App object property 85RTrim Function 72
Index 117
SSaveSetting
global function 107Scale
Column Instance property 91Script
App object property 85Second Function 66Seek Function 66Seek Statement 66Select Case Statement
Control structure 16SendKeys Function 67ServerUserId
App object property 85Set Statement 68SetFromFile
Target object property 89SetGlobalWork
global function 108Shell Function 68
Return value 68Window styles 68
Sin Function 69Source object properties 89
Column 87ColumnList 87CreateFile 88CreatorId 88DBAlias 88IsColumn 88OwnerId 89Table 89
Space Function 69Sqr Function 69StartLogging
App object property 85Modes 85
Statement terminatorMultiple statements on one line 13
StatementsAppActivate 29Call 30ChDir 31ChDrive 32Close 33Const 34Declare 38Dim 38Do...Loop 39End 40Erase 40Exit 41FileCopy 41For Each...Next 42For...Next 42Function 48Get 49Global 49GoTo 49If...Then...Else 50Input # 51Kill 54Let 55Line Input # 55MkDir 57Name 57
Statements (continued)On Error 58, 61Open 61, 62Option Base 62Option Explicit 62Print # 63Randomize 64ReDim 64Rem 65RmDir 65Seek 66Set 68Static 69Sub 70Type 73While...Wend 75With 76Write # 76
Statements and Functions 29Listed by type 4Quick reference 3Syntax 29
Static Statement 69Declare an array within a
procedure 21Str Function 70StrComp Function 70String Function 70Sub Statement 70Subroutines and Functions 17
Naming conventions 17Syntax, functions and statements 29
TTable
Source object property 89Tan Function 71Target object properties 89
Column 89SetFromFile 89Value 90
TempDirApp object property 86
ThreadHandleApp object property 86
ThreadIdApp object property 87
Time Function 71Timer Function 71TimeSerial Function 72TimeValue Function 72To keyword
Specify the lower bound of anarray 21
Trim Function 72Type
Column Instance property 91Type Statement 73
Create user-defined types 22
UUBound Function 74UCase Function 74user-defined Types 73
User-Defined Types 22Type statement 22
VVal Function 74Value
Column Instance property 91Target object property 90
Variable data types 14Variables 14, 15
Data types 14Declaration of (Dim statement) 14Variable and Constant Names 14Variant data type 15Variants and concatenation 15
Variants 15Concatenation 15
VarType Function 75Determine the data type of a
variant 15Return values 75
WWeekday Function 75While...Wend Statement 75
Control structure 16With Statement 76Write # Statement 76
YYear Function 77
118 IBM Optim: Optim Basic Language Reference
����
Printed in USA