Programming Client APIs for Use Inside a Visual Basic Application
Articles and Tips: article
Developer Support Engineer
01 Aug 1996
Programming languages such as Visual Basic take Windows programming into a simple GUI environment and require a fraction of the overhead required by traditional languages. This article, which is intended for developers familiar with the basics of Visual Basic programming, shows how to prototype Novell Client APIs for use inside a Visual Basic application. Topics covered include a description of the program, writing the program, and defining functions and variables.
For rapid development of applications for the Windows platforms, nothing beats the visual languages. Programming languages such as Visual Basic, Delphi, and Smart Talk (to name a few) take Windows programming from the struggles of understanding WinMain() into a simple GUI programming environment.
With the user interface being a simple grab-and-paste setup and existing object/controls whose properties and attributes can be modified on the fly, programmers are left to fill in simple code pages with a handful of instructions. These programming instructions are always a fraction of the overhead required for developing in C++, C, or (heaven forbid) assembly.
For Novell Developers, the only challenge that is left, after mastering the basic syntax of a visual language, is understanding how to prototype function calls into the Novell SDK Dynamic Link Libraries.
This article is intended for those programmers who are already familiar with the basics of programming in Microsoft's Visual Basic programming environment.
With the information in this article, anyone with an elementary understanding of the Visual Basic language can use the information in this article to prototype Novell Client APIs for use inside a Visual Basic application.
The sample code shown here is also located on CompuServe on the NDEVSUP forum, also on the Internet at either ftp://ftp.novell.com/pub/netwire/ndevsup/03/ or HTTP://DEVSUP.NOVELL.COM under the filename VBCAP.EXE.
How the Program Works
The sample application is a simple program for capturing LPT ports to a given queue on a specified server. The program checks your LPT ports and displays whether or not they are captured. To use the program you first enter the name of the server you wish to capture to. After pressing the ENTER button, all of that server's available queues are automatically displayed.
If you wish to capture to a particular queue, you highlight the queue, then highlight whichever LPT port you want captured, and then press the CAPTURE button. The program will then capture that LPT port to the specified queue and update the "Status of LPT Ports:" text box to reflect the change. To "uncapture" an LPT port you simply highlight the LPT port and press the END CAPTURE button. Again the "Status of LPT Ports:" text box is automatically updated to reflect the change.
Writing the Program and Defining Functions and Variables
A typical VB application consists of at least three files:
projname.mak (which is the main project file), projname.frm (which is the actual program form and associated code), and projname.bas. This last file is a simple text file containing all your prototypes for the Novell API function calls that you are going to make. In this file you must also include any specific variables or structures that will be accessed, such as OT_PRINT_QUEUE.
The Novell specific function calls,structures and variables used in this sample program are:
OT_PRINT_QUEUE NWCAPTURE_FLAGS1 NWCAPTURE_FLAGS2 NWCallsInit() NWGetConnectionHandle() NWScanObject() NWGetObjectName() NWGetCaptureFlags() NWGetMaxPrinters() NWFlushCapture() NWEndCapture() NWStartQueueCapture() NWDSCreateContext() NWDSFreeContext()
These are all prototyped in the capture.bas file, which is then included in the project file capture.mak.
Prototyping the functions can be confusing. Many developers, not wishing to bother with this will go out and purchase a Visual Basic SDK for Novell APIs from a third party vendor. This avoids having to hassle with trying to get all the function calls and data types defined correctly.
To define the function correctly you need to look at the C definition for the function.
Let's take NWScanObject() as an example. This is defined in the SDK manual as:
NWCCODE N_API NWScanObject( NWCONN_HANDLE conn, pnstr8 searchName, nuint16 searchType, pnuint32 objID pnstr8 objName, pnuint16 objType, pnuint8 hasPropertiesFlag, pnuint8 objFlags, pnuint8 objSecurity);
The first three parameters conn, searchName, and searchType are being passed (IN) to the DLL, so they are defined as being passed ByVal. This is important to include because the default in VB is to pass values by reference (ByRef) which if used on data being passed into a function will GPF your program.
The variable names used in the .BAS file have nothing to do with the names you can use later in your program when you actually call these functions. For example, you could define in your prototype with the variable name of your connection handle to be "ByVal myConn As Integer", and then in the code section of your form pass in an integer "ThisNEWNameForConn%" as the variable. Keeping the names the same in the .BAS and .FRM file is only for clarity.
For the (OUT) values, chars,and ints and ptrs to chars and ints(i.e., anything 16 bits or less), the values being received back from the DLL are to be defined ByRef as Integer. Longs are defined as longs. Strings are a little different; if the value coming back is a pointer to a string, as in the case of objName (in NWScanObject) then the value is received ByVal as String.
Another important note on how strings are to be received is that space MUST be allocated in advance of the call. Note that for the value objName in NWScanObject the string objName is defined as: Dim ObjName As String * 50
If space has not been set aside for the returning string data (i.e., Dim ObjName As String 'no * 50 ) , the function will return successfully, but memory WILL be overwritten to provide space for the Object Name. Just a few lines later in the execution of the code, the program will GPF. This can be quite puzzling, since the GPF can happen several lines after the actual cause of the failure.
There are two other things to remember about strings in VB. First, VB doesn't create NULL terminated strings by default. You must do this manually by adding 'CHR$(0)' to the end of the string. Second, a string defined as "DIM MyString As String * 15" has whatever text you put in it, padded with trailing spaces. Therefore, if you create MyString and put "THISVALUE" into it, the value will actually be "THISVALUE ". Once again, you would want to NULL terminate this after the end of your text, before passing this as a value in function call.
In the call NWScanObject we also have an objectType OT_PRINT_QUEUE. This is defined in the 'C' header files as a 0x0300. To do this in VB we define this objType as: Global Const OT_PRINT_QUEUE = &H300
One datatype we haven't covered in NWScanObject is the Struct (structure data type.) NWGetCaptureFlags() receives the NWCAPTURE_FLAGS structures and NWGetObjectName uses them to get information on a queue's name. Please review how these are defined at the beginning of the capture.bas file, to become familiar with how to define structures in VB.
Visual Basic is an excellent language for writing Novell-specific applications. After understanding how to prototype functions and variables, making calls into Novell's various DLL's is quite simple.
One last note: the sample code shown here is written using 16-bit DLL's. If you were programming this for a 32-bit platform, the connection handles and return codes would be longs instead of ints. Also, you will notice that NWGetCaptureFlags() is defined to use the old NWCALLS.DLL, because under the current CALWIN16.DLL this function does not work properly.
Figure 1: Program to Capture Printer Ports.
This file contains the Visual Basic Prototypes for Novell API functions:
Global Const OT_PRINT_QUEUE = &H300& Type NWCAPTURE_FLAGS1 jobDescription(0 To 49) As String * 1 jobControlFlags As String * 1 tabSize As String * 1 numCopies As Integer printFlags As Integer maxLines As Integer maxChars As Integer formName As String * 13 reserved As String * 9 formType As Integer bannerText As String * 13 reserved2 As String * 1 flushCaptureTimeout As Integer ' DOS/WIN only flushCaptureOnClose As String * 1 ' DOS/WIN only End Type Type NWCAPTURE_FLAGS2 connID As Integer queueID As Long setupStringMaxLen As Integer resetStringMaxLen As Integer LPTCaptureFlag As String * 1 ' DOS/WIN only fileCaptureFlag As String * 1 ' DOS/WIN only timingOutFlag As String * 1 ' DOS/WIN only inProgress As String * 1 ' DOS/WIN only printQueueFlag As String * 1 ' DOS/WIN only printJobValid As String * 1 ' DOS/WIN only queueName(0 To 64) As String * 1 End Type Declare Function NWCallsInit Lib "CALWIN16.DLL" (empty1 As Integer, empty2 As Integer) As Integer" Declare Function NWGetConnectionHandle Lib "CALWIN16.DLL" (ByVal serverName As String, " ByVal mode As Integer, Conn As Integer, ByVal connScope As Long) As Integer Declare Function NWScanObject Lib "CALWIN16.DLL" (ByVal Conn As Integer, ByVal " searchName As String, ByVal searchType As Integer, objectID As Long, ByVal objectName As String, objectType As Integer, hasPropertiesFlag As Integer, objectFlags As Integer, objectSecurity As Integer) As Integer Declare Function NWGetObjectName Lib "CALWIN16.DLL" (ByVal Conn As Integer, " ByVal objectID As Long, ByVal objectName As String, objectType As Integer) As Integer Declare Function NWGetCaptureFlags Lib "NWCALLS.DLL" (ByVal LPTDevice As " Integer, captureFlags1 As NWCAPTURE_FLAGS1, captureFlags2 As NWCAPTURE_FLAGS2) As Integer Declare Function NWGetMaxPrinters Lib "CALWIN16.DLL" (numPrinters As Integer) As Integer" Declare Function NWFlushCapture Lib "CALWIN16.DLL" (ByVal LPTDevice As Integer) As Integer" Declare Function NWEndCapture Lib "CALWIN16.DLL" (ByVal LPTDevice As Integer) As Integer" Declare Function NWStartQueueCapture Lib "CALWIN16.DLL" (ByVal Conn As Integer, ByVal LPTDevice" As Integer, ByVal queueID As Long, ByVal queueName As String) As Integer Declare Function NWDSCreateContext Lib "NWNET.DLL" () As Long" Declare Function NWDSFreeContext Lib "NWNET.DLL" (ByVal Context As Long) As Integer" (General Declarations) Option Explicit 'Forces all variable to be defined Dim Conn As Integer 'Make the connection handle global to this form Private Sub Command1_Click() ' THIS THE CAPTURE BUTTON Dim code As Integer Dim Printer As Integer Dim queueID As Long Dim queueName As String Dim Context As Long Printer = List2.ListIndex + 1 'Get Queue ID and Name for Capture call queueID = List1.ItemData(List1.ListIndex) queueName = List1.List(List1.ListIndex) 'Flush any existing print jobs and end any existing capture code% = NWFlushCapture(Printer) code% = NWEndCapture(Printer) 'Required for NDS Context = NWDSCreateContext() 'Capture LPT and report in status box code% = NWStartQueueCapture(Conn%, Printer, queueID, queueName) If code% = 0 Then Label1.Caption = List2.List(List2.ListIndex) & & redirected to & & List1.List(List1.ListIndex)& GetPrinterList End If code% = NWDSFreeContext(Context) End Sub Private Sub Command2_Click() ' This is the End Capture button Dim code As Integer Dim Printer As Integer Dim queueID As Long Dim queueName As String 'Get which LPT to be endcap'd Printer = List2.ListIndex + 1 'Flush any existing print jobs and end existing capture code% = NWFlushCapture(Printer) code% = NWEndCapture(Printer) Label1.Caption = "Capture ended for: " + List2.List(List2.ListIndex)" GetPrinterList End Sub Private Sub Command3_Click() 'EXIT BUTTON End End Sub Private Sub Command4_Click() 'Enter button to register a servername Dim code As Integer code% = NWGetConnectionHandle(Text1.Text + Chr$(0), 0, Conn%, 0) If code% << 0 Then< Label1.Caption = "ERROR: SERVER NOT FOUND." + Chr(13) + "Enter the Name of " the Server You Wish to Capture to:"" Text1.SetFocus Else 'If valid server name then scan it's queues and display current LPT port status Label1.Caption = "Successful Connection Handle was returned"" Scan_queues GetPrinterList End If End Sub Private Sub Form_Load() Dim code As Integer code% = NWCallsInit(0, 0) If (code << 0) Then< Label1.Caption = "Could not find NWCALLS.DLL"" End End If Show Label1.Caption = "Enter" the Name of the Server You Wish to Capture to:"" Text1.SetFocus GetPrinterList Command1.Enabled = False Command2.Enabled = False List2.Enabled = False End Sub Private Sub GetPrinterList() Dim code As Integer Dim Printers As Integer Dim Counter As Integer Dim ObjName As String * 50 Dim ObjType As Integer Dim connID As Integer Dim f1 As NWCAPTURE_FLAGS1 Dim f2 As NWCAPTURE_FLAGS2 List2.Clear code% = NWGetMaxPrinters(Printers) For Counter = 1 To Printers ' See if the printer is already captured f2.queueID = 0 code% = NWGetCaptureFlags(Counter, f1, f2) If f2.queueID Then code% = NWGetObjectName(f2.connID, f2.queueID, ObjName, ObjType) List2.AddItem "LPT" + Format$(Counter) + ": "" " " ObjName" Else ' Not captured List2.AddItem "LPT" + Format$(Counter) + ": (LOCAL)"" End If Next Counter End Sub Private Sub List1_Click() List2.Enabled = True End Sub Private Sub List2_Click() Command1.Enabled = True If InStr(List2.List(List2.ListIndex), "(LOCAL)") = 0 Then" Command2.Enabled = True Else Command2.Enabled = False End If End Sub Public Static Sub Scan_queues() Dim code As Integer Dim ObjName As String * 50 Dim ObjType As Integer Dim ObjFlag As Integer Dim ObjSec As Integer Dim HasProps As Integer Dim ObjId As Long Dim q_found As Integer List1.Clear 'CLEAR OUT ANY EXISTING ITEMS FROM LIST BOX q_found = 0 'FLAG TO DETERMINE IF ANY QUEUE'S ARE FOUND ObjId = 1 Do code% = NWScanObject(Conn%, "*", OT_PRINT_QUEUE, ObjId, ObjName, ObjType, " HasProps, ObjFlag, ObjSec) If code% = 0 Then q_found = 1 'SET Q FLAG TO TRUE List1.AddItem ObjName 'ADD QUEUE NAME TO LIST BOX List1.ItemData(List1.NewIndex) = ObjId 'STORE DATA FOR CAPTURE End If Loop While code% = 0 If q_found = 0 Then Label1.Caption = "NO QUEUES FOUND ON THIS SERVER"" End If End Sub
* Originally published in Novell AppNotes
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.