Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Client-Side Addendum (Worldgroup v2)

Applies to: v10

Not in v10. This whole chapter describes removed functionality. Client/Server mode, Worldgroup Manager (WGM), the Visual Basic client apps, the Netscape plug-in and the multimedia client are not in v10 (MBBS10.txt section 2). The chapter is kept as WG1-3.x history only. Nothing in it can be used to write a v10 module.

Applies to: WG1-3.x (client side: C/S, WGM)

Editor’s note: this material comes from the client-side half of the Developer’s Addendum for Worldgroup v2. There is no WG1 client chapter to merge it into (the Client App Developer’s Guide is not part of this draft), so it is collected here. Per project convention client (C/S, WGM) content is tagged WG1-3.x rather than WG2+. The material itself first appears in Worldgroup 2.0 (it is not in the WG1 manuals); the tag records platform scope, not introduction version. Page references in the text are to the original manuals.

Web-aware Client Apps

A client app written for the Worldgroup Major BBS platform can act as a plug-in Web application as well as an online service application — even running off of the same Worldgroup Major BBS server — without the app developer having to lift a finger. The Worldgroup Major BBS platform does the work required to handle the different venues in which an app may be run.

The Worldgroup Major BBS platform handles the connection between the client and the server. As a result, app developers do not need to worry about whether their app is communicating with the server through a phone line, ISDN link, Novell LAN, X.25 network, or TCP/IP (Internet or Intranet) connection.

This was the case with Worldgroup’s the Major BBS’s v1.x development platform and is described in the Client App Developer’s Guide. In Worldgroup v2.0, TCP/IP connectivity is the connectivity of choice for plug-in Web apps.

The Worldgroup Major BBS plug-in for Netscape recognizes EMBED tags in HTML files that call out Worldgroup the Major BBS apps. It launches Worldgroup Manager, indicating the domain name of the server to contact, optionally what app to run, and optionally what command string to pass to that app.

...

Applies to: v10

Not in v10. Historical figure: the Client/Server protocol architecture it shows (Worldgroup Manager, plug-in, agents, client apps) does not exist in v10.

If you haven’t used Worldgroup the Major BBS on the Web, check out our Web site at http://www.gcomm.com.

Any Worldgroup Major BBS app can be launched as a plug-in Web app if configured to do so on the server. There are some things app developers can do to better interact with the Web browser in these contexts, as explained in the following sections.

Command Strings

Command strings are nothing new. They’re discussed at length in the Client App Developer’s Guide. Basically, they provide a method for the Sysop to specify not only an app to be launched and when, but also what the app should do right away (like pop up a particular window). Command strings become very important when a Webmaster is integrating Worldgroup the Major BBS apps into his Web site. The more control he can have over what happens when an app is launched, the better.

...

When developing an app, be sure to think about supporting command strings that would be helpful to Webmasters.

Finding and Launching URLs

Applies to: WG1-3.x (Client)

Editor's note: the Year 2000 changes to client date entry and output (replace masked edit boxes with text boxes, use Format$() and DateValue()) are client-side material that first appears in the WG 3.12 addendum; see chapter 24, "Client Application Date Entry", "Date Output" and "Date Input", where they are tagged WG1-3.x (Client).

The interaction between the Web browser and a Worldgroup Major BBS app doesn’t have to stop when the browser launches the app. The app can pass a new URL back to the browser. For example, if the Message Center app sees something like http://www.gcomm.com in the text of an e-mail message, it will highlight the URL so that the user may click on it.

...

If you’re writing a new app, it’s easy to integrate this sort of functionality. Two API calls exist to help with this. One API call finds URLs embedded in text. The other API call passes a URL to the currently running Web browser.

findurl

The findurl() function takes two parameters. The first is the index, the position (1-based) within the passed string to begin looking for URLs. To examine the entire string, pass an index of 1. The second parameter is the string of text itself.

...

Here’s how to identify all URLs in a string:

Code Block
Dim idx As Integer, urllen As Integer

