CapeSoft Logo

CapeSoft NetTalk
Upgrading to NetTalk 8

Download Latest Version
Installed Version Latest Version

NetTalk Upgrade to NetTalk 8

Note: NetTalk Web Services requires xFiles version 2.86 or later

Introduction

This document works through the major changes between NetTalk 7and NetTalk 8. It is designed for users, currently experienced with NetTalk 7 to quickly identify and use the new features in NetTalk 8. It covers things that are likely to break when you upgrade your app, and instructions on how to correct the application to allow for a smooth upgrade. It also covers other new features which you may wish to make use of in your application.

Quick Bits

The goal of this section is a quick overview of things that have changed since NetTalk 7 which experienced NetTalk 7 users will want to know about. Since there are a few changes in NetTalk 8 which invalidate things that were true in NetTalk 7, and unlearning previously sound information and habits is hard, please pay particular attention to this section.

Clarion 5.5, 6 and 7 are no longer supported.

NetTalk 8 requires Clarion 8 or later.

PACKET and LOC:OPTIONS have changed, PacketLen removed

See here and here and here for more

Some p_Web Method names have been tweaked

Check for Orphaned Embeds in the WebHandler procedure

Changes Required to Convert your App from NetTalk 7 to NetTalk 8

All New Packet variable

The local variable called PACKET is now a StringTheory object, not a String. If you have set, or added to the Packet variable in your embed code, then that code will need to be slightly altered.

replace
packet = clip(packet) & 'whatever'
with
packet.append('whatever')

replace
packet = whatever
with
packet.SetValue('whatever')

While the first construction will result in an error (Cannot call procedure as function) the second construction above (packet = something) will not. In order to identify the places in your code where you may have this construction, you should
  1. Go to the Application Global Extensions, to the Activate NetTalk Web Server extension, Advanced tab and set the Packet Variable Name to something other than packet, like for example, pkt
  2. Compile the application. Only hand-code use of the Packet variable should result in errors. Replace the hand-code with the correct code as described above (using the new name you set in step 1.)
  3. When the app compiles cleanly then it is recommended (although not mandatory) that you go back to step 1, reset the variable name to Packet, and recompile again. On this pass through change pkt back to packet. This step is not strictly necessary, but will make supporting the app in the longer term much easier. We recommend taking a few minutes to do this.

The PacketLen variable has been deprecated

the PacketLen variable (generated by the templates) is no longer used, and has been removed. You can get the length of the packet, if necessary using packet.Length()

All New Loc:options variable

The local variable loc:options is now a StringTheory object, not a String. This means that if you have used this variable in your hand code, then your hand-code will need to change slightly. The biggest difference is that the SetOption method no longer returns the string. For example;

loc:options = p_web.SetOption(loc:options,'setting','value')

becomes

p_web.SetOption(loc:options,'setting','value')

While the first construction will result in an error (Cannot call procedure as function) the second construction above (loc:options = something) will not. In order to identify the places in your code where you may have this construction, you should
  1. Go to the Application Global Extensions, to the Activate NetTalk Web Server extension, Advanced tab and set the Options Variable Name to something other than loc:options, like for example, jOptions
  2. Compile the application. Only hand-code use of the loc:options variable should result in errors. Replace the hand-code with the correct code as described above (using the new name you set in step 1.)
  3. When the app compiles cleanly then it is recommended (although not mandatory) that you go back to step 1, reset the variable name to loc:options, and recompile again. On this pass through change jOptions back to loc:options. This step is not strictly necessary, but will make supporting the app in the longer term much easier. We recommend taking a few minutes to do this.

Web Server Log List Format Updated

More fields have been added to the LogQueue in the WebServer, so you need to do one of the following;
  1. Delete the Log Control Template, and add it back again OR
  2. Use the Format-List functionality in the Window Editor to map the columns to the items in the LogQueue structure OR
  3. Use the Window Source Editor, to replace the FORMAT() property of the LIST control to
    FORMAT('51L(2)|M~IP Address~@s30@28L(2)|M~Socket~@n7@28L(2)|M~Thread~@n3@51L(2)|M~Date~@D17B@36L(2)|M~Time~@T4B@1020L(2)|M~Description~@s255@')

