Date: 04-21-2017 Subject: RELEASE 9.9A Runtime Files These release notes pertain to the following programs or files: EMBEDINI 9.9A 21 Apr 2017 9,9,1,500 EMBEDINI64 9.9A 21 Apr 2017 9,9,1,500 HEXDUMP 9.9A 21 Apr 2017 9,9,1,500 HEXDUMP64 9.9A 21 Apr 2017 9,9,1,500 MAKECLI 9.9A 21 Apr 2017 9,9,1,500 MAKECON 9.9A 21 Apr 2017 9,9,1,500 MAKECONET 9.9A 21 Apr 2017 9,9,1,500 MAKEDEF 9.9A 21 Apr 2017 9,9,1,500 MAKEMFD 9.9A 21 Apr 2017 9,9,1,500 MANAGECE 9.9A 21 Apr 2017 9,9,1,500 OBJMATCH 9.9A 21 Apr 2017 9,9,1,500 OBJMATCH64 9.9A 21 Apr 2017 9,9,1,500 ODBCINST64 9.9A 21 Apr 2017 9,9,1,500 PLBCGI 9.9A 21 Apr 2017 9,9,1,500 PLBCLICON 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBCLIENT 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBCLINET 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBCON 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBCONET 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBDSIGN 9.9A 21 Apr 2017 9,9,1,500 PLBNET 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) PLBSERVE 9.9A 21 Apr 2017 9,9,1,500 (Processed Server) PLBSERVET 9.9A 21 Apr 2017 9,9,1,500 (Threaded Server) PLBWEBSRV 9.9A 21 Apr 2017 9,9,1,500 (Processed Server) PLBWEBSRVT 9.9A 21 Apr 2017 9,9,1,500 (Threaded Server) PLBWIN 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 6) SUNAAMDX 9.9A 21 Apr 2017 9,9,1,500 SUNAAMDX64 9.9A 21 Apr 2017 9,9,1,500 SETGUID 9.9A 21 Apr 2017 9,9,1,500 SUNINDEX 9.9A 21 Apr 2017 9,9,1,500 SUNINDEX64 9.9A 21 Apr 2017 9,9,1,500 SUNLS 9.9A 21 Apr 2017 9,9,1,500 SUNMOD 9.9A 21 Apr 2017 9,9,1,500 SUNMOD64 9.9A 21 Apr 2017 9,9,1,500 SUNSORT 9.9A 21 Apr 2017 9,9,1,500 SUNSORT64 9.9A 21 Apr 2017 9,9,1,500 WININST 9.9A 21 Apr 2017 9,9,1,500 PLBCLICON5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBCLIENT5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBCLINET5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBCON5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBCONET5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBNET5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) PLBWIN5 9.9A 21 Apr 2017 9,9,1,500 (ComCtl 5) ODSBAC32.DLL 9.9A 21 Apr 2017 ODSBAC64.DLL 9.9A 21 Apr 2017 SA_DLL32.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWADO.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWADO25.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWADO28.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWMSQL.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWODBC.DLL 9.9A 21 Apr 2017 9,9,1,500 SUNWSRV.DLL 9.9A 21 Apr 2017 9,9,1,500 DBGIFACE 9.9A 21 Apr 2017 PLBCMP 9.9A 21 Apr 2017 PLBDBUG 9.9A 21 Apr 2017 ADMEQU.INC 9.9A 21 Apr 2017 PLBEQU.INC 9.9A 21 Apr 2017 PLBMETH.INC 9.9A 21 Apr 2017 PLBCLI.ZIP 9.9A 21 Apr 2017 9,9,1,600 (ComCtl 6) PLBRUN.ZIP 9.9A 21 Apr 2017 9,9,1,600 (ComCtl 6) *============================================================================== Notes for some NEW Items: - PL/B Web Server Provides 'REST' API Interface. Documentation Available in 'pat99A.me'. - PL/B Web Server PANEL Object 'InnerHtml' Event support added. Documentation Available in 'pat99A.me'. - Enhanced jQuery Framework Support Documentation Available in 'pat99A.me'. 1) jQuery Events for all PWS and InnerHtml objects. 2) Access to jQuery properties, attributes, and values for all PWS and InnerHtml objects. - Enhanced PL/B Web Client Support Documentation Available in 'pat99A.me' and 'pat99A_webapp.me'. 1) QR Code Support for Configuration Setup 2) APP Beacons are supported except for a 'PlbWebCli' Windows App. 3) PL/B Client 'PlbWebCli' Windows App available in Microsoft Windows Store. *============================================================================== Notes for DOCUMENTATION: - In the PL/B Language Reference manual in the 'SETPROP' instruction section, make the following changes: 1. Change the instruction format as follows: (1) [label] SETPROP {object},{property}: [({index})][={value}][,{property}[={value}...]] (2) [label] SETPROP {object1},*{property}: [({index})][={value}][,*{property}[={value}...]] Where: {object1} Required. A previously created NETOBJECT, NETCONTROL, CONTROL, CONTAINER, AUTOMATION object, a pointer to any of these objects, or a COLLECTION that contains any of these objects. 2. Change the Note (1.) to read as follows: Note (1.) The {object} must have been previously defined and created. When using the format (1), the {object} can be any GUI object except for a NETOBJECT, NETCONTROL, CONTROL, CONTAINER, or AUTOMATION object. When using the format (2), the {object1} should be a NETOBJECT, NETCONTROL, CONTROL, CONTAINER, AUTOMATION, or a COLLECTON that contains these objects. 3. Change the Note (11.) to read as follows: Note (11.) Any properties available for a NETOBJECT are found in the class library description as specified by the CLASS identification string. All properties must be specified using the '*' syntax format (2) or a format as described under the NETOBJECT description notes. - In the PL/B Language Reference manual under the 'TYPE' instruction, make the following changes: A. Change the TYPE values table in Note (2.) to remove the following PLB Data Type items: 'PROFILE' 'EQUCMDLIN' 'EQUATE' 'RECORD' 'RECORDEF' B. Under the TYPE values table in Note (2.), add this statement. "The PLB data definitions 'EQUATE', 'PROFILE', 'RECORD', and 'RECORD DEFINITION' are ONLY used when compiling a PLB program. These data definitions CAN NOT be used as the {var} for the TYPE instruction because they DO NOT exist as data variables in the UDA of a PLB program." - In the PL/B Language Reference manual under the 'RECORD and RECORDEND' section, change the Notes as follows: Change Note (11.) to read as follows: 11. "A ROUTINE, LROUTINE, FUNCTION, or LFUNCTION expecting a pointer to a RECORD as a parameter must pass in a pointer to a RECORD. Attempting to call the routine using a RECORD variable will result in an F05 runtime error. In addition, the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION will not have any knowledge of the structure of the incoming RECORD." Change Note (12.) to read as follows: 12. "A pointer of this type can be used with any instruction that supports variable lists." - In the PL/B Language Reference manual, change the 'Index' link named '%RECORDLABLES' to be '%RECORDLABELS'. - In the PL/B Language Reference manual, modify the 'WINPOS Property' section to include the $MAXIMIZEWIDTH value in the Note (4.) table described as follows. 6 $MAXIMIZEWIDTH Windows OS program is same as $MAXIMIZE. PWS Server program maximizes the width and the height is ONLY initially set one time to the window creation height or the client browser viewport height depending on which height is larger. - In the PL/B Language Reference manual, modify the '*PDFDEFPRTNAME (SETMODE)' section keyword syntax to read as follows: *PDFDEFPRTNAME={ value } - In the PL/B Language Reference manual, modify the '*PDFDEFPRTMETRICS (SETMODE)' section keyword syntax to read as follows: *PDFDEFPRTMETRICS={ 0 | 1 } - In the PL/B Language Reference manual, change the 'PDF GETFILE and GETINFO Notes' section to include a new Note (5.) that reads as follows: Note the following: 5. When the 'GETINFO TYPE={font},,PRINTER=PFILE' instruction is execute where the PFILE is opened for the 'pdf:' device, the PL/B runtimes use the Windows OS Default printer to establish a 'Printer Device Context' which is used to retrieve the printer {font} metrics. In addition, if the SETMODE keywords named *PDFDEFPRTMETRICS and *PDFDEFPRTNAME are used, this 'GETINFO TYPE={font},,PRINTER=PFILE' instruction first attempts to use the Windows Printer specified by these SETMODE keywords to retrieve the printer {font} metrics. - In the PL/B Runtime Reference Manual, add the following Object error descriptions: O158 - An IMAGELIST is being used as a property {value} before it has been created. O159 - An invalid data variable type has been encountered for a GETPROP or SETPROP property {value}. - In the PL/B Language Reference manual, change the 'SaveXml Method (XDATA)' section first sentence to replace 'SaveJson' with 'SaveXml'. - In the PL/B Web Server manual, include a link for the 'PLBWEB_MSGCOMPRESS' keyword to allow access to the 'PLBWEB_MSGCOMPRESS Keyword' description page. - In the PL/B Web Server manual, add the following keyword to the 'Server Configuration Keywords': PLBWEB_HTTPTASK_DEBUG PLBWEB_HTTPTASK_DEBUG={on|off} This keyword enables\disables the collection of extended GPF\SEGV data to be reported in a '.gpf' file. By default this keyword is 'off' to avoid any possible performance impact. This keyword should ONLY be turned 'on' when actively trying to debug\resolve a difficult GPF\SEGV fault in the PWS Server. Note: 1. This keyword can be placed in the 'plbwebsrv.ini' {Environment] section. 2. This keyword is implemented to take immediate affect when any new client browser logon action occurs. Thus, this keyword can take affect without having to restart the PWS server. - In the PL/B Web Server manual, change the 'PLBWEB_LOG_HTTP Keyword' page description to include the following bit mask table items: Keyword Value Meaning LOG_ERROR 64 Log protocol error messages sent to client 0x40 browser. LOG_SYSERR 128 Log OS errors that occur when process protocol 0x80 messages. - In the PL/B Language Reference manual, change the 'SetWebStyle Method' example as follows: Change this statement: Panelx.SetWebStyle USING "background-color"="Red" To Read as follows: Panelx.SetWebStyle USING *CSSNAME="background-color": *STRVALUE="Red" - In the PL/B Language Reference manual, add the 'CgiString Method (RUNTIME)' to the 'Methods' link for the RUNTIME object. - In the PL/B Language Reference manual, add a new Note (28.) to the COPYFILE instruction that reads as follows: "28. When using the PWS server, the COPYFILE instruction cannot be used to copy files directly to a client browser. See the CLIENT object method named 'Open' for information on downloading a file to a client browser." - In the PL/B Web Server reference manual, make the following change in the 'PL/B Web Client Installation' section: Change From: "Any requirements for the installation and configuration of a Sunbelt Web App will be determined at a later date." To Read: Android PlbWebCli App 1. Login to the Android 'Play Store' using your 'gmail' account. 2. Download and install the Sunbelt 'plbwebcli' APP. 3. Open and configured the newly installed 'PlbWebCli' App. See the following PDF document for more detailed information: "PlbWebCli_Android_QuickStart.pdf" Windows PlbWebCli App 1. Login to the Microsoft 'Windows Store' using your Microsoft account. 2. Download and install the Sunbelt 'plbwebcli' APP. 3. Open and configured the newly installed 'PlbWebCli' App. See the following PDF document for more detailed information: "PlbWebCli_Windows_QuickStart.pdf" *============================================================================== The following files have been changed as noted: ------------------------------------------------------------------------------- All Sunbelt Products - All Sunbelt products changed for 2017 CopyRight. ------------------------------------------------------------------------------- PLBWEBSRV (HTML\JS\CSS) - Modified to support 9.9A changes. plbwebbasic.css 9.9Ac 170228 plbwebbasic.js 9.9Ac 170302 plbwebctls.js 9.9Ac 170302 plbwebtvcssinfo.html 9.9 161028 plbwebstart.html 9.9A 170228 - Modified 'plbwebbasic.js' to work around a problem where a 'selectall' operation for a PWS EDITTEXT would cause a 'focus' change using an 'Internet Explorer' or 'Safari' client browser. This unexpected 'focus' change for the 'selectall' DID NOT occur using the 'FireFox', 'Chrome', and 'Edge' client browsers. ------------------------------------------------------------------------------- PLBWEBSRV (Linux\Unix) - The Linux\Unix PWS servers have been modified to use 'processes' instead of 'threads' when interfacing with child program runtime processes. This change is being done to minimize memory conflicts between the various PWS tasks that are executing. Note: 1. By changing over to use 'fork' interface processes, any one interface process can 'crash' without impacting the PWS main logon process. 2. With this PWS change, there are ONLY two threads used by the PWS main login process and all other PWS tasks are being performed by OS processes. - Correct a problem where the PWS interface processes were not generating the '.gpf' file when a Linux\Unix SIGSEGV signal occurred. ------------------------------------------------------------------------------- PLBWEBSRV (Windows) - Modified the PWS memory usage for the http threads to support a separate memory heap for each thread. This change helps to avoid any memory usage conflicts between the http threads. ------------------------------------------------------------------------------- PLBWEBSRV - The following PL/B methods have been added for all PWS GUI objects: EnableJqEvent This PWS object method is executed to enable a specific jQuery event by name for the client browser HTML object. Note, that the EVENTREGISTER instruction must be executed to register the PL/B event number 200 ( $JQueryEvent ) for the PWS object. See the EVENTREGISTER instruction for more details. See Sample Program 'DemoMbJq.zip'. DisableJqEvent This PWS object method is executed to disable a specific jQuery event by name for the client browser HTML object. See Sample Program 'DemoMbJq.zip'. ............................................................... . EnableJqEvent Method for All PWS Objects . The EnableJqEvent method can be used to enable one or more jQuery events by name for the PWS GUI object. This method must be used along with the EVENTREGISTER event number 200 ( $JQueryEvent ) before the jQuery events can be generated and dispatched to a PL/B routine to be processed. See the following link for more information on available jQuery Events: http://api.jquery.com/category/events/ NOTE: This is an advanced method that is required only when custom coding is performed using the JQuery framework. The method uses the following format: [label] {object}.EnableJqEvent GIVING {return}: USING [*EVENTS=]{jqevents}[: [*SELECTOR=]{selector}][: [*FLAGS=]{flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS GUI object that has been previously Required declared. {return} is a Numeric Variable that always returns the value of zero. {jqevents} is a Character String Variable or string Required literal that specifies one or more jQuery event names to be enabled for the HTML object rendered for the PWS {object}. {selector} Optional is a Character String Variable or string literal that contains selection criteria that is used to select all HTML objects that match the criteria. If this parameter is not specified, the id of the PWS {object} is used for the selector criteria. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the behaviors of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is always set to TRUE because the {return} value is always zero. 2. The OVER flag is set to TRUE if the {return} variable is too small to receive the numeric result. 3. The EVENTREGISTER instruction must be executed to register the $JQueryEvent ( event number 200 ) for the {object} PWS object. See EVENTREGISTER for more details. 4. The EnableJqEvent method uses the {jqevents} and {selector} parameters to invoke the jQuery '.on' method as described at this URL link: http://api.jquery.com/on/ 5. The {jqevents} is a Character string that contains one or more jQuery events separated by whitespace characters. The jQuery events as described at this URL link: http://api.jquery.com/category/events/ 6. The {selector} Character string is a filter to determine which HTML element(s} have the jQuery event(s) enabled. If the {selector} parameter is not specified, the 'id' of the PWS {object} is used for the selector. If the {selector} is specified, the {jqevents} are enabled for all HTML objects matching the selector. The {selector} Character string is passed exactly as specified to the jQuery '.on' method when the EnableJqEvent method is executed. Note, the jQuery events generated for any of the HTML objects matching the {selector} are sent to the $JQueryEvent ( 200 event number } registered for the PWS {object} executing this method. See this following URL link for more information for the {selector} criteria: http://api.jquery.com/category/selectors/ 7. The {flags} parameter is reserved for future use to control the behaviors of this method. Example Code: Panel1.EnableJqEvent Using "click" Panel1.EnableJqEvent Using "click","##zz1" EventReg Panel1,$JQueryEvent,JqEvPanel,ARG1=JsonData ... JqEvPanel EventInfo.LoadJson Using JsonData Display *WRAPON,JsonData Panel1.DisableJqEvent Using "click","##zz1" return Example Description: Panel1.EnableJqEvent Using "click" In this case, the {selector} defaults to use the HTML 'id' of Panel1. Therefore, if the user clicks on Panel1, an event to dispatched if the 200 ( $JQueryEvent ) event has been registered for Panel1. Panel1.EnableJqEvent Using "click","##zz1" In this case, the {selector} is specified as '#zz1' as the 'id' of one or more HTML object(s) on Panel1. Therefore, if the user clicks on a HTML object that matches the '#zz1' id, this causes an event to be dispatched when the 200 ( $JQueryEvent ) event has been registered for Panel1. EventReg Panel1,$JQueryEvent,JqEvPanel,ARG1=JsonData This EVENTREG instruction registers the $JQueryEvent (event number 200) to dispatch to the 'JqEvPanel' PLB routine where the event results of ARG1 are to be stored into the 'JsonData' DIM variable. ............................................................... . DisableJqEvent Method for All PWS Objects . The DisableJqEvent method can be used to disable one or more jQuery events by name for the PWS GUI object. See the following link for more information on available jQuery Events: http://api.jquery.com/category/events/ NOTE: This is an advanced method that is required only when custom coding is performed using the JQuery framework. The method uses the following format: [label] {object}.DisableJqEvent GIVING {return}: USING [*EVENTS=]{jqevents}[: [*SELECTOR=]{selector}][: [*FLAGS=]{flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS GUI object that has been previously Required declared. {return} is a Numeric Variable that always returns the value of zero. {jqevents} is a Character String Variable or string Required literal that specifies one or more jQuery event names to be disabled for the HTML object rendered for the PWS {object}. {selector} Optional is a Character String Variable or string literal that contains selection criteria that is used to select all HTML objects that match the criteria. If this parameter is not specified, the id of the PWS {object} is used for the selector criteria. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the behaviors of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is always set to TRUE because the {return} value is always zero. 2. The OVER flag is set to TRUE if the {return} variable is too small to receive the numeric result. 3. The DisableJqEvent method uses the {jqevents} and {selector} parameters to invoke the jQuery '.off' method as described at this URL link: http://api.jquery.com/off/ 4. The {jqevents} is a Character string that contains one or more jQuery events separated by whitespace characters. The jQuery events as described at this URL link: http://api.jquery.com/category/events/ 5. The {selector} Character string is a filter to determine which HTML element(s} have the jQuery event(s) disabled. If the {selector} parameter is not specified, the 'id' of the PWS {object} is used for the selector. If the {selector} is specified, the {jqevents} are disabled for all HTML objects matching the selector. The {selector} Character string is passed exactly as specified to the jQuery '.off' method when the DisableJqEvent method is executed. See this following URL link for more information for the {selector} criteria: http://api.jquery.com/category/selectors/ 6. The {flags} parameter is reserved for future use to control the behaviors of this method. Example Description: Panel1.DisableJqEvent Using "click" In this case, the {selector} defaults to use the HTML 'id' of Panel1 when disabling the jQuery event. Panel1.DisableJqEvent Using "click","##zz1" In this case, the {selector} is specified as '#zz1' as the 'id' of one or more HTML object(s) on Panel1 for which the jQuery event(s) is disabled. - The PL/B Web Server EVENTREGISTER instruction has been modified to support a new event number 200 ( $JQueryEvent ). The $JQueryEvent event can be registered for any PWS GUI object. However, the PL/B event 200 ( $JQueryEvent ) is not generated unless one or more jQuery Event(s) is enabled as follows: 1) All PWS GUI objects have a new method named 'EnableJqEvent' that can be executed to enable one or more jQuery Event(s) by name. See the description in the PL/B Language Reference manual under the section named 'EnableJqEvent Method'. 2) In addition, if the PWS GUI object is a PANEL, an alternative technique can be used to enable a specific jQuery Event. In this case, the jQuery Event can be included in the PANEL 'InnerHtml' method data string\stream by specifying the HTML attribute formatted as 'data-plbevent={eventnames}' for an HTML object. When the $JQueryEvent event is generated, the result is always returned as a string JSON object notation which is stored in ARG1. ARG1 contains a JSON object string for the event data that includes the follow: "type" = The text event name. See URL link: https://api.jquery.com/event.type/ "id" = The 'id' name of the HTML object which generated the event. "pageX" = The X relative mouse position. See URL link: https://api.jquery.com/event.pageX/ "pageY" = The Y relative mouse position. See URL link: https://api.jquery.com/event.pageY/ "metaKey" = Flag if meta key state when event occurred. See URL link: https://api.jquery.com/event.metaKey/ "which" = Which key value or mouse button caused the event. See URL link: https://api.jquery.com/event.which/ "target" = The currentTarget id value that generated the event. See URL link: http://www.w3schools.com/jsref/event_currenttarget.asp Example ARG1 JSON object string returned for jQuery event: {"type":"click","id":"sizzle","pageX":390,"pageY":96, "metaKey":false,"which":1,"target":"sizzle"} - The following PL/B methods have been added for the PWS CLIENT object: JqGet This PWS CLIENT method is an advanced method that allows direct access to client browser HTML element properties, css styles, values, text, or HTML contents of the first HTML element in the set of elements that matches the selector criteria. See Sample Program 'DemoMbJq.zip'. JqSet This PWS CLIENT method is an advanced method that allows client browser HTML element properties, css styles, values, text, or HTML contents of one or more HTML element(s) to be changed in the set of elements that matches the selector criteria. See Sample Program 'DemoMbJq.zip'. ............................................................... . JqGet Method for CLIENT Object . The JqGet method can be used to retrieve low level HTML element properties, css styles, values, text, or HTML contents from the client browser. The method gets the request data from the first HTML element of a set of elements matching selector criteria. NOTE: This is an advanced method that is required only when custom coding is performed using the JQuery framework. The method uses the following format: [label] {object}.JqGet GIVING {return}: USING [*SELECTOR=]{selector}: [*NAME=]{name}[: [*FLAGS=]{flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS CLIENT object that has been previously Required declared. {return} is a Character String Variable that returns a string from a HTML element depending on the {name} data type. {selector} Required is a Character String Variable or string literal that contains selection criteria that is used to select a set of HTML elements that match the criteria. The match set of elements can be one element or multiple elements depending on the selection criteria. {name} is a Character String Variable or string Required literal that identifies the type of data to be retrieved from the HTML element. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the behaviors of this method. Flags Affected: EOS Note the following: 1. The EOS flag is set if the returned data string is larger than the DIM variable used to receive the data. 2. The {selector} Character string is a filter to determine a set of HTML elements used for data retrieval. The {selector} string is sent to the jQuery API exactly the same as received from the PLB program variable. See this following URL link for more information for the {selector} criteria: http://api.jquery.com/category/selectors/ 3. The {name} is a Character string that identifies the type of data to be retrieved from the set of HTML elements matching the {selector} criteria. Depending on the {name} data type being retrieved, the data may come from the first HTML element in the set of elements or the returned data may be retrieved from all of the HTML elements in the element set. This element data access behavior can be determine from jQuery API documentation links found at: http://api.jquery.com The {name} parameter can be a pre-defined special name or it can be a HTML attribute, css, or property name for the HTML element being accessed. The pre-defined special name and the HTML attribute names are ONLY returned when the current {flags} value is set to zero (0). Special Comment See jQuery URL Link Html Html Contents http://api.jquery.com/html/ Text Text all elements http://api.jquery.com/text/ Val Current value http://api.jquery.com/val/ {attr} A valid jQuery http://api.jquery.com/attr/ Attribute name. If the {flags} is set to access CSS styles (value 0x0001) or to access HTML element properties (value 0x0002), the {name} gives the specific CSS or property name to retrieve. Css\Prop Comment See jQuery URL Link {cssname} A valid css http://api.jquery.com/css/ name for HTML element. {propname} A valid jQuery http://api.jquery.com/prop/ property name. 4. The {options} parameter is a bitmask value the forces specialized behaviors for the execution of this method.. The bitmask values are defined as follows: Options Value $JQ_FLAG_CSS EQU 1 When this bit is set, the {name} must be set to a valid CSS style name for the HTML element being accessed. See this URL link: http://api.jquery.com/css/ $JQ_FLAG_PROP EQU 2 When this bit is set, the {name} must be set to a valid property name for the HTML element being accessed. See this URL link: http://api.jquery.com/prop/ 4. The {return} string depends on the {name} data type being requested. Example: Client.JqGet Giving GetCss Using "##radio input:checked ~ label": "color", $JQ_FLAG_CSS In this example, the CSS style named "color" is retrieved from the first radio button checked. The GetCss variable returns a string as follows without including the (") characters: "rgb(255, 0, 0)" ............................................................... . JqSet Method for CLIENT Object . The JqSet method can be use to set low level HTML element properties, css styles, values, text, or HTML contents at the client browser. This method affects all of the HTML elements in the set of elements matching the selector criteria. NOTE: This is an advanced method that is required only when custom coding is performed using the JQuery framework. The method uses the following format: [label] {object}.JqSet GIVING {return}: USING [*SELECTOR=]{selector}: [*NAME=]{name}: [*VALUE=]{value}[: [*FLAGS=]{flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS CLIENT object that has been previously Required declared. {return} is a Numeric variable that always has a zero value returned. {selector} Required is a Character String Variable or string literal that contains selection criteria that is used to select a set of HTML elements that match the criteria. The match set of elements can be one element or multiple elements depending on the selection criteria. {name} is a Character String Variable or string Required literal that identifies the type of data to be changed in the set of HTML elements. {value} is a Character String Variable or string Required literal that has the value string applied to the {name} data type. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the behaviors of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is always set TRUE. 2. The OVER flag is always set FALSE. 3. The {selector} Character string is a filter to determine a set of HTML elements to be changed. The {selector} string is sent to the jQuery API exactly the same as received from the PLB program variable. See this following URL link for more information for the {selector} criteria: http://api.jquery.com/category/selectors/ 4. The {name} is a Character string that identifies the type of data to be changed in the set of HTML elements matching the {selector} criteria. The affected HTML elements may depend on the {name} data type. However, in most cases, the behavior is to affect all HTML elements in the set of elements matching the selection criteria. The {name} parameter can be a pre-defined special name or it can be a HTML attribute, css, or property name for the HTML element being accessed. The pre-defined special name and the HTML attribute names are ONLY used when the current {flags} value is set to zero (0). Special Comment See jQuery URL Link Html Html Contents http://api.jquery.com/html/ Text Text of elements http://api.jquery.com/text/ Val Current value http://api.jquery.com/val/ {attr} A valid jQuery http://api.jquery.com/attr/ Attribute name. If the {flags} is set to access CSS styles (value 0x0001) or to access HTML element properties (value 0x0002), the {name} gives the specific CSS or property name to be changed. Css\Prop Comment See jQuery URL Link {cssname} A valid css http://api.jquery.com/css/ name for HTML element. {propname} A valid jQuery http://api.jquery.com/prop/ property name. 4. The {options} parameter is a bitmask value the forces specialized behaviors for the execution of this method.. The bitmask values are defined as follows: Options Value $JQ_FLAG_CSS EQU 1 When this bit is set, the {name} must be set to a valid CSS style name for the HTML element being accessed. See this URL link: http://api.jquery.com/css/ $JQ_FLAG_PROP EQU 2 When this bit is set, the {name} must be set to a valid property name for the HTML element being accessed. See this URL link: http://api.jquery.com/prop/ Example: Client.JqSet Using "##radio label": //Labels with id=#radio "color": //Text color css style "##FF0000": //Red color $JQ_FLAG_CSS //CSS style type In this example, the CSS style named "color" is changed to be red for all HTML labels with the selector id of '#radio'. - PL/B Web Server has been modified to support events for the HTML objects rendered into a PWS PANEL object using the 'InnerHtml' method. See Sample Program 'DemoMbPanel.zip'. The *FLAGS parameter has been modified to include a new bit mask value defined as follows to allow HTML events. Value Meaning 0x1 Enable HTML events for any HTML objects in the InnerHtml {htmlpage} that has the HTML element data-plbevent='eventname' attribute defined. This flag is referenced as $HTML_HAS_EVENTS in the 'plbmeth.inc' definitions. Note (8.) added as follows: 8. The PWS PANEL {htmlpage} data string can include the 'data-plbevent={eventnames}' attribute for a HTML object that is being declared in the HTML page data string. When the 'data-plbevent' is being used, the HTML object events can be only occur as follows: a. The 'data-plbevent={eventnames}' must be declared for each HTML object which is to generate an event. Where: {eventnames} - This is a string of one or more javascript event names which must be separated by a whitespace character delimiter. See this URL Link for more information on events: https://developer.mozilla.org/en-US/docs/Web/Events b. The EVENTREGISTER must be executed to register the $JQueryEvent ( 200 event number ) event for the PANEL {object} executing the 'InnerHtml' method. The PANEL {object} $JQueryEvent routine receives all of the HTML events declared by the 'data-plbevent' in the 'InnerHtml' data string. The ARG1 contains a JSON objects string for the event data. See the EVENTREGISTER for more details on the $JQueryEvent. Example: HTML object sample with 'data-plbevent' declared: EventRegister Required: EventReg Panel1,$JQueryEvent,PanelEvent,ARG1=JsonData or EventReg Panel1,200,PanelEvent,ARG1=JsonData - The PL/B Web Client Apps for Android and iOS (not released yet) have been modified to support Beacons as following: Beacon Support: ...................................................................... . Overview: "The term iBeacon and Beacon are often used interchangeably. iBeacon is the name for Apple's technology standard, which allows Mobile Apps (running on both iOS and Android devices) to listen for signals from beacons in the physical world and react accordingly. In essence, iBeacon technology allows Mobile Apps to understand their position on a micro-local scale, and deliver hyper-contextual content to users based on location. The underlying communication technology is Bluetooth Low Energy." Quoted from: http://www.ibeacon.com/what-is-ibeacon-a-guide-to-beacons/ Also see: https://en.wikipedia.org/wiki/IBeacon Beacon Features: 1. Each Beacon transmits 3 pieces of information as follows: UUID This is a 16 byte string known as a universally unique identifier used to differentiate a large group of related beacons. Major This is a 2 byte value used to distinguish a smaller subset of beacons within the larger group. Minor This is a 2 byte value meant to identify individual beacons. 2. Beacon monitoring enables programs to detect movement in-and-out of range of the beacons 3. Beacon monitoring is limited to 20 regions and has different events to notify the listening app (and user) of entry/exit in the region. 4. Beacon ranging provides a list of beacons detected in a given region, along with the estimated distance from the user's device to each beacon. The distance (between transmitting iBeacon and receiving device) is categorized into 3 distinct ranges: a. Immediate - Within a few centimeters b. Near - Within a couple of meters c. Far - Greater than 10 meters away 5. Beacons are referenced by regions which consist of a program provided identifier, a UUID, a major number and a minor number. 6. The beacon support is provided by the following Cordova plugin: https://github.com/petermetz/cordova-plugin-ibeacon All beacon interactions and generated events are produced directly from this package. ...................................................................... . The following PL/B methods have been added for the CLIENT object: AppBeacon This PWS CLIENT object method is executed to perform specific Beacon operations that start or stop Beacon monitoring and range checking. Once a Beacon is started, the active Beacon can only be canceled using this method to stop the Beacon operations. Also, active Beacons cause events to be dispatched where ARG1 contains JSON string values with the Beacon event data. See Sample Program 'AppBeacon' in 'DemoAppMaster.zip'. AppBeaconStatus This PWS CLIENT object method is executed to determine the current beacon support available on the 'PlbWebCli' mobile device. When this method executes successfully, the AppEventBeaconStatus is generated where ARG1 contains a JSON string value. See Sample Program 'AppBeacon' in 'DemoAppMaster.zip'. ............................................................... . AppBeacon Method for PWS CLIENT Object . The AppBeacon method is used to start or stop specific Beacon actions. The specific actions for a Beacon are determined by the method parameters. Once a Beacon starts monitoring or ranging activities, these Beacon operations continue without being stopped until the AppBeacon method is executed to stop the Beacon actions. Also, note that a CHAIN does not cancel\stop the Beacon operations. However, after a CHAIN all Beacon events are ignored until the events are registered again using the EVENTREGISTER instruction. Note: 1. Beacon support is only available when using a 'PlbWebCli' client for an Android or iOS device. 2. The beacon support is provided using the Cordova plugin found at the following URL link: https://github.com/petermetz/cordova-plugin-ibeacon All beacon interactions and generated events are produced directly from this Cordova plugin package. The method uses the following format: [label] {object}.AppBeacon GIVING {return}[: USING [*ID=]{id}][: [*UUID=]{uuid}][: [*MAJOR=]{major}][: [*MINOR=]{minor}][: [*EVENTFREQ=]{eventfreq}][: [*FLAGS={flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS CLIENT object that has been previously Required declared. {return} is a Numeric Variable that always returns the pass or fail value.. {id} is a Character String Variable or string Optional literal that specifies Beacon region identifier provided by the PL/B program. If this parameter is not used, the default region identifier name of 'PlbWebCli' is used. {uuid} is a Character String Variable or string Optional literal that specifies the Beacon region UUID to match for. If this parameter is not specified, the default UUID string of "14A09BE4-B6B3-444F-93C8-B8A47EFB0447" is used to perform general actions for the mobile device only. {major} is a Numeric Variable or decimal number that Optional gives a region major number used to match for a specific Beacon. If this parameter is not specified, the default is to match for 'all' Beacon major values available. {minor} is a Numeric Variable or decimal number that Optional gives a region minor number used to match for a specific Beacon. If this parameter is not specified, the default is to match for 'all' Beacon minor values available. {eventfreq} is a Numeric Variable or decimal number that Optional gives the frequency in seconds between 'AppEventDidRangeBeaconsInRegion' events. If this parameter is not used, the default event frequency of 1 second is used. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the operations of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is set to be TRUE if the {return} value is zero indicating that the method execution was ok. Otherwise, the ZERO flag is set to be FALSE indicating that the method execution failed. 2. The OVER flag is set to TRUE if the {return} variable is too small to receive the numeric result. 3. Some operations performed by the 'AppBeacon' method are based on the four (4) method parameters of {id}, {uuid}, {major}, and {minor} which are used to specify a region(s) to either monitor or range. These parameters are only needed when the {flags} parameter value is set to perform on of these actions: AppBeaconMonitorStart AppBeaconMonitorStop AppBeaconRangeStart AppBeaconRangeStop The method parameters are used as follows: a. The {id} parameter allows the PL/B program to specify a program name as an identifier for a Beacon region. If this parameter is not specified, the default name of 'PlbWebCli' is used. b. The {uuid} parameter allows the PL/B program to specify the unique UUID of a Beacon region to find and perform the {flags} action against. c. The {major} parameter allows the PL/B program to specify the MAJOR number of a Beacon region(s) to find and perform the {flags} action against. If this parameter is not specified, the default is to match for 'all' Beacon major values available. d. The {minor} parameter allows the PL/B program to specify the MINOR number of a Beacon region(s) to find and perform the {flags} action against. If this parameter is not specified, the default is to match for 'all' Beacon minor values available. 4. The {eventfreq} parameter is only used to determine the frequency in seconds between Beacon range events of the 'AppEventDidRangeBeaconsInRegion' event. If this parameter is not used, the default event frequency of 1 second is used. When Beacan range checking is turned on, the Cordova plugin continually generates and reports the range event. The {eventfreq} parameter can be used by the PL/B program to throttle\control the number of range events that are passed to the PL/B range checking logic in a specific time frame. 5. The {flags} parameter is numeric value where the combination of the bit mask values can be used to perform Beacon action(s) applied to a Beacon region. The {flags} action bit mask values are defined as follows: AppBeaconMonitorStart EQU 1 //0x0001 Starts monitoring for a specific region identified by {id}, {uuid}, {major}, and {minor}. This {flags} action can generate the following events: AppEventDidStartMonitoringForRegion AppEventMonitoringDidFailForRegionWithError AppEventDidExitRegion AppEventDidEnterRegion AppBeaconMonitorStop EQU 2 //0x0002 Stop monitoring the a specific region identified by {id}, {uuid}, {major}, and {minor}. AppBeaconMonitorStopAll EQU 256 //0x0100 Stop monitoring all regions. AppBeaconRangeStart EQU 4 //0x0004 Start range checking for a specific beacon region identified by {id}, {uuid}, {major}, and {minor}. This {flags} action can generate the following event: AppEventDidRangeBeaconsInRegion AppBeaconRangeStop EQU 8 //0x0008 Stop range checing the specific beacon region identified by {id}, {uuid}, {major}, and {minor}. AppBeaconRangeStopAll EQU 512 //0x0200 Stop range checking for all beacon regions. AppBeaconBlueToothEnable EQU 16 //0x0010 Enables Bluetooth on mobile device. (ANDROID ONLY) AppBeaconBlueToothDisable EQU 32 //0x0020 Disables Bluetooth on mobile device. (ANDROID ONLY) AppBeaconRequestWhenInUseAuthorization EQU 64 //0x0040 Request access to locate beacons when application is running. (iOS ONLY) AppBeaconRequestAlwaysAuthorization EQU 128 //0x0080 Request access to locate beacons for application, even when not running. (iOS ONLY) 6. Once a beacon is monitored or ranged, scanning is not be canceled by a CHAIN operation. Only a Beacon stop or stop all operation terminates the scanning. 7. The {return} value is either a 0 when the method executes OK. Otherwise, the {return} value is an error value as follows: AppErrorNone EQU 0 //No Error AppErrorNoCordovaSupport EQU 1 - Error action not supported by Cordova. AppErrorWithExtendedInfo EQU 2 - Error with extended information. See CLIENT method named 'AppExtendedError'. 8. The 'AppBeacon' method actions implemented by the Cordova plugin cause various events to occur. The events documented for specific 'AppBeacon' method actions under the {flags} parameter must be registered in the PL/B program using the EVENTREGISTER instruction. The results of the Beacon generated events are stored in the EVENTREGISTER ARG1 variable. The ARG1 Beacon event data is returned as a JSON string for the data provided by the Cordova event operations and determined by vendor Beacon settings. The event numbers used to register the Beacon events using EVENTREGISTER are defined as follows: AppEventDidStartMonitoringForRegion EQU 121 AppEventDidRangeBeaconsInRegion EQU 122 AppEventMonitoringDidFailForRegionWithError EQU 123 AppEventDidExitRegion EQU 124 AppEventDidEnterRegion EQU 125 AppEventBeaconStatus EQU 126 Sample Beacon event data is: The general meaning of JSON tags: accuracy - Estimated distend in meters to 2 decimal places. proximity - A string containing one of: ProximityUnknown Beacon proximity is unknown. ProximityImmediate Beacon proximity is half a meter or less. ProximityNear Beacon proximity is 4 meters of less. ProximityFar Beacon proximity is greater than 4 meters. rssi - Received signal strength indication tx - Indicates what the expected signal level should be when you are one meter away. AppEventDidStartMonitoringForRegion { "region": { "typeName": "BeaconRegion", "minor": 9770, "major": 16100, "identifier": "Mint", "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D" }, "eventType": "didStartMonitoringForRegion" } AppEventDidRangeBeaconsInRegion Sample JSON string for NO Beacons. { "region": { "typeName": "BeaconRegion", "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D", "identifier": "Estimote" }, "eventType": "didRangeBeaconsInRegion", "beacons": [] } --- Android --- Sample JSON string for 2 Beacons using Android. { "eventType": "didRangeBeaconsInRegion", "region": { "identifier": "Estimote", "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d", "typeName": "BeaconRegion" }, "beacons": [ { "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d", "major": "47441", "minor": "40095", "proximity": "ProximityImmediate", "rssi": -51, "tx": -72, "accuracy": 0.030000 }, { "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d", "major": "62676", "minor": "6136", "proximity": "ProximityImmediate", "rssi": -58, "tx": -72, "accuracy": 0.100000 }] } --- IOS ---- Sample JSON string for 3 Beacons using iOS. { "region": { "typeName": "BeaconRegion", "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D", "identifier": "Estimote" }, "eventType": "didRangeBeaconsInRegion", "beacons": [ { "minor": 6136, "rssi": -72, "major": 62676, "proximity": "ProximityNear", "accuracy": 1.150000, "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D" }, { "minor": 40095, "rssi": -74, "major": 47441, "proximity": "ProximityNear", "accuracy": 1.200000, "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D" }, { "minor": 9770, "rssi": -80, "major": 16100, "proximity": "ProximityNear", "accuracy": 2.340000, "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D" }] } AppEventMonitoringDidFailForRegionWithError { "region": { "typeName": "BeaconRegion", "minor": 9770, "major": 16100, "identifier": "Mint", "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D" }, "eventType": "monitoringDidFailForRegionWithError", "error": "Error Domain=kCLErrorDomain Code=4 \"(null)\"" } AppEventDidExitRegion { "eventType": "didExitRegion", "region": { "identifier": "Mint", "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d", "major": "16100", "minor": "9770", "typeName": "BeaconRegion" } } AppEventDidEnterRegion { "eventType": "didEnterRegion", "region": { "identifier": "Mint", "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d", "major": "16100", "minor": "9770", "typeName": "BeaconRegion" } } 9. Example Code: .Setup for beacon interaction Client.AppBeacon Giving Result: Using *FLAGS=(AppBeaconRequestWhenInUseAuthorization+: AppBeaconBlueToothEnable) .Clear all beacon monitoring and ranging: Client.AppBeacon Giving Result: Using *FLAGS=(AppBeaconMonitorStopAll+: AppBeaconRangeStopAll) .Monitor one beacon region: EventReg Client: AppEventDidStartMonitoringForRegion: Event2: ARG1=BeaconEventData EventReg Client: AppEventMonitoringDidFailForRegionWithError: Event2: ARG1=BeaconEventData EventReg Client: AppEventDidExitRegion: Event2: ARG1=BeaconEventData EventReg Client: AppEventDidEnterRegion: Event2: ARG1=BeaconEventData Client.AppBeacon Giving Result: Using "Mint": "B9407F30-F5F8-466E-AFF9-25556B57FE6D": 16100,9770: *FLAGS=AppBeaconMonitorStart .Range beacon regions based on uuid: BeaconUUID Init "B9407F30-F5F8-466E-AFF9-25556B57FE6D" EventReg Client: AppEventDidRangeBeaconsInRegion: Event2: ARG1=BeaconEventData Client.AppBeacon Giving Result: Using "Estimote": BeaconUUID: *FLAGS=AppBeaconRangeStart ............................................................... . AppBeaconStatus Method for PWS CLIENT Object . The AppBeaconStatus method is used to retrieve the status of beacon capabilities for a mobile device. The requested status information is returned to the PL/B program as a JSON string in the ARG1 result variable for an event named 'AppEventBeaconStatus'. Therefore, EVENTREGISTER instruction must be executed to register the 'AppEventBeaconStatus' event before this method is executed. Note: 1. Beacon support is only available when using a 'PlbWebCli' client for an Android or iOS device. 2. The beacon support is provided using the Cordova plugin found at the following URL link: https://github.com/petermetz/cordova-plugin-ibeacon All beacon interactions and generated events are produced directly from this Cordova plugin package. The method uses the following format: [label] {object}.AppBeaconStatus GIVING {return}[: USING [*FLAGS=]{flags}] Where: {label} is an optional Program Execution Label. {object} is a PWS CLIENT object that has been previously Required declared. {return} is a Numeric Variable that always returns the pass or fail value.. {flags} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the operations of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is set to be TRUE if the {return} value is zero indicating that the method execution was ok. Otherwise, the ZERO flag is set to be FALSE indicating that the method execution failed. 2. The OVER flag is set to TRUE if the {return} variable is too small to receive the numeric result. 3. The {return} value is either a 0 when the method executes OK. Otherwise, the {return} value is an error value as follows: AppErrorNone EQU 0 //No Error AppErrorNoCordovaSupport EQU 1 - Error occurred because operation is not supported by Cordova. AppErrorWithExtendedInfo EQU 2 - Error with extended information. See CLIENT method named 'AppExtendedError'. 4. The {flags} parameter is numeric value reserved for future bit mask values to control the behaviors of this method. 5. The 'AppBeaconStatus' method operation is performed by the Cordova plugin. The resulting data is returned to the PL/B program as an event named 'AppEventBeaconStatus' which must be registered using an EVENTREGISTER instruction before this method is executed. The resulting data is stored as a JSON string value in the ARG1 result variable. The event number used to register the Beacon status event using EVENTREGISTER is defined as follows: AppEventBeaconStatus EQU 126 The ARG1 JSON string result fields are defined as follows: JSON Field Name isBluetoothEnabled - boolean and valid for Android only isRangingAvailable - boolean (can AppBeaconRangeStart be used) getAuthorizationStatus - object with one field authorizationStatus - string value (eg AuthorizationStatusAuthorized) Sample Event JSON string data: { "isBluetoothEnabled": true, "isRangingAvailable": true, "getAuthorizationStatus": { "authorizationStatus": "AuthorizationStatusAuthorized" } } Example: EventReg Client: AppEventBeaconStatus: Event2: ARG1=BeaconEventData Client.AppBeaconStatus - Added a new keyword named 'PLBWEB_HTTPTASK_DEBUG={on|off}' for the PWS Server. When this keyword is included in the PWS INI [Environment] section and set to be 'on', the PWS collects\maintains data for the PWS tasks which gives extended details when a GPF\SEGV fault occurs. This extended data is included in a '.gpf' file which is created when a fault occurs. Note: The PWS Server DOES NOT have to be restarted when the 'PLBWEB_HTTPTASK_DEBUG' state is reset. - The PWS Server memory usage has been modified to avoid any possible memory buffer overflows that could result in GPF or SEGV behaviors. In addition, changes have been made to allow improved debugging data to be collected to diagnose memory\buffer usage. - The PWS Server has been modified to provide a WEB API interface based on the REST (Representational State Transfer) technology. The REST in the PWS Server provides PLB Web Developers with the framework, infrastructure, and PLB language constructs to implement Web REST APIs accessible from any Web application. The RESTful Web Services provides an interface that is lightweight, maintainable, and scalable that gives the PLB Web Developer a design environment with access to the PLBWIN, PLBNET, and PLB (Unix) runtimes to execute PL/B programs. For more information and tutorials on the REST technology, see the following links: http://www.drdobbs.com/web-development/restful-web-services-a-tutorial/ 240169069 This link provides a good overview of the RESTful Web Services concept\technology. This is a good starting point for the PL/B Web Developer that has an interest in proving a REST Web Service using the PL/B Web Server. http://www.restapitutorial.com/ This link gives a tutorial perspective on 'what is REST?'. This tutorial gives information that can help reinforce expected standards and rules required a REST Web Service. The PL/B REST support provided by the PL/B Web Server is described as follows: ******************************************* OVERVIEW (PL/B REST Support) What is REST? Representational state transfer (REST) or RESTful web services are one way of providing interoperability between a PL/B Web Server (PWS) and generic web clients. In a REST web service, requests made to a resource's URL will elicit a response that may be in XML, HTML, JSON. The PWS Server can be configured to detect a specific base URL and execute a PL/B program using a PLBWIN, PLBNET, or PLB (Unix) runtime. This program uses the RUNTIME object 'CgiString' method operations to obtain information about a request. The program can return the response to a web client using the RUNTIME object 'HttpResponse' method or using the PL/B STREAM instruction. If the PL/B program is terminated without giving a response, a default HTTP response with an HTTP status code of 500 (internal error) is returned to the web client. REST Reference Web Sites for information on REST services. http://www.drdobbs.com/web-development/ restful-web-services-a-tutorial/240169069 http://www.restapitutorial.com/ REST Sample Code and Test Tools 1. Phonemsg.pls Sample Program A sample program named 'phonemsg.pls' is available in your PWS programs directory. When the PWS server is configured to provide the PL/B REST 'MyServices/' service, the PWS executes the 'phonemsg.plc' program when the input url from a web client specifies the segments as 'MyServices/phonemsg'. PLBWIN INI Configuration Keyword: PLB_CGI_DIR=c:\mypath\mycgi\z PLBWEBSRV INI Configuration Minimum Keywords: PLBWEB_CGI_INFODIR=c:\mypath\mycgi\z PLBWEB_REST_BASEURL01=MyServices/ PLBWEB_REST_CMDLINE01=plbwin.exe -h %s %s 2. Restcli Html Web Pages created using Dreamweaver Project Sample HTML web pages have been generated using the Dreamweaver Project which can be used to access a PWS server configured to support the PL/B RESET 'MyServices/' service. These HTML pages utilize JavaScript functions which interface with the PWS REST service. The sample HTML, JavaScript, and CSS files are provided as follows: restsupp.css restsupp.js restentry.html restmain.html restquery.html Note: 2a. The end-user MUST modify the 'restsupp.js' file variable named 'commAddr' to provide the URL\IP address and port of the PWS server being accessed. var commAddr = "http://192.168.1.12:8081/MyServices/phonemsg"; 3. Also note, the Chrome browser and the ARC (Advanced Rest Client) App can be used in the evaluation and testing of a REST service implemented by a PL/B developer. 4. See 'DemoRestApi.zip' for RestApi Demo Programs. ******************************************* PL/B Web Server Configuration Keywords The PL/B REST support allows up to 99 REST web services to be configured using the PWS keywords as follows: PLBWEB_REST_BASEURL Required PLBWEB_REST_CMDLINE Required PLBWEB_REST_AUTH_REALM Optional PLBWEB_REST_SSLnn Optional PLBWEB_REST_BASEURL=/ This keyword is required and is placed in the [Environment] section of the PWS configuration INI file. This keyword specifies the base URL used by a web application to access the PL/B REST web service. Where: - The 'nn' that is appended to the PWS keyword name and can be a string value from '01' to '99'. Example: PLBWEB_REST_BASEURL01=MyServices/ PLBWEB_REST_BASEURL99=SomeService/ - The assigned keyword string identifies the specific base URL string that must be used when accessing the PWS server. Example: PLBWEB_REST_BASEURL01=MyServices/ The URL used by the client browser web application would be submitted as follows: http://127.0.0.1:8081/MyServices/programname Where: 'MyServices/' identifies the PWS web service that is being accessed. 'programname' identifies the PL/B program to be executed at the PWS server. PLBWEB_REST_CMDLINE= %s %s This keyword is required and is placed in the [Environment] section of the PWS configuration INI file. This keyword specifies the command line to be formatted and executed by the PWS when a PL/B REST service is found in a client browser URL. Where: 'nn' - The 'nn' that is appended to the PWS keyword name can be a string value from '01' to '99'. Example: PLBWEB_REST_CMDLINE01=plbwin -h %s %s PLBWEB_REST_CMDLINE02=c:\mydir\plbnet -i %s %s PLBWEB_REST_BASEURL99=plb -h %s %s - The identifies the PL/B runtime to be executed including 'plbwin', 'plbnet', or 'plb'. Also, the can be a fully path with the PL/B runtime executable. - This can be specified as any of the supported {options} found in the PL/B Runtime Reference manual under the command line option descriptions. %s - The '%s' strings must be specified in the keyword command line string as shown. 1. The first '%s' is replaced by the PWS server with '-cgi ' string when a PL/B RESET web service is detected in a URL. The is automatically created by the PWS server. 2. The second '%s' in the command line is replaced by the PWS server with the first segment following the base URL segment. All other segments after the second segment must be decoded in the PL/B program after retrieving the REQUEST_URL keyword data using the RUNTIME 'CgiString' method. Note, that a URL segment is the data between adjacent '/' characters in the URL. Example: URL received From Client Browser: http://192.168.1.12:8081/MyServices/phonemsg/search/Bill This is the URL as received from the client browser executing a web application accessing the PWS Server 'MyServices/' REST services to execute the 'phonemsg.plc' PL/B program. Where: 'MyServices' - is the PL/B REST service being accessed. 'phonemsg' - is the PL/B program executed. 'search/Bill' - is data available to the PL/B program using the RUNTIME 'CgiString' method with the REQUEST_URI keyword. Command Line formatted and executed by the PWS Server: plbwin -h -cgi phonemsg This is the command generated by the PWS server and executed with the following PWS REST keyword: PLBWEB_REST_CMDLINE01=plbwin -h %s %s PLBWEB_REST_AUTH_REALM= This keyword is optional and can be placed in the [Environment] section of the PWS configuration INI file. This keyword can be used to invoke basic authentication identifying the web client user. If there is no user/password supplied in the authentication header used to access the PWS REST service, a Http 401 response is sent back to the web client as follows: WWW-Authenticate: Basic realm= This causes a browser to bring up a username/password dialog and resubmit the Http request providing the user/password entered into the dialog. Where: 'nn' - The 'nn' that is appended to the PWS keyword name can be a string value from '01' to '99'. - This is the realm string that is shown in the username/password dialog by the client browser. Example: PLBWEB_REST_AUTH_REALM01=PL/B Services Note: 1. Using the PL/B RUNTIME method named 'CgiString', the CGI string for the AUTH_TYPE field keyword can be used to determine the authentication input data. 2. The user name sent can be found in the AUTH_USER or REMOTE_USER keyword CGI strings using the RUNTIME 'CgiString' method. 3. The full base64 username:password string can be found in the AUTH_DATA keyword CGI string using the RUNTIME 'CgiString' method. PLBWEB_REST_SSL= This keyword is optional and can be placed in the [Environment] section of the PWS configuration INI file. It controls the the type of protocol available when accessing the PWS REST service. Where: 'nn' - The 'nn' that is appended to the PWS keyword name can be a string value from '01' to '99'. - The parameter can be specified as 'ON', 'OFF', or 'BOTH' invoking the following PWS behaviors: ON - PL/B REST service is available using the HTTPS protocol. In this case, the PLBWEB_SSL_ADDRESS keyword must be configured to enable a PWS SSL listening socket. OFF - PL/B REST service is not available using the HTTPS protocol. BOTH - PL/B REST service is available using both the HTTP and HTTPS protocols. In this case, both the PLBWEB_ADDRESS and PLBWEB_SSL_ADDRESS keywords must be configured to provide socket listening sockets. Example: PLBWEB_REST_SSL01=BOTH ******************************************* PL/B Web Server CGI Information Generation The PLBWEB_CGI_INFODIR configuration keyword specifies the location of the temporary CGI files. These temporary CGI files are created by the PWS REST services when a web client REST request is accepted. These temporary CGI files are loaded into memory by the PL/B runtime specified in the 'PLBWEB_REST_CMDLINE' keyword configured for the REST service specified in the base URL. After a temporary CGI file is loaded by the PL/B runtime, it is immediately deleted before the REST PL/B program starts executing. The RESET PL/B program can use the RUNTIME 'CgiString' method to access the CGI data fields as needed to process the REST API request. The following keywords are an example of the CGI fields available to the REST PL/B program: GATEWAY_INTERFACE=CGI/1.1 AUTH_TYPE=None CONTENT_LENGTH=53 REMOTE_ADDR=192.168.1.12 REQUEST_METHOD=PUT REQUEST_URI=/MyServices/phonemsg/6 SCRIPT_NAME=/MyServices/phonemsg/6 SERVER_SOFTWARE=PlbWebSrv SERVER_PROTOCOL=HTTP/1.1 SERVER_PORT=8081 HTTP_HOST=192.168.1.12:8081 Note: 1. If CGI 'AUTH_TYPE' field is returned as 'Basic', then extra CGI keywords are available as follows: AUTH_USER=Bill REMOTE_USER=Bill AUTH_DATA= ******************************************* PL/B Language REST Support 1. The PL/B runtimes including 'plb' (Linux\Unix), 'plbwin', and 'plbnet' support a new command line option named '-cgi '. The 'cgi' runtime option is ONLY generated by a PWS server configured to support REST services. When the 'cgi' option is detected by the runtime, it causes the runtime to load the temporary CGI file and allows the RUNTIME 'CgiString' to access the REST CGI keyword fields. After the CGI data is loaded, the runtime deletes the temporary CGI file before the REST PL/B program starts executing. 2. The 'PLB_CGI_DIR=' keyword MUST be specified in the runtime INI [Environment] section and the assigned keyword string MUST match the 'PLBWEB_CGI_INFODIR' keyword string specified in the PWS INI file. 3. The PL/B XDATA data object can be used to create and decode JSON and XML data processed by the REST request and result strings. 4. Optionally, the PL/B STREAM instruction using *STDIN and *STDOUT can be used to get\send a HTTP POST, PUT, DELETE, and PATCH request. Note: 1. The 'STREAM *STDOUT' allows the PL/B REST program to send customized data to the REST client application. 2. When the PL/B REST program uses the 'STREAM *STDOUT' to output customized data, the RUNTIME 'HttpResponse' method MUST NOT be used. Otherwise, unexpected\indeterminate results can occur. 5. RUNTIME Object Method Changes for PL/B Runtimes The RUNTIME object for the PL/B runtimes 'plb', 'plbwin', and 'plbnet' (excluding PWS) has been modified to support the 'CgiString' and 'HttpResponse' methods as follows: ............................................................... . 'CgiString' REST API Support The RUNTIME 'CgiString' method can be used to access HTTP header fields that are submitted by a REST API. Note the following: 1. When a REST API request is accepted by a PWS server, the PWS server extracts the Http header data from the request and stores it into a CGI data file. In this case, the PWS server stores the CGI data into a file based on the PWS keyword named 'PLBWEB_CGI_INFODIR'. Also, the PWS server starts a PL/B runtime including the command line option '-cgi '. 2. When the PL/B runtime detects the new command line option named '-cgi ', the PL/B runtime preloads the data so the RUNTIME object 'CgiString' can access the CGI keyword data. The CGI keywords are the same as described for the 'CgiString' for a PWS server program. After the data is preloaded, the PL/B runtime deletes the temporary CGI file before the PL/B REST program starts executing. 3. Also, if CGI 'AUTH_TYPE' keyword has a returned string value of 'Basic', these CGI keywords are available with meaningful data: AUTH_USER REMOTE_USER AUTH_DATA ............................................................... . 'HttpResponse' REST API Support The RUNTIME object method named 'HttpResponse' is available to return the results of a REST API operation to the client browser that submitted the REST request. This method generates a HTTP response in HTTP 1.1 format. See the RUNTIME 'HttpResponse' method description found in the PL/B Language Reference manual for more details. The generated HTTP response includes the following header fields: 1) The HTTP 1.1 header is generated. "HTTP/1.1 {httpcode} \015\012" The {httpcode} value is specified by the RUNTIME 'HttpResponse' method. The is the expected text string associated with the {httpcode} value as follows: Http Code Value 200 OK 201 Created 202 Accepted 204 No Content 205 Reset Content 206 Partial Content 301 Moved Permanently 302 Found 303 See Other 304 Not Modified 400 Bad Request 401 Unauthorized 402 Payment Required 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 407 Proxy Authentication Required 408 Request Timeout 409 Conflict 410 Gone 411 Length Required 412 Precondition Failed 413 Payload Too Large 414 URI Too Long 415 Unsupported Media Type 416 Range Not Satisfiable 417 Expectation Failed 418 I'm a teapot 421 Misdirected Request 422 Unprocessable Entity 423 Locked 424 Failed Dependency 426 Upgrade Required 428 Precondition Required 429 Too Many Requests 431 Request Header Fields Too Large 451 Unavailable For Legal Reasons If the {httpcode} value is not one of the values in this table, then the default result will be a code of '500' with a text string of 'Internal Server Error' with a mime type of 'text/plain' and there is no body in the HTTP response message. 2) The connection header field is added as follows: "Connection: close\015\012" 3) By default, this header field is added to the response output unless the 'HttpResponse' {options} bit mask specifies the '0x0002' (Allow Cache Control). "Cache-Control: no-cache,no-store\015\012" The {options} '$HttpResp_AllowCacheControl' (0x0002) bitmask value can be used to exclude the output of this header field. 4) The content type header field is added as: "Content-Type: {mimetype>}\015\012" The {mimetype} value is specified by the RUNTIME 'HttpResponse' method. 5) By default 'Access-Control-Allow' HTTP headers are added to the response shown as follows: "Access-Control-Allow-Credentials: true\015\012" "Access-Control-Allow-Origin: *\015\012" "Access-Control-Allow-Headers: Content-Type\015\012" "Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE, PATCH, PUT\015\012" The {options} '$HttpResp_NoAccessControl' (0x0001) bitmask value can be used to exclude the output of these header fields. 6) All extra headers specified by the HttpResponse {extrahdrs} parameter are added at this point. 7) The content length is calculated for the {body} and added to the HTTP response message as follows: "Content-Length: nnnnn\015\012" 8) The HTTP 'end of header' "\015\012" is placed in the HTTP response message. 9) If the {body} content length is non-zero, the {body} data is added to the HTTP response exactly as provided by the user program. . ....HttpResponse End........................................... - Added a new keyword named 'PLBWEB_SSL_PROTOCOL={0|1|2|3}'. This keyword can be used to set the SSL minimum protocol version to be used. The keyword values are defined as follows: Value SSL Protocols Allowed are: 0 SSLv3, TLSv1.0, TLSv1.1, or TLSv1.2 1 (Default) TLSv1.0, TLS1.1, or TLSv1.2 2 TLSv1.1 or TLSv1.2 3 TLSv1.2 Note: If the 'PLBWEB_SSL_SELFSIGNED=ON' is being use in the 'plbwebsrv.ini' file, the PLBWEB_SSL_PROTOCOL keyword is ignored and the minimum SSL protocol version SSLv3 is used. - Modified to allow a PWS suspended child task to keep a Data Manager connection open until the child task is terminated. Keep in mind that a PWS child task is suspended when the client\browser stops communicating with the PWS server. This change is implemented to allow a 'Plbwebcli' client to continue executing a PLB program with a Data Manager connection after a mobile device awakes from an extended sleep state. - The PWS server has been modified to allow SSL accept logon operations to occur concurrently. This change is implemented to improve the performance and to support the new SSL IP blacklist operations. By default the PWS server allows up to 50 concurrent SSL logon threads. The new PLBWEB_SSL_ACCEPT_MAX keyword can be used to allow from 1 to 100 SSL logon threads. - Modified the PWS server to log the peer ip address of the client browser in the PWS server log file when an HTTPS logon error occurs. - Modified the PWS Server to support a new WINPOS property value named $MAXIMIZEWIDTH (value = 6) position mode. When the $MAXIMIZEWIDTH position mode is used for a PWS Server WINDOW object, the WIDTH of the WINDOW object is maximized while the height is initially set to the window creation height or the client browser viewport height depending on which height is larger. - Blacklist IP support has been added to the PWS server to close any logon socket that matches an IP address found in the current blacklist. The blacklist IP support is configured\implemented to support both non-SSL IP filtering and SSL socket operations. The basic blacklist operations are implemented: 1. Pre-load a blacklist file that defines a set of IP addresses to reject when immediately detected. This is available for both non-SSL and SSL blacklist support. 2. Monitor current blacklist IP addresses to reject and track accept logon attempts accessing the PWS server. 3. New PWS commands '-br', '-bd', and '-bl' have been added to manage the PWS blacklist operations. 4. The non-SSL support is ONLY enabled when the appropriate blacklist keywords named PLBWEB_BLACKLIST_FILE and PLBWEB_BLACKLIST_REPORT are declared in the 'plbwebsrv.ini' configuration file. 5. The SSL blacklist support is ALWAYS enabled to detect and monitor malicious SSL logon attempts which could disrupt PWS SSL logon operations. The new keywords named PLBWEB_SSL_BLACKLIST_FILE and PLBWEB_SSL_BLACKLIST_REPORT can be optionally used to allow the PWS administrator to define the blacklist files to be used. If these keywords are not used, the PWS uses default pre-defined blacklist file names. The SSL blacklist support dynamically detects SSL accept logons that take an excessive amount of time to perform the required SSL accept operations to finish the SSL connection. 6. These new keywords are now supported for the blacklist implementation. PLBWEB_BLACKLIST_FILE PLBWEB_BLACKLIST_REPORT PLBWEB_SSL_BLACKLIST_FILE PLBWEB_SSL_BLACKLIST_REPORT PLBWEB_SSL_ACCEPT_TIMEOUT PLBWEB_SSL_ACCEPT_MAX PLBWEB_SSL_LOCKOUT_MAX Please note the following: I. New 'plbwebsrv.exe' commands to manage\report blacklist operations: plbwebsrv -br (reset blacklist) This command causes the PWS server to clear all of the current blacklist data. See the 'non-SSL' and 'SSL' descriptions for specific details on the reset blacklist operation. plbwebsrv -bd (dump blacklist) This command causes the PWS server to dump the current PWS blacklist data into a dump file with the data format expected\used when pre-loading blacklist data. See the 'non-SSL' and 'SSL' descriptions for specific details on the dump blacklist operation. The data in the dump file has a format which is the same as expected when a blacklist is pre-loaded. The data format can be partial or exact IP addressing using this format: nnn.nnn.nnn.nnn //Exact IP address nnn.nnn.nnn. //Partial IP address nnn.nnn. //Partial IP address nnn. //Partial IP address Example: 112. 156.112. 192.168.1.22 192.168.1.23 192.168.1.5 plbwebsrv -bl (output a blacklist listing) This command causes the PWS server to output the current PWS blacklist data into a report\listing file. See the 'non-SSL' and 'SSL' descriptions for specific details on the listing blacklist operation. The data in the listing file has a format to give the blacklist IP address and the current usage count of the blacklist IP. The format is the listing output data is as follows: 1 Locked I/P Address 112. has 0 hits 2 Locked I/P Address 156.112. has 0 hits 3 Locked I/P Address 192.168.1.12 has 11 hits 4 Error I/P Address 192.168.1.22 has 2 hits 5 Locked I/P Address 192.168.1.23 has 0 hits 6 Locked I/P Address 192.168.1.5 has 0 hits Where: 'Locked' - Indicates that the IP address(s) are locked out and not allowed to make a connection to the PWS server. 'Error' - Indicates that the IP address(s) have caused a logon accept failure at least 1 time. However, the IP is not locked out. II. Blacklist for non-SSL socket accept operations: The non-SSL blacklist support is ONLY enabled when the PLBWEB_BLACKLIST_FILE keyword is declared in the 'plbwebsrv.ini' configuration file settings. If this keyword DOES NOT exist in the PWS INI, the PWS server DOES NOT enable non-SSL blacklist monitoring. When the non-SSL blacklist monitoring is enabled, the PWS performs the following operations: 1. The file specified by the PLBWEB_BLACKLIST_FILE keyword is used to pre-load a user defined IP blacklist when the PWS starts. If this keyword is not specified in 'plbwebsrv.ini' configuration, the PWS DOES NOT start\use the non-SSL IP blacklist filtering. If the PWS options '-br' or '-bd' is executed, this keyword file is used for non-SSL support. PLBWEB_BLACKLIST_FILE={[path]+filename} 2. The file specified by the PLBWEB_BLACKLIST_REPORT keyword is used to specified the output file that receives the non-ssl IP blacklist when the PWS command option '-bl' is executed. PLBWEB_BLACKLIST_REPORT={[path]+filename} 3. When a non-SSL logon occurs, the PWS matches the new accept logon peer IP to the current IP blacklist being used. If the new logon IP is found on the IP blacklist, the connection is immediately closed before any TCP\IP communications are attempted. 4. The new PWS command options '-br', '-bd', and '-bl' can be used to reset, dump, or list the current non-SSL blacklist IP addresses only when the PLBWEB_BLACKLIST_FILE and\or PLBWEB_BLACKLIST_REPORT keywords are used. Keywords: PLBWEB_BLACKLIST_FILE={[path]+filename] This keyword file specifies the filename used to pre-load the blacklist IP addresses used for non-SSL IP filtering. If this keyword is not used, the PWS DOES NOT perform any blacklist IP filtering. PLBWEB_BLACKLIST_REPORT={[path]+filename] This keyword file specifies the filename used to output the current non-SSL blacklist IP addresses being used for non-SSL IP filtering along with the usage\activity count for the IP. PWS commands used when PLBWEB_BLACKLIST_FILE and PLBWEB_BLACKLIST_REPORT keywords are used: plbwebsrv -br (reset blacklist) plbwebsrv -bd (dump blacklist) plbwebsrv -bl (output a blacklist report) III. Blacklist for SSL socket operations: The SSL blacklist support is ALWAYS enabled to detect and monitor malicious\unexpected SSL logon attempts which can disrupt PWS SSL logon operations. There are two new keywords named PLBWEB_SSL_BLACKLIST_FILE and PLBWEB_SSL_BLACKLIST_REPORT that optionally can be used to allow a PWS administrator to define the SSL blacklist file which contains blacklist IP addresses to be filtered. If these keywords are not used, the PWS uses default pre-defined blacklist file names as follows: 'plbwebsrv_ssl_blacklist.txt' 'plbwebsrv_ssl_blacklist_report.txt' The PWS performs the following operations for the SSL blacklist monitoring: 1. The SSL blacklist support dynamically detects SSL accept logons that take an excessive amount of time to perform the required SSL accept operations to finish the SSL connection. 2. The file specified by the PLBWEB_SSL_BLACKLIST_FILE keyword is used to pre-load and output an IP blacklist when the PWS starts. If this keyword is not specified in 'plbwebsrv.ini' configuration, the PWS uses the default file name 'plbwebsrv_ssl_blacklist.txt' to pre-load and\or receive the dumped blacklist IP addresses. If the PWS option '-br' or '-bd' is executed, the current blacklist data can be reset or dumped using the current blacklist IP data file. PLBWEB_SSL_BLACKLIST_FILE={[path]+filename} 2. The file specified by the PLBWEB_SSL_BLACKLIST_REPORT keyword is used to specified the output file that receives the SSL IP blacklist report when the PWS command option PWS command '-bl' is executed. PLBWEB_SSL_BLACKLIST_REPORT={[path]+filename} 3. When a SSL logon occurs, the PWS matches the new accept logon peer IP to the current SSL IP blacklist being used. If the new logon IP is found on the IP blacklist and the usage count executes the maximum allowed attempt count, the connection is immediately closed before any SSL TCP\IP communications are attempted. 4. The new PWS command options '-br', '-bd', and '-bl' can be used to reset, dump, or list the current SSL blacklist IP addresses when the PWS server is running. 5. The PWS server always dumps SSL blacklist data when the server shuts down. 6. Dynamic Blacklist Filtering is always enabled as follows: a. If the PWS SSL logon detects excessive time in a ssl_accept, the 1) This time can be configured in seconds using the PLBWEB_SSL_ACCEPT_TIMEOUT keyword. 2) When a timeout occurs and the SSL IP logon timeout has occurred an excessive number of times, the SSL IP address is added to the SSL IP blacklist. 3) The PWS server always dumps the SSL IP blacklist when the PWS is shutdown. b. The number of active ssl_accepts are limited to to restrict the number of SSL logon threads that can be executed concurrently. By default the PWS server limits to 50 concurrent SSL logon operations. The PLBWEB_SSL_ACCEPT_MAX keyword can be used to set the limit from 1 to 100 concurrent SSL logons. c. When an SSL IP LOCKOUT occurs and it becomes permanent on the SSL IP blacklist, an error is logged and a admin MAIL message is sent when it is configured. Keywords: PLBWEB_SSL_BLACKLIST_FILE={[path]+filename] This keyword file specifies the filename used to pre-load and\or output the SSL blacklist IP addresses used for IP filtering. If this keyword is NOT used, the PWS server server defaults to use the file named 'plbwebsrv_ssl_blacklist.txt' when pre-loading or dumping IP filtering data. PLBWEB_SSL_BLACKLIST_REPORT={[path]+filename] This keyword file specifies the filename used to output the current SSL blacklist IP addresses along with the usage\activity count for the IP. If this keyword is NOT used, the PWS server defaults to use the file named 'plbwebsrv_ssl_blacklist_report.txt'. PLBWEB_SSL_ACCEPT_TIMEOUT={seconds} This keyword file specifies the elapsed time out given in seconds to wait when an SSL logon accept connection is being made. If this timeout occurs, the IP is either added or updated in the SSL blacklist data. The {seconds} valid range is: minimum 10 seconds and maximum of 600 seconds. If this keyword is not used, the PWS server defaults to use 60 seconds. PLBWEB_SSL_ACCEPT_MAX={acceptmax} This keyword specifies the maximum number of concurrent SSL accept logons. If this keyword is not used, the PWS server defaults to allow 50 concurrent SSL accept logons. The {acceptmax} valid range is: minimum 5 and maximum 100. PLBWEB_SSL_LOCKOUT_MAX={lockoutmax} This keyword specifies the maximum number of SSL IP logon accept timeout events that can occur before a specific IP address is added to the SSL blacklist. After a SSL peer IP address is added to the SSL blacklist, that SSL IP address is immediately closed upon detection until the IP address is removed from the SSL blacklist by the PWS administrator. An SSL IP address can ONLY be removed by editing the SSL blacklist data file as defined by the PLBWEB_SSL_BLACKLIST_FILE keyword or the default file being used. If this keyword is not used, the PWS server defaults to allow a maximum of 5 SSL logon accept errors. The {lockoutmax} valid range is: minimum of 1 and the maximum is unlimited. PWS commands used for SSL blacklist are: plbwebsrv -br (reset SSL blacklist) plbwebsrv -bd (dump SSL blacklist) plbwebsrv -bl (output a SSL blacklist report) - Modified the PWS to capture and log information if a GPF\SEGV error occurs in the web server processing which controls the communications and interface to the browser clients. With this change, GPF\SEGV information is logged into in files named 'plbweb_nnnn.gpf' where the 'nnnn' identifies the id of the failing thread or process. Note: 1. This change resolves an issue where the PWS LOGON would start rejecting logon accept requests if the PWS web server processing encountered a GPF\SEGV error. In this case, the PWS server would start logging the following error multiple times: "Accept on socket failed (10038)" - Corrected a problem where a 'DESTROY COLLECTION' instruction could cause memory loss. - Corrected a problem where the RUNTIME 'CgiString' was always returning the string value of 'Basic' for the AUTH_TYPE keyword erroneously. - Corrected a problem where a 'DESTROY FLOATMENU' operation caused a menu bar to be drawn on a WINDOW. - Due to problems and inconsistent behaviors fir different client browsers, the 'SelectAll'method for a PWS EDITTEXT and EDITNUMBER ONLY works on an object that has the current focus. - Corrected a problem where the 'OVERTYPE' property for a 'CREATE EDITTEXT' did not work properly. ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLB(UNIX) - Added a new keyword named 'PLB_CGI_DIR={path}' to the PL/B runtimes ( PLBWIN, PLBNET, and PLB(Unix) ). This keyword specifies the path where the CGI temporary data files are located when processing the CGI file specified by the command line option '-cgi '. Format: PLB_CGI_DIR={path} Where: {path} - The directory where CGI temporary files are located. This directory MUST be the same directory as specified by the PWS server 'PLBWEB_CGI_INFODIR' keyword. - Modified the PL/B runtimes ( PLBWIN, PLBNET, and PLB(Unix) ) to support a new command line option named '-cgi '. This '-cgi' option is included in a PL/B runtime command line by a PWS server which invokes the execution of a runtime when a REST request is detected. '-cgi ' command line option: This option is normally used to access CGI data that has been stored into the by a PWS server which has accepted a REST request to be processed. This option causes the file CGI data to be preloaded into memory before a PL/B program starts executing. After the PL/B program starts executing, the RUNTIME object method 'CgiString' can be used to retrieve the data using CGI keywords. - Modified the RUNTIME object to provide meaningful information for the 'CgiString' method to support the PL/B REST implementation. See the PL/B Web Server manual for more details on the PL/B REST support. The Runtime 'CgiString' method has been changed as follows: 1. When a REST API request is accepted by a PWS server, the PWS server extracts the Http header data from the request and stores it into a CGI data file. In this case,the PWS server stores the CGI data into a file based on the PWS keyword named 'PLBWEB_CGI_INFODIR'. Also, the PWS server starts a PL/B runtime including the command line option '-cgi '. 2. When the PL/B runtime detects the new command line option named '-cgi ', the PL/B runtime preloads the data so the RUNTIME object 'CgiString' method can access the CGI keyword data. The CGI keywords are the same as described for the 'CgiString' for a PWS server program. After the data is preloaded, the PL/B runtime deletes the temporary CGI file before the PL/B REST program starts executing. 3. Also, if the CGI 'AUTH_TYPE' keyword has a returned string value of 'Basic', these CGI keywords are available with meaningful data: AUTH_USER REMOTE_USER AUTH_DATA - Added a new RUNTIME object method named 'HttpResponse'. This method accepts input parameters and uses the data to format a Http message that is output using the runtime StdOut. This method is ONLY available for the PLB(Unix), PLBWIN, and PLBNET runtimes. ............................................................... . HttpResponse Method for RUNTIME Object . The HttpReponse method can be used to format program data into a valid Http message that is output to the runtime StdOut channel. The method uses the following format: [label] {object}.HttpResponse GIVING {return}: USING [*HTTPCODE=]{httpcode}[: [*MIMETYPE=]{mimetype}][: [*BODY=]{body}][: [*EXTRAHDRS=]{extra}][: [*OUTPUT=]{output}][: [*OPTIONS=]{options}] Where: {label} is an optional Program Execution Label. {object} is a RUNIME object that has been previously Required declared. {return} is a Numeric Variable that returns the pass\failure values for the execution of the method. {httpcode} is a Numeric Variable or decimal number that Required specifies the http return code to be included in the http message body. This should be a valid http code or the http code of 500 is used. {mimetype} is a Character String Variable or string Optional literal that specifies the mime type of the data that is included in the body parameter. {body} Optional is a Character String Variable or string literal that contains the HTTP body text to be sent in the response. The body text is a text, JSON, or XML string that is returned in the response message. {extra} is a Character String Variable or string Optional literal that contains any other generated HTTP header fields to be included in the response message. Each line must be terminated with the 0x0D and 0x0A characters. {output} is a Character String Variable or string Optional literal that contains the name of a data file where the response data is to be stored. This parameter can be used to debug the REST program output. {options} is a Numeric Variable or decimal number that Optional specifies a bit mask value that can be used to control the behaviors of this method. Flags Affected: OVER, ZERO Note the following: 1. The ZERO flag is set to TRUE if the {return} value is zero. 2. The OVER flag is set to TRUE if the {return} variable is too small to receive the numeric result. 3. The normal expected use of this method is to simplify responses sent to a REST client which is connected to a PWS server to process a REST request via the PL/B runtime StdOut channel. See the PWS Server REST Overview for more information on PL/B Rest support. 4. The supported {httpcode} values must be a valid http response code as shown in the following table. Http Code Value Code Message Action 200 OK 201 Created 202 Accepted 204 No Content 205 Reset Content 206 Partial Content 301 Moved Permanently 302 Found 303 See Other 304 Not Modified 400 Bad Request 401 Unauthorized 402 Payment Required 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 407 Proxy Authentication Required 408 Request Timeout 409 Conflict 410 Gone 411 Length Required 412 Precondition Failed 413 Payload Too Large 414 URI Too Long 415 Unsupported Media Type 416 Range Not Satisfiable 417 Expectation Failed 418 I'm a teapot 421 Misdirected Request 422 Unprocessable Entity 423 Locked 424 Failed Dependency 426 Upgrade Required 428 Precondition Required 429 Too Many Requests 431 Request Header Fields Too Large 451 Unavailable For Legal Reasons If the code is not one of these than the default result will be a code of '500 Internal Server Error' with a mime type of 'text/plain' and no body. 5. The {mimetype} identifies the mime type (i.e. format) of the data that is included in the {body} parameter. If the {mimetype} is not given, the HttpResponse uses the 'text/plain' as the default. Simple mime types can be specified as: "text/html" "application/json" "application/xml" 6. The {body} is a text, JSON string, or XML string generated and provided by the executing program. The {body} format and syntax that is generated by the user program should be consistent with the {mimetype} parameter. 7. The {extra} parameter specifies any other HTTP header fields that are to be included in the response message. For example, a POST operation might return the location of the new item as follows: Location: http://127.0.0.1/MyServices/PhoneMsg/24 8. The {options} parameter is a bitmask value the forces specialized behaviors for the execution of the RUNTIME 'HttpResponse' method. The bitmask values are defined as follows: Options Value $HttpResp_NoAccessControl EQU 1 When this bit is set the 'HttpResponse' DOES NOT include the default 'Access-Control-Allow' headers fields in the HTTP message. See the 'PL/B Web Server' manual for details on these header fields. $HttpResp_AllowCacheControl EQU 2 When this bit is set the 'HttpResonse' DOES NOT include the default 'Cache-Control:' HTTP header field in the HTTP message headers. See the 'PL/B Web Server' manual for details on this header field. ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLBSERVE, PLBWEBSRV (Windows) - Modified the 'SETPROP COLLECTION,*VISIBLE={0|1}' instruction to allow properties to take affect when a collection ONLY contains normal GUI objects and it DOES NOT include NETOBJECT, NETCONTROL, CONTROL, CONTAINER, or AUTOMATION objects. Recommendations with 9.9A changes: 1. The 'SETPROP COLLECTION, PROPERTY={value}' instruction syntax should be used when the COLLECTION contains ONLY normal GUI objects like BUTTON, EDITTEXT, STATTEXT, ...etc. 2. The 'SETPROP COLLECTION, *PROPERTY={value}' instruction syntax MUST be used when the COLLECTION contains object types of NETOBJECT, NETCONTROL, CONTROL, CONTAINER, and AUTOMATION. WARNING: In this case, any normal GUI objects in this same COLLECTION are IGNORED and ARE NOT changed for the *PROPERTY. 3. As changed by the 9.9A patch release version, the 'SETPROP COLLECTION, *PROPERTY={value}' instruction syntax can change\take affect for normal objects in the COLLECTION ONLY if the collection DOES NOT include a NETOBJECT, NETCONTROL, CONTROL, CONTAINER, or AUTOMATION object. WARNING: This 9.9A change is ONLY being made to allow programs compiled after 9.5B to properly execute using the 'SETPROP COLLECTION, *PROPERTY={value}' instruction when a COLLECTION ONLY contains normal GUI objects that DO NOT include NETOBJECT, NETCONTROL, CONTROL, CONTAINER, or AUTOMATION object types. Example: A BUTTON S STATTEXT COL COLLECTION . CREATE A... CREATE S... . LISTINS COL, A, S . . Note the following instruction: . . 1. The following instruction worked prior to 9.5B. . . 2. The following instruction stopped working with 9.5B . changes. . . 3. The following instruction works with 9.9A as LONG . as the COL collection DOES NOT include a NETOBJECT, . NETCONTROL, CONTROL, CONTAINER, or AUTOMATION object. SETPROP COL, *VISIBLE=1 //Worked prior to 9.5B change. //Works after 9.9A change. . . Note the following instruction: . . 1. The following instruction works with all runtime . versions. . SETPROP COL, VISIBLE=1 . ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLBSERVE, PLB(UNIX), PLBWEBSRV - Modified the CHAIN instruction to clear the debugger TP (Trace Point) table being used by the character debugger. This change corrects an indeterminate\GPF error that could occur after a CHAIN of a program while debugging with debugger TP variables being used. - Corrected a problem where the GETFILE of an XFILE was erroneously reporting that an XFILE was opened after it had implicitly been closed when its parent XFILE was closed. Example to reproduce the 'GETFILE XFILE' problem: . People XFILE Person XFILE SEQ FORM "-1" . OPEN People,"test.xml" READ People,SEQ;PERSON=Person ..... . At this point, both People and Person are OPEN XFILE variables! . CLOSE People ..... . When the 'People' XFILE is closed, the children XFILE variables . to 'People' are implicitly closed. Therefore, the 'Person' . XFILE is implicitly closed. ..... . The following 'GETFILE Person' instruction should clear the ZERO . flag. . GETFILE Person //ZERO flag should be cleared! IF ZERO DISPLAY "Zero...Person XFILE is opened!" ELSE DISPLAY "Not Zero...Person XFILE is closed!" ENDIF . ............................................................... . 'test.xml' data file . John Smith James Jones - Corrected a problem where the MOVEVL and MOVELV instructions did not support an Array VAR variable with a variable index. Note, the 9.9A PLBCMP compiler is required to compiler the MOVELV and MOVEVL statements using an array VAR variable. Example: arrVar VAR [2]^ $2 INTEGER 1,"2" LabPtr LABEL ^ . xFunc FUNCTION ENTRY ... FUNCTIONEND . MOVELV xFunc, arrVar[$2] MOVEVL arrVar[$2], LabPtr - Corrected a problem where the execution of a FLUSH instruction on a file variable that has never been used could cause a GPF. - Corrected a problem where a literal used as a parameter in a 'CALL USING' instruction was giving a F04 or F05 error when the destination parameter list was a VAR array. Example of Problem: CALL ABC USING "Literal" //Gives F05 without 9.9A fix! STOP . ABC FUNCTION var VAR (5)@ ENTRY . KEYIN "I am here:",s$cmdlin . FUNCTIONEND - Corrected a problem where XFILE_XMLOUTFMTCVTTOSPC mode was causing international characters (0xA0 to 0xFF) to be replaced with a 0x20 character by mistake. ------------------------------------------------------------------------------- PLBWIN, PLBNET, ALL GUI CLIENTS - Modified the LISTVIEW 'LoadCSVFile' and 'SaveCSVFile' methods have been modified to support a new {options} bit mask value which prevents OEM to ANSI and ANSI to OEM translations when these methods are executed. LoadCSVFile method {options} $LV_CSVRD_NOOEM2ANSI - 0x100 //NO OEM to ANSI translation SaveCSVFile method {options} $LV_CSVWR_NOANSI2OEM - 0x100 //NO ANSI to OEM translation - Corrected a problem where the 'GETINFO TYPE=font, string, printer=PFILE' instruction did not detect\use the 'SETMODE *PDFDEFPRTNAME and *PDFDEFPRTMETRICS' keywords when the 'PFILE' was opened to the Sunbelt 'pdf:' device. - Corrected a problem where a mult-line EDITTEXT object was ignoring the MAXCOLS property. This bug started occurring after a change made in release 9.5B that corrected a single line EDITTEXT MAXCOLS property issue. - Corrected a problem where the PRTOPEN using the "!@pdf:" printer type was not appending the '.pdf' extension to the {jobname} parameter for the PDF output file name. - Corrected a problem where the 'GETFILE PFILE, PDFNAME=name' instruction was not returning a PDF file name when the PRTOPEN was using a {device} parameter string of "!@pdf:" or "@pdf:". ------------------------------------------------------------------------------- PLBCMP - Corrected a problem where the DTYPE compiler directive reported invalid label type values for the labels of the ADMIN, DBSTATEMENT, VAR, and SNDFILE data variables. With this 9.9A compiler change, the Labels for these data variable types are generated correctly as follows: Data Variable Base Data Type ADMIN 73 (0x49) DBSTATEMENT 74 (0x4A) VAR 99 (0x63) SNDFILE 68 (0x44) - Corrected a problem where the DTYPESUB compiler directive did not set the correct values for INTEGER data variables. Prior to this change the DTYPESUB INTEGER value was always set to be zero. With this 9.9A change the DTYPESUB INTEGER type value is the size of the INTEGER (i.e. 1, 2, 3, 4, or 8). - Corrected a problem where a RECORD pointer used as the first parameter of a FUNCTION might not be restored properly when the FUNCTION ended. In this scenario, the first parameter RECORD pointer could point to an unexpected RECORD if the FUNCTION called itself iteratively such that the first parameter was not being restored when the FUNCTION ended. - Corrected a compiler bug where the FUNCTION parameter variables might exclude a RECORD pointer which would cause an unexpected F05 error when the FUNCTION was called. This compiler bug was caused by a 9.8B compiler change that fixed a different FUNCTION parameter list problem using RECORD variables. Example of Error: Rec RECORD Name1 DIM 10 Name2 DIM 10 RECORDEND . RecPtr RECORD ^,Rec . RecVal RECORD Value1 DIM 10 Value2 DIM 10 RECORDEND . RecValPtr RECORD ^, RecVal . X XFILE . CALL Func USING RecPtr, RecValPtr, X //F05 error! SHUTDOWN ... Func FUNCTION Names RECORD ^ Values RECORD ^ xPtr XFILE ^ ENTRY . DEBUG . FUNCTIONEND . - Corrected a problem where the MOVEVL and MOVELV instructions did not allow an array VAR variable to be compiled\used. Example: arrVar VAR [2]^ LabPtr LABEL ^ . xFunc FUNCTION ENTRY ... FUNCTIONEND . MOVELV xFunc, arrVar[2] MOVEVL arrVar[2], LabPtr ------------------------------------------------------------------------------- PLBDBUG - Modified the character debugger to reset the debugger TP table entries when a CHAIN operation is executed in a debug session. ------------------------------------------------------------------------------- DBGIFACE - Corrected an O105 error when the GUI debugger was invoked using the Sunide. ------------------------------------------------------------------------------- ADMEQU.INC - Reviewed for 9.9A patch release. ------------------------------------------------------------------------------- PLBEQU.INC - Modified the $T_INTEGER(n) type equate values to properly reflect the PLB TYPE instruction as follows: $T_INTEGER EQU 0x0108 ;True type for variable in UDA $T_INTEGER1 EQU 0x0108 ;Integer 1 True type for variable in UDA $T_INTEGER2 EQU 0x0208 ;Integer 2 True type for variable in UDA $T_INTEGER3 EQU 0x0308 ;Integer 3 True type for variable in UDA $T_INTEGER4 EQU 0x0408 ;Integer 4 True type for variable in UDA $T_INTEGER8 EQU 0x0808 ;Integer 8 True type for variable in UDA - Removed the following TYPE instruction equate values: $T_PROFILE EQU 0x007B ;True type for variable $T_EQUCMDLIN EQU 0x007C ;True type for variable $T_EQU EQU 0x007D ;True type for variable $T_RECORD EQU 0x0104 ;True type for variable $T_INTEGERARR1 EQU 0x0108 ;Integer 1 array $T_RECORDEF EQU 0x0204 ;True type for variable $T_INTEGERARR2 EQU 0x0208 ;Integer 2 array $T_INTEGERARR3 EQU 0x0308 ;Integer 3 array $T_INTEGERARR4 EQU 0x0408 ;Integer 4 array $T_INTEGERARR8 EQU 0x0808 ;Integer 8 array - Added the equate value types generated for the compiler 'DTYPE(label)' directive that can be used EQUATE and %IF conditional compilation directives. See the PLBEQU.INC table of equates formatted as '$DT_{data|object}'. Example: $DT_VARLIST EQU 0x0004 ;True type for variable compiled $DT_INTEGER EQU 0x0008 ;True type for variable compiled $DT_FORM EQU 0x0010 ;True type for variable compiled $DT_FILELIST EQU 0x0014 ;True type for variable compiled ... etc ... - Added $JQueryEvent EQU used to register events for HTML objects that have been created in a PWS PANEL object using the PANEL InnerHtml method. ------------------------------------------------------------------------------- PLBMETH.INC - Added JqGet, JqSet, AppBeacon, AppBeaconStatus PWS CLIENT object methods. - Added generic methods named EnableJqEvent and DisableJqEvent for all of the PWS GUI objects. - Added $HTML_HAS_EVENTS equate value for the PWS PANEL InnerHtml Method *FLAGS parameter. - Added $JQ_FLAG_CSS and $JQ_FLAG_PROP equate values for the *FLAGS parameter of the JqGet and JqSet methods for the PWS CLIENT object. ------------------------------------------------------------------------------- DESIGNER.PLC - Added the WebClass property to the Designer generated TabPanels. - Corrected an O105 error that could occur during the Print function. - Corrected an error during object array creation. ------------------------------------------------------------------------------- EDITOR.PLC - Corrected an issue with the shortcut menu. ------------------------------------------------------------------------------- SUNCS21.OCX - Modified to allow only one mouse button to be active at a time. ------------------------------------------------------------------------------- SCHEMAEDITOR.PLC - Added support for the BigInt SQL type. - Modified the import PLB logic to allow a specification for FORMs larger than 10 to use a default SQL type of BigInt. -------------------------------------------------------------------------------