' stg is the string we're finding URLs in
idx = 1
Do
        urllen = findurl(idx, stg)
        If urllen > 0 Then
                ' URL found at index idx in stg, length urllen
                idx = idx + urllen
        End If
Loop While urllen <> 0

Once you know the location of a URL within a string, it’s your decision as to what to do with it. You can make a clickable (hypertext-like) link out of it, put it in a URL list for the user to select, etc.

gotoURL

To pass a URL to the currently running Web browser, call the gotoURL() routine. For example, assuming urlstg contains a string of characters which form a URL, this passes the URL to the browser:

Code Block
gotoURL urlstg

It’s that easy. If a supported Web browser is currently running, it will be sent to that URL. If not, the user will be asked to run a Web browser and try again. Be on the lookout for opportunities to take advantage of URLs in any apps you develop. Users appreciate not having to type URLs by hand.

Dynapak Status

There are now more functions for getting the status of dynapaks above and beyond stsdpk():

...

In the case of dynapak reads, the callback’s response value is the value of the dynapak. In the case of statuses, the value is the appropriate length, as a Long. To get the value, use cbkrsp():

Code Block
junk = cbkrsp(Len(lenaslong), lenaslong)

See stsdpk() for more on getting the status of dynapaks and the lengths that result.

Visual Basic v4.x

Worldgroup The Major BBS apps developed in Visual Basic, for the moment, are best developed in Visual Basic v3.0. VB3 is what was used to develop the baseline Worldgroup Major BBS apps. We chose not to upgrade our VB environment to VB4 because of an awareness that the size of the client (Worldgroup Manager and required apps combined) is of great importance to our customers. For the same functionality delivered by VB3’s .vbxs, VB4’s 16-bit .ocxs are much larger (in many cases twice as large). If we used VB4 for our apps, the size of the client would grow considerably. Given the benefits of VB4 (in 16-bit mode, as we want, for the moment, apps to run on both Win16 and Win32 platforms) and given the growth of the client, we chose to stick with VB3.

It is technically possible for you to develop apps with VB4. Just name all needed VB4 support files in your app’s .mdf file (see Shared Support Files on page 15). Such apps, given all needed support files, will be quite large. Users needing to fetch them on the fly will find themselves sitting through very lengthy downloads. The tradeoffs are yours to weigh.

Development in non-VB Environments

Although the Worldgroup v1.x client development environment was designed for apps written in Visual Basic, it is now possible to write apps in non-VB environments (C++ or Delphi, for example). It is a more difficult task, as the Client App Developer’s Guide is geared towards VB development and not all aspects of the API are available to you. But, it is quite possible. Here’s how...

...

Be sure to include any support files needed by your app in your app’s .mdf file. See Shared Support Files on page 15.

Multimedia Development

For Worldgroup v1.01, there was the Client/Server Developer’s Kit and there was the Multimedia Client/Server Developer’s Kit. The latter included everything in the former, plus an additional manual, the Multimedia Developer’s Guide, describing extensions to the client API for displaying and manipulating images.

...

The following functions have been added...

rmventid

NAME

rmventid — removes entries from one or more windows’ paint lists, by image id

SYNOPSIS

Code Block
result = rmventid(fromall, imgid, hwnd)

result As Integer SUCCESS if entries were removed, else an error code

fromall As Integer True to remove from all windows, False for just one

imgid As Integer id of the image to be removed

hwnd As Integer if fromall is False, window to remove from, else ignored

DESCRIPTION

This function removes one or more entries from windows’ paint lists. Given an image id, it will remove all occurrences of that image in one or all windows. Specify fromall as True to remove the image from all windows’ paint lists. Specify fromall as False and the hWnd of the window to remove the image from if you only want it removed from one window.

RETURNS

SUCCESS if the operation successfully removed the specified entries. Otherwise, one of the following:

  • HWNDNOTFND no paint list exists for the specified window
  • IDNOTFND no entry with the specified image id was found
  • HWNDDEL the paint entry was removed, and there are no more remaining paint entries for the specified window

