Home
HCL Domino Designer Basic User Guide and Reference
This guide provides information on using HCL Domino Designer and programming language reference information.
LotusScript® Language
Welcome to the LotusScript® Language section of Domino® Designer Help.
Compile-time Error Messages
This chapter describes the compile-time error messages in the LotusScript® language.
Illegal BYVAL on arguments to: <subprogram name>

HCL Domino Designer Basic User Guide and Reference
This guide provides information on using HCL Domino Designer and programming language reference information.
- What's new in Domino Designer 12?
  The following features are new for developers in HCL Domino® Designer 12.
- Accessibility and keyboard shortcuts
  Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to use information technology content successfully.
- Application Design
  Welcome to the Application Design section of Domino® Designer Help.
- Application Management
  Welcome to the Application Management section of Domino® Designer Help.
- Domino® Query Language
  Domino® Query Language (DQL) is a facility running on a Domino server that provides a terse, shorthand syntax for finding documents. It supports a wide variety and complexity of search terms. It leverages existing design elements, avoiding the need to write detailed code to access them. DQL consolidates all methods in Domino for searching document contents.
- Composite Applications - Design and Management
  Composite applications are a key element in a service-oriented architecture (SOA) and contextual collaboration strategy. The ability to create and edit composite applications lets you easily integrate different types of components and technologies.
- DB2® Access views
  Domino® Designer includes two types of design elements to assist you in managing data contained in DB2® enabled Notes® databases:
- Programming Overview and User Interface
  This section contains general guidelines and examples that show where to use Java, LotusScript, and the formula language.
- Formula Language
  This section documents the formula language.