_NoColon method renamed to NoColon

If you have used p_web._nocolon in your hand-code then replace it with p_web.NoColon. Check the WebHandler procedure for orphaned embeds.

File Methods have been renamed

The file methods _OpenFile, _CloseFile, _AddFile, _PrimeFile, _GetFile, _UpdateFile and _DeleteFile have been renamed to OpenFile, CloseFile, AddFile, PrimeFile, GetFile, UpdateFile and DeleteFile respectivly.
If you have used these in your hand-code then remove the leading _. Check the WebHandler procedure for orphaned embeds.

Note that it is perfectly ok for you to use normal ABC file handling methods in your own hand-code. The file methods are included in the class to cater for non-ABC programs. there is a slight performance gain when using the ABC file methods over the p_web methods.

SetProgress Method has changed

The SetProgress method now takes three parameters instead of two. If you have called SetProgress in your own code (as described in the Report documentation) then you will need to review that code to use the extra parameter. If you have used it in your code, then the compiler will generate an error

No Matching Prototype Available

Web Client

Structure Changes

Net:simpleSSLCertificateOptionsType

  • CARootFile, CertificateFile and PrivateKeyFile fields extended to bigger strings.
  • ServerName property Added

Net:SimplePacketType

  • SharedMemory property added
  • _Reserved property size reduced

Security

Equates for TLS1.1 and TLS1.2 added as possibilities for SSLMethod property.
Equate for all TLS (1.0, 1.1 and 1.2) added.
Equate for SSLv3, TLS 1.0, TLS1.1 and TLS 1.2 added.

Performance

Although unglamorous, a number of performance enhancements have been made. The following list contains some of the more important ones;

Shared Ram for Static File Downloads

RAM is one of the biggest constraints of the web server. A 32 bit program can only access, at most, 3 Gigs of memory. In NetTalk 7 static files are loaded into RAM before they are sent to the browser. In NetTalk 8 these memory blocks are shared, meaning that if the server is busy sending a (large) file to one browser, and another user requests the same file, then the second request can share the same file-in-memory as the first request.

Support for keep-alive

Support for the Keep-alive header has been added. This allows a connection between the browser and the server to be kept open for a small period of time after a request is made (and replied to.) This allows the browser to make another request, across the same connection if desired, which in turn is faster because it does not have to negotiate a new connection. This improvement is most applicable to SSL connections where the connection setup can take a bit of time.

Auto-Cache

NetTalk now caches small static files up to a maximum cache size. This improves delivery of common small static files, such as CSS, JS and Image files. You can adjust the size of the cache, and the maximum size of files being cached on the new WebServer Performance tab.

Various Code Optimizations

Web Services

Note: NetTalk Web Services requires xFiles version 2.86 or later

NetTalk 8 contains new templates for creating Web Services. That is discussed here.

Form

Maps

A new Form Field type called "Map" has been added. Maps consist of a base layer (for example a map or satellite image) provided by a Provider, combined with data from your database. Data can be expressed as "Markers" on the map, or it can be expressed as an "Area" on the map. A single map can contain multiple data sources.

You can read more about the Maps feature here.

YouTube

A new Form Field Type called "YouTube" has been added. This allows you to embed a YouTube video inside your application. All the Google options for an embedded video are exposed via the template interface.

The settings for the YouTube control are documented here.

Webcam

A new Form Field Type called "Webcam" has been added. This allows you to access the Webcam on the client machine (if the user gives you permission to do so.) This field uses the GetUserMedia API which is currently not available in some browsers.

The settings for the Webcam control are documented here.

External

A new Form Field Type called "External" has been added. This allows you to fetch data from a second server (called an Agent) and include that data on a web form.

The settings for the External control are documented here.

Procedure

Up to NetTalk 7 the Procedure form field type did not allow a Form to be embedded on a form. NetTalk 8 removes this restriction for a specific case.
A new template option Generate <FORM> tag has been added to MEMORY forms. If this is OFF then no <form> and </form> HTML tags will be generated, thus allowing this form to become includable on a parent form.

Start Button

Template option to make Start button trigger automatically when the form is opened.

Progress Bar

Browse