rmventidrect

NAME

rmventidrect — removes entries from one or more windows’ paint lists, by image id and rectangle

SYNOPSIS

Code Block
result = rmventidrect(fromall, imgid, imgrect, hwnd)

result As Integer SUCCESS if entries were removed, else an error code

fromall As Integer True to remove from all windows, False for just one

imgid As Integer id of the image to be removed

imgrect As RECT rectangle of image to be removed

hwnd As Integer if fromall is False, window to remove from, else ignored

DESCRIPTION

This function removes one or more entries from windows’ paint lists. Given an image id and a rectangle, it will remove all occurrences of that image in that rectangle in one or all windows. Specify fromall as True to remove the image from all windows’ paint lists. Specify fromall as False and the hWnd of the window to remove the image from if you only want it removed from one window. This function is the same as rmventid() except that it’s more specific in handling images displayed at particular locations.

RETURNS

SUCCESS if the operation successfully removed the specified entries. Otherwise, one of the following:

  • HWNDNOTFND no paint list exists for the specified window
  • IDRECTNOTFND no entry with the specified image id and rectangle was found
  • HWNDDEL the paint entry was removed, and there are no more remaining paint entries for the specified window

rmventnum

NAME

rmventnum — removes entry from a window’s paint list, by entry index

SYNOPSIS

Code Block
result = rmventnum(entidx, hwnd)

result As Integer SUCCESS if the entry was removed, else an error code

entidx As Integer 0-based index of paint entry to remove

hwnd As Integer hWnd of the window to remove from

DESCRIPTION

This function removes a paint entry from a window’s paint list. Just pass in the index (0-based) of the entry to remove and the hWnd of the window to remove it from. See the pntlst() function for getting the paint list for a specific window. A list returned from pntlst() would generally be used to find the index of a paint entry to remove.

RETURNS

SUCCESS if the operation successfully removed the paint entry. Otherwise, one of the following:

  • HWNDNOTFND no paint list exists for the specified window
  • INVENTNUM no entry with specified index exists in the paint list
  • HWNDDEL the paint entry was removed, and there are no more remaining paint entries for the specified window

paintimgbkgd

NAME

paintimgbkgd — paints an image to a window, behind any others

SYNOPSIS

Code Block
painted = paintimgbkgd(hwnd, imgid, destrect, result)

painted As Integer True if image was successfully painted, False otherwise

hwnd As Integer hWnd of the window (form, picture box, etc.) to paint to

imgid As Integer image id of the image to paint

destrect As RECT destination rectangle to paint to (in pixels)

result As Integer if the function fails, this contains an error code

DESCRIPTION

This function is exactly the same as paintimg() except that it paints the image behind any others already painted. It puts this image, if successfully painted, first in the window’s paint list. See paintimg() for full details.

CAUTIONS

See paintimg() for cautions.

RETURNS

See paintimg() for return values.

Shared Support Files

Applies to: WG1-3.x (client side: C/S, WGM)

Covered, with the server-side installation rules, under "Shared support files" in Chapter 3.

Toolbars

In our never-ending battle to keep the overall size of the client down, we’ve created a VB API for supporting standard toolbars with bubble help (rather than using a .vbx). All of our baseline apps that have toolbars use this API. Since you have the VB sources for those apps, check them out for good, working examples. Below is a brief description of the API.

...

See the Registry app’s sources for a simple example of this API in use. See the Message Center app’s sources for a more complex example (more toolbars and more buttons).

Launching Files

To launch a file, simply call launchfile() with the file to launch. Using the current user’s Windows file association for the file’s extension, the Main Menu app will launch the file (bringing it up in Excel if a .xls file, Word if a .doc file, etc.). If no association is set up, the user is asked to set one up on the spot.

...