- LotusScript® Language
  Welcome to the LotusScript® Language section of Domino® Designer Help.
  - Introduction to LotusScript®
    This chapter introduces LotusScript® and describes, in general terms, how to use the script editor to write and modify scripts, how to compile scripts, and how to use the debugger to locate problems in the logic of your applications.
  - Script and Statement Construction Rules
    This chapter describes the rules for writing the basic elements of a script in the LotusScript® language.
  - Data Types, Constants, and Variables
    This chapter provides information about LotusScript® constants and variables and the data types of the values that they can represent.
  - Expressions and Operators
    This chapter describes the set of LotusScript® operators, how they may be combined with operands to form expressions, and how those expressions are evaluated.
  - Procedures: Functions, Subs, and Properties
  - File Handling
    This chapter describes file handling in the LotusScript® language.
  - Error Processing
    This chapter describes error processing in the LotusScript® language.
  - User-Defined Data Types and Classes
    This chapter describes two kinds of custom data structures that you can define in LotusScript®. Each can hold data of different types in a single data structure.
  - Managing Flow in Scripts
    The flow of execution of a script generally follows the sequence of statements in the script. This chapter describes the behavior of particular statements that alter the flow of execution.
  - Managing Asynchronous Web Agents in Domino®
    This chapter describes how to use multiple threads and synchronization to manage HTTP agents with Domino®.
  - Beyond Core LotusScript®
    This chapter discusses the role that LotusScript® plays with HCL products, your operating environment, other programs, and interactive user applications.
  - LotusScript® Language Reference
    This chapter describes the use of statements, built-in functions, subs, data types, and directives in the LotusScript® language.
  - Language and Script Limits
    This appendix describes LotusScript® language limits of several kinds: for example, the legal ranges in data representation, the limits on numerical specifications within statements, and the maximum number of different kinds of elements that can be defined in a script.
  - Platform Differences
    The LotusScript® language and functionality on the UNIX™ platform, the Macintosh platform, and the IBM i® platform differ in various ways from the language and functionality described in the rest of this language reference. This appendix describes the differences.
  - LotusScript/REXX Integration
    This appendix provides an overview of REXX integration in the LotusScript® language.
  - LotusScript® Aliases
    This appendix lists the LotusScript® aliases and their equivalent text.
  - MIME Charset Names
  - Compile-time Error Messages
    This chapter describes the compile-time error messages in the LotusScript® language.
    - DELETE not valid on: <name>
    - Too many nested INCLUDEs
    - File contains too many source lines
      The source file contains too many lines.
    - Illegal OPTION BASE after array declaration
    - Illegal OPTION DECLARE after implicit declaration
    - Too many items specified in input/output statement
      More than 255 items were specified in one of the following:
    - Illegal value for OPTION BASE
      The following conditions could have caused this error:
    - Too many labels specified in ON...GOTO statement
    - SUB NEW arguments do not match parent's SUB NEW arguments
    - Name previously declared: <name>
      A name that has already been declared in the current scopeis being declared again in the same name space. Names that reside in the same name space may only be declared once in a scope. Each module, sub, function, property, class, and user-defined data type has a particular scope. LotusScript® has three separate name spaces:
    - Class is not a parent of this class: <class name>
      Either of the following conditions could have caused this error:
    - Illegal name for class or type: <name>
      You used the word Object as the name of a user-defined class or data type. Object is a LotusScript® reserved word.
    - Public symbol is declared in another module: <name>
    - Member is not a subprogram: <member name>
      You used "dotdot" notation to refer to a member variable of a base class. This notation is legal only for referring to a member function, sub, or property of a base class. It is not legal for referring to member variables of a base class.
    - Illegal executable code at the module level
      An executable statement appears at the module level. The product in which you are running LotusScript® does not allow executable statements at the module level.
    - Illegal PUBLIC instance of PRIVATE class or type: <instance name>
    - Illegal type suffix on name: <name>
      You appended a data type suffix character to one of the following:
    - ISELEMENT argument is not a list or variant: <name>
    - Illegal scope for PUBLIC or PRIVATE on: <name>
    - Illegal constructor clause on: <sub name>
    - Parent SUB NEW has arguments, SUB NEW is required for: <class name>
    - Illegal USE or UseLSX statement after declaration
    - Member declared in a parent class
      You tried to declare a member variable in a derived class using the same name as a member variable, sub, function, or property of the base class. This is not allowed.
    - Event handler must be a LotusScript® SUB or FUNCTION: <handler name>
    - Member of PUBLIC class or type is instance of a PRIVATE class or type: <member name>
    - FORALL alias variable was previously declared: <name>
      You may not have a Dim statement for the reference variable of a Forall statement. For example:
    - FORALL alias variable already in use: <variable name>
    - CASE ELSE must be the last CASE in a SELECT statement
    - TYPE declaration has no members
    - Declaration of external subprogram is not legal inside a class
    - Illegal use of array or list element as FORALL target
    - Illegal use of property: <property name>
      You tried to use the named property as one of the following:
    - Wrong data type for argument <argument name> in event handler <event handler name>
    - Maximum array dimensions (8) exceeded: <array name>
      You either declared an array with more than eight dimensions or you used more than eight subscripts in referring to an array. An array can have a maximum of eight dimensions.
    - Illegal array bound for: <array name>
      The following conditions could have caused this error:
    - Array size exceeds maximum: <array name>
      You declared an array whose total size is greater than the maximum allowable size. The maximum allowable array size is 65,536 bytes (64K).
    - Illegal specification of array bounds for: <array name>
      You included array bounds in specifying a parameter in the declaration of a sub or function. A parameter that is an array should contain empty parentheses only.
    - Declaration not valid in TYPE scope: <name>
      You declared one of the following as a member of a user-defined data type:
    - Statement is illegal in TYPE block: <keyword>
    - Statement is illegal in CLASS block: <keyword>
    - TYPE may not have instance of itself as a member: <instance name>
      You declared an instance of the user-defined data type being defined as a member of itself. The definition of a user-defined data type may include an instance of another user-defined data type as a member, but not an instance of itself. For example:
    - Out of memory
      You must free enough memory to perform the operation that caused this error message. To free memory in your computer, do one of the following:
    - Size of data cannot exceed 64K in this scope
      The data in the enclosing scope (module or class) exceeds the limit of 64K bytes.
    - Size of data cannot exceed 32K in this scope
      The data in the enclosing scope (sub, function, or property) exceeds the limit of 32K bytes.
    - Illegal constant expression for: <CONST name>
    - Arguments not legal in declaration of: <sub name>
      The following conditions could have caused this error:
    - Undefined label: <label name>
      The sub, function, or property just compiled contains a reference to a label that was never defined. The line number of the error message identifies the End Sub, End Function, or End Property statement that marks the end of the offending procedure. Labels must be defined within the same scope in which they are referenced.
    - Illegal data type for argument: <argument name>
      You used a fixed-length string as a parameter in the declaration of a sub or function. Fixed-length strings are not legal as parameters in subs or functions.
    - Too many arguments for: <subprogram name>
      You specified more than the limit of 31 parameters in the declaration of a sub or function. The maximum number of parameters that may be specified for a sub or function is 31.
    - Cannot subclass: <class name>
      You specified a product class as the base class of a derived class. A product class may not be used as the base class of a derived class.
    - Derived class may not be PUBLIC when parent is PRIVATE: <class name>
    - Illegal use of NEW or DELETE
    - DIM required on declarations in this scope
      You declared a variable at module level without the Dim, Public, or Private keyword, or you declared a variable inside a procedure without the Dim or Static keyword. One of these is required.
    - Illegal PRIVATE declaration of: <name>
    - Illegal PUBLIC declaration of: <name>
    - Name was forward declared as something else: <name>
    - Duplicate forward declaration: <name>
    - Storage class or visibility does not match forward declaration: <subprogram name>
    - Return type does not match forward declaration: <function name>
    - Number of arguments does not match forward declaration: <subprogram name>
    - Argument does not match forward declaration: <argument name>
    - Illegal function return type for: <function name>
    - Method was declared as something else in a parent: <method name>
    - Method signature does not match parent method: <method name>
    - PROPERTY GET and SET must have same storage class and visibility
      One of the following occurred:
    - Illegal property type for: <property name>
    - PROPERTY GET and SET must have same data type
    - Property was declared as something else in a parent: <property name>
    - Property type does not match parent property: <property name>
    - Illegal pass by value: <argument name>
      One of the following happened:
    - Illegal STATIC on: <name>
    - Illegal external argument: <argument name>
      You declared a C function and specified the data type of one of its parameters as a fixed-length string or as a list. You cannot specify a C function parameter as a fixed-length string or a list.
    - Illegal construction of type instance: <instance name>
      You used the keyword New in the declaration of a variable of a user-defined data type or in a statement assigning a value to a variable of a user-defined data type. The keyword New is not allowed in referring to variables of a user-defined type. For example:
    - Class or type name not found: <name>
      You used a name that does not refer to an existing class or user-defined data type where one of these was required. You used the name in one of the following contexts:
    - Illegal range specifier
    - Illegal DEFtype statement after declaration
    - Duplicate range specifier
    - Label is illegal outside of a subprogram
      You defined a label at the module level. Labels may not be defined at the module level. Executable statements at the module level are executed as the module is compiled, and then discarded. Therefore, control cannot be transferred to a labeled statement at the module level.
    - Error number must be INTEGER constant: <name>
    - Error number must be INTEGER
    - Illegal ON ERROR statement
    - Statement is illegal outside of a subprogram
      You used a statement that is not legal at the module level. These statements include:
    - Not a product class: <name>
      You used a user-defined class name in the following statement:
    - Not a product class instance: <name>
    - Not an event name: <name>
    - Not a sub or function name: <name>
      In a statement where the name of a function or sub is expected, you specified a name that is not recognized as a sub or function name. The statement is one of the following:
    - Illegal REDIM on: <name>
    - Illegal RESUME statement
    - FOR count variable already in use: <name>
    - FORALL alias variable is not of same data type: <name>
    - FOR count variable must be a scalar variable: <name>
    - Illegal type suffix on FORALL alias variable: <name>
    - Not a PUBLIC member: <name>
    - Illegal reference to FORALL alias variable: <name>
    - Type suffix does not match data type: <name>
      You referred to a variable, constant, function, or property with a data type suffix character that does not match its declared data type. If a variable is declared as a Variant, references to that variable may not contain any suffix character.
    - Not a member: <name>
      You referred to a nonexistent member of a class or user-defined data type. For example:
    - Variable not declared: <name>
    - Illegal single-line IF
    - Name does not match FOR count variable: <name>
    - Not an array, list, collection or variant: <name>
    - ME not valid outside of class scope
      You used the keyword Me outside of a procedure within a class. Use the keyword Me only inside procedures within a class. You use Me within the definition of a class when referring to members of that class.
    - .. not valid outside of class scope
      You used "dotdot" syntax outside of a procedure within a class. The "dotdot" syntax is only valid inside procedures within a class. You use "dotdot" notation when referring to a procedure in a base class when the derived class has a procedure of the same name, as in the following example:
    - Reference must contain exactly one subscript: <name>
      A reference to a list or collection contains either no subscript or more than one subscript. A list or collection reference must contain exactly one subscript.
    - Illegal parenthesized reference: <name>
      You referred to a name followed by parentheses, but the reference is not to an array, list, or a collection, or a Variant containing a reference to one of these, or to a function.
    - Wrong number of array subscripts for: <array name>
      The number of subscripts in an array reference does not match the number of defined dimensions for the array.
    - Not an instance name: <name>
      A name is followed by a dot, but the name is not an object reference variable, a Variant variable containing a reference to an object, or a variable of a user-defined data type. Use "dot" notation only with variables of one of these three kinds.
    - Bounds must be specified in REDIM of: <array name>
    - Variable required: <name>
    - Named product class instance not valid here
      In one of the following statements, you used the name of a product object in a context in which it is not allowed:
    - Illegal reference to: <name>
      You used a name as though it contained or referred to a value, but it doesn't. For example:
    - Numeric overflow
    - Numeric underflow
    - Illegal numeric constant
      You tried to define a numeric constant, assigning it a value that doesn't match the specified or default data type. For example:
    - Illegal product constant: <name>
      You specified a product constant name that was not recognized by the product.
    - Name too long: <name>
      The specified name is too long (it is truncated in the error message). The maximum length of a LotusScript® name is 40 characters.
    - Token is too long
      The maximum length of a LotusScript® token (a sequence of characters with a unique meaning) may not exceed the maximum allowable length of a string constant (16K characters) plus its delimiters.
    - Declaration may not contain type suffix and data type: <name>
    - Illegal string length constant for: <name>
      You specified a length for a fixed-length string as one of the following:
    - Illegal use of NEW on array or list declaration: <name>
      You used the keyword New in declaring an array or list. This not allowed. In an array or a list whose type is a class, the elements must be constructed individually.
    - INCLUDE filename must be a string constant
    - Cannot open included file: <file name>
      One of the following conditions could have caused this error:
    - Unterminated %REM block
    - Unterminated string constant
      You omitted the double quotation mark that signals the end of a quoted literal on a single line. Double quotation marks must be paired on the same line. For example:
    - Unterminated multiline string
      You omitted the vertical bar (|) that marks the end of a multiline string; or you omitted the close brace (}) that marks the end of a multiline string; or you used a brace as one delimiter and the "|" character as the other. For example:
    - Unterminated square bracket reference
      A square bracket reference was not terminated by a close square bracket (]) on the same line. Square brackets are used in some cases when referring to the names of product items.
    - Illegal character after continuation character
      The line-continuation character underscore ( _ ) is followed on the same line by a character that is not the comment character ('). The line-continuation character must be the last character on a line, except for an optional comment, beginning with the comment character.
    - Illegal character after %INCLUDE directive
    - SET required on class instance assignment (message explained)
      You attempted to assign an object reference to a variable but omitted the Set keyword. (An object reference can be a reference to an instance of a user-defined class, a product object, an OLE automation object, or the constant NOTHING.) The Set keyword is required in object reference assignments. For example:
    - Unterminated <keyword> block
      You omitted the keyword that marks the end of one of the following block statements:
    - Unexpected: <token>; Expected: <token>
      The compiler encountered an unexpected language element.
    - Parser stack overflow at: <token name>
    - Unknown statement
      The compiler could not parse the statement on the line specified in the error message.
    - Maximum number of errors reached
      The maximum of twenty compilation errors has been reached, causing compilation to stop.
    - PROPERTY SET not defined for: <property name>
    - PROPERTY GET not defined for: <property name>
    - Duplicate option
    - Missing argument for: <function name>
      The following conditions could have caused this error:
    - Expected expression before end of argument list for: <function name>
      You used a comma before the last optional argument in a call to a built-in function, but you did not supply the argument. For example:
    - Wrong number of arguments for: <name>
      The following conditions could have caused this error:
    - LISTTAG argument is not a FORALL alias variable
    - Type mismatch on: <name>
      The following conditions could have caused this error.
    - Illegal BYVAL on arguments to: <subprogram name>
    - Illegal TO in reference to: <name>
      One of the following conditions could have caused this error:
    - Illegal BYVAL
      One of the following conditions could have caused this error:
    - Duplicate label: <label name>
      You defined the label specified in the error message more than once within the same scope.
    - Illegal EXIT <EXIT type>
    - Illegal OPTION PUBLIC after declaration
    - Illegal use of ERASE
    - SET may only be used on class instance assignments
    - Illegal pass by value
      You tried to pass an argument by value that may not be passed by value, either by using parentheses around the argument, or by using the ByVal keyword on an argument in a call to an external C function.
    - Wrong number of arguments to constructor for class: <class name>
    - Illegal reference to array or list: <array or list name>
      You used the name of an array or list in an illegal context. Illegal contexts include the following, where X is the name of an array or list:
    - Illegal type suffix on keyword: <keyword>
      You included an illegal data type suffix character in the name of a LotusScript® built-in function. Certain LotusScript built-in functions can end in the $ type suffix character; no other data type suffix character is valid on these functions. The names of other functions cannot end in a data type suffix character. For example:
    - Compiler statement stack overflow at: <token name>
    - Maximum allowable code size exceeded
      The module you are compiling contains more than 64K bytes of executable code.
    - Maximum allowable data size exceeded
      The module you are compiling contains more than 64K bytes of data.
    - Maximum allowable symbol table size exceeded
      The module you are compiling contains more than 64K bytes of symbols (names).
    - PUBLIC is not allowed in this module
    - Illegal call to: <sub name>
    - Empty parentheses not legal on: <name>
      You included empty parentheses in referring to a variable of type Variant or an undefined function or sub (which LotusScript® interprets as a reference to an implicitly declared variable of type Variant). For example:
    - Illegal use of parentheses
      You called a sub or function and enclosed its argument list in parentheses. You can only do this under the following circumstances:
    - Class not specified on BIND into: <name>
    - Illegal Directive
      Any of the following could have caused this error:
    - Unterminated %IF, %ELSEIF, or %ELSE directive
      Your script contains a %If directive to which there is no corresponding %End If. For example:
    - Illegal character after directive
    - LIB name must be a string constant
    - USE or USELSX name must be a string constant
    - EVALUATE argument must be a string constant
    - Illegal second parenthesized expression
      You tried to refer to an element in a nested array, list, or collection. For example:
    - Statement is illegal in a subprogram
      You used one of the following statements within a LotusScript® procedure:
    - Illegal use of UNICODE or LMBCS keyword
    - UNICODE and LMBCS strings must be declared BYVAL
    - Too many nested WITHs
      You tried to nest a series of With statements to more than 16 levels. This is not allowed.
    - Illegal use of escape character in identifier: <name>
      You included an escape character in one of the following contexts in which that character is not allowed:
    - Illegal use of escape character
      You included an escape character at the end of a line. This is not allowed. For example:
    - Error in EVALUATE macro (message 1)
    - Name previously referenced in this scope
      You declared a variable in an outer scope. You then referred to this variable in an inner scope and then declared it in that scope. For example:
    - Wrong number of arguments for event handler: <sub name>
    - Property is read-only: <property name>
    - Missing array subscript or collection index for: <name>
      Either of two conditions could have caused this error:
    - Missing argument to constructor for: <class name>
    - Missing array bound for: <array name>
    - LEN argument must be a variable or string expression
    - Missing collection index for: <name>
      You included empty parentheses in a reference to a collection. This is not allowed. You can either remove the empty parentheses or insert the appropriate subscript. Removing the parentheses makes the reference be to the entire collection, while including the subscript makes the reference be to a single element in the collection.
    - Missing list subscript for ISELEMENT argument: <list name>
    - Cannot assign into collection item
      You tried to assign a value to a collection item. You can retrieve items in a collection but you cannot assign values to them.
    - Cannot forward declare CLASS or TYPE
    - CLASS or TYPE declaration may not be inside a control block
    - Procedure declaration may not be inside a control block
    - Product class does not have a New method: <class name>
    - Collection item is not an instance
      You referred to an item in an indexed collection as though that item were an object, but it isn't. For example, if iColl is a collection of integers, the following statement would be illegal:
    - Illegal on declarations in this scope: <keyword>
      The following conditions could have caused this error:
    - Wrong return type in event handler <handler_name>
      The return type of the event does not match the return type of the function.
    - Event handler must be a FUNCTION
      The event handler for an object is a function and the user-defined procedure is a sub.
    - Event handler must be a SUB
      The event handler for an object is a sub and the user-defined procedure is a function.
    - Conflicting option
    - PROPERTY GET and SET arguments do not match: <property_name>
      The corresponding parameters to Get and Set for a property are not of the same type.
    - Number of arguments do not match for PROPERTY GET and SET <property_name>
      The number of parameters to Get and Set for a property are not the same.
    - Property signature does not match parent property: <property name>
    - Type suffix character required on: <name>
      A variable that was implicitly declared with a data type suffix character was used without the suffix character. When a variable is implicitly declared with a suffix character, all subsequent references must contain the suffix character. A reference without the suffix character is treated as an implicit declaration of an already declared variable. This is illegal (a variable can't be declared twice).
    - Must be a sub: <procedure_name>
      A module-level procedure named "Initialize" or "Terminate" must be a sub. Initialize and Terminate are special subs at the module level. Initialize is executed when the module is loaded and Terminate when it is unloaded.
  - Run-time Error Messages
    This chapter describes the run-time error messages in the LotusScript® language.
- LotusScript/COM/OLE Classes
- Java/CORBA Classes
  This section documents the Java/CORBA classes.
- Connectors
  Connectors provide native access to a wide variety of DBMS products, ODBC, the platform File system, Enterprise Resource Planning systems, and Transaction Processing systems.
- Javadoc™ for Domino® Designer related APIs
  As part of providing additional Java™ reference documentation, Domino® Designer ships with a help plugin that contains Javadoc™ for additional Domino Designer related APIs.

Illegal BYVAL on arguments to: <subprogram name>

You used the ByVal keyword in a call to a procedure that is not an external C function. The ByVal keyword may only be used when specifying the parameters in the declaration or definition of a sub or function with a Declare, Sub, or Function statement, in specifying the parameters of an external C function with a Declare, and in calling an external C function with a Call statement.

Remove the ByVal keyword, revise the definition of the sub or function, or use parentheses around the argument in the call statement to pass the argument by value.