There are three steps involved in using a library from within an NSBasic program:

1. Add the library to your project as a resource, with type 'libr'.
2. Load the library using LoadLibrary.
3. Use the functions and subroutines within the library using object syntax with the name of the library.

Loading the Library

Before an NSBasic program can use a library, it must first load it using the LoadLibrary statement. The best place for this is the application's startup code.

   Syntax:
      LoadLibrary filename[, refname]
   Description:
      Filename is a file ending with a .inf extension that can be found in the
      Lib subdirectory, with the .inf extension being optional.  Refname is an
      optional variable name that will be used to refer to the library in
      subsequent calls to external procedures.  Calling LoadLibrary from the
      Project Startup Code ensures that a library will be accessible globally
      in your project.
   Examples: (NS Basic IDE)
      LoadLibrary "Mathlib"           'Uses Mathlib.inf, refname = mathlib
      LoadLibrary "Shortlib.inf"      'Uses Shortlib.inf, refname = shortlib
      LoadLibrary "newlib", "nl"      'Uses Newlib.inf, refname = nl

You can use the GetVersion(libName) function to return the version string in the TVER resource of any .prc file, including libraries. Not all libraries have TVER resources, but for those that do, you can use this to determine version information.

Using the Functions and Subroutines

Once the library has been loaded, you can access the functions and subroutines within the library by using the short name, if you provided one, or the long name (without the .inf), as follows:

libName.subName [parameter {, parameter}]
variable = libName.funcName ( [parameter {, parameter}] )

This is just like using an intrinsic subroutine or function, except that it uses a compound name made of the library name separated from the subroutine or function name with a period.

You can pass scalars of all types to libraries. You can also pass arrays of Short, Integer, Float, Double, and Byte to libraries, which may modify the values in the arrays. The best place to find out how to use a specific library is the documentation and examples that come with the library. If this documentation is missing or incomplete, you may need to figure it out.

If you pass a string to a library function or subroutine, and the function or subroutine can modify the contents of the string, you should first initialize the string to be as long as the largest possible return string. NSBasic will automatically expand strings to 300 bytes if they are shorter.

There are two versions of NSBasic libraries. Version 2 provides automatic type conversion and automatic passing by reference and is much safer to use. Version 1 does not. To determine the version of a library, locate its information file. The name of this file will end in .inf, and it should be in the Lib directory of the install folder (e.g. C:\NSBasic\Lib). Version 2 files contain a line InfVers=2.0

Due to the improvements in Version 2 libraries, using one is easy. Using subroutines and functions within a library just as you would use intrinsic or defined subroutines and functions should work. It is an error, however, to use a library function as a subroutine or a subroutine as a function. With Version 1 libraries, on the other hand, you must be extremely careful about what types you pass to libraries. The remainder of this section describes how to use Version 1 libraries, but it is good practice for using Version 2 libraries as well.

If you use literals, NS Basic/Symbian OS will assume you mean certain data types. These are as follows:

It is much safer, however, only to use variables defined by Dim statements when passing parameters to library functions and subroutines. For scalar values, the following data types will be used:

If a library function requires a char or Char parameter, you can pass it as a single Short.

Scalar types are normally passed by value, with the exception of strings and bytes, which are always passed by reference/pointer. You can also pass entire arrays of Byte, Short, Integer, Float, or Double.

The array mechanism also allows you to pass single parameters by reference/pointer. Declare an array using the Dim statement containing two or more elements of the desired data type. Use the first element as the value. (It is necessary to declare two or more elements because, at runtime, a single-element array is indistinguishable from a scalar.)