Like many APIs, a lower level set of functions can be accessed if you’re writing an advanced app. Functions exist to see if a file association exists, ask the user to create a new association, read entries from the Windows Registration Database, etc. Normally, these are the sorts of behind-the-scenes magic that Main Menu is left to. If you’d like to investigate these lower level functions, check out the Main Menu sources and the functions it calls in gcspcli.bas and gcsfassc.bas.

Download Manager

The Download Manager API has been updated. There is now one universal Download Manager integrated into the Worldgroup Manager. Among other things, this allows non-MDI apps to make use of the Download Manager.

...

gcsdlm.bas contains these three routines as your app’s interface to the Download Manager:

Code Block
Function tagpath (ByVal filname as String) as String

Pass a default filename to this function and it brings up a file dialog (gcsfdlgd.frm) to allow the user to select a path and filename to download to. This is called automatically by tagsub() if dlpath is passed as "".

Code Block
Sub tagrmv (ByVal appid as String, ByVal locdpk as String, ByVal tagspec as String)

Pass the App-ID, local dynapak prefix, and tagspec to cause a file to be removed from the Download Manager.

Code Block
Sub tagsub (ByVal desc as String, ByVal appid as String, ByVal filpfx as String, ByVal locpfx As String, ByVal

tagspec As String, ByVal dlpath As String, ByVal recfname As String, ByVal later As Integer, ByVal launch As

Integer)

Pass all necessary information to the Download Manager so it can manage the downloading of a file from the server:

...

If your application wanted to cause a particular file to be downloaded from the File Libraries agent, say the file plotter.doc in the GRAPHICS Library, allowing the user to specify the destination directory, and you wanted to download now, launching the file after completion (usually, .doc files launch into Microsoft Word, if installed), you would call tagsub() with the following parameters:

Code Block
tagsub "PLOTTER.DOC", "MYAPPID", "sa=GALFIL;uf:download ", "sa=GALFIL;ul:fl ", "GRAPHICS PLOTTER.DOC", "", "PLOTTER.DOC", False, True

Given this tagspec for a File Libraries file of "GRAPHICS PLOTTER.DOC", the following dynapaks will be associated with a file:

Code Block
sa=GALFIL;ul:fl GRAPHICS PLOTTER.DOC

sa=GALFIL;uf:download GRAPHICS PLOTTER.DOC

The first dynapak is used by the Download Manager to keep track of the file locally. The second is used to actually download the file.

...

Applies to: WG1-3.x (client side: C/S, WGM)

Server side (forreal() and stsdpk() support in agents): see "Download Manager Support in Agents" in Chapter 5.

Virtual Terminal Mode

The Virtual Terminal Mode (VTM) API is the Worldgroup Major BBS equivalent of Windows NT’s console mode API. Some Worldgroup Major BBS apps will need to make use of a standard, ANSI terminal window to allow the user to interact. Doors is one of those apps in Worldgroup’s the Major BBS’s baseline package. Without dropping into terminal mode and running a terminal mode module, users in apps that use VTM (like Doors) can make use of a terminal window alongside other client/server apps.

...

Applies to: WG1-3.x (client side: C/S, WGM)

Agent side of VTM: see "Virtual Terminal Mode (Agent Side)" in Chapter 4.

Miscellaneous

Be very careful about the times and dates of client files. Released files with the same name but different time/date stamps will conflict on user’s hard drives, causing them to potentially re-download files needlessly when switching from system to system. Read through the Procedures for Proper Version Control section of the Client App Developer’s Guide very carefully. Follow those guidelines. Failure to do that results in lots of bug reports to Galacticomm due to files re-downloading when the user doesn’t think they should.

...

Only call posisave() after first calling posiload() or reporeg(). This was not clear in the Client App Developer’s Guide. You can call the new posiexist() function to find out whether a saved position currently exists for a particular form. Using the return value from posiexist(), you can determine whether you want to call posiload() or position the form initially yourself and call reporeg().

...

Previous: Major BBS v10: 19 X.25 Programming  |  Contents  |  Next: Major BBS v10: 21 Development Environment (Worldgroup 3.x)