Export Button

Use of this feature requires xFiles version 2.86 or later. For more on xFiles see the CapeSoft Web Site.

An Export button has been added to browses. When this is clicked the server will create an Excel spreadsheet (as xml), based on the browse, and send it to the user. They can then open the file in Excel, save it locally and so on.

The button is declared globally (WebServer / Buttons) and can be activated or deactivated globally (WebServer / Defaults). You can include, or exclude the button locally as well.

Other

Wizard Changes

NetWebPage Changes

Reports

Using the Media control, and the new Progress Bar and Start button functionality, it is possible to include generated reports directly onto a form. The Example PDFReportRequiresEE (13) has been updated to reflect these new options. The Reports Documentation has also been updated to document how it is done.

Global WebServer Extension

Advanced Tab

  1. As mentioned above, you can set the name of the PACKET variable on the WebServer Global Extension. This is very useful to do to identify the use of PACKET in hand code (which may now be incorrect).
  2. New option on the Advanced tab to set the Maximum Threads limit.

Settings Moved

WebServer Procedure

Advanced Tab

  1. Combine Common Files, Serve Pre-compressed Files, Compress Static Files, Compress Dynamic Files and Auto-Check Cached Files have all been changed to an Expression instead of a checkbox. This allows these settings to be set at runtime using an INI field, or Settings field or whatever.

Garbage Collection

Files in the \web\reports folder which are dated before yesterday, are automatically deleted.

Updated Scripts

External JavaScript Updates

New p_web Properties and Methods

Properties

Property Description
ShortSOAPAction (String) contents of the SOAPAction header field, but with the Host name (if it exists) removed.
SOAPAction (String) contents of the SOAPAction header field
ServiceErrorQueue (&ServiceErrorQueueType) A queue which is populated with errors when a service method has been called.
WSDL (&NetWSDL) Pointer to a NetWSDL Class. Used when generating WSDL files.
xml (Long) Set to 1 (and p_web.GetValue('xml') is primed, if the incoming request has a content-type of text/xml or application/soap+xml


Methods

Method Description
AddServiceError Adds an entry to the ServiceErrorQueue
ClarionTimePicture (pic) Takes a Clarion time picture and returns an example string of that picture (like hh:mm)
CreateMapDiv  
CreateYouTube  
GetBrowseHash  
GetLatLng  
SetMapZoom  
SetMapDevIdOptions  
WrapOptions
Methods refactored to use StringTheory thus removing string length limitations: CreateHyperLink, CreateSelect, CreateMedia, CreateInput, CreateRadio, CreateTextArea

Examples

PDFReportRequiresEE (13)

Using the Media control, and the new Progress Bar and Start button functionality, it is possible to include generated reports directly onto a form. The Example PDFReportRequiresEE (13) has been updated to reflect these new options. The Reports Documentation has also been updated to document how it is done.

Media (74)

The Media (74) example has been updated to include YouTube videos on a Form, and as a child of a Browse.

Maps (76)

A new example, Maps (76) has been added. This shows the use of the MAP form field in various places in the application.

WebService (77)

A new example WebService (77) has been added. This contains several services, and multiple methods which acts as a demonstrator of several common WebService techniques. This example requires xFiles version 2.86 or later.

ExportRequiresXFiles (78)

A new example ExportRequiresXFiles (78) has been added. This requires xFiles, and demonstrates the ability to export a browse to an Excel spreadsheet.

Webcam (79)

A new example Webcam (79) has been added. This demonstrates the ability to use a webcam to take a photo of the user on a NetWebForm.

ExternalServer (80)

A new example ExternalServer (80) has been added. This demonstrates reading data from a second web server (called an AGENT) to provide information to the form. In this case the agent program reads in strings in a COM port (using WinEvent) and provides that to the web page. This has the effect of allowing local hardware (such as a barcode or prox-tag reader) to be attached to the client computer, and for the web page to access the information coming from that hardware.

The example is in two parts, the normal web80.app program, and an agent.app program that runs on the client machines, and accesses the client hardware. Note the settings tab on this app which allows you to set the COM port being read, and also the port number to run the agent on.
[End of this document]
Return to NetTalk Documentation Index