Class

NilObjectException

Description

Occurs when code tries to access an object that doesn't exist.

Properties

Name	Type	Read-Only	Shared
ErrorNumber	Integer
Message	String

Methods

Name	Parameters	Returns
Constructor	message As String = "", errorCode As Integer = 0
Stack		String
StackFrames		StackFrame

Property descriptions

NilObjectException.ErrorNumber

ErrorNumber As Integer

Used to contain an error number that describes the runtime error.

The following example displays a message box if, for example, you try to create more than one KeychainItem for the same application.

Var newItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  // Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  // Create a new keychain item for the application and assign the password
  System.Keychain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If
Exception err As KeychainException
  MessageBox(err.Message + ". Error Code: " + err.ErrorNumber.ToString)

NilObjectException.Message

Message As String

Used to contain descriptive text to display when the runtime exception is encountered.

The following example displays a message box if, for example, you try to create more than one KeychainItem for the same application.

Var newItem As KeyChainItem
If System.KeyChainCount > 0 Then
  newItem = New KeyChainItem
  // Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  // Create a new keychain item for the application and assign the password
  System.KeyChain.AddPassword(newItem, "SecretPassword")
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If
Exception err As KeyChainException
  MessageBox(err.Message + ". Error Code: " + err.ErrorNumber.ToString)

Method descriptions

NilObjectException.Constructor

Constructor(message As String = "", errorCode As Integer = 0)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Used to raise your own RuntimeException with a message and optional error code.

NilObjectException.Stack

Stack As String

Returns a String array that contains a list of all of the methods in the stack from the main entrypoint to the point at which the exception was invoked.

The stack contains all the method names up and including the current method name.

This feature only works if the IncludeFunctionNames property on the App object is selected in the Shared Build Settings.

In addition to your own method calls, you will also see framework method calls, but these may not always be completely accurate due to insufficient symbols for the OS to resolve.

NilObjectException.StackFrames

StackFrames As StackFrame

Returns an array containing the stack when the exception was first raised.

Notes

A NilObjectException occurs when you use a property or variable to access an object that doesn't exist. For example, when the FolderItem.Constructor method is passed an invalid pathname, it returns Nil. Certain functions that are designed to return FolderItems on one platform may return Nil when run on other platforms. If your code attempts to access or write to a property of a Nil FolderItem, a NilObjectException will occur.

A function also returns Nil if there isn't enough memory to load the object. For example, if you tried to load a large picture into memory but your application didn't have enough RAM left to load the picture, the function used to load the picture would return Nil.

Immediately after calling a function that returns an object (like FolderItem.Constructor, for example) you should check the object to see if it is Nil or add an Exception or Try block to the end of the method that handles NilObjectExceptions. Any function's result that is not a data type is an object and should be checked.

Sample code

This example tries to open a jpeg file using the FolderItem's Constructor method and display it in an DesktopImageViewer. If the pathname passed to the FolderItem is invalid, it returns Nil. The NilObjectException is handled in the Exception block which is after the last "regular" line of the method.

If the pathname is valid, but the item does not exist, the FolderItem's Constructor returns a valid FolderItem whose NativePath property is equal to the pathname. You should check the Exists property of the FolderItem to determine whether the file exists before trying to do something with the FolderItem.

This code, in other words, checks for two different problems — invalid pathname and valid path to a nonexistent file.

Var f As FolderItem
Try
  f = new FolderItem("/Users/fred/Documents/Fluffy.jpeg")
  If Not f.Exists Then
    System.Beep
    MessageBox("The file " + f.NativePath + "doesn't exist!")
  Else // document exists
    ImageViewer1.Image = Picture.Open(f)
  End If
Catch e As NilObjectException
  MessageBox("Invalid pathname!")
End Try

The following example creates a new, empty picture. If there isn't enough memory to create the picture, Nil will be returned by the Picture constructor. The example code checks for this and informs the user:

Var p As New Picture(10000, 10000)
If p = Nil Then
  System.Beep
  MessageBox("There isn't enough memory available to create the picture.")
Else
  // do something with the picture here
End If

Compatibility

All project types on all supported operating systems.