The powerful and easy-to-use Fourth Generation Language (4GL) that allows you to control your NetWare® environment
All rights reserved. No part of this publication may be reproduced, transmitted, or stored in any form or by any means, including photocopying, photographing, recording, or by any other photographic, electronic or mechanical information retrieval system, without the prior agreement and written permission of HiTecSoft Corporation.
Unless otherwise noted, all data used in examples are fictitious and are solely to illustrate potential uses of this product
Network Management Language and Network Management Extension are trademarks of HiTecSoft Corporation. HiTecSoft is a registered trademark of High Technology Software Corporation. NetWare is a registered trademark and NetWare Directory Services is a trademark of Novell Inc. within the United States and other countries. All other brand and product names are trademarks of their respective owners
Excerpts from NetWare Directory Services, ©
1991, 1994 Novell, Inc. All Rights Reserved. Used with permission.
© 1996 HiTecSoft Corporation. All rights reserved.
Welcome to NetBasic. The purpose of this documentation is to provide you with a reference guide for using NetBasic.
NetBasic is adaptable to your programming style. You may type commands in upper case, lower case or a mixture of both. The following conventions are used throughout this documentation:
The chapter headings are displayed in a
The topic headings are displayed in a
The topic subheadings are displayed in a
User input and information shown on the computer screen are displayed as courier font.
For the purpose of readability, the commands are displayed as a mixture of Upper And Lower case. For example, WIN:Heading:Off.
Variables, parameters and returned values are surrounded by < > symbols and their types are identified by a preceding lower case character. In the example <sName> = NET:Server:Name (<iConnectionID>), the type of the returned value <sName> is string and the type of the parameter <iConnectionID> is integer. The following table shows the meaning of each lower case character.
| Character | Type | Examples |
| s | String | "ABCD", "E" |
| r | Real | 3.14159, 2.71828 |
| i | Integer | 1000, 12, 125 |
| o | Object | See Objects topic |
| l | Logical | True, False |
| h | Handle | File handle |
| x | Any Type | String, Real, Integer |
Optional parameters are surrounded by [ ] symbols. In the example WIN:Close ([<hHandle>]), supplying the parameter <hHandle> is optional.
Multiple parameters are separated by commas. A range of parameters is displayed by separating the first and last parameter with three dots. For example, the command WIN:Popup (<sMessage1> [, <sMessage2>,...<sMessage20>]) accepts a maximum of twenty parameters and the parameters number two through twenty are optional.
All the commands within a specific class or subclass are displayed
as three dots following the class or subclass name. For example,
the syntax WIN:Cursor:..., represents the WIN:Cursor:Column, WIN:Cursor:Hide,
WIN:Cursor:Row and WIN:Cursor:Show commands.
A NetWare Loadable Module (NLM) is a program that runs on a NetWare file server. NLMs are supported on NetWare versions 3.0 and higher.
NLM programs are loaded into memory or unloaded from memory using the LOAD and UNLOAD commands at the file server's console screen. The file server's console screen can be accessed directly from the file server itself or remotely through NetWare's RCONSOLE utility. Please see the NetWare Utilities Reference manual for more information.
NetWare is a multitasking environment that allows multiple NLM programs to run simultaneously and gives control of the CPU to each NLM program according to their schedule. When NetWare gives an NLM program control of the CPU, it is the responsibility of the NLM program to return control back to NetWare in a timely manner. NetBasic is designed to behave according to NetWare's internal operating conventions and automatically yields to the NetWare Operating System. However, when developing an NLM program, it is desirable to use a delay command within all CPU intensive loops. The delay command will reduce the CPU utilization by allowing the NetWare Operating System to gain control of the CPU during the delay period and run other tasks (see the SYS:Delay command and the Do While statement topic). In the following example, the SYS:Delay command is used to create a one-second delay every time the file server's time is displayed:
Do While True
DateObj = NET:Server:Date:Get
If (DateObj.Error != 0)
WIN:At(1,70); WIN:Say(DateObj.Time)
EndIf
SYS:Delay(1000)
EndDo
NetBasic applications are executed using the NetBasic interpreter.. NETBASIC.NLM is the NetBasic interpreter for NetWare.. To run an application in the interpreter, first load the interpreter into memory by typing LOAD NETBASIC from the file server console. To run a NetBasic application, use the RUN command from the file server console, e.g. to run FCONSOLE.BAS, type RUN FCONSOLE.
The NetBasic interpreter can also be executed in an interactive mode which behaves similar to a DOS prompt. In this mode, the NetBasic interpreter can execute any NetBasic program. Thus the command set supported in interactive mode is extended as new NetBasic programs are introduced. NetBasic's interactive mode and its open architecture characteristics are referred to as the "open interactive shell." The open interactive shell has only two internal commands, Quit and Exit, both of which are used to terminate the shell.. To run NetBasic in interactive mode from the file server console, first load the NETBASIC interpreter into memory by typing LOAD NETBASIC, then type SHELL and press Enter. To run a program while in the interactive mode, simply type the name of the program at the shell prompt and press Enter. The interactive shell searches the directories specified by the NetBasic environment variable PATH to find these programs (see the Environment Objects topic). Many programs and utilities are provided with NetBasic in the SYS:NETBASIC\UTIL directory.
To pass parameters to a NetBasic application, list the parameters after the application name, separated by spaces. For example, to pass the SYS:PUBLIC parameter to the DIR.BAS application from file server console, type LOAD NB SYS:PUBLIC.
Use the steps below to test your NLMs:
Prior to a full installation, setup the application for a small scale production test. Start by installing the application on one server or one group. Collect data on the application's performance. Remember that networks provide a vast number of services, so monitor the application's performance for a period of time.
When a NetBasic application is running on the file server and is not logged in as a user, the application process has a security level equivalent to a supervisor. When the application logs in as a user, the application process has a security level equivalent to that of the user which logged in.
Since NLM programs have full access to all NetWare services, only qualified users should have access to the file server's console screen. NetWare provides password security features to lock out unauthorized users from accessing the file server's console. Please see the NetWare Utilities Reference manual for MONITOR and RCONSOLE security features. For example, the following program creates a user who has a security level equal to the supervisor, and who has no password. Any user who has access to the file server's console could run this program.
#include "NET.H"
Sub Main
BindObj = NET:Bindery:Get
If (BindObj.Error != 0); Quit; EndIf
BindObj.Name = "SUPERUSER"
BindObj.Type = NET_USER
BindObj = NET:Bindery:Set(BindObj)
If (BindObj.Error != 0); Quit; EndIf
SuperObj = NET:Bindery:Get("SUPERVISOR", NET_USER)
If (SuperObj.Error != 0); Quit; EndIf
If (NET:Bindery:Property:Add(BindObj, "SECURITY_EQUALS",
SuperObj))
Print("Superuser has been created")
EndIf
End Sub
NetBasic commands are grouped to form a class. The class name appears as the first part of the command name and in this manual, it is shown in uppercase. Some commands are further grouped into subclasses, in which case the name of the subclass also appears as part of the command name. For example, the WIN:Cursor:Column, WIN:Cursor:Hide, WIN:Cursor:Row and WIN:Cursor:Show commands are in the WIN class and the Cursor subclass.
NetBasic is not case sensitive. All commands can be typed in upper case, lower case or a combination of both. The commands NET:SERVER:DATE:GET, net:server:date:get and NET:Server:Date:Get are all acceptable.
NetBasic commands may or may not return a value. In this manual, for the purpose of clarity, the commands that return a value are sometimes referred to as functions. Parentheses are used to supply parameters to commands. For commands that do not receive any parameters, typing the parentheses is optional. For example, the commands WIN:Cursor:Show and WIN:Cursor:Show() are both valid.
NetBasic commands may return an object (see the Objects topic). To better understand such commands, first read about the related object. Next read the command syntax and review the examples. For example, first consult the Link Objects description in this chapter, then see the NET:Link:... commands, and review the examples provided for NET:Link:Open:Server and NET:Link:Open:Client commands.
The supported operators are listed in the table below.
The operand column shows the data types used with each operator
and indicates special notes that apply to the operators and operands.
| Operator | Name | Operands and Notes |
| + | Addition or Concatenation | Integer, Real and String |
| - | Subtraction | Integer and Real |
| * | Multiplication | Integer and Real |
| / | Division | Integer and Real |
| & | AND | Logical |
| | | OR | Logical |
| = | Equality | Integer, Real, String and Logical |
| != | Inequality | Integer, Real, String and Logical |
| < | Less than | Integer, Real, String and Logical |
| > | Greater than | Integer, Real, String and Logical |
| <= | Less than or equal | Integer, Real, String and Logical |
| >= | Greater than or equal | Integer, Real, String and Logical |
ConNo = 1Do While (ConNo <=250) ConObj
= NET:Connection:Info(ConNo) If ((ConObj.Error = 0) &
(ConObj.Bindery.Name = "BOB")) NET:Broadcast:Send("Hello
Bob", ConNo)
EndIf ConNo = ConNo + 1
EndDo
Parentheses are used to specify the order in which the expressions are evaluated.. When parentheses are not used, expressions are evaluated from left to right in the following order:
· Multiplication, Division and Logical AND
· Addition, Subtraction and Logical OR
· Comparison operators
NetBasic provides automatic variable declaration. Memory variables and array elements are created inside the application when assigned a value. The memory variable name can be up to 32 characters in length and must start with an alphabetic character, optionally followed by more alphabetic characters, numbers and underlines.
Unless the Local command is used to declare memory variables as local, all created memory variables are global and can be accessed from anywhere within the source file. A local memory variable can be accessed only from within the function or subroutine in which it was created. Arrays and their elements cannot be declared as local. In the following example, the names for all connections are saved in the array called NAME:
Local("Count", "ConObj")
Count = 1
Do While Count <= 250
ConObj = NET:Connection:Info(Count)
If ConObj.Error = 0
Name(Count) = ConObj.Name
EndIf
Count = Count + 1
EndDo
The Function and Subroutine commands (abbreviated Func and Sub) are used by programmers to create reusable code. All functions and subroutines are terminated by the Return command. The Return command always returns a value to the calling program. When the Return command is used without any parameter, it returns a null value. Traditionally, when reusable code returns a value, it is referred to as a function. Reusable code that does not return any value is referred to as a subroutine or procedure. Within NetBasic applications, both the Function and Subroutine commands are used interchangeably and are executed in the same manner. Any programmer desiring to follow the traditional course may do so freely, however, the traditional course is not enforced. The subroutine that starts the NetBasic application is called "Main". Every NetBasic application must have one "Main" subroutine. With the exception of remote procedures (see the RPC:Call command), the entire NetBasic application, including all functions and subroutines s, must be placed in one source file. The "Main" subroutine can be placed anywhere within the source file and is terminated by either a Return or Quit command.
The following is a complete source code listing for a NetBasic application:
Sub Main
ListPrimes(1,100)
Quit
Sub ListPrimes
' This Subroutine lists all the prime numbers between two ' specified
numbers.
If PARAM:Count<2; Return; EndIf
FirstNumber = Param(1); LastNumber = Param(2)
If FirstNumber = 1; FirstNumber = 2; EndIf
Do While FirstNumber <= LastNumber
Divisor = 2; Prime = True
Do While Divisor<FirstNumber
If MATH:Mod(FirstNumber, Divisor) = 0
Prime = False
Exit
EndIf
If Divisor = 2; Divisor = 3; Else; Divisor = Divisor
+ 2; EndIf
EndDo
If Prime; Print(FirstNumber," "); EndIf
FirstNumber = FirstNumber + 1
EndDo
End sub
To pass parameters to a user-defined function or subroutine, list the parameters inside parentheses after the function or subroutine name, separated by commas. For example, the parameters 1 and 100 are passed to the ListPrimes subroutine as ListPrimes(1,100).
Prior to running any NetBasic application, the preprocessor processes the source file and creates a temporary file executed by NetBasic. The temporary file is created in the directory specified by the NetBasic environment variable TEMP (see Environment Objects). If the environment variable TEMP is not specified, the preprocessor creates the file in the /SYSTEM/NMX directory of the SYS: volume.
The #include command is used to include a file into the source code. The preprocessor inserts the file specified by the #include command into the source code when the temporary file is created for the NetBasic application. The include files provided with the NetBasic package have the H. The #include command must be in lower case and positioned outside of the main subroutine. The file name must be in quotation marks. The following example uses the #include command to include the WIN.H file in the source file.
#include "WIN.H"
Sub Main
WIN:Clear
Window = WIN:Define(5,20,10,60); WIN:Show
WIN:Color(WIN_FG_RED+WIN_BG_WHITE)
WIN:At(2,10); WIN:Say("Hello network users.")
Quit
The #define command is used to replace a string throughout the source file. The preprocessor replaces the first string specified after the #define command with the second string when the temporary file is created for NetBasic. The #define command must be in lower case and positioned outside of the main subroutine. The following example uses the #define command:
#define At WIN:At
#define Say WIN:Say
#define Clear WIN:Clear
Sub Main
Clear
At(1,2); Say("Hello network users")
Quit
The Do While - EndDo statement executes a block of code that starts immediately after the Do While instruction and repeats until the logical expression supplied to the Do While instruction is no longer true, or until an optional Exit instruction is encountered. When the logical expression supplied to the Do While instruction is no longer true, the program will continue with the first command following the EndDo instruction. If an Exit instruction is encountered within the Do While - EndDo statement, the program will continue with the first command following the EndDo instruction. The optional Loop instruction prevents the execution of any code that occurs after the Loop instruction. If a Loop instruction is encountered within the Do While - EndDo statement, the program will return to the Do While instruction.
The structure of the Do While - Loop - Exit - EndDo statement is as follows:
Do While <lLogicalExpression>
< Block of code >
[ Loop ] [ Exit ]
< Block of code >
EndDo
The Else instruction in the If - Else - EndIf statement is optional. The If - Else - EndIf statement evaluates the logical expression supplied to the If instruction. When the logical expression is true, the block of code that starts immediately after the If and ends by the Else instruction is executed. When the logical expression is false, the block of code that starts immediately after the Else and ends by the EndIf instruction is executed. Once the If - Else - EndIf statement has executed, the program will continue with the first command following EndIf. The structure of the If - Else - EndIf statement is as follows:
If <lLogicalExpression>
.
.
< First block of code >
.
.
Else
.
.
< Second block of code >
.
.
EndIf
The If - EndIf statement conditionally executes the block of code that starts immediately after the If and ends by EndIf. The block of code is executed if the logical expression supplied to the If instruction is true. Once the If - EndIf statement has executed, the program will continue with the first command following EndIf. The structure of the If - EndIf statement is as follows:
If <lLogicalExpression>
.
.
< Block of code >
.
.
EndIf
A window is a region of the screen that can be used to display information or a menu. There are four types of windows:
The desktop window is the entire computer screen. When no other window has been defined, the desktop window is the default (active) window. For the desktop window, the coordinate (1,1) refers to the upper left corner and (25,80) refers to the lower right corner of the screen. The desktop window does not have any window borders. The Win:Heading:... commands are specific to the desktop window.
A popup window is used to display a single message that is up to 20 lines long; each line can be up to 78 characters in length. The message appears in a window at the center of the screen and will remain on the screen until a key is pressed. The WIN:Popup command is specific to popup windows.
Display windows are used to display information or to accept user input on the screen. When defining a display window, specify the coordinates for the upper left and lower right corners of the window. These coordinates will be absolute with respect to the main screen, and they specify where the display window will appear. Once the window has been defined, the relative coordinates (1,1) are used to access the upper left corner of the display window. The relative coordinates used to access the lower right corner of the display window are based on the size of the window. The following commands are specific to display windows: WIN:At, WIN:Clear, WIN:Color, WIN:Cursor:... , WIN:Define, WIN:Get:... , WIN:Say, WIN:Scroll, WIN:Trim:... .
Menu windows are used to display menus. Menu items are vertically displayed as bar items within the menu window. When defining a menu window, specify the coordinates for the upper left corner of the window. These coordinates are absolute with respect to the main screen, and they specify where the menu window will appear. The absolute coordinates for the lower right corner of the menu window are automatically calculated based on the width and number of items in the menu. The WIN:Menu:... commands are specific to menu windows.
Display and menu window types are similar in concept. The following are some notes to remember when working with the two different window types:
· When defining a display window, two coordinates are required (upper left and lower right). When defining a menu window, only one coordinate is required (upper left). The lower right coordinate for the menu window is automatically calculated based on the width and number of items in the menu.
· WIN:Define and WIN:Menu:Define commands are used to define display and menu windows, respectively. Both commands return a window handle that can be used to refer to the created window. When a display or menu window is defined, the window will not be shown until the WIN:Show or WIN:Menu:Start command is issued.
· When multiple windows are opened, the last window is selected as the default window. The default window is the window which is currently active, and can be either a display or a menu window. For some window commands, supplying the window handle is optional. When the optional window handle is not supplied to these commands, the default window is assumed.
· It is possible to add menu items to a display window or to write information to a menu window, however it is highly recommended to avoid mixing the two window types. In future releases, mixing the window types may result in an error message being displayed.
· Usually some programming code can be saved if consecutively opened windows are linked together in such a way that when one window is closed, the previous window becomes active. For this purpose, when multiple display and/or menu windows are opened, a linked list internally keeps track of the order of the windows. When a window is closed or hidden, the previous window in the list will be selected as the default window. Therefore, the programmer needs to keep track of the order in which the display and menu windows are linked.
· If windows are displayed overlapping one another, the windows should be closed in reverse order from which they were opened, otherwise the screen may not be properly restored.
· The WIN:Close, WIN:Hide, WIN:Show and WIN:Title commands are used for both display and menu window types.
Objects are arrays of information embedded into one memory variable. There are many types of objects, covering a broad range of applications (refer to the individual objects for further information).
The information stored inside an object is referred to as the attributes of the object. For example, a file object has attributes called Name, Extension, Type, Size, Date, Time and Error. Each attribute of the object is represented by placing a period between the object name and the attribute name. For example, FileObj.Name refers to the Name attribute of the file object.
The following example demonstrates the use of an object for displaying the files of the current directory:
Sub Main
WIN:Clear
REM - Get the first directory object.
FileObj = DIR:File:First("*.*")
Do While True
REM - Stop when there are no more files.
If FileObj.Error != 0
Quit
EndIf
REM - Print the file name, extension, size, date and time.
Print(FileObj.Name, " ", FileObj.Extension," ",
FileObj.Size," ") Print(FileObj.Date, " ",
FileObj.Time); Newline
REM - Get the next directory object.
FileObj = DIR:File:Next(FileObj)EndDo
Some attributes can be assigned new values and are referred to as read-write attributes. Other attributes are read only and cannot be assigned new values; these are called read-only attributes. When the value of an attribute is changed, the object has to go through an object manager (a command which "sets" the change and implements it throughout the system), in order for the changes to take effect. In the example below, the file object Name is changed by assigning the value NEWPROG to the Name attribute of the file object. However, the name change to the file itself does not take place until the new file object is "set" with the DIR:File:Set command. The following example changes a file name within the current directory:
Sub Main
FileObj = DIR:File:Get("OLDPROG.BAS")
Print("Old Name ",FileObj.Name);
Newline
FileObj.Name = "NEWPROG"
FileObj = DIR:File:Set(FileObj)
Print("New Name ",FileObj.Name);
Newline
Quit
When an object is returned from a function, the Error attribute is set to zero if the function executes properly, and to non-zero if an error has occurred. See the appendices for the description of the error numbers associated with each object type.
Objects are frequently used to transfer data across networks and therefore are formatted with special characters to accommodate different architectures.
Since no error checking is performed at the time that new values are assigned to an attribute, it is possible to create objects that contain invalid attribute values. However, when an object containing an invalid attribute value is supplied as the parameter to a command or function, the error attribute of that object will be set to indicate an error.
The bindery object provides identification information for network resources and clients. File servers, database servers, print servers, print queues or any other logical or physical entity that provides services on the network are called resources. Users, user groups or any other logical or physical entity on the network that uses the service are called clients. Each NetWare file server maintains a bindery that has one record for each of its own resources and clients.
The NET:Bindery:.. commands are used to access the bindery and provide identification information in the form of bindery objects (see the Objects topic in this chapter). Each bindery object contains an ID, Name, Type, Flag, Read security, Write security, Internet.Socket, Internet.Node, Internet.Network and Error attributes. For example, when the BindObject = NET:Bindery:First("*", NET_USER) command is issued to retrieve information on the first user in the bindery, the attributes of the bindery object BindObject would be as follows:
· BindObject.ID represents the unique ID for the retrieved user.
· BindObject.Name represents the name of the retrieved user.
· BindObject.Type contains a code that indicates the retrieved information is for a user.
· BindObject.Flag contains a code that indicates the retrieved information is permanent in the bindery.
· BindObject.Security.Read contains a code that indicates the security level needed in order to read the information of this user from the bindery.
· BindObject.Security.Write contains a code that indicates the security level needed in order to change the information of this user in the bindery.
· BindObject.Error contains a code that indicates whether an error has been encountered.
· The Internet.Socket, Internet.Node and Internet.Network attributes will not contain any data. These attributes contain data only when the retrieved object is for a server (in this case the retrieved information is for a user).
ID attribute: The ID attribute is a read-only integer, and represents the ID of the bindery record. The bindery has one record for each resource or client. Each record has a unique ID, which is used to identify the record. Since each file server maintains its own bindery, this ID is assigned by the file server and is unique only within the bindery of that file server.
Name attribute: The Name attribute is a read-write string, and represents the name of the resource or client in the bindery. The name can be up to 48 characters long, consisting of printable letters only. Control characters, spaces, slashes, backslashes, colons, semicolons, commas, asterisks, question marks or tildes cannot occur in any part of the name attribute. When searching the bindery by name, wildcard characters (asterisks and question marks) can be used to specify all or some of the characters in the name string. The asterisk is used to replace any length string, and the question mark is used to replace one character within a string.
Type attribute: The Type attribute is a read-write integer, and identifies the type of the record in the bindery list. Although the Type attribute is read-write, changing the type of an existing object is not recommended. The following type constants are defined in the NET.H file and are used to identify the type of common resources and clients. In addition to these predefined type constants, programmers can define new types for resources and clients that are not listed.
· NET_UNKNOWN
· NET_USER
· NET_USER_GROUP
· NET_PRINT_QUEUE
· NET_FILE_SERVER
· NET_JOB_SERVER
· NET_GATEWAY
· NET_PRINT_SERVER
· NET_ARCHIVE_QUEUE
· NET_ARCHIVE_SERVER
·
· NET_ADMINISTRATION
·
NET_NAS_SNA_GATEWAY
·
NET_REMOTE_BRIDGE_SERVER
·
NET_TIME_SYNC_SERVER
·
NET_ARCHIVE_SERVER_DYNAMIC_SAP
·
NET_ADVERTISING_PRINT_SERVER
·
NET_BTRIEVE_VAP
· NET_PRINT_QUEUE_USER
· NET_WILD
(Matches any type and is used only when searching the bindery
list.)
Flag attribute: The Flag
attribute is a read-only integer, and defines the state of the
bindery record, which can be either static or dynamic. The static
state indicates that the record in the bindery is to remain permanently.
The record for users or user groups is permanent in the bindery
and will remain until deleted. The dynamic state indicates that
the bindery record is temporary. Temporary records are removed
automatically when the service for which the record was created
is no longer available. The record for advertising servers is
created when the service is made available and will be removed
when the service is terminated (see the Link Objects topic).
Security.Read attribute:
The Security.Read attribute is a read-write integer, and indicates
the security level required in order to read the information from
the bindery record. See Security.Write below for the constants
defined for the Security.Read attribute in NET.H.
Security.Write attribute:
The Security.Write attribute is a read-write integer, and indicates
the security level required for changing the information in the
bindery record. The following constants are defined for Security.Read
and Security.Write attributes in NET.H.
NET_WRITE_ANYONE
Any client that is logged in.
NET_WRITE_LOGGED_CLIENT
Anyone, even clients, that are not logged in.
NET_WRITE_SAME_CLIENT
Logged in clients that have the same name, type and
password as the record being modified.
NET_WRITE_SUPERVISOR
Logged in clients with supervisory rights.
NET_WRITE_NETWARE
NetWare operating system only.
Internet.Socket attribute:
The Internet.Socket attribute is a read-only string, and is provided
only when the bindery record is for a server that has advertised
its services (see Link Objects in this chapter). This attribute
contains the socket address that identifies the server's process
(see the Internet Objects topic in this chapter). When multiple
processes are running on the same computer, the socket address
uniquely identifies each process.
Internet.Node attribute:
The Internet.Node attribute is a read-only string, and is provided
only when the bindery record is for a server that has advertised
its services (see Link Objects in this chapter). This attribute
contains the physical node address that identifies the computer
that is running the server's process (see Internet Objects in
this chapter). The node address uniquely identifies each computer
within a network.
Internet.Network attribute:
The Internet.Network attribute is a read-only string, and is provided
only when the bindery record is for a server that has advertised
its services (see Link Objects in this chapter). This attribute
contains the network number that identifies the network of the
server's process (see Internet Objects in this chapter). Each
network has a number that uniquely identifies that network among
all other networks of an internetwork system.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Each bindery record may have one or more bindery
properties attached to it. The bindery property holds references
to other, related, bindery records. The NET:Bindery:Property:...
commands can be used to access the properties of a bindery record.
The following constants are defined for properties in NET.H.
"GROUP_MEMBERS" property:
This property attaches to records that are of the type NET_USER_GROUP
and contains references to records for the users who are in that
group. The NET_READ_SAME_CLIENT and NET_WRITE_SUPERVISOR security
levels are required to read from or write to this property.
"GROUPS_I'M_IN" property:
This property attaches to records that are of the type NET_USER
and contains references to records for the groups that the user
belongs to. The NET_READ_LOGGED_CLIENT and NET_WRITE_SUPERVISOR
security levels are required to read from or write to this property.
"OPERATORS" property:
This property attaches to records that are of the type NET_FILE_SERVER
and contains references to records that are authorized console
operators. The NET_READ_SUPERVISOR and NET_WRITE_SUPERVISOR security
levels are required to read from or write to this property.
"Q_OPERATORS" property:
This property attaches to records that are of the type NET_PRINT_QUEUE,
NET_JOB_QUEUE, NET_ARCHIVE_QUEUE or any other queue type and contains
references to records that are authorized queue operators. The
NET_READ_SUPERVISOR and NET_WRITE_SUPERVISOR security levels are
required to read from or write to this property.
"Q_SERVERS" property:
This property attaches to records that are of the type NET_PRINT_SERVER,
NET_JOB_SERVER, NET_ARCHIVE_SERVER or any other queue server type
and contains references to records that are authorized to attach
to a queue and service jobs. The NET_READ_SUPERVISOR and NET_WRITE_SUPERVISOR
security levels are required to read from or write to this property.
"SECURITY_EQUALS"
property: This property attaches to records that are of the type
NET_USER and NET_USER_GROUP and contains references to records
that have an equivalent security level. The NET_READ_SUPERVISOR
and NET_WRITE_SUPERVISOR security levels are required to read
from or write to this property.
Connection information objects are used to retrieve
information on a specific connection. Connection information objects
contain all the attributes of a bindery object plus Date and Time
attributes (see Bindery Objects in this chapter). All attributes
of connection information objects are read-only.
Date attribute: The Date
attribute is a read-only string, and specifies the date the client
logged in to the server in the format DD-MM-YYYY.
Time attribute: The time
attribute is a read-only string, and specifies the time the client
logged in to the server in the format HH:MM:SS.
Connection objects are used to select a default file
server. Prior to logging in, the client must attach to a file
server (see the NET:Server:Attach command). Each client can attach
to a maximum of thirty-two file servers. The NET:Connection:Get
and NET:Connection:Set commands are used to select one of the
currently attached file servers as the default. Network commands
for which the target file server is not specified are presumed
to be for the default file server.
The connection information accessed by the NET:Connection:...
commands is in the form of connection objects (see Objects in
this chapter). Each connection object contains ID, Number and
Error attributes. When the command ConnectObj=NET:Connection:Info(1)
is issued to retrieve the information about the first connection
of the default file server, the attributes of the connection object
ConnectObj are as follows:
·
ConnectObj.ID
contains a number that identifies the file server.
· ConnectObj.Number
contains a number that identifies the client (assigned by the
file server).
· ConnectObj.Server.Name
contains the name of the file server.
ConnectObj.Server.ID contains the connection ID of
the file server.ConnectObj.Error contains a code that indicates
if an error has been encountered. ID attribute: The ID
attribute is a read-write integer, and indicates the connection
ID which is used to identify the default file server. Each file
server has a unique connection ID, and clients can attach to a
maximum of thirty-two file servers. The connection ID identifies
the target file server that will receive all client requests.
Error attribute: The Error
attribute is read-only and indicates any error encountered during
an operation on the object. The error attribute is returned as
an integer. When no error is encountered, the Error attribute
will be zero.
Number attribute: The
Number attribute is a read-only integer, and indicates the connection
number. When a client attaches to a file server, a number is assigned
to the client by that file server. This connection number uniquely
identifies the client among all the connections of the file server.
When a client is connected to more than one file server, each
file server assigns to the client its own connection number, which
may or may not be the same as the connection numbers assigned
to that client by other file servers.
Server.Name attribute:
The Server.Name attribute is a read-write string, and it specifies
the name of the server to which this object refers. This value
can be overwritten with a new server name, in order to change
the current default file server for the application.
Server.ID attribute:
The Server.ID attribute is a read-write integer, and it specifies
the connection ID for the server to which this object refers.
This attribute is the same as the ID attribute of a connection
object.
Date Objects are used to retrieve the date and time
information given the total number of seconds since Jan 1, 1970.
The date Jan 1, 1970 is considered the beginning of time for Universal
Time Format (UTF). The DATE:UTF command is used to determine the
total number of seconds between any date and Jan 1, 1970. For
example, the command Seconds=DATE:UTF("03-21-1996")
is used to store the total number of seconds between Jan 1, 1970
and March 21, 1996 into the memory variable "Seconds".
The total number of seconds can be supplied to DATE:Object command
for creating a date object. The attributes of a date object are
Year, UTF.Year.Century, UTF.Year.Day, UTF.Year.Week, UTF.Year.Leap,
Month, UTF.Month.Name, UTF.Month.Days, Day, UTF.Day.Name, Date,
Time, UTF.Time.Hour, UTF.Time.AmPm, UTF.Time.Minute, UTF.Time.Second,
UTF.Time.AmPmHour and Error.
Year attribute: The Year
attribute is read-only and contains a two digit number representing
the year. For example 93.
UTF.Year.Century attribute:
The UTF.Year.Century attribute is read-only and contains a four
digit number representing the year and century. For example 1996.
UTF.Year.Day attribute:
The UTF.Year.Day attribute is ready-only and contains a three
digit number between 001 and 366 representing the day of the year.
UTF.Year.Week attribute:
The UTF.Year.Week attribute is read-only and contains a two digit
number between 00 and 51 representing the week of the year. The
first day of the week is Monday.
UTF.Year.Leap attribute:
The UTF.Year.Leap attribute is read-only and contains TRUE for
leap years and FALSE otherwise.
Month attribute: The Month
attribute is ready-only and contains a two digit number between
1 and 12 representing the month of the year.
UTF.Month.Name attribute:
The UTF.Month.Name attribute is read-only and specifies the name
of the month. For example MARCH.
UTF.Month.Days attribute:
The UTF.Month.Days attribute is ready-only and contains any of
the numbers 28, 29, 30 or 31, representing the number of days
within the month.
Day attribute: The Day
attribute is read-only and contains a two digit number between
01 and 31 representing the day of the month.
UTF.Day.Name attribute:
The UTF.Day.Name attribute is read-only and specifies the name
of the weekday. For example FRIDAY.
Date attribute: The Date
attribute is read-only and specifies the date in the MM-DD-YYYY
format. For example 03-21-1993.
Time attribute: The Time
attribute is read-only and specifies the time in the HH:MM:SS
format. For example 08:30:15
UTF.Time.Hour attribute:
The UTF.Time.Hour attribute is read-only and contains a two digit
number between 00 and 23 representing the hour of the time. For
example 01 to represent the first hour in the morning and 13 to
represent the first hour in the afternoon.
UTF.Time.AmPmHour attribute:
The UTF.Time.AmPmHour attribute is read only and contains a two
digit number between 01 and 12 representing the hour of the time.
For example 01 to represent the first hour in the morning or afternoon.
UTF.Time.Minute attribute:
The UTF.Time.Minute attribute is read-only and contains a number
between 00 and 59 representing the minute of the time.
UTF.Time.Second attribute:
The UTF.Time.Second attribute is read-only and contains a number
between 00 and 59 representing the second of the time.
UTF.Time.AmPm attribute:
The UTF.Time.AmPm attribute is read-only and contains AM for morning
and PM for afternoon.
Error attribute: The Error
attribute is read-only and indicates any error encountered during
an operation on the object. The error attribute is returned as
an integer. When no error is encountered, the Error attribute
will be zero.
Directory objects are used to parse the directory
information for a path name. Directory objects have some of the
attributes of a file object and all of the attributes of a path
object. When the command DirObj=DIR:Object("..\MYPROG.EXE")
is issued to parse the path name ..\MYPROG.EXE, the attributes
of the directory object DirObj are as follows:
·
DirObj.File.Name
contains "MYPROG" for the name of the file.
·
DirObj.File.Extension
contains "EXE" for the extension of the file.
·
DirObj.Path
contains the full path to the file "MYPROG.EXE".
· DirObj.Volume.Name
contains the name of the volume that the file resides on.
· DirObj.Server.Name
contains the name of the file server that has the volume specified
by Volume.Name.
· DirObj.Error
contains a code that indicates if an error has been encountered.
See File Object and Path Object in this chapter for
more information on the above attributes.
Environment objects are used to access and change
environment variables of NetBasic. The environment is a section
of memory that is shared among all NetBasic applications. The
ENV:Get and ENV:Set commands are used to read, change or create
environment variables. Each environment variable has a name and
a data value. Programmers can freely create any environment variables,
however the following are some important notes to remember:
Any environment variable name that ends with a colon
must reference a volume, and should have a data value that contains
a full directory path name including the server name, volume name,
path and the last backslash. Any command that opens a file can
accept environment variables such as the path to the file. For
example, when the environment variable F: has the value HITECSOFT/
SYS:\USERS, The FIO:Open("F:\MYDATA.DAT", FIO_TEXT)
command can be issued within the NetBasic application to open
the HITECSOFT/SYS:\USERS\MYDATA.DAT file.
The environment variable name PATH is used to specify
the search directories for the interactive shell (see Interactive
Shell in the Getting Started section). When the user runs NetBasic
programs within the interactive shell, the current directory and
all search directories are scanned for the application or program
name. By default, the interactive shell sets the search path to
SYS:NETBASIC\USER; SYS:NETBASIC\INCLUDE; SYS:NETBASIC\UTIL directories,
however the search path can be changed by assigning new values
to the PATH variable.
The environment variable name TEMP is used to specify
the directory in which temporary files are created (see Preprocessor
in the Getting Started section). By default, TEMP is set to the
mail directory, or to the root directory. During program execution,
temporary files must remain accessible by the program. When the
program cannot access temporary files (i.e. if you logout from
the server), it will terminate abnormally.
The attributes of environment objects are Name, Data
and Error.
Name attribute: The Name
attribute is a read-write string, and indicates the name for the
environment variable.
Data attribute: The Data
attribute is a read-write string, and indicates a value for the
environment variable.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
File objects are used to access files. The attributes
of file objects are Name, Extension, Type, Size, Date, Time and
Error.
Name attribute: The Name
attribute is a read-write string, and indicates the file name
(up to 8 characters). A file can be renamed by changing the Name
attribute.
Extension attribute: The
Extension attribute is a read-write string, and indicates the
file's three-character extension. A file's extension can be renamed
by changing the Extension attribute.
Type attribute: The Type
attribute is a read-only integer, and contains either "FILE"
or "DIR".
Size attribute: The Size
attribute is a read-only integer, and contains the size of the
file in bytes.
Date attribute: The Date
attribute is a read-only string, and contains the date the file
was last updated, in MM-DD-YYYY format.
Time attribute: The Time
attribute is a read-only string, and contains the time the file
was last updated, in HH:MM:SS format.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Internet objects are used to locate a process within
an Internet-based system. A workstation may run multiple processes.
A network can have many workstations (nodes). Multiple networks
may be connected to form an Internet-based system. The attributes
of an Internet object are Network, Node, Socket and Error. All
attributes of the Internet object are read-only.
Socket attribute: The
Internet.Socket attribute is a read-only string, and contains
the socket address that identifies the process. When multiple
processes are running on the same computer, the socket address
uniquely identifies each process. This attribute is only available
for the current connection, and for all other connections it is
zero.
Node attribute: The Internet.Node
attribute is a read-only string, and contains the physical node
address that identifies the computer that the process is running
on. The node address uniquely identifies each computer within
a network.
Network attribute: The
Internet.Network attribute is a read-only string, and contains
the network number that identifies the network of the process
(see Internet Objects in this chapter). Each network has a number
that uniquely identifies that network among all other networks
of an Internet-based system.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Link objects are used by client applications to communicate
with server applications. A server application is a program that
usually starts prior to the client application. The server application
informs clients of its presence by using the advertising protocols
which add the server's information to the bindery. Since the server
does not have a client's address, the server application goes
into receive mode and suspends itself waiting for the client to
connect and send data. The data is any string with a maximum length
of 512 bytes. The client application is a program that usually
starts after the server goes into the receive mode. The client
searches the bindery by server name and type and retrieves the
server's information i.e. network, node and socket number that
the server is advertising on. The client uses the server's address
to send data to the server application. The server application
then processes the data, and returns a reply to the client. .
Both the client and server applications must use the same communication
protocol in order to successfully communicate. Link objects currently
support both Sequenced Packet Exchange (SPX) and Internet-based
Packet Exchange (IPX) protocols.
SPX Protocol
For the SPX protocol, the connection between the
client and server application is established prior to sending
any data. The server application must be active and in receive
mode before the client application can establish the connection
and send any data. (The server application cannot initiate sending
data; the first data must be sent by the client after the connection
is established.) The SPX protocol provides guaranteed delivery
of all. For the SPX protocol, if the connection is interrupted,
communications will be disconnected, and the connection must be
reestablished in order to send more data. Both client and server
applications must provide routines to trap any connection interruptions
that may occur during communication. The SPX protocol insures
that the data packets (strings of up to 512 bytes) are received
in the exact order that they are sent.
IPX protocol
For the IPX protocol, data can be sent even when
no connection is established. Thus, the IPX protocol does not
guarantee the delivery of data. For the IPX protocol, the data
packets (strings of up to 512 bytes) may not be received in the
exact sequential order that they are sent. It is up to the application
to provide its own sequencing logic. The IPX protocol allows the
client application to be active and to send data even when the
server application is down and not receiving any data. The IPX
protocol provides better speed and flexibility than the SPX protocol,
however it does not maintain the integrity of the data.
The attributes of link objects are Name, Type, Data,
Protocol.Name, Protocol.Handle, Internet.Network, Internet.Node,
Socket and Error.
Data attribute: The Data
attribute is a read-write string, and contains a string of up
to 512 bytes that is sent to or received from the destination.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. The error attribute is returned
as an integer. When no error is encountered, the Error attribute
will be zero.
Internet.Network attribute:
The Internet.Network attribute is a read-write string, and contains
the network number for the client or server application (see Internet
Objects topic). Each network has a 4 byte number that uniquely
identifies that network among all other networks of an Internet-based
system. The Internet.Network attribute is internally maintained
to contain the destination network address and usually is not
changed. However, advanced users can assign new values to this
attribute.
Internet.Node attribute:
The Internet.Node attribute is a read-write string, and contains
the physical node address for the client or server application
(see Internet Objects topic). The node address uniquely identifies
each workstation within a network. The Internet.Node attribute
is internally maintained to contain the destination physical node
address and usually is not changed. However, advanced users can
assign new values to this attribute.
Internet.Socket attribute: The
Internet.Socket attribute is a read-write string, and contains
the socket address for the client or server application (see Internet
Objects topic). When multiple processes are running on the same
workstation or the same file server, the socket address uniquely
identifies each process. The Internet.Socket attribute is internally
maintained to contain the destination socket address and usually
is not changed. However, advanced users can assign new values
to this attribute.
Name attribute: The Name
attribute is a read-only string, and contains the bindery name
for the server application. This attribute is assigned by the
programmer when the server is created and should be a valid bindery
name.
Protocol.Handle attribute:
The Protocol.Handle attribute is a read-only integer, and contains
a handle that is used internally to reference the protocol. This
attribute is not used by the programmer.
Protocol.Name attribute:
The Protocol.Name attribute is a read-only string, and contains
the protocol name for the link object (see IPX and SPX protocols
above).
Type attribute: The Type
attribute is a read-only integer, and contains the bindery type
for the server application. This attribute is assigned by the
programmer when the server is created and should be an appropriate
bindery type. Bindery types are listed in the NET.H file. In addition
to these predefined type constants, programmers can define new
types for servers that are not listed. The Type attribute uniquely
identifies the type of service that the server provides (see Bindery
Objects topic in this chapter).
Modules objects are used to return information regarding
NLMs. The attributes of the NLM objects are error, name, major,
minor, revision, date, copyright, description, and version.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Name attribute: The name
attribute is a read-only string that contains the name of the
NLM.
Major attribute: The major
attribute is a read-only integer that contains the major version
number of the NLM.
Minor attribute: The minor
attribute is a read-only integer that contains the minor version
number of the NLM.
Revision attribute: The
revision attribute is a read-only integer type that contains the
revision number of the NLM.
Date attribute: The date
attribute is a read-only string that contains the build date of
the NLM.
Copyright attribute: The
copyright attribute is a read-only string type that contains the
copyright string of the NLM.
Description attribute:
The description attribute is a read-only string that contains
the description of the NLM.
Version attribute: The
version attribute is a read-only string that contains a string
representation of the NLM's version.
Path objects are used to change the current path.
The attributes of a path object are Server.Name, Volume.Name,
Path and Error.
Server.Name attribute:
The Server.Name attribute is a read-only string, and specifies
the server name. The default server is specified by the connection
ID (See Connection Objects topic in this chapter).
Volume.Name attribute:
The Volume.Name attribute is a read-write string, and specifies
the volume name for the path. For NetWare volumes, the complete
volume name must be used.
Path attribute: The path
attribute is a read-write string, and contains the path name.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Queue job objects are used to access the jobs in
a queue. A queue is a central storage mechanism that keeps track
of service requests for different clients. Service requests are
referred to as jobs in the queue. When a client places a service
request in the queue, a job is added to the bottom of the queue.
The job server is an application that performs a service for each
job in the queue. When the service has been performed, the job
is removed from the queue. The queue behaves as a first in first
out stack, where jobs are added by clients to the bottom of the
stack and removed by the job server from the top of the stack.
A queue job object contains attributes that provide information
about the queue itself, the job in the queue, the client submitting
the job and the job server that services the job. The attributes
of a queue job object are ID, Client.Connection.Number, Client.Task,
Client.Bindery.ID, Target.Jobserver.Bindery.ID, Target.Service.Date,
Target.Service.Time, Jobserver.Connection.Number, Jobserver.Task,
Jobserver.Bindery.ID, Job.Create.Date, Job.Create.Time, Job.File.Name,
Job.File.Handle, Job.Number, Job.Type, Job.Position, Job.Name,
Job.Text and Error.
Client.Connection.Number attribute:
The Client.Connection.Number attribute is a read-only integer,
and contains the connection number for the client that submitted
the job to the queue (see the Connection Objects topic in this
chapter).
Client.Task attribute:
The Client.Task attribute is a read-only integer, and contains
a number that designates the task the client was performing when
the job was submitted to the queue.
Client.Bindery.ID attribute:
The Client.Bindery.ID attribute is a read-only integer, and contains
the bindery ID assigned to the client in the bindery. Each object
in the bindery has a unique ID. The unique bindery ID assigned
to the client is used to identify the client who added the job
to the queue (see Bindery Objects in this chapter).
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
ID attribute: The ID attribute
is a read-only integer, and contains the bindery ID assigned to
the queue in the bindery. Each object in the bindery has a unique
ID. When a queue is created, it is added to the bindery. The unique
bindery ID assigned to the queue is used to identify the queue
(see the Bindery Objects topic in this chapter).
Jobserver.Connection.Number attribute:
The Jobserver.Connection.Number attribute is a read-only integer.
If the queue job object is retrieved while the job is being serviced,
this attribute will contain the connection number for the job
server that is performing the service. Otherwise this attribute
is set to zero.
Jobserver.Task attribute:
The Jobserver.Task attribute is a read-only integer. If the queue
job object is retrieved while the job is being serviced, this
attribute will contain a number that designates the task the job
server is. Otherwise this attribute is set to zero.
Jobserver.Bindery.ID attribute:
The Jobserver.Bindery.ID attribute is a read-only integer. If
the queue job object is retrieved while the job is being serviced,
this attribute will contain the bindery ID for the job server
that is performing the service. Otherwise this attribute is set
to zero. Each object in the bindery has a unique used to identify
which job server is performing the service (see Bindery Objects
in this chapter). This attribute can be used to determine whether
a job is currently being serviced.
Job.Control attribute:
The Job.Control attribute is a read-write integer. Job control
attribute affect the way the queue server processes a queue job.
The flags define the following bits. (Bits 0, 1, and 2 must be
0.):
First Byte
The service auto-start flag indicates
how to handle the job should the client station lose its connection
before submitting the job. If this flag is set, the job will
be marked for processing if the client station loses its connection
to the queue. If this flag isn't set, the job is removed from
the queue.
The service restart flag indicates
how to handle the job if the queue server fails during processing.
If the flag is set, the job will be left in the queue for re-servicing.
The entry open flag indicates whether
the job is ready to be processed. When the job entry is first
created, this flag is set to indicate the job hasn't been submitted
yet. When the client submits this job, this flag is cleared.
The user hold flag indicates whether
the job may be processed. If the flag is set, the job will not
be processed until the flag is clear, but the job continues to
advance toward the front of the queue. An operator or the client
who submitted the job can modify this flag.
The operator hold flag indicates whether
the job may be processed. If the flag is set, the job will not
be processed until the flag is clear, but the job continues to
advance toward the front of the queue. Only operators can modify
this flag.
Job.Create.Date attribute:
The Job.Create.Date attribute is a read-only string, and contains
the date the job was created in the queue, in MM-DD-YYYY format.
Job.Create.Time attribute:
The Job.Create.Time attribute is a read-only string, and contains
the time the job was created in the queue, in HH:MM:SS format.
Job.File.Handle attribute:
The Job.File.Handle attribute is a read-only integer, and contains
the handle of the file that is created by the queue to hold the
information on the job. The job server receives the information
required for its services from this file. The required information
is written to the file using the file handle specified by the
Job.File.Handle attribute.
Job.File.Name attribute:
The Job.File.Name attribute is a read-only string, and contains
the name of the file that is created by the queue to hold the
information on the job.
Job.Name attribute: The
Job.Name attribute is a read-write string, and contains a name
or description that is assigned to the job by the client. The
Job.Name attribute is up to 50 characters in length and can be
used by other applications to identify the purpose of the job.
Job.Number attribute:
The Job.Number attribute is a read-only integer, and contains
a unique number assigned to the job by the queue.
Job.Position attribute:
The Job Position attribute is a read-write integer, and contains
the order number for the position of the job in the queue. Jobs
are ordered sequentially from 1 through 250, where job number
1 is positioned at the top of the queue. The Job.Position attribute
can be changed only by the queue operator. When a queue is created,
it is added to the bindery list as a bindery object. The "Q_OPERATORS"
property for the queue's bindery object contains the list of objects
that are authorized queue operators (see Bindery Objects in this
chapter).
Job.Text attribute: The
Job.Text attribute is a read-write string, and contains any additional
information that is assigned to the job by the client. The Job.Text
attribute is up to 152 characters in length and can be used to
transmit information to the job server or to other applications.
Job.Type attribute: The
Job.Type attribute is a read-write integer, and contains a number
that indicates the type of the job submitted to the queue. Usually,
the Job.Type attribute is set to zero to indicate that this attribute
is not being used. The job server may be set up to service only
the jobs for which the Job.Type attribute matches a specified
number. Therefore, the Job.Type attribute should contain a number
that is recognized by the job server.
Target.Jobserver.Bindery.ID attribute:
The Target.Jobserver.Bindery.ID attribute is a read-write integer,
and contains the bindery ID for the job server that should perform
the service for the job. Each object in the bindery has a unique
ID used to identify which job server should perform the requested
service (see Bindery Objects in this chapter). When a queue job
object is retrieved, the Target.Jobserver.Bindery.ID attribute
is originally set to "FFFFFFFF," which indicates that
the first available job server should provide the service. This
attribute can be changed to contain the bindery ID of a specific
job server.
Target.Service.Date attribute:
The Target.Service.Date attribute is a read-write string, and
contains the earliest date the job can be serviced, in MM-DD-YYYY
format. This attribute is originally set to the job creation date,
which causes the job to be serviced at the first opportunity.
Target.Service.Time attribute:
The Target.Service.Time attribute is a read-write string, and
contains the earliest time the job can be serviced, in HH:MM:SS
format. This attribute is originally set to the job creation time,
which causes the job to be serviced at the first opportunity.
Server date objects are used to retrieve and change
the date and time of the default file server. The attributes of
the server date objects are Date, Time, and Error.
Date attribute: The Date
attribute is a read-write string, and contains the date of the
default file server in MM-DD-YYYY format.
Time attribute: The Time
attribute is a read-write string, and contains the date of the
default file server in HH:MM:SS format.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Server description objects are used to retrieve information
about the company that distributed the NetWare Operating System
that is currently running on the default file server. The attributes
of server description objects are Company, Revision, Date, Copyright
and Error. All attributes of the server description objects are
read-only.
Company attribute: The
Company attribute is a read-only string, and contains the name
of the company that distributed the NetWare Operating System that
is running on the default file server. The Company attribute is
up to 80 characters long.
Revision attribute: The
Revision attribute is a read-only string, and contains the version
and revision for the NetWare Operating System that is running
on the default file server. The Revision attribute is up to 80
characters long.
Date attribute: The Date
attribute is a read-only string, and contains the revision date
for the NetWare Operating System that is running on the default
file server in MM-DD-YYYY format.
Copyright attribute: The
Copyright attribute is a read-only string, and contains the copyright
notice for the NetWare Operating System that is running on the
default file server. The Copyright attribute is up to 80 characters
long.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
System date objects are used to retrieve the system
date and time. The attributes of system date objects are Date,
Time and Error.
Date attribute: The Date
attribute is a read-write string, and contains the system date
in MM-DD-YYYY format.
Time attribute: The Time
attribute is a read-write string, and contains the date of the
default file server in HH:MM:SS format.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
System information objects are used to retrieve information
about the system currently running the NetBasic application. The
attributes of system information objects are OS.Type, OS.Version,
Shell.Version, Monitor.Type and Error. All attributes of volume
information objects are read-only.
OS.Type attribute: The
OS.Type attribute is a read-only string, and contains the type
for the Operating System currently running on the system.
OS.Version attribute:
The OS.Version attribute is a read-only string, and contains the
name of the Operating System currently running on the system.
Shell.Version attribute:
The Shell.Version attribute is a read-only string, and contains
the version and revision number of NetBasic that is currently
running the application.
Monitor.Type attribute:
The Monitor.Type attribute is a read-only string, and contains
the type of the monitor attached to the current system.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
Volume information objects are used to retrieve information
about the volumes that are available for the default file server.
The attributes of volume information objects are Name, Blocks.Total,
Blocks.Free, Blocks.Purgable, Blocks.Size, Dir.Total, Dir.Free,
Hashing, Removable, Mounted and Error. All attributes of volume
information objects are read-only.
Name attribute: The Name
attribute is a read-only string, and contains the name of the
volume, up to 16 characters long.
Blocks.Total attribute:
The Blocks.Total attribute is a read-only integer, and contains
the total number of blocks on the volume.
Blocks.Free attribute:
The Blocks.Free attribute is a read-only integer, and contains
the number of unused blocks on the volume.
Blocks.Purgable attribute:
The Blocks.Purgable attribute is a read-only integer, and contains
the number of blocks occupied by deleted files on the volume that
have not been permanently removed.
Blocks.Size attribute:
The Blocks.Size attribute is a read-only integer, and contains
the size of each block in bytes.
Dir.Total attribute: The
Dir.Total attribute is a read-only integer, and contains the total
number of directories allocated for the volume during installation.
Dir.Free attribute: The
Dir.Free attribute is a read-only integer, and contains the number
of unused allocated directories that remain on the volume.
Hashing attribute: The
Hashing attribute is a read-only boolean, and contains "TRUE"
when hashing is enabled and "FALSE" otherwise.
Removable attribute: The
Removable attribute is a read-only boolean, and contains "TRUE"
when the volume is removable and "FALSE" otherwise.
Mounted attribute: The
Mounted attribute is a read-only boolean, and contains "TRUE"
when the volume is mounted and "FALSE" otherwise.
Error attribute: The Error
attribute is a read-only integer, and indicates any error encountered
during an operation on the object. When no error is encountered,
the Error attribute will be zero.
The NetWare Directory Service (NDS) extensions for
NetBasic are a powerful addition to the tools available to NetBasic
developers. The NDS extensions provide a well rounded set of
high-level 4GL functions that allow complete access to the management,
maintenance and administrative operations associated with NDS
programming in the lower level SDK environment.
Anyone who has written client or server applications
for the NDS environment using the NetWare SDKs is, no doubt, familiar
with the voluminous code that must be written to perform seemingly
simple tasks. Additionally, the learning curve associated with
the NDS SDK and the ancillary aspects of it can be very steep
even for the most seasoned developer.
Novell has implemented a directory service that is
very well suited for the global environment. It is scaleable,
reliable, flexible and secure. The task now facing developers
is to embrace the power of NDS by developing applications that
take full advantage of that power. NetBasic's NDS extensions can
be of great assistance in this endeavor.
NetBasic and its NDS extensions can make you a productive
NDS programmer in a fraction of the time it would otherwise take.
The NDS extensions don't hide the important aspects of NDS programming,
however, they do a lot of the tedious work for you. The NDS extensions
are well organized and present an intuitive set of functions that
provide you with the same amount of programming flexibility that
you have come to expect from NetBasic.
NetWare Directory Services was developed as a hierarchical
design with multiple levels of organizational units, users, groups,
and network resources. This hierarchical structure is referred
to as the Directory tree. The Directory tree is formed by organizing
objects in a multiple level structure.
This Directory tree structure has the tree growing
upside down, starting with the name of the tree or [Root] object
at the top of the tree and branching downward.
Directory objects consist of categories of information,
known as classes, and the data included in those classes. This
information is stored in the Directory database.
The Directory database contains three types of objects:
[Root] object (Directory tree
name)
Container objects
Leaf objects
These objects represent both actual and logical resources
in the network, such as users and printers, or groups and print
queues.
The Directory tree name ([Root] object) is automatically
placed at the top of the tree by the NetWare 4 installation program.
Branches of the Directory tree consist of container objects and
all of the objects they hold. These container objects can also
contain other container objects. Leaf objects are at the ends
of the branches and do not contain any other objects. Container
objects hold (or contain) other Directory objects. Container objects
are a means of logically organizing all other objects in the Directory
tree. Just as directories are used to group related files together
in a file system, container objects are used to group related
items in the Directory tree. A container object that contains
other Directory objects is known as a parent object. The following
is a list of container objects:
Country
Locality
Organization
Organizational Unit
Directory leaf objects are objects that do not contain
any other objects. These represent actual network entities such
as users, servers, printers, computers, etc. You create leaf
objects within a container object. The following is a list of
leaf objects:
AFP Server
Alias
Computer
Directory Map
External Entity
Group
List
Message Routing Group
Organizational Role
Organizational Unit
Printer
Print Queue
Print Server
Profile
User
Volume
Each type of object (such as a User object, Organization
object, or Profile object) has certain properties that hold information
about the object. These properties are called attributes. For
example, a User object's attributes include a login name, E-mail
address, password restrictions, group memberships, etc. A Profile
object's attributes include profile name, login script, and volume.
Some attributes are required for a specific object
before setup of that object is complete. These attributes are
called mandatory attributes. Other attributes can be added later
as the need arises. These attributes are called optional attributes.
Many attributes allow you to enter more than one
value. These attributes are said to be multi-valued. Attributes
that must always be represented by one and only one value are
said to be single valued.
Attributes can contain many types of data. These
data types are called syntaxes. A syntax may be as simple as
an integer or it may be as complex as a complete directory map
with separate volume and directory path string components.
As with file system file and directory rights, access
to objects and their attributes can be controlled. This is accomplished
through object and attribute Access Control Lists
(ACLs). ACLs are implemented to control the access
rights that one object has to another object or its attributes.
Each object's and each object attribute's ACLs are maintained
separately.
In NetWare Directory Services (NDS), context refers
to the location of an object in the Directory tree. This context
is important for NDS to locate specified network resources.
The complete context, or path, from an object to
the [Root] of the Directory tree identifies and forms the object's
Distinguished Name. The context, or path, from an object to another
object of the Directory tree identifies and forms the object's
Relative Distinguished Name
( RDN).
All leaf objects in the Directory have a common name
(CN). For User objects, the common name is the login
name displayed in the Directory tree.
Names in the Directory tree have two name types:
typed and typeless. A typed name includes the name type (OU,
O, etc.) of each object when identifying the Distinguished Name
of that object. A typeless name excludes the name type for each
object in a name. A name type distinguishes the specific object
you are referring to, such as a User object or an Organizational
Unit object.
Directory partitions are logical
divisions (or portions) of the Directory database that can be
replicated. They form a distinct unit of data in the Directory
tree used to store and replicate Directory information. The fact
that an NDS database can be separated into partitions located
on servers across the network enables it to be referred to as
a distributed database.
The partitioning of the NDS information is completely
transparent to network users, making the network look like a single,
cohesive collection of resources. Partitions are created to increase
performance and provide ease of management and scalability.
A partition is a subtree or branch of the Directory
tree. Each partition is named according to the [Root]-most container
object within the partition (the one that is closest to the [Root],
also called the Partition Root Entry). The [Root] object (also
at the top of the tree) is always included in the first partition
created, which is known as the[Root] partition.
When a partition is subordinate to another in the Directory tree,
it is referred to as a child partition. The partition above it
is referred to as the parent partition.
A replica is an instance of a partition.
You can create an unlimited number of replicas for each partition
and store them on any NetWare 4 servers on the network. There
are several different replica types.
Master
Read/Write
Read-Only
Subordinate Reference
When changes are made to objects within a partition,
those changes are automatically sent to all other replicas of
that partition. This ensures that the global Directory database
remains consistent. Only changes are sent to other replicas. For
example, if a user changes a phone number, only the new phone
number is sent, not the entire User object.
For this synchronization to occur, each replica must
be contacted. Each replica maintains a record of the location
of each of its replicas. The locations are stored in the partition's
replica property, with one property entry for each replica of
the partition. The collection of replica properties of a partition
forms a list of the replicas, sometimes called a replica ring
or replica list.
One aspect of NDS programming that NetBasic handles
on your behalf is local buffer management. NDS buffers are the
data structures and link lists that are used to communicate NDS
requests from the client application to NDS and to return responses
to those requests. Each group of NetBasic NDS functions has a
set of NDS result buffers that are shared by functions in the
group. The object function group, attribute function group and
partition function group each have their own result buffers.
This design allows NetBasic developers to access data from NDS
without having to write the code associated with the allocation,
initialization, access and configuration of the NDS buffers.
The code reduction that is realized by this design is very significant.
Many of the different syntaxes used for NDS data
are complex data types. NetBasic's NDS extensions are designed
so that every syntax can be represented by the simpler data types
Boolean, Integer or String. If you have already developed applications
in the NetBasic environment then you will recognize these data
types as the basic NMX (see Appendicies for more information on
NMX) data types.
In order to adequately represent the more complex
NDS data types with the simpler NMX data types some conversion
conventions must be employed. As a NetBasic developer you do
not have to perform these conversions, however, you do need to
understand the attribute data formats that are used. The following
are some examples of the formats used to represent the more complex
attribute values as simple NMX values.
Object ACL Type Attribute Values
An object ACL has 3 components. They are the subject
name, the attribute name and the privileges to be associated.
The NMX data type used to represent these components is the NMX
String type with the following format:
"[S]<subject name>,[A]<attribute
name>,[P]<privilege characters>"
In this example the subject CN=User1.O=TestOrg1 is
granted read, write and compare privileges to the login script
attribute of the object controlled by this ACL entry.
"[S]CN=User1.O=TestOrg1,[A]Login Script,[P]RWC"
In this example the subject CN=User1.O=TestOrg1 is
granted browse, add, delete and rename privileges to the object
controlled by this ACL entry.
"[S]CN=User1.O=TestOrg1,[A]Entry Rights,[P]BADR"
Path Type Attribute Values
The Path attribute type has three components. The
name space type, the volume name and the volume directory path.
The NMX String data type is again used with the following format:
"[N]<name space type>,[V]<volume>,[P]<path>"
In this example the DOS name space for the path \PUBLIC
on volume CN=Eng_1_SYS.O=TestOrg1 is represented.
Semaphores are used to synchronize events between
two or more applications. NetBasic supports local and global
semaphores. Local semaphores are used to synchronize events on
the same server. Global semaphores are used to synchronize events
on a server and its clients. A client can also be other server.
NetBasic has 5 local semaphore IDs (1 through 5),
that can be used. So when application A opens a local semaphore,
it must open it with a ID of 1 through 5. If another application
(B) needs to synchronize with A, it must use the same semaphore
ID. Once a local semaphore is opened, the same ID is used to
access the other local semaphore API's. A Global Semaphore, however,
use strings rather than IDs. Two applications must use the same
string to open the same semaphore. Once a global semaphore is
opened, it returns a handle that is used in all subsequent calls
to the global semaphore APIs.
HTML Documents
HTML documents are ASCII files which are created
using any standard text editor. Normally, these documents are
very static in nature. That is, they are created, placed into
the WEB server's document directory, and then served on request
to a WEB browser. Using NetBasic's document management component
(DOC.NLM), you can write BASIC language scripts which generate
HTML documents on the fly. For example, you could write a script
that produces a list of users on a server, and present that list
inside a combo box of an HTML document. Since the document is
created on-demand, the information it contains is always up to
date. Another example might be creating a dynamic report by accessing
an online corporate database.
Although knowledge of HTML is not required to use
the NetBasic Document Management component, some familiarity with
it might be helpful. There are many resources available on the
Internet which discuss HTML, if you would like more information.
This manual does not attempt to explain HTML, but instead illustrates
how to use NetBasic's built-in DOC API set to create dynamic HTML
documents.
NetBasic commands may or may not return a value.
In this manual, for the purpose of clarity, the commands that
return a value are sometimes referred to as functions. Parentheses
are used to supply parameters to commands. For commands that do
not receive any parameters, typing the parentheses is optional.
For example, the commands WIN:Cursor:Show and WIN:Cursor:Show()
are both valid.
Bindery Properties
Connection Information Objects
Connection Objects
Date Objects
Directory Objects
Environment Objects
File Objects
Internet Objects
Link Objects
Module Objects
Path Objects
Queue Job Objects
Bit 3 = service auto-start
Bit 4 = service restart
Bit 5 = entry open
Bit 6 = user hold
Bit 7 = operator hold
Server Date Objects
Server Description Objects
System Date Objects
System Information Objects
Volume Information Objects
NetWare Directory Services
NetWare Directory Services
Directory Tree
Directory Objects
NDS Object Attributes
NDS Object and Attribute Rights
Context and Names
Directory Partitions
Partition Replicas
Synchronization
NDS Buffers and Link List
Attribute Data Representations
"[N]0,[V]CN=Eng_1_SYS.O=TestOrg1,[P]\public"
NetWare Semaphore Class
HTML
Document Class
Commands and Functions