Date: 03-11-2015 Subject: RELEASE 9.8A Runtime Files These release notes pertain to the following programs or files: EMBEDINI 9.8A 11 Mar 2016 9,8,1,500 EMBEDINI64 9.8A 11 Mar 2016 9,8,1,500 HEXDUMP 9.8A 11 Mar 2016 9,8,1,500 HEXDUMP64 9.8A 11 Mar 2016 9,8,1,500 MAKECLI 9.8A 11 Mar 2016 9,8,1,500 MAKECON 9.8A 11 Mar 2016 9,8,1,500 MAKECONET 9.8A 11 Mar 2016 9,8,1,500 MAKEDEF 9.8A 11 Mar 2016 9,8,1,500 MAKEMFD 9.8A 11 Mar 2016 9,8,1,500 MANAGECE 9.8A 11 Mar 2016 9,8,1,500 OBJMATCH 9.8A 11 Mar 2016 9,8,1,500 OBJMATCH64 9.8A 11 Mar 2016 9,8,1,500 ODBCINST64 9.8A 11 Mar 2016 9,8,1,500 PLBCGI 9.8A 11 Mar 2016 9,8,1,500 PLBCLICON 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBCLIENT 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBCLINET 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBCON 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBCONET 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBDSIGN 9.8A 11 Mar 2016 9,8,1,500 PLBNET 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) PLBSERVE 9.8A 11 Mar 2016 9,8,1,500 (Processed Server) PLBSERVET 9.8A 11 Mar 2016 9,8,1,500 (Threaded Server PLBWEBSRV 9.8A 11 Mar 2016 9,8,1,500 (Processed Server) PLBWEBSRVT 9.8A 11 Mar 2016 9,8,1,500 (Threaded Server) PLBWIN 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 6) SUNAAMDX 9.8A 11 Mar 2016 9,8,1,500 SUNAAMDX64 9.8A 11 Mar 2016 9,8,1,500 SETGUID 9.8A 11 Mar 2016 9,8,1,500 SUNINDEX 9.8A 11 Mar 2016 9,8,1,500 SUNINDEX64 9.8A 11 Mar 2016 9,8,1,500 SUNLS 9.8A 11 Mar 2016 9,8,1,500 SUNMOD 9.8A 11 Mar 2016 9,8,1,500 SUNMOD64 9.8A 11 Mar 2016 9,8,1,500 SUNSORT 9.8A 11 Mar 2016 9,8,1,500 SUNSORT64 9.8A 11 Mar 2016 9,8,1,500 WININST 9.8A 11 Mar 2016 9,8,1,500 PLBCLICON5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBCLIENT5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBCLINET5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBCON5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBCONET5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBNET5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) PLBWIN5 9.8A 11 Mar 2016 9,8,1,500 (ComCtl 5) ODSBAC32.DLL 9.8A 11 Mar 2016 ODSBAC64.DLL 9.8A 11 Mar 2016 PLBNETSUP.DLL 9.8A 11 Mar 2016 9,8,1,500 Required for PLBNET PLBWSEC.DLL 9.8A 11 Mar 2016 9,8,1,500 Req'd PLBWIN/PLBNET SA_DLL32.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWADO.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWADO25.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWADO28.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWMSQL.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWODBC.DLL 9.8A 11 Mar 2016 9,8,1,500 SUNWSRV.DLL 9.8A 11 Mar 2016 9,8,1,500 DBGIFACE 9.8A 11 Mar 2016 PLBCMP 9.8A 11 Mar 2016 PLBDBUG 9.8A 11 Mar 2016 DBEXPLORER 9.8A 11 Mar 2016 WATCH 9.8A 11 Mar 2016 SCHEMAEDITOR 9.8A 11 Mar 2016 EDITOR 9.8A 11 Mar 2016 SUNIDE 9.8A 11 Mar 2016 DESIGNER 9.8A 11 Mar 2016 ADMEQU.INC 9.8A 11 Mar 2016 PLBEQU.INC 9.8A 11 Mar 2016 PLBMETH.INC 9.8A 11 Mar 2016 SUNCS21.OCX 9.8A 11 Mar 2016 PLBCLI.ZIP 9.8A 11 Mar 2016 9,8,1,600 (ComCtl 6) PLBRUN.ZIP 9.8A 11 Mar 2016 9,8,1,600 (ComCtl 6) *============================================================================== Notes for some NEW Items: - Added new runtime XDATA object support to allow raw processing of XML, JSON, SOAP, HTML, and REST data structures. *============================================================================== Notes for WARNINGS: - All SunDM Data Manager versions have a 16-bit limit on individual DIM variables in a READ or WRITE variable list. If individual DIM variables in a READ\WRITE have a size larger than 65535 bytes, it is possible that unexpected\indeterminate results for these instructions CAN occur. All PLB programs should avoid using individual DIM variables in READ\WRITE instructions that are larger than 65535 bytes. Note: To avoid this DIM size issue accessing files on a Data Manager, a PLB READ or WRITE can use multiple DIM variables whose size DOES NOT exceed 65535. - Based on the 16-bit limits for the Data Manager READ\WRITE operations, the 9.8A or newer PLB runtimes and Data Managers have been modified to generate appropriate I82 errors. These I82 error are generated if unexpected\indeterminate interface data is detected\encountered when DIM variables with a size larger than 65535 are being used. See the PL/B Runtime Reference manual for new I82 error description details. Note: To avoid this DIM size issue accessing files on a Data Manager, a PLB READ or WRITE can use multiple DIM variables whose size DOES NOT exceed 65535. - All runtime\sundm versions prior to the 9.8A version can cause data record corruption when using a FILTER expression for an IFILE if a repeating sequence of READKS and UPDATE instructions is processed. This same problem can occur when using a READKP (with a filter) and UPDATE sequence that is repeated. *============================================================================== Notes for DOCUMENTATION: - In the PL/B Language Reference manual in section 'HTTP', add the following error code value description in the Note (10.): 31 - This error SHOULD NEVER occur! However, if this error does occur, the receive buffer for the HTTP result being received using 'chunked' blocks has overflowed. Report this error to Sunbelt Support and send any trace logs and\or other information regarding this error event for evaluation. - In the PL/B Runtime Reference manual in the 'U(Untrappable) Errors' section, change the U15 error description to read as follows: "Graphical User Interface statement encountered with a non-graphical runtime. Also indicates an unsupported feature encountered in the Personal Version. This error can occur if a GETFILE instruction encounters a keyword that is not supported by the current runtime version." - In the PL/B Language Reference manual in the 'SQLIO Administrative Tables' section, change the 'Sun_Sqlio_Afile' description for the 'file_name' to read as follows: file_name Text column that identifies the TXT file name associated with the AAM file. The data in this column is used to look up information contained in the 'SUN_SQLIO_FILE' system table. The attribute named 'file_name={filename}' can be used to override this schema field for a PLB OPEN or PREPARE AFILE operation. - In the PL/B Language Reference manual in the 'SQLIO Administrative Tables' section, change the 'Sun_Sqlio_Ifile' description for the 'file_name' to read as follows: file_name Text column that identifies the TXT file name associated with the ISI file. The data in this column is used to look up information contained in the 'SUN_SQLIO_FILE' system table. The attribute named 'file_name={filename}' can be used to override this schema field for a PLB OPEN or PREPARE IFILE operation. - In the PL/B Runtime Reference manual in the 'I/O Error Sub-codes' section, change the first paragraph to read as follows: "There are two tables as follows that describe the Windows error codes and the PLB sub-codes that can appear in a PLB error description. The first table identifies Windows I/O error values and the second table identifies 'errno' sub-code values derived from the Windows I/O error values. The first table identifies Windows I/O errors that can occur in the PLBWIN file subsystem. The errors identified as 'ERROR_' are the Windows operating system error constant name. Note that the 'ERROR_...' definition is included as 'Extended Data' WINERR:0xnn in the error message where '0xnn' is defined as one of the following values:" - In the PL/B Runtime Reference manual in the 'I/O Error Sub-codes' section, change the first PLBWIN table heading to read as follows: Error Code Winerr Description - In the PL/B Application Server manual in the 'PLBCS_MAXPROGVMEM Keyword' section, change the keyword description as follows: "This optional keyword defines the virtual program space to be allocated for a PLB Client task. The {size} value is specified in bytes. If this keyword is not specified, the default virtual program space size is set to 4,096,000 bytes (4MB) for the threaded Application Server runtime (i.e. 'plbservet.exe'). If the processed based Application Server runtime (i.e. 'plbserve.exe') is being used, the default virtual program space size is set to 20,480,000 bytes (20MB). If this keyword is specified in the PLBSERVE.INI file, it is used for all client tasks generated by the Application Server Windows runtimes." - In the PL/B Web Server manual in the 'PLBWEB_MAXPROGVMEM Keyword' section, change the keyword description as follows: "This optional keyword defines the virtual program space to be allocated for a PLB Client task. The {size} value is specified in bytes. If this keyword is not specified, the default virtual program space size is set to 4,096,000 bytes (4MB) for the threaded PL/B Web Server runtime (i.e. 'plbwebsrvt.exe'). If the processed based PL/B Web Server runtime (i.e. 'plbwebsrv.exe') is being used, the default virtual program space size is set to 20,480,000 bytes (20MB). If this keyword is specified in the PLBSERVE.INI file, it is used for all client tasks generated by the PL/B Web Server Windows runtimes." - In the PL/B Language Reference manual in the 'UPDATE,UPDATETAB(FILELIST)' section, change the Note (2.) to read as follows: Note the following: 2. The instruction will update all keys of the ISAM or AAM files defined in the FILELIST that are changed by the {list} variables. WARNING: When the update changes the key for an ISAM file in the FILELIST, the current key pointer for this ISAM file is changed to reflect the new key position in the ISI tree. Therefore, any READKS or READKP instruction for an IFILE in the FILELIST whose key has been changed reads the key sequential record relative to the NEW key pointer position. - In the PL/B Runtime Reference manual in the 'I(I/O) Errors' section, add the following I82 subcode error descriptions: 34 - The runtime is shutting down the Data Manager socket connection and a socket error is being ignored. 35 - A PLB runtime has detected a WRITE operation to a SunDM data manager where a single DIM variable in the WRITE variable list has a size larger than 65535 bytes. All individual DIM variables written to the Data Manager must have a size less than 65536 bytes. 36 - The SunDM Data Manager has encountered an invalid WRITE data variable identifier. The intent of this error is to eliminate indeterminate write results if the write data stream has an invalid format. One scenario that can cause this error is when a 9.8 or earlier runtime version attempts to WRITE a DIM variable with a data size larger than 65535 bytes. 37 - A PLB runtime has detected a READ operation to a 9.8 or older SunDM Data Manager version where a single DIM variable in the READ variable list has a physical size larger than 65535 bytes. All individual DIM variables being used for a READ from the Data Manager must have a size less than 65536 bytes. 38 - The SunDM Data Manager has encountered a READ operation where a single DIM variable in the READ variable list is larger than 65535 bytes and the amount of data to be returned to the PLB runtime is larger than 65535 bytes. All individual DIM variables being used for a READ from the Data Manager must have a size less than 65536 bytes. Please note, a READ operation using a 9.8A or newer Data Manager can operate without this I82 error ONLY if the data size to be returned is less than 65535 bytes. 39 - A PLB runtime has detected READ operation data as received from a Data Manager where the data size to be stored in a PLB INTEGER is too large and can not be stored into the INTEGER without overflowing resulting in UDA corruption. The most likely cause of this error can be when a 9.8A or newer PLB runtime is accessing a 9.8 or older Data Manager and a DIM variable with a size larger than 65535 is followed by an INTEGER in the READ variable list. 40 - A PLB runtime has detected READ operation data as received from a Data Manager where the data size to be stored in a PLB FORM is too large and can not be stored into the FORM without overflowing resulting in UDA corruption. The most likely cause of this error can be when a 9.8A or newer PLB runtime is accessing a 9.8 or older Data Manager and a DIM variable with a size larger than 65535 is followed by a FORM in the READ variable list. 41 - A PLB runtime has detected READ operation data as received from a Data Manager where the data size to be stored in a PLB DIM is too large and can not be stored into the DIM without being truncated. The most likely cause of this error can be when a 9.8A or newer PLB runtime is accessing a 9.8 or older Data Manager and a DIM variable with a size larger than 65535 is followed by a DIM in the READ variable list. - In the PL/B Runtime Reference in the 'U(Untrappable) Errors' section, modify the U67 error description to read as follows: U67 - This error occurs when a PL/B instruction or instruction feature is encountered that is NOT supported by the Plb Web Server. - In the PL/B Web Server Reference manual in the 'Consideration' section, modify the Notes as follows: Modify these Notes: 8. Add the 'PRTPLAY' to the unsupported PL/B instructions. 9. Change the PRTOPEN in Note (9.) to read as follows: PRTOPEN- Server side only using ‘pdf:’. If the '!' character is used as the leading character in the {device} string, a U67 error occurs. - In the PL/B Language Reference manual in the 'PRTOPEN' instruction, add a Note (17.) that reads as follows: Note the following: 17. When using the PL/B Web Server, the {device} string can not have a leading '!' character since a {device} printing device can not be opened at the client browser. If a leading '!' is used for the {device} string, a U67 error occurs. - In the PL/B Language Reference manual in the 'PRTPLAY' instruction descriptions, add the following new Notes: Note the following: 8. When executing a PRTPLAY instruction using the PL/B Application server (i.e. Plbserve), output local to the server system is NOT supported. Therefore, the PRTPLAY instruction ALWAYS renders the {device} output to the PLBCLIENT client workstation. 9. The PRTPLAY instruction is NOT supported by the PL/B Web Server runtime. In this case, a U67 error occurs. - In the PL/B Language Reference manual in the 'PDF PRTPLAY Notes', add the new Notes as follows: Note the following: 8. When executing a PRTPLAY instruction using the PL/B Application server (i.e. Plbserve), output local to the server system is NOT supported. Therefore, the PRTPLAY instruction ALWAYS renders the {device} output to the PLBCLIENT client workstation. 9. The PRTPLAY instruction is NOT supported by the PL/B Web Server runtime. In this case, a U67 error occurs. - In the PL/B Language Reference manual add a new Note (11.) to the 'EVENTINFO' instruction that reads as follows: Note the following: 11. The EVENTINFO instruction can be used to retrieve event information for any PLB Event that currently exists on the PLB event queue. Typically, this instruction is used in the PLB program event routines. - In the PL/B Language Reference manual add new notes to the 'DoubleClick Event' descriptions as follows: Note the following: 4. When the PICT 'Double Click Event' is registered and being used, a Double Click action DOES NOT generate\dispatch the PICT Default (i.e. ACTIVATE) and single 'Click' events. 5. The 'DoubleClick Event' is NOT supported for the PL/B Web Server (PWS) PICT object. This restrict exists because there are inconsistent behaviors for different client Browsers. In addition, some mobile devices CAN NOT perform any double clicking actions. - In the PL/B Language Reference manual in the 'ACTIVATE' instruction modify the Note (2.) to read as follows: Note the following: 2. The {routine} is called as if a CALL instruction was performed. It is only called when a EVENTCHECK or EVENTWAIT is processed. The LABEL execution pointer variable cannot be used in an ACTIVATE instruction. Otherwise, a compiler error occurs. - In the PL/B Language Reference manual in the 'EVENTREGISTER' instruction modify the Note (2.) to read as follows: Note the following: 2. The {routine} is CALLed when the event action occurs. The LABEL execution pointer variable cannot be used in an EVENTREGISTER instruction. Otherwise, a compiler error occurs. - In the PL/B Language Reference manual in the 'LOWERCASE' instruction, modify the Note (2.) to read as follows: Note the following: 2. The Logical String of {source} is moved into the {dest} variable. If the {source} is a NULL variable, the {dest} is changed to be a NULL variable. - In the PL/B Language Reference manual in the 'UPPERCASE' instruction, modify the Note (2.) to read as follows: Note the following: 2. The Logical String of {source} is moved into the {dest} variable. If the {source} is a NULL variable, the {dest} is changed to be a NULL variable. - In the PL/B Language Reference manual in the 'OCCURS' instruction, modify the Note (2.) to read as follows: Note the following: 2. The EOS flag is set TRUE if the {source} or {search} variable is NULL and the {result} variable value is set to be zero. - In the PL/B Language Reference manual in the 'WINAPI' instruction, add the new Notes as follows: Note the following: 15. When processing a WINAPI using the PL/B Web Server to process a JavaScript function, all WINAPI DIM\PDIM parameter data MUST be formatted as VALID JavaScript parameter(s). Otherwise, unexpected JavaScript errors or behaviors can occur. See the following link for information on JavaScript function parameters: http://www.w3schools.com/js/js_function_parameters.asp 16. When processing a WINAPI using the PL/B Web Server to process a JavaScript function, ONLY the logical length of any input DIM or PDIM variable is used. If the DIM\PDIM variable is NULL, NO data is used for the WINAPI input parameter. - In the PL/B Language Reference manual in the 'ADMCOMMAND' instruction, modify the Note (4.) to read as follows: Note the following: 4. {data} is specific to the class selected by the {type} parameter. The {data} can specify a single filter operation that is used to determine how the command is be applied. The {data} string may be null to match all characters or it may contain the following: - an asterisk (*) to match a group of characters. - a question mark (?) to match a single character. - a leading <, >, =, >=, <=, <> if the type is numeric Example filter usage: ADM ADMIN NULL DIM 1 ..... . In this scenario, the soft terminate command is applied . to a Sunbelt server child task that has an . identification number of 312. . AdmCommand ADMIN, $ADMCMDSOFTTERM: //Command $ADMITEMADMID: //Type data "=312" //Filter one task ..... . In this scenario, the soft terminate command is applied . to a Sunbelt server child task that has an . identification number greater than 215. . AdmCommand ADMIN, $ADMCMDSOFTTERM: //Command $ADMITEMADMID: //Type data ">215" //Multiple tasks ..... . In this scenario, the soft terminate command is applied . to all Sunbelt server child tasks that exist. . AdmCommand ADMIN, $ADMCMDSOFTTERM: //Command $ADMITEMADMID: //Type data NULL //All child tasks . - In the PL/B Web Server manual in the 'Browser Client URL' section, add the following modifications where PWS PLB programs can be invoked using HTTP POST requests. Change the browser client URL format(s) as follows: (1) {Ip|Url}:{portnum}/{prgname}[?[runopt={runopts}][cmdline={prgopt}] (2) {Ip|Url}[:{portnum}]/{htmlpage} Add the following {htmlpage} description: {htmlpage} The {htmlpage} shown in format (2) allows an HTML web page to be loaded and processed which causes a PLB program to be processed by the PWS server. The processing of the HTML or JavaScript in the {htmlpage} depends on the behaviors and restrictions implemented by the type\version of client browser being used. The use of an HTML web page can be implemented to use HTTP GET or POST requests to invoke processing of the PLB program at the PWS server. Add examples as follows using format (2): http://www.sunbelt-plb.com:8081/mypage.html This URL logon string causes a logon to a PL/B Web Server processing on the Sunbelt Server. In this case, an HTML web page file named 'mypage.html' is downloaded to a client browser and processed. The following HTML\Javascript web page coding shows very simple coding to invoke a PWS PLB program after downloading the 'mypage.html' from a 3rd party Web Server. Example (1) using HTML web page with HTTP GET request: In this case, the following HTML page uses an HTTP GET request to logon to a PWS server when the submit operation occurs and the JavaScript document 'submit' instruction executes. Also, the 'runopt' and 'cmdline' data is added to the URL command by the client browser when the URL command is sent to the PWS server which executes the program 'userprog.plc'. In this case, the 'runopt' and 'cmdline' data appears in the browser URL command.
Example (2) using HTML web page with HTTP POST request: In this case, the following HTML page uses an HTTP POST request to logon to a PWS server where the submit operation is performed using a JavaScript instruction. Also, the 'runopt' and 'cmdline' data is submitted in the HTTP POST request without being shown to the end-user in the browser URL command.
- In the 'PL/B Web Server', 'Sunbelt Data Manager', and 'PL/B Application Server' manuals under the 'Administrative Emails' section, add the following sentence to the end of the first paragraph description. "When ADMIN email errors occur, the appropriate 'Mnn' errors are logged in the server log file where the 'Mnn' description is the same as documented under the 'M(MailSend) Errors' section in the 'PL/B Runtime Reference' manual." - In the PL/B Language Reference manual under the 'SQLIO Limitations' section, modify the Note (2.) to read as follows: 2. SQLIO DOES NOT support ISAM keys that do not exist in the record data. ISAM keys must be composed using complete SQL column data. - In the PL/B Language Reference manual under the 'SQLIO Administrative Tables', modify the 'Sun_Sqlio_Afile' 'key_info' column description to read as follows: key_info - Text column that contains AFILE key specifications that are the same as specified for an AFILE PREP instruction. Additionally, explicit column names can be specified instead of field/column position values. For example, the following AFile key specification format is allowed when using a column name. See 'SQLIO Schema File Format' for more details. "U,COLNAME,x20-25" - In the PL/B Language Reference manual under the 'SQLIO Schema File Format' section, modify the ' Schema Record' tag description to read as follows: This XML tag element has text data that contains one or more comma separated column names. - In the PL/B Runtime Reference manual under the 'I (I/O) Errors' section, add a new I86 subcode 53 error description as follows: I86 53 - The runtime has detected a SQL error creating a user SQL table. Two possible causes for this SQLIO error are described as follows: 1. There is a SQL statement syntax error which means that there is PLB SQLIO runtime error. 2. This error can also occur if the SQL statement encountered some kind of SQL Database Engine limitation issue or unexpected error. When this error is encountered, the end-user should gather the following information and send it to Sunbelt Support to be evaluated: 1. Use the PLB_SQLIO_DEBUG_LOG={LogFileName} keyword and capture a debug log file that contains the SQL statements that are executed when the I86 subcode 53 error occurs. 2. Send the PLB_SQLIO_DEBUG_LOG file that was captured. 3. Send the .PLC and .SDB of the failing program. 4. Send the a SQLIO schema that contains the schema definitions of the failing file\table. 5. Provide a basic description of the error encountered. - In the PL/B Runtime Reference manual under the 'I (I/O) Errors' section, modify the I86 subcode 36 error description to read as follows: I86 subcode 36 The runtime has detected a SQL language syntax error. This is caused by a SQL type mismatch caused by a SQLIO misconfiguration. The probable cause is the PLB_SQLIO_SQLTYPE keyword value is incorrect for the SQL database engine being used. If the PLB_SQLIO_SQLTYPE being used is correct, the end user should gather the following information and send to Sunbelt Support to be evaluated: 1. Use the PLB_SQLIO_DEBUG_LOG={LogFileName} keyword and capture a debug log file that contains the SQL statements that are executed when the I86 subcode 53 error occurs. 2. Send the PLB_SQLIO_DEBUG_LOG file that was captured. 3. Send the .PLC and .SDB of the failing program. 4. Send the a SQLIO schema that contains the schema definitions of the failing file\table. 5. Provide a basic description of the error encountered. - In the PL/B Language Reference manual under the 'EDITTEXT' section, add this new Note (10.) that reads as follows: Note the following: 10. Any character below 0x20 sent to an EDITTEXT is used\treated to give specific behaviors implemented by an OS/Browser. - In the PL/B Language Reference manual under the 'CLIENT' Methods section, add the 'SetUTF8Convert' and 'SetUTF16Table' method names to the CLIENT object method list. - In the PL/B Language Reference manual under the 'COPYFILE' instruction, change the descriptions as follows: Format: (2) [label] COPYFILE {source}{sep}{dest}{sep2}{retcount}[: MODE={mode}][{sep}BLOCKSIZE={size}][: DECRYPT={key}][{sep}ENCRYPT={key] Where: retcount Required. A Numeric Variable that returns the number of blocks required to complete the transfer using the format (2) which invokes the enhanced copyfile operation. Note the following: 1. The first syntax above (1) is a Simple Mode COPYFILE and the second syntax (2) is Enhanced Mode. The keywords MODE, BLOCKSIZE, DECRYPT, and ENCRYPT are only used for Enhanced copyfile operations using syntax (2) format. - In the PL/B Language Reference manual under the 'SQLIO Limitations' section, change the Note (2) to read as follows: 2. ISAM keys that do not exist in the record data are not supported. Conditional ISAM keys defined for primary record selection using the 'Px={yy}' key specification are not supported. - In the PL/B Utilities manual under the Sunlist utility, make the following changes. (1) Change the Note (9.) 'I' option as follows: Note: 9. Allowable {options} are as follows: I - List via ISI file. All records are listed unless a beginning key or line number is entered. If a beginning key is entered, it must immediately follow the 'I' option and must be enclosed in single quotes. Under Unix, the single quotes must each be preceded by a \. When using the Windows Command Shell, replace single quote characters with double quote characters to enclose the Isam key when it has embedded blank characters. - In the PL/B Language Reference manual under the '*IOCANCELCHAR (SETMODE)' section, modify the description as follows: Replace: "The {char} identifier is a character string variable, a literal, or one of the following values:" With: "The {char} is a Character String Variable or a Literal. The Character String Variable or Literal contains a single character value or it contains a character sequence defined as follows:" Add the following to the end: Examples: MyChar INIT "x" MyCharEsc INIT "Escape" . SETMODE *IOCANCELCHAR="a" //Single 'a' character is used. SETMODE *IOCANCELCHAR=MyChar //Single 'x' character is used. SETMODE *IOCANCELCHAR="F1" //F1 function key is used. SETMODE *IOCANCELCHAR=MyCharEsc //Escape character is used. . *============================================================================== The following files have been changed as noted: ------------------------------------------------------------------------------- All Sunbelt Products - Copyright changed for 2016 reference. ------------------------------------------------------------------------------- PLBSERVE - Added a new keyword for the Application server to enable extra program information when a socket error program reconnection errors are generated while accessing the SunDM Data Manager. The new keyword is named 'HandleSocketErrToDM_Debug={anything}'. If this keyword exists in the PLBSERVE INI [Environment] section and the ADMIN_LOGLEVEL keyword is set to a value of '2', the additional program information is logged when socket reconnection errors occur accessing the Data Manager. Example: PLBSERVE INI [Environment] ... HANDLESOCKETERRTODM_DEBUG=something ... ADMIN_LOGLEVEL=2 ... PLBSERVE LOG FILE Sample: HandleSocketErrToDM...Id:20 Thread Id: (1c58) HandleSocketErrToDM...Context State.....: 40 HandleSocketErrToDM...PL/B Program Name.: 'tmfio.plc' HandleSocketErrToDM...Current IP........: 0x00000094 HandleSocketErrToDM...Current OPCODE....: 0x4821 HandleSocketErrToDM...User Name.........: Edward HandleSocketErrToDM...Computer Name.....: HP-EDWARD HandleSocketErrToDM...Before ServerReConnectOne HandleSocketErrToDM...ServerReConnectOne Ok! ------------------------------------------------------------------------------- PLBWEBSRV (HTML\JS\CSS) - Modified to support 9.8A changes. plbwebbasic.css 9.8 plbwebbasic.js 9.8A plbwebctls.js 9.8A plbmobstart.html 9.8A New for Mobile App Support plbwebstart.html 9.8A plbwebidleterm.html 9.7C - Added a JavaScript source reference in the 'plbwebstart.html' named 'plbwebuser.js'. The 'plbwebuser.js' MUST be generated by the PLB developers who require JavaScript functions to be loaded in the client browser and executed using the WINAPI '!JS' instructions. Sunbelt DOES NOT provide nor ship a 'plbwebuser.js' file. Any PLB developers who use the 'plbwebuser.js' should have knowledge of JavaScript and know how to debug JavaScript logic using a client browser debug tools. Also, the PLB developers should not modify the 'plbwebbasic.js' and 'plbwebctls.js' as shipped by Sunbelt. - Modified the 'plbwebbasic.js' to support enhancements for the PWS server. - Modified the 'plbwebbasic.js' to support GetStorage and SetStorage CLIENT methods. - Modified the 'plbwebbasic.js' to detect unexpected exceptions. - Corrected a problem where a PWS EDITNUMBER object would unexpectedly display two decimal points after a tabbing action when the EDITNUMBER contained a negative value. - Corrected a problem for a PWS Combobox where HTML Entities (i.e. '&', '<', and '>' were being returned in the GETITEM instruction and the GetText method results when '&', '<' and '>' characters existed in COMBOBOX items. _ Corrected a problem where items formatted as '' was being misinterpreted as an HTML tag. In case, the COMBOBOX item showed as a blank line in the COMBOBOX item list. - Corrected a problem in the 'plbwebbasic.js' where the WINAPI support JS function was NOT returning a string when a JS Exception error occurred. - Corrected a problem where the 'mouseup' event for a child PANEL was bubbling\propagating to the parent PANEL. Without this fix, the parent PANEL could get an unexpected 'mouseup' event after a 'mouseup' event occurred for the child PANEL. ------------------------------------------------------------------------------- PLBWEBSRV - A PWS keyword named 'PLBWEB_MSGBUFFSIZE={size}' keyword has been added to allow the message size to be increased from 10240 bytes to a defined size. This keyword was being implemented to improve the DATALIST load times caused by an excessive number of TCP\IP messages like sending 3000 Datalist items from Australia to Austria, Canada, and the USA. - Modified to log more information when idle termination is sent to the client browser. - Modified the PRTPLAY instruction to give a U67 error which identifies that this instruction is NOT supported by the PL/B Web Server. - Modified the PRTOPEN instruction to give a U67 error when the {device} string is specified with a leading '!' character. This error occurs because there are NO client browser direct printing capabilities. - Modified the WINAPI DIM and PDIM data types to ONLY use the logical string of a DIM variable to be sent to a JavaScript function. Prior to this change the WINAPI was sending ALL of the data found in the DIM variable including data beyond the LL (Logical Length pointer). This issue could cause unexpected WINAPI errors to occur when accessing JavaScript functions. - Modified the PL/B Web Server to allow a PLB program to be invoked using an HTTP POST request embedded in an HTML web page. This support is implemented to allow a PLB user to specify the PWS 'cmdline' and 'runopt' command line keywords without showing the data to the end-user. This PWS logon method can be implemented using the HTML
element, element, and the submit button (i.e. ) or a JavaScript document submit instruction. Example (1) using HTML web page without Javascript: In this case, the following HTML page uses an HTTP POST request to logon to a PWS server where the submit operation is performed when the end-user clicks on the submit button. Also, the 'runopt' and 'cmdline' data is submitted in the HTTP POST request without being shown to the end-user on the browser URL.
Example (2) using HTML web page using Javascript: In this case, the following HTML page uses an HTTP POST request to logon to a PWS server where the submit operation is performed using a JavaScript operation. Also, the 'runopt' and 'cmdline' data is submitted in the HTTP POST request without being shown to the end-user on the browser URL.
- Modified the PWS CLIENT object to support two new methods named 'StorageGet' and 'StorageSet'. These methods can be used to allow user defined data to allow get and set operations for HTML5 'localStorage Object', HTML5 'sessionStorage Object', and browser cookies. See the following links for more information on the HTML5 storage objects: http://www.w3schools.com/html/html5_webstorage.asp These new CLIENT methods are described as follows: ............................................................... . StorageGet Method for CLIENT Object . The StorageGet method is used to retrieve HTML5 'localStorage Object', HTML5 'sessionStorage Object', and browser cookies data. The HTML5 storage objects can be used to store PL/B Web program data at the browser using the StorageSet method which can be retrieved at a later time or in another browser session using the StorageGet method. This method uses a {keyname} keyword to fetch data from the browser storage. See the following links for more information on the HTML5 storage objects: http://www.w3schools.com/html/html5_webstorage.asp The method uses the following format: [label] {object}.StorageGet [GIVING {return}]: USING [*KEY=]{keyname}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} A CLIENT object. {return} A Character String Variable that receives the string data retrieved from the browser storage. {keyname} A Character String Variable or literal that specifies the keyword name string that defines a unique storage\cookie keyword name at the browser to be used. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, OVER, ZERO Note the following: 1. The EOS flag is set to TRUE if the returned data is truncated. 2. The ZERO flag is set to FALSE. 3. The OVER flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000000 The default action by this method occurs when the *OPTIONS parameter is set to zero or when this parameter is not used. The default method operation is to use the browser 'localStorage object'. 0x00000001 This bit value causes this method to perform the operation using the browser 'sessionStorage object'. 0x00000002 This bit value causes this method to perform the operation using a browser storage cookie. ............................................................... . StorageSet Method for CLIENT Object . The StorageSet method is used to set HTML5 'localStorage Object', HTML5 'sessionStorage Object', and browser cookies. The HTML5 storage objects can be used to store PL/B Web program data at the browser which can be retrieved at a later time or in another browser session using the StorageGet method. This method uses a {keyname}/{value} to set or remove the storage or cookie data at the browser. See the following links for more information on the HTML5 storage objects: http://www.w3schools.com/html/html5_webstorage.asp The method uses the following format: [label] {object}.StorageSet [GIVING {return}]: USING [*KEY=]{keyname}][: [*VALUE=]{value}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} A CLIENT object. {return} A Numeric Variable that receives a value to pass or fail for the method execution. {keyname} A Character String Variable or literal that specifies the keyword name string that defines a unique storage\cookie keyword name at the browser to be used. {value} A Character String Variable or literal that optional specifies the string value to be stored for the {keyname} at the browser. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000000 The default action by this method occurs when the *OPTIONS parameter is set to zero or when this parameter is not used. The default method operation is to use the browser 'localStorage object'. 0x00000001 This bit value causes this method to perform the operation using the browser 'sessionStorage object'. 0x00000002 This bit value causes this method to perform the operation using a browser storage cookie. 5. If the {value} parameter is not specified when this method executes, the {keyname} is removed from the browser using the specific {keyname} for a storage object type. - A new keyword named 'PLBWEB_CGI_INFODIR={['path\']['prefix']}' has been added to the PWS server. When this keyword is specified in the PWS 'plbwebsrv.ini' configuration file [Environment] section, the PWS is enabled to capture CGI (Common Gateway Interface) data. When the CGI data is captured, it can be accessed\retrieved using the RUNTIME object 'CgiString' method. This keyword can be changed to take immediate affect without having to restart the PWS server. If this keyword is NOT used, the 'CgiString' method does not return any CGI data. PLBWEB_CGI_INFODIR={['path\']['prefix']} Where: 'path\' - The 'path\' is optional. It is an OS specific path where the CGI work files are to be located. If the 'path\' is not specified the CGI work files are located in the current work directory of the PWS server. 'prefix' - The 'prefix' is optional. It is a user defined pre prefix character sequence that is prepended to the CGI work files. If the 'prefix' is not specified, the CGI work file name simply does not have a user defined prefix. Note: 1. When the PLBWEB_CGI_INFODIR keyword is defined, the CGI work files are named using the following format: ['path\']['prefix']T{progid}.cgi Where: 'path\' is an optional OS path. 'prefix' is an optional user defined prefix character sequence. {progid} is the PWS child process unique identification number. 2. The CGI works files are temporary and immediately deleted after transferring the CGI data to the PWS child process. If the user defines the 'PLBWEB_CGI_KEEP=ON' keyword in the 'plbwebsrv.ini' file, the CGI files are NOT deleted. When this keyword is used, the PWS administrator is responsible for deleting the CGI files. Therefore, the 'PLBWEB_CGI_KEEP=ON' should ONLY be used when debugging and should NEVER be left defined for PRODUCTION operations for an extended period of time. Examples: [Environment] PLBWEB_CGI_INFODIR=z In this case, a CGI work file name 'zTnnnn.cgi' is created in the PWS current working directory. This CGI work file is immediately deleted after data is initially transferred to the PWS child process. PLBWEB_CGI_INFODIR= In this case, a CGI work file named 'Tnnnn.cgi' is created in the PWS current working directory. This CGI work file is immediately deleted after data is initially transferred to the PWS child process. PLBWEB_CGI_INFODIR=c:\temp\pwstmp\ In this case, a CGI work file named 'Tnnnn.cgi' is created in the 'c:\temp\pwstmp\' directory. This This CGI work file is immediately deleted after data is initially transferred to the PWS child process. PLBWEB_CGI_INFODIR=c:\temp\pwstmp\z_ In this case, a CGI work file named 'z_Tnnnn.cgi' is created in the 'c:\temp\pwstmp' directory. This CGI work file is immediately deleted after data is initially transferred to the PWS child process. - Modified the PWS RUNTIME object to support one new method named 'CgiString'. This method uses the CGI (Common Gateway Interface) to allow a PWS PLB program to retrieve keyword named parameters and HTTP Request header fields sent by the browser to the PWS server when a PLB program is started. These new CLIENT methods are described as follows: ............................................................... . CgiString Method for RUNTIME Object . The CgiString method is used to retrieve CGI (Common Gateway Interface) data that is received by the PWS when a PLB program is started. This method can be used to fetch the query string found in the HTTP request header. The full query string data stream can be retrieved or individual keyword named query string parameters can be retrieved. Regular precautions should be used when using CGI data like any other web server environment. Also, the 'PLBWEB_CGI_INFODIR={[path]+prefix}' must be specified in the Plbwebsrv.ini to enable PWS CGI data collecting. If this keyword is NOT used, there is NO CGI data collected by the PWS server and this method returns a NULL data string. The method uses the following format: [label] {object}.CgiString [GIVING {return}]: USING [*KEY=]{keyname}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} A RUNTIME object. {return} A Character String Variable that receives the CGI data retrieved from the HTTP Request header fields. {keyname} A Character String Variable or literal that specifies the keyword name string that defines the CGI data to be retrieved. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, OVER, ZERO Note the following: 1. The EOS flag is set to TRUE if the returned data is truncated. 2. The ZERO flag is set to FALSE. 3. The OVER flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000000 The default action by this method occurs when the *OPTIONS parameter is set to zero or when this parameter is not used. The default method operation is retrieve the QUERY_STRING or pre-defined HTTP Request header fields. See note (5a.) for more details. 0x00000001 This bit value causes this method to retrieve the data for a user specified keyword specified in the Query_String. See note (5b.) for more details. 0x00000002 This bit value causes this method to perform the same operation as described for the '0x00000000' default operation except all '+' characters are changed to a 0x20 blank character. In addition, all URL encoded character sequences are decoded. See note (6.) for more details. 5. When CGI data is being collected by the PWS server, there are two sets of data available to the PLB program that was transferred from the browser to the PWS server. a. The HTTP Request header fields of the original GET or POST message are captured so the PLB program can retrieve these fields. See the following link for more details on the HTTP header fields: "https://en.wikipedia.org/wiki/Common_Gateway_Interface" The PWS ONLY supports the following HTTP Request field keywords that can be retrieved using the CgiString method: AUTH_TYPE CONTENT_LENGTH CONTENT_TYPE QUERY_STRING REMOTE_ADDR REQUEST_METHOD REQUEST_URI SCRIPT_NAME SERVER_SOFTWARE SERVER_PROTOCOL SERVER_PORT HTTP_ACCEPT HTTP_ACCEPT_ENCODING HTTP_ACCEPT_LANGUAGE HTTP_COOKIE HTTP_HOST HTTP_REFERER HTTP_USER_AGENT b. When the browser performs the initial logon operation, a QUERY_STRING can be added to the URL, an HTML form using a GET or POST request. The QUERY_STRING contains keyword or parameter data that can be used by a PLB program. See the following link for more details on a QUERY_STRING: "https://en.wikipedia.org/wiki/Query_string" 6. The QUERY_STRING data can be retrieved either in a raw URL encoded format (i.e. Default behavior) or in a cooked mode (i.e. *OPTIONS=2) where the data is decoded to remove the URL encoding sequences. See the following link for more details on URL Encoding: "http://www.w3schools.com/tags/ref_urlencode.asp" 7. The following examples show CgiString operations that retrieve data when the 'PLBWEB_CGI_INFODIR' keyword is declared in the 'plbwebsrv.ini' configuration file. Example I. - Retrieve QUERY_STRING Raw Encoded Data R RUNTIME //Runtime object Raw Encoded Data R.CgiString Giving DATA Using "QUERY_STRING" Example II. - Retrieve QUERY_STRING Decoded Data R.CgiString Giving DATA Using "QUERY_STRING", 2 Example III. - Retrieve QUERY_STRING 'Name' Keyword Data R.CgiString Giving DATA Using "Name", 1 Example IV. - Retrieve QUERY_STRING 'cmdline' Keyword Data R.CgiString Giving DATA Using "cmdline", 1 Example V. - Retrieve HTTP 'REQUEST_URL' Keyword Data R.CgiString Giving DATA Using "REQUEST_URI" Example VI. - Retrieve HTTP 'HTTP_USER_AGENT' Keyword Data R.CgiString Giving DATA Using "HTTP_USER_AGENT" - Corrected a problem when using a PWS LISTVIEW object where the items of a row would disappear when the 'SetItemText' method was executed on column 0 that had a width of 0. - Corrected PWS LISTVIEW problem where the FindItem method was returning the wrong value. - Corrected PWS TABCONTROL problem where the SetTab method did not properly render tab changes which cause an invalid tab presentation. - Corrected a problem with a PWS multi-line EDITTEXT where the first character of the second line was missing using a SETPROP, INSERTITEM or SETITEM to send the following character sequence to the EDITTEXT. "{data}<0D><0A>{data|" where: <0D> is a 0x0D character value <0A> is a 0x0A character value Warning: Any character below 0x20 sent to an EDITTEXT is used\treated to give specific behaviors implemented by an OS\Browser. - Corrected a problem where a DATALIST did not appear\show in the client browser viewport when it was created with no data items. ------------------------------------------------------------------------------- PLBSERVE, PLBWEBSRV - Modified\cleaned up the command options '-f', '-r', '-s', and '-t' to pause after displaying messages so the end-user can read the message details. Also, the '-wn' command option can be used to specify a user defined pause. ------------------------------------------------------------------------------- PLBSERVE, PLBWEBSRV (Windows ONLY) - The PLBSERVE\PLBWEBSRV (Processed based) Windows OS servers have been modified to allocate a default 'Program Virtual Memory' size of 20,480,000 bytes. This 'Program Virtual Memory' size is the same as the PLBWIN\PLBNET runtimes. This change has been made to help reduce U09 errors that can occur when a PLB program size is larger than the default Application Server Virtual Memory. Note: 1. The 'plbserve.exe' binary is the Windows OS Application Server that generates child tasks as separate OS child processes. The 20,480,000 virtual memory default size change ONLY applies to this Application Server runtime. 2. The 'plbservet.exe' binary is the Windows OS Application Server that generates child tasks as separate child threads that exist for one 'plbservet.exe' process. In this case, the default virtual memory size is still 4,096,000 bytes. 3. The 'PLBCS_MAXPROGVMEM' or 'PLBWEB_MAXPROGVMEM' keyword can be used to override the default program virtual memory sizes. ------------------------------------------------------------------------------- PLBWIN, PLBNET - Corrected a problem where the DragDrop event was not being saved into a '.plf' form for a LISTVIEW object when using the PLB Designer. ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLBSERVE, PLBWEBSRV (Windows) - Corrected a GPF error that could occur if a 'CREATE CLIENT' instruction was executed. The 9.8A compiler has been modified to give a compiler error if a CREATE or DESTROY instruction is processed for a CLIENT, RUNTIME, or XDATA object. ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLBSERVE, PLB(UNIX), PLBWEBSRV - Added a new instruction named 'MOVEVARADDR'. This instruction moves the UDA memory address of the actual data for a DIM or INTEGER into a destination INTEGER by value. The destination INTEGER value can be used as a WINAPI parameter when the API parameter references a 'C' structure whose members are defined as some address of 'C' data. This instruction is being implemented to eliminate the need to use the MOVEA instruction when building 'C' structure data members. The MOVEVARADDR instruction is described as follows: MOVEVARADDR This instruction moves the UDA memory address of the actual data for a DIM or INTEGER into a destination INTEGER by value. The intended use of this instruction is eliminate the necessity of using a MOVEA instruction to determine the memory addresses which are required when using the WINAPI instruction. (1) [label] MOVEVARADDR {source} {sep} {dest} Where: {label} An optional Program Code Label. {source} A previously defined Character String Variable or INTEGER Variable whose data address is moved by value to the {dest} INTEGER Variable. {sep} A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO. {dest} A previously defined INTEGER Variable that has a size of 4 or 8 bytes. The UDA data address of the {source} is moved to the INTEGER by value. Flags Affected: NONE Note the following: 1. The UDA data address for the {source} variable points to the actual data after the header for the DIM or INTEGER variable. This memory address always points to the first byte following the header for {source} variable. For a DIM variable this may not be where the Form Pointer is pointing. 2. The primary use of the MOVEVARADDR instruction is to eliminate the required use of the MOVEA instruction when a WINAPI 'C' structure parameter requires embedded addresses of physical data that exists in a DIM or INTEGER variable. Example: ................................................................. . This sample for the MOVEVARADDR shows how the physical UDA . address of D2 can be used to build a PLB representation for . a 'C' structure. The PLB RECORD variables in this case are . being used to identify the 'C' structure members in PLB . variable terms. . %IFDEF NOTUSED ................................................................. . Sample 'C' structure with embedded 'C' integer and character . pointers. In this sample, the 'MQCDStruct' member is the . address of a second 'C' structure. . struct { long Strucid; long Version; long Options; long Offset; char* MQCDStruct; } %ENDIF . $0 INTEGER 4 BinZero INIT 0x00 ................................................................. . This RECORD provides a layout that can be used to populate a . DIM variable to represent the 'C' structure members. . S1 RECORD Strucid INTEGER 4 Version INTEGER 4 Options INTEGER 4 Offset INTEGER 4 pMQCDSTRUCT INTEGER 4 ;Address of second structure! RECORDEND ................................................................. . This is a second sample structure pointed to by . the 'pMQCDSTRUCT' member found in the 'S1' RECORD layout. . S2 RECORD A INTEGER 4 B INTEGER 4 C INTEGER 4 RECORDEND . D1 DIM 32 ;Working PLB DIM for 'C' S1 data. D2 DIM 32 ;Working PLB DIM for 'C' S2 data. . . Set the D1 and D2 data to be all binary zeros. . This is NOT needed. But, I prefer that all data in the DIM . initialized to binary zeros. . FILL BinZero,D1,D2 CLEAR D1,D2 . . Initialize S2 structure members . MOVE "1",S2.A MOVE "2",S2.B MOVE "3",S2.C PACK D2,S2 ;Structure 2 data is in the D2 dim! . . Initialize S1 structure members!! . MOVE "10",S1.Strucid MOVE "20",S1.Version MOVE "30",S1.Options MOVE "40",S1.Offset . . This MOVEVARADDR instruction moves the physical UDA address . of the data for the 'D2' DIM variable into the INTEGER . variable named 'S1.pMQCDSTRUCT'. . MOVEVARADDR D2,S1.pMQCDSTRUCT . . This PACK creates a 'C' structure representation that . is created in the 'D1' DIM variable. . . Note: . The 'S1.pMQCDSTRUCT' INTEGER contains the UDA physical . address of a SECOND 'C' structure that was packed\created . in the 'D2' DIM variable. . PACK D1,S1 ;Structure 1 data with pointer ;to Structure 2 data in pMQCDSTRUCT! . KEYIN "Hit enter to exit:",s$cmdlin . - Modified the HTTP instruction to support an unlimited HTTP header size. - Modified the error dialog to report the file name when an SQLIO IO operation encounters an error. - Added support for the READKEY instruction when a file variable is opened for SQLIO operations. - Modified the GETFILE instruction for a file variable opened for SQLIO to support the keywords named TXTNAME, ISINAME, AAMNAME, ISIRECORDLEN, and KEYLENGTH. Note: 21. When retrieving the following GETFILE keywords for a file variable opened for SQLIO operations, the returned names are described as follows: GETFILE TXTNAME (SQLIO) The TXTNAME keyword returns the schema data depending on whether a AFILE, FILE, or IFILE file variable is being used. The returned name is described as follows: FILE The TXTNAME name is retrieved from the 'Sun_Sqlio_File' schema data under the 'file_name' column. IFILE The TXTNAME name is retrieved from the 'Sun_Sqlio_IFile' schema data under the 'file_name' column. AFILE The TXTNAME name is retrieved from the 'Sun_Sqlio_AFile' schema data under the 'file_name' column. GETFILE ISINAME (SQLIO) The ISINAME keyword returns the SQLIO schema data as specified by the 'Sun_Sqlio_IFile' data under the 'name' column which is used for a file variable opened for SQLIO operations. GETFILE AAMNAME (SQLIO) The AAMNAME keyword returns the SQLIO schema data as specified by the 'Sun_Sqlio_AFile' data under the 'name' column which is used for a file variable opened for SQLIO operations. - Added new keys for the GETFILE instruction as follows: SQLIODATABASE={svar} This keyword gives the database name that exist on the SQL database engine where the file variable SQLIO data table exists. This database name may be specified in the 'Sun_Sqlio_Databases' administration schema table under the 'name' column. Otherwise, it may be specified by the attribute named 'database={databasename}' found in the 'SQLIO PLB Language Changes' section in the 'PL/B Language Reference' manual. SQLIOTABLE={svar} This keyword gives the name of the SQL table that is being used and contains the data for the file variable used for the SQLIO operations. This table name may be specified in the 'Sun_Sqlio_File' administration schema table under the 'table_name' column. Otherwise, it may be specified by the attribute named 'table_name={tablename}' keyword found in the 'SQLIO PLB Language Changes' section in the 'PL/B Language Reference' manual. SQLIOHOST={svar} This keyword gives the database source as specified\described by the following: 1. Sun_Sqlio_Databases schema 'host' column. 2. PLB_SQLIO_HOST keyword. 3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). SQLIOUSER={svar} This keyword gives the user name as specified\described by the following: 1. Sun_Sqlio_Databases schema 'user_name' column. 2. PLB_SQLIO_USER runtime keyword. 3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). SQLIOPASS={svar} This keyword gives the password as specified\described by the following: 1. Sun_Sqlio_Databases schema 'pass' column. 2. PLB_SQLIO_PASS runtime keyword. 3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). SQLIOCONN={svar} This keyword gives the login information as specified\described by the following: 1. Sun_Sqlio_Databases schema 'conn' column. 2. PLB_SQLIO_CONN runtime keyword. 3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). SQLIOEXT={svar} This keyword gives the extension data as specified\described by the following: 1. Sun_Sqlio_Databases schema 'ext' column. 2. PLB_SQLIO_EXT runtime keyword. 3. The 'SETMODE *SQLTABLEDB' keyword under the Note (3). - Modified the WRITE operations to a SunDM data manager to generate an I82 subcode 35 error when a single DIM variable in the WRITE variable list has a size larger than 64KB. All DIM variables written to a Data Manager must have a size less than 65536 bytes. - Modified the READ operations to a pre 9.8A version SunDM Data Manager to generate an I82 subcode 37 error when a DIM variable in the variable list is larger than 65535 bytes. All DIM variables being used for a READ from the Data Manager must have a size less than 65536 bytes. - Modified the PLB runtimes and Sundm servers to allow the *CDFON IO control delimiter character (i.e. comma) to be defined and set by the end user application as follows: 1. Use new runtime\sundm keyword named 'PLB_CDFDELMDEFAULT={delmchr}'. 2. Use 'SETMODE *CDFDELMDEFAULT={svar}' instruction to set the *CDFON delimiter character under program control. When the 'SETMODE *CDFDELMDEFAULT' instruction is executed in a program, the 'SETMODE CDFDELMDEFAULT' replaces the setting specified by the 'PLB_CDFDELMDEFAULT' runtime keyword. 3. When executing under Windows OS, enable the *CDFON locale delimiter mode which causes the Windows Locale List Separator OS setting to be used for the *CDFON delimiter character. The Windows OS locale mode can be enabled using the 'SETMODE *CDFDELMUSELOCALE=1' instruction. Enabling the locale mode takes precedence over all other settings used for the *CDFON delimiter character. 4. Use a new OPEN\PREP {mode} parameter bit setting named 'CMP_LOCALECDF' which invokes the Windows OS locale mode for the file variable. Using the 'CMP_LOCALECDF' mode setting takes precedence over all other *CDFON delimiter character settings and CAN NOT be changed as long as the file variable is opened. The 'CMP_LOCALECDF' ONLY applies to AFILE, FILE, and IFILE variables. - Added a new {mode} bit parameter for the OPEN\PREP instructions to enable the Windows OS locale mode to allow the Windows OS list separator locale setting (i.e. single character) to be used in place of the *CDFON delimiter character. This new {mode} bit parameter is described as follows: CMP_LOCALECDF - 0x01000000 (Windows OS ONLY!) This {mode} bit setting enables the Windows OS locale mode which causes the *CDFON delimiter character (i.e. normally comma) to be replaced by the Windows OS List Separator locale character setting (i.e. single character used!). - Added new keywords to the GETMODE and SETMODE instructions as follows: GETMODE *CDFDELMDEFAULT={svar} The CDFDELMDEFAULT keyword retrieves the current runtime setting for the user default CDF delimiter. The user default CDF delimiter can be set using the runtime INI keyword named 'PLB_CDFDELMDEFAULT={dlmchr}' or the 'SETMODE *CDFDELMDEFAULT={svar}' instruction. GETMODE *CDFDELMLOCALE={svar} (Windows ONLY) The CDFDELMLOCALE keyword retrieves the current runtime OS locale list separator setting for Windows OS. Since there is no locale list separator for the Linux\Unix OS environments, this keyword always returns a NULL using Linux\Unix runtimes. GETMODE *CDFDELMUSELOCALE={nvar} The CDFDELMUSELOCALE keyword retrieves the current runtime state flag which enables\disables the locale list separator substitution for the *CDFON operations. The locale list separator is only used for the Windows OS environments and is ignored for the Linux\Unix environments. SETMODE *CDFDELMDEFAULT={svarlist} The CDFDELMDEFAULT keyword sets the current runtime setting for the user default CDF delimiter. The user default CDF delimiter can be set using the runtime INI keyword named 'PLB_CDFDELMDEFAULT={svar}' or the 'SETMODE *CDFDELMDEFAULT={svar}'. If the 'SETMODE *CDFDELMDEFAULT=NULL' instruction is executed, the PLB runtime reverts back to using the ',' (i.e. comma) as the *CDFON delimiter character. SETMODE *CDFDELMUSELOCALE={dnumnvar} The CDFDELMUSELOCALE keyword sets the current runtime state flag which enables\disables the locale list separator substitution for the *CDFON operations. The locale list separator is only used for the Windows OS environments and is ignored for the Linux\Unix environments. For a Windows OS runtime, the execution of the 'SETMODE *CDFDELMUSELOCALE=1' takes precedence over user defined delimiter character setting. - Added a new runtime keyword named 'PLB_CDFDELMDEFAULT={delmchr}' which can be used to set the runtime user defined delimiter character for *CDFON operations. When this keyword is used, the default *CDFON delimiter character is used unless the 'SETMODE *CDFDELMDEFAULT={svar}' instruction is used. For a Windows OS runtime, the execution of the 'SETMODE *CDFDELMUSELOCALE=1' takes precedence over user defined delimiter character setting. - Added new keywords to the GETFILE instruction as follows: CDFDELMCHAR={svar} This keyword returns the *CDFON user defined delimiter character which was determined when the file variable was opened or prepared. If the returned {svar} is NULL, there is NO user defined delimiter substitution being used for the file variable and thus, the normal comma delimiter is used\expected. OSLOCALEDELMCHAR={svar} This keyword returns the Windows OS locale list separator character available when the file variable was opened or prepared. This keyword provides information only and does not have any impact on the behavior of the *CDFON control. If the returned {svar} is NULL, there was NO OS locale list separator available when the file was opened or prepared. The Linux\Unix runtime and data managers DO NOT have locale list separators and therefore a NULL is expected. - Added a new method named 'JsMakeString' for the CLIENT object. This method takes a PLB DIM string and converts it into a properly formatted json string. This method can be used to help generate a json string with appropriate UTF8 conversion and data escaping. This method is intended to simplify conversion of a PLB string into a json format. This method are described as follows: ............................................................... . JsMakeString Method for CLIENT Object . The JsMakeString method can be used to convert a PLB DIM data string into a properly formatted JSON string including UTF8 conversion and data escaping. The method uses the following format: [label] {object}.JsMakeString GIVING {return}: USING [Text=]{inputstr} Where: {label} An optional Program Code Label. {object} A CLIENT object. {return} A Character String Variable that returns the result as a properly formatted json string. {inputstr} A Character String Variable or literal that contains the input PLB string to be converted into a JSON string. Flags Affected: EOS, OVER, ZERO Note the following: 1. The EOS flag is set to TRUE if the returned data is truncated. 2. The ZERO flag is set to FALSE. 3. The OVER flag is set to FALSE. 4. The {return} string is always generated with a leading and trailing double quote character (i.e. '"'). 5. Any embedded '\' or '"' characters in the {inputstr} data is escaped with a leading '\' character as: 6. Any characters in the {inputstr} with a character value greater than 0x7F are converted to a UTF8 sequence. 7. Any characters in the {inputstr} with a value less than 0x20 are converted to a 0x20 value except for the following characters: 0x08 - '\b' 0x0A - '\n' 0x0D - '\r' Example CLIENT 'JsMakeString: A INIT "Hello World" B INIT "Hi there #"Bill#"!" C INIT 0x08,0x0D,0x0A RESDATA DIM 50 CL CLIENT ... CL.JsMakeString GIVING RESDATA USING A DISPLAY "A--->",*ll,RESDATA,"<---" CL.JsMakeString GIVING RESDATA USING B DISPLAY "B--->",*ll,RESDATA,"<---" CL.JsMakeString GIVING RESDATA USING C DISPLAY "C--->",*ll,RESDATA,"<---" Keyin "Hit enter to exit: ",A Stop - Modified the 'SCHEMA {database},IMPORT={svar}' to create empty SQLIO administrative system tables without causing an error when the {svar} is a PLB NULL variable. This change ONLY applies to the SQLIO schema operations and requires the 'FLAGS={dnumnvarlit}' bit mask value of 0x8. Otherwise, the {svar} CAN NOT be specified as a PLB NULL variable which causes an appropriate error. - A new object named 'XDATA' has been added to all runtimes to allow for generation and parsing of XML and JSON data structures. In addition, this implementation can be used to create HTML pages, SOAP messages, REST, and JSON data. The XDATA object exists in all PLB runtimes and ONLY supports methods to process the XML and JSON data. In addition, the XDATA object is similar to the CLIENT and RUNTIME objects where these objects are NOT created. *---------------------------------------------------------------------- XDATA Object Events: None Properties: None Methods: Any PLB developer that uses the XDATA methods should have a working knowledge of the DOM, XML, and JSON concepts to be able to create\use well-formed XML\JSON documents. ChildCount GIVING {nvar} CreateAttribute GIVING {nvar}: USING *POSITION={dnumnvar}: *LABEL={svarslit}: *TEXT={svarslit}: *JSONTYPE={dnumnvar}: Optional *OPTIONS={dnumnvar} Optional CreateComment GIVING {nvar}: USING *POSITION={dnumnvar}: *COMMENT={svarslit}: *OPTIONS={dnumnvar} Optional CreateDocType GIVING {nvar}; USING *POSITION={dnumnvar}: *NAME={svarslit}: *SYSID={svarslit}: Optional *PUBID={svarslit}: Optional *OPTIONS={dnumnvar} Optional CreateElement GIVING {nvar}: USING *POSITION={dnumnvar}: *LABEL={svarslit}: *TEXT={svarslit}: Optional *JSONTYPE={dnumnvar}: Optional *OPTIONS={dnumnvar} Optional CreatePI GIVING {nvar}: USING *POSITION={dnumnvar}: *TARGET={svarslit}: *DATA={svarslit}: *OPTIONS={dnumnvar} Optional CreateText GIVING {nvar}: USING *POSITION={dnumnvar}: *TEXT={svarslit}: *JSONTYPE={dnumnvar}: Optional *OPTIONS={dnumnvar} Optional DeleteNode GIVING {nvar}: USING *POSITION={dnumnvar} Optional FindNode GIVING {nvar}: USING *FILTER={svarslit}: *POSITION={dnumnvar}: Optional *OPTIONS={dnumnvar} Optional FindNext GIVING {nvar} GetComment GIVING {svar} GetData GIVING {svar} GetExtendedError GIVING {svar} USING *OPTIONS={dnumnvar} Optional GetJsonType GIVING {nvar} GetLabel GIVING {svar} GetName GIVING {svar} GetPubId GIVING {svar} GetPosition GIVING {nvar} GetSysId GIVING {svar} GetTarget GIVING {svar} GetText GIVING {svar} GetType GIVING {nvar} LoadJson GIVING {nvar}: USING *DATA={svarslit}: *OPTIONS={dnumnvar} Optional LoadXml GIVING {nvar}: USING *DATA={svarslit}: *OPTIONS={dnumnvar} Optional MoveToNode GIVING {nvar}: USING *POSITION={dnumnvar} Reset GIVING {nvar} SaveJson GIVING {nvar}: USING *FILENAME={svarslit}: *OPTIONS={dnumnvar} Optional SaveXml GIVING {nvar}: USING *FILENAME={svarslit}: *OPTIONS={dnumnvar}: Optional *ROOTNAME={svarslit} Optional StoreJson GIVING {svar}: USING *OPTIONS={dnumnvar} Optional StoreJsonSize GIVING {nvar}: USING *OPTIONS={dnumnvar} Optional StoreXml GIVING {svar}: USING *OPTIONS={dnumnvar}: Optional *ROOTNAME={svarslit} Optional StoreXmlSize GIVING {nvar}: USING *OPTIONS={dnumnvar}: Optional *ROOTNAME={svarslit} Optional UpdateNode GIVING {nvar}: USING *LABEL={svarslit}: Optional *TEXT={svarslit}: Optional *JSONTYPE={dnumnvar}: Optional *NAME={svarslit}: Optional *SYSID={svarslit}: Optional *PUBID={svarslit}: Optional *COMMENT={svarslit}: Optional *TARGET={svarslit}: Optional *DATA={svarslit} Optional Method Return Error Values: XDATA_ERR_NONE EQU 0 Method executed successfully. XDATA_ERR_NO_MEM EQU 1 Insufficient memory to execute method. XDATA_ERR_INVALID_POSITION_TYPE EQU 2 The method position type is invalid as described in the 'POSITION Types' or 'Create POSITION Types' constants. XDATA_ERR_INVALID_DELETE_NODE EQU 3 There is no node in that position to delete. XDATA_ERR_NODE_NOT_FOUND EQU 4 The specified node could not be found. XDATA_ERR_INVALID_UPDATE_DATA EQU 5 This node type does not have this type of data. The specified node type is invalid for the type of data being used. XDATA_ERR_NO_CURRENT_POSITION EQU 6 There is no Current position to be used for the method. XDATA_ERR_DOCUMENT_POSITION EQU 7 The method action is not allowed at document position. XDATA_ERR_BAD_FILTER_FIELD EQU 8 Filter used field identifier that is not one of the following: Comment Data JsonType Label Name ParentLabel PubId SysId Type Text Target XDATA_ERR_BAD_FILTER EQU 9 Filter Syntax is incorrect. XDATA_ERR_NO_CURRENT_FILTER EQU 10 No valid filter has been previously given. XDATA_ERR_INVALID_POSITION EQU 11 No node exists at that position. (i.e. MOVE_FIRST_CHILD when node has no children). XDATA_ERR_OPEN_FAILED EQU 12 Unable to open a file on loading a JSON or XML file. XDATA_ERR_PARSER_CREATE EQU 13 Unable to create expat parser. XDATA_ERR_PARSE EQU 14 Unable to parse XML or JSON file. XDATA_ERR_FILE_CREATE EQU 16 Unable to create a file when saving JSON or XML. XDATA_ERR_FILE_TOO_BIG EQU 17 Unable to store JSON or XML string into given variable. XDATA_ERR_BAD_WRITE EQU 18 Unable to write to a file when saving JSON or XML. XDATA_ERR_XMLSUBERRSTART EQU 500+nn All errors between 500 to 600 are XML sub errors where the 'nn' value represents the XML error. The XML sub errors can be found in the 'PL/B Runtime Reference' manual in the 'I(I/O) Errors' section in 'XML base handler' table. Overview\Definitions: DOM The Document Object Model (DOM) is an interface for valid HTML and well-formed XML documents. The DOM relationships are described as follows: The entire document is a document node. Every XML element is an element node. The text in the XML elements are text nodes. Every attribute is an attribute node. Comments are comment nodes Terms DOM_ATTRIBUTE_NODE is formed as: label The 'label' is a named reference for the node. In XML, the 'label' is the tag name (ie. label="value"). In JSON, the 'label' is the name component in a JSON name/value pair (i.e. "label":value). text The 'text' is the value component for the node. In XML, the 'text' is the value (i.e. label="value"). In JSON, the 'text' is the value in a JSON name/value pair (i.e. "label":value). JsonType The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The value for JSON value may or may not be enclosed in double quotes depending on the 'jsontype'. DOM_TEXT_NODE is formed as: label The 'label' does not exist for a DOM_TEXT_NODE. text The 'text' is the value component for the node. In XML, the 'text' is the value (i.e. label="value"). In JSON, the 'text' is the value in a JSON name/value pair (i.e. "label":value). JsonType The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The value for JSON value may or may not be enclosed in double quotes depending on the 'jsontype'. DOM_ELEMENT_NODE is formed as: label The 'label' is a named reference for the node. In XML the 'label' is the tag name (ie. ). In JSON, the 'label' is the name component in a JSON name/value pair (i.e. "label":value). text The 'text' does not exist for DOM_ELEMENT_NODE. children nodes The children nodes can be DOM_ATTRIBUTE_NODE, DOM_TEXT_NODE, or DOM_ELEMENT_NODE nodes that are used for the value component for the DOM_ELEMENT_NODE. JsonType The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The supported 'jsontype' values are only JSON_TYPE_ARRAY, JSON_TYPE_OBJECT, or JSON_TYPE_NONE. Node A Node represents a logical construct in a DOM type of document. A node can be an element node, an attribute note, a text node, etc... The NODE types used in the XDATA implementation are defined as follows: Document - Represents the entire document. This node is never created, but it is used for positioning. DocumentType - Provides an interface to the entities or legal building blocks of an XML document. ProcessingInstruction - Represents a node type that can occur anywhere in a document and is intended to carry instructions to an application. Element - Represents an element that includes everything from (including) the element's start tag to (including) the element's end tag. Attribute - Represents the attribute information used to describe the XML element. Text - Represents textual content in an element. Comment - Comment represented in an XML document as content between ''. In XML, the character sequence '--' cannot be used within a document. POSITIONING The nodes in the node tree have a hierarchical relationship to each other. The terms parent, child, and sibling are used to describe the node relationships. The support node positions are defined as follows: Node Tree The XML DOM views an XML document as a tree-structure. The tree structure is called a node-tree. All nodes can be accessed through the tree. Their contents can be modified or deleted, and new elements can be created. A node tree starts at the document node and branches out to the text nodes at the lowest level of the tree. Node Parents, Children, and Siblings The nodes in a node tree have a hierarchical relationship to each other. The terms parent, child, and sibling are used to describe the relationships. Parent nodes have children. Children on the same level are called siblings (brothers or sisters). The following characteristics are used for nodes: - In a node tree, the top node is called the document. - Every node, except the document node, has exactly one parent node. - A node can have any number of children. - A leaf is a node with no children. - Siblings are nodes with the same parent. Positioning Parameter values A position parameter value can be a position type or a position type added to a value returned by the GetPosition method. The basic positioning values are defined as follows: MOVE_CURRENT_NODE EQU 0 Stay at the current node location. MOVE_PARENT_NODE EQU 1 Move to parent node. MOVE_FIRST_CHILD EQU 2 Move to first child node. MOVE_LAST_CHILD EQU 3 Move to last child node. MOVE_PREVIOUS_SIBLING EQU 4 Move to previous sibling node. MOVE_NEXT_SIBLING EQU 5 Move to next sibling node. MOVE_DOCUMENT_NODE EQU 6 Move to document position. The position parameter values can be specified using one of three formats as follows: Static Pre-Defined Position Values MOVE_CURRENT_NODE EQU 0 MOVE_PARENT_NODE EQU 1 MOVE_FIRST_CHILD EQU 2 MOVE_PREVIOUS_SIBLING EQU 4 MOVE_NEXT_SIBLING EQU 5 MOVE_DOCUMENT_NODE EQU 6 GetPosition Direct Values The {return} position value from the 'GetPosition' method identifies a unique number assigned to each node in the node tree. This 'GetPosition' value can be used to position directly to a node in the node tree. Combined Pre-Defined Plus GetPosition Direct Values In this case, the position parameter is performed in two steps as follows: 1) The first step is to use the to position directly to a node. 2) The second step is to use the position value to perform the final positioning action starting from the position in the first step. Example Combination Position: {position} = + JSON Specifics See the following link for basic JSON syntax elements and rules: http://www.w3schools.com/js/js_json.asp JSON only uses the DOM_ATTRIBUTE_NODE, DOM_ELEMENT_NODE, and DOM_TEXT_NODE nodes. Any other DOM node types are ignored. XDATA process overview as follows: DOM_ATTRIBUTE_NODE translates as: LABEL becomes the name in the name/value pair. TEXT becomes the value in the name/value pair. DOM_ELEMENT_NODE translates as: LABEL becomes the name in the name/value pair. Children nodes become the value in the name/value pair. DOM_TEXT_NODE translates as: TEXT becomes the value in the name/value pair. A JSON array is a DOM_ELEMENT_NODE with a label of array and jsontype of JSON_TYPE_ARRAY. It can have multiple DOM_TEXT_NODE as values and multiple DOM_ELEMENT_NODE as object values. A JSON object is a DOM_ELEMENT_NODE with a label of object and jsontype of JSON_TYPE_OBJECT. It can have multiple DOM_ATTRIBUTE_NODE and DOM_ELEMENT_NODE nodes as key value pairs. XDATA to JSON Syntax Format: The JSON format is syntactically identical to the code for creating JavaScript objects. Because of this similarity, a JavaScript program can easily convert JSON data into native JavaScript objects. JSON Syntax Rules - Data is in name/value pairs - Data is separated by commas - Curly braces hold objects - Square brackets hold arrays JSON Data - A Name and a Value JSON data is written as name/value pairs, just like JavaScript object properties. A name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value: "firstName":"John" Where: "firstName" is a JSON name field. ':' colon character separates the name and value fields. "John" is the JSON value field. Note: JSON names require double quotes. JavaScript names don't. XML Node Creation Types DOM_ATTRIBUTE_NODE - Generated as label="value" inside an element tag. DOM_COMMENT_NODE - Generated as DOM_DOCUMENT_TYPE_NODE - Generated as Example: DOM_ELEMENT_NODE - Generated as a set. DOM_PROCESSING_INSTRUCTION_NODE - Generated as . Example: target -> 'xml-stylesheet' data -> 'type="text/css" href="style.css"' DOM_TEXT_NODE - Generated as just text. *********************************************************************** Here is a description of the methods supported for the XDATA object: *********************************************************************** ....................................................................... . ChildCount Method for XDATA Object . The ChildCount method can be used to retrieve the number of direct children that exists for the current node. The method uses the following format: [label] {object}.ChildCount [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} Is a Numeric Variable that receives child count. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The child count includes any child node type that is immediately connected to a parent node. ....................................................................... . CreateAttribute Method for XDATA Object . The CreateAttribute method is used to create an attribute node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The method uses the following format: [label] {object}.CreateAttribute [GIVING {return}]: USING [*POSITION=]{createpos}: [*LABEL=]{labelname}: [*TEXT=]{text}[: [*JSONTYPE=]{type}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the attribute is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new attribute node. {labelname} A Character String Variable or literal that specifies the label string value of the node. {text} A Character String Variable or literal that specifies the text string value of the node. {type} A decimal number or Numeric Variable that optional specifies the a jsontype value used when outputing a document for JSON. This parameter is ONLY used for JSON output which causes the {text} data to be enclosed in double quotes when the JSON_TYPE_STRING is used. Otherwise, the JSON {text} is not enclosed by double quotes for any other JSON type value. If this parameter is NOT used, the JSON output defaults to use JSON_TYPE_STRING. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {createpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the attribute. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 ............................................................... . CreateComment Method for XDATA Object . The CreateComment method is used to create a comment node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The method uses the following format: [label] {object}.CreateComment [GIVING {return}]: USING [*POSITION=]{createpos}: [*COMMENT=]{comment}[: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the comment is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new comment node. {comment} A Character String Variable or literal that specifies the comment string value of the node. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {creatpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the comment. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 ............................................................... . CreateDocType Method for XDATA Object . The CreateDocType method is used to create a document type node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The method uses the following format: [label] {object}.CreateDocType [GIVING {return}]: USING [*POSITION=]{createpos}: [*NAME=]{name}[: [*SYSID=]{sysid}][: [*PUBID=]{pubid}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the document type is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new document type node. {name} A Character String Variable or literal that specifies the name string value of the node represented as %name% in Note 7. {sysid} A Character String Variable or literal that Optional specifies the sysid string value of the node represented as %sysid% in Note 7. {pubid} A Character String Variable or literal that Optional specifies the pubid string value of the node represented as %pubid% in Note 7. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {creatpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the document. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 7. The CreateDocType method generates a document node formatted as follows: Example: Where: %name% is replaced with: html %pubid% is replaced with: "-//W3C//DTD XHTML 1.0 Strict //EN" %sysid% is replaced with: "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> ............................................................... . CreateElement Method for XDATA Object . The CreateElement method is used to create an element node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The method uses the following format: [label] {object}.CreateElement [GIVING {return}]: USING [*POSITION=]{createpos}: [*LABEL=]{labelname}[: [*TEXT=]{text}][: [*JSONTYPE=]{type}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the element is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new element node. {labelname} A Character String Variable or literal that specifies the label string value of the node. {text} A Character String Variable or literal that optional specifies the text string value of the node. If the {text} parameter is given, the element node is created as a child DOM_TEXT_NODE as the first child. {type} A decimal number or Numeric Variable that optional specifies the a jsontype value used when outputing a document for JSON. This parameter is ONLY used for JSON output which causes the {text} data to be enclosed in double quotes when the JSON_TYPE_STRING is used. Otherwise, the JSON {text} is not enclosed by double quotes for any other JSON type value. If this parameter is NOT used, the JSON output defaults to use JSON_TYPE_STRING. The JSONTYPE parameter applies the JSON {type} value to the DOM_ELEMENT_NODE node if no {text} parameter is given. Otherwise, the JSONTYPE parameter applies the JSON {type} value to the child DOM_TEXT_NODE. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {createpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the attribute. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 7. If the {text} parameter and the JSON {type} parameters are not being used, the default method behavior when outputing a JSON document is to generate a JSON object. 8. EXAMPLES of CreateElement Method usage: I. Example of CreateElement method for JSON or XML: xData XDATA . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_LAST_CHILD: *LABEL="employee": *JSONTYPE=JSON_TYPE_OBJECT: *OPTIONS=MOVE_TO_CREATED_NODE . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_FIRST_CHILD: *LABEL="firstName": *TEXT="John": *JSONTYPE=JSON_TYPE_STRING: *OPTIONS=MOVE_TO_CREATED_NODE xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_NEXT_SIBLING: *LABEL="lastName": *TEXT="Doe": *JSONTYPE=JSON_TYPE_STRING In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods "employee":{"firstName":"John", "lastName":"Doe"} In this case, the "employee" is a JSON object with two JSON fields named "firstName" and "lastName". These JSON fields have a value that is a JSON string. In this example code, the following simple XML string is created by the previous XDATA CreateElement methods John Doe II. Example of CreateElement method for JSON or XML when NO {text} or JSON {type} parameters are used. In this example, all of the elements are defaulting to a JSON_TYPE_OBJECT. xData XDATA . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_LAST_CHILD: *LABEL="employee": *OPTIONS=MOVE_TO_CREATED_NODE . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_FIRST_CHILD: *LABEL="firstName": *OPTIONS=MOVE_TO_CREATED_NODE xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_NEXT_SIBLING: *LABEL="lastName" In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods where the "firstName" and the "lastName" are JSON objects that are empty. "employee":{"firstName":{}, "lastName":{}} In this case, the "employee" is a JSON object with two JSON fields named "firstName" and "lastName". These JSON fields have a value that is an empty JSON object. In this example code, the following simple XML string is created by the previous XDATA CreateElement methods. III. Example of CreateElement method for JSON or XML for array output: xData XDATA . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_LAST_CHILD: *LABEL="employee": *JSONTYPE=JSON_TYPE_ARRAY: *OPTIONS=MOVE_TO_CREATED_NODE . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_FIRST_CHILD: *LABEL="firstName": *TEXT="John": *JSONTYPE=JSON_TYPE_STRING: *OPTIONS=MOVE_TO_CREATED_NODE . xData.CreateElement GIVING result: USING *POSITION=CREATE_AS_NEXT_SIBLING: *LABEL="lastName": *TEXT="Doe": *JSONTYPE=JSON_TYPE_STRING In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods to output a JSON array. "employee":[{"firstName":"John"}, {"lastName":"Doe"}] In this case, the "employee" is a JSON array with two array JSON object elements. In this example code, the following simple XML string is created by the previous XDATA CreateElement methods John Doe ............................................................... . CreatePI Method for XDATA Object . The CreatePI method is used to create a DOM_PROCESSING_INSTRUCTION node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The DOM_PROCESSING_INSTRUCTION node is ignore for JSON output. The method uses the following format: [label] {object}.CreatePI [GIVING {return}]: USING [*POSITION=]{createpos}: [*TARGET=]{target}: [*DATA=]{data}[: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the processing instruction node is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new processing instruction node. {target} A Character String Variable or literal that specifies the target string value of the node. The {target} string value replaces the %target% field in the PI. {data} A Character String Variable or literal that specifies the data string value of the node. The {data} string value replaces the %target% field in the PI. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {createpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the PI. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 7. The DOM_PROCESSING_INSTRUCTION node is only used to generate XML with the following format: Where: %target% The name that immediately follows the leading '?' is the name of the Processing Instruction (PI). The target string must be followed by a space. %data% Any %data% following the %target% is the content of the PI up to the trailing '?' character. Example: %Target% --> xml-stylesheet %Data% --> href="mystyle.css" type="text/css" 8. EXAMPLES of CreatePI Method usage: I. Example of CreatePI method for XML: xData XDATA xTarget INIT "xml-stylesheet" xData INIT "href=#"mystyle.css#" type=#"text/css#"" . xData.CreatePI GIVING result: USING *POSITION=CREATE_AS_PARENT_NODE: *TARGET=xTarget: *DATA=xData: *OPTIONS=MOVE_TO_CREATED_NODE . In this example code, the following simple XML string is created by the previous XDATA CreatePI method ............................................................... . CreateText Method for XDATA Object . The CreateText method is used to create a DOM_TEXT_NODE node at a specified position. If the position is MOVE_CURRENT_NODE, the current node is replaced. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used. The method uses the following format: [label] {object}.CreateText [GIVING {return}]: USING [*POSITION=]{createpos}: [*TEXT=]{text}[: [*JSONTYPE=]{type}][: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {createpos} A decimal number or Numeric Variable that specifies the position in the node tree where the text node is inserted. If the {createpos} value is CREATE_AS_CURRENT_NODE, the current node is replaced with the new text node. {text} A Character String Variable or literal that specifies the text string value of the node. {type} A decimal number or Numeric Variable that optional specifies the a jsontype value used when outputing a document for JSON. This parameter is ONLY used for JSON output which causes the {text} data to be enclosed in double quotes when the JSON_TYPE_STRING is used. Otherwise, the JSON {text} is not enclosed by double quotes for any other JSON type value. If this parameter is NOT used, the JSON output defaults to use JSON_TYPE_STRING. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The create {createpos} position values are defined as follows: CREATE_AS_CURRENT_NODE EQU 0 - Replace the current node. CREATE_AS_PARENT_NODE EQU 1 - Insert node as the parent. CREATE_AS_FIRST_CHILD EQU 2 - Insert node as first child node CREATE_AS_LAST_CHILD EQU 3 - Insert node as last child node CREATE_AS_PREVIOUS_SIBLING EQU 4 - Insert node as previous sibling node CREATE_AS_NEXT_SIBLING EQU 5 - Insert node as next sibling node 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current node tree position to be changed to the newly created node position of the text. See the MOVE_TO_CREATE_NODE value. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_POSITION EQU 11 7. EXAMPLES of CreateText Method usage: I. Example of CreateText method for XML: xData XDATA xText INIT "Somebody Listening?" . xData.CreateText GIVING result: USING *POSITION=CREATE_AS_FIRST_CHILD: *TARGET=xText: *OPTIONS=MOVE_TO_CREATED_NODE . In this example code, the following simple JSON string is created by the previous XDATA CreateText method {"Somebody Listening?"} In this example code, the following simple XML string is created by the previous XDATA CreateText method Somebody Listening? ............................................................... . DeleteNode Method for XDATA Object . The DeleteNode method is used to delete a node including all children at a specified position. The method uses the following format: [label] {object}.DeleteNode [GIVING {return}]: USING [*POSITION=]{deletepos} Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {deletepos} A decimal number or Numeric Variable that specifies the position in the node tree where the node is deleted. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The delete {deletepos} position values are defined as follows: DELETE_CURRENT_NODE EQU 0 - Delete the current node and all of its children. DELETE_PARENT_NODE EQU 1 - Delete the parent node and all of its children. DELETE_FIRST_CHILD EQU 2 - Delete the first child node and all of its children. DELETE_LAST_CHILD EQU 3 - Delete the last child node and all of its children DELETE_PREVIOUS_SIBLING EQU 4 - Delete the previous sibling node and all of its children. DELETE_NEXT_SIBLING EQU 5 - Delete the next sibling node and all of its children. DELETE_DOCUMENT_NODE EQU 6 - Position to the document node and all the children. 5. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_INVALID_DELETE_NODE EQU 3 XDATA_ERR_INVALID_POSITION EQU 11 6. EXAMPLE of DeleteNode Method usage: I. Example of DeleteNode method: xData XDATA . xData.Delete GIVING result: USING *POSITION=DELETE_DOCUMENT_NODE ............................................................... . FindNode Method for XDATA Object . The FindNode method locates a node starting at the current node by using the FILTER parameter. The method uses the following format: [label] {object}.FindNode [GIVING {return}]: USING [FILTER=]{filter}[: [*POSITION=]{startpos}][: [*OPTIONS=]{mask} Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {filter} A Character String Variable or literal that specifies the filter string value used to find a node in the node tree. {startpos} A decimal number or Numeric Variable that specifies the position in the node tree where the find operation starts searching. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. The OPTIONS parameter is reserved for future options. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The find {startpos} position values are defined as follows: START_CURRENT_NODE EQU 0 - Start the find operation at the current node. START_PARENT_NODE EQU 1 - Start the find operation at the parent node. START_FIRST_CHILD EQU 2 - Start the find operation at the first child node. START_LAST_CHILD EQU 3 - Start the find operation at last child node. START_PREVIOUS_SIBLING EQU 4 - Start the find operation at the previous sibling node. children. START_NEXT_SIBLING EQU 5 - Start the find operation at the next sibling node. START_DOCUMENT_NODE EQU 6 - Start the find operation at the document node. 5. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_NODE_NOT_FOUND EQU 4 XDATA_ERR_INVALID_POSITION EQU 11 6. The FILTER parameter uses the same expression syntax that is is for the FILTER instruction. However, all of the field names are static with the following names: Comment Data JsonType Label Name ParentLabel PubId SysId Type Text Target 7. If a FindNode match is successful, the current node position is moved to the matching node. 8. EXAMPLE of FindNode Method usage: I. Example of FindNode method: xData XDATA . xData.FindNode GIVING result: USING *FILTER="label='FirstName'": *POSITION=START_DOCUMENT_NODE . xData.FindNode GIVING result: USING *FILTER="jsontype=2 AND label LIKE '%ray%'": *POSITION=START_DOCUMENT_NODE ............................................................... . FindNext Method for XDATA Object . The FindNext method locates the next node that matches the criteria as defined by the filter for the last FindNode method. The method uses the following format: [label] {object}.FindNext [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NODE_NOT_FOUND EQU 4 XDATA_ERR_NO_CURRENT_FILTER EQU 10 ............................................................... . GetComment Method for XDATA Object . The GetComment method returns the comment string value for a DOM_COMMENT_NODE node. The method uses the following format: [label] {object}.GetComment [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the string value for a DOM_COMMENT_NODE node. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If the comment string exists, the {return} contains the string data. Otherwise, the {return} variable is set to be NULL. ............................................................... . GetData Method for XDATA Object . The GetData method returns the data string value for a DOM_PROCESSING_INSTRUCTION_NODE node. The method uses the following format: [label] {object}.GetData [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the string value for a DOM_PROCESSING_INSTRUCTION_NODE node. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If the data string exists, the {return} contains the string data. Otherwise, the {return} variable is set to be NULL. 5. If this method is executed on a node type other than a DOM_PROCESSING_INSTRUCTION_NODE node, the {return} variable is set to a NULL PLB variable. Under normal operations, the PLB program would execute this method after the node type has been determined. 6. The DOM_PROCESSING_INSTRUCTION_NODE 'data' is defined as follows: DOM_PROCESSING_INSTRUCTION_NODE . Example: target -> 'xml-stylesheet' data -> 'type="text/css" href="style.css"' ............................................................... . GetExtendedError Method for XDATA Object . The GetExtendedError method returns extended error information from the last LoadJson or LoadXml method that returned a parsing error defined by XDATA_ERR_PARSE (i.e. error value 14). The method uses the following format: [label] {object}.GetExtendedError [GIVING {return}][: USING [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the extended error information from the last LoadJson or LoadXml method that encountered an XDATA_ERR_PARSE error. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value causes the current extended error buffer to be cleared upon completion of this method. XDATA_CLEAR_ERROR EQU 1 5. The expected extended error is returned as generated by the XML expat or JSON parsers. This information can help identify invalid or unexpected XML or JSON data that causes parsing errors. ............................................................... . GetJsonType Method for XDATA Object . The GetJsonType method returns the JSON type of the current node. The method uses the following format: [label] {object}.GetJsonType [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives the JSON type value of the current node. Flags Affected: EOS, 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 JSON type value is too large to be stored in the {return} numeric variable. 3. The EOS flag is always set to FALSE. 4. If the current node does not have a JSON type, the {return} value is zero. 5. A JSON type only exists for the node types of DOM_ELEMENT_NODE, DOM_ATTRIBUTE_NODE, and DOM_TEXT_NODE. Therefore, this method should only be executed for these node types. Otherwise, the {return} is returned with a zero value. 6. The supported JSON types stored into the {return} variable are defined as follows: JSON_TYPE_NONE EQU 0 JSON_TYPE_OBJECT EQU 1 JSON_TYPE_ARRAY EQU 2 JSON_TYPE_INTEGER EQU 3 JSON_TYPE_DOUBLE EQU 4 JSON_TYPE_STRING EQU 5 JSON_TYPE_BOOLEAN EQU 6 JSON_TYPE_NULL EQU 7 ............................................................... . GetLabel Method for XDATA Object . The GetLabel method returns the label string value for the DOM_ELEMENT_NODE and DOM_ATTRIBUTE_NODE node types. The method uses the following format: [label] {object}.GetLabel [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the label string value for the DOM_ELEMENT_NODE and DOM_ATTRIBUTE_NODE node types. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If the label string exists for the current node, the {return} contains the label string data. Otherwise, the {return} variable is set to be NULL. ............................................................... . GetName Method for XDATA Object . The GetName method returns the name string value for the DOM_DOCUMENT_TYPE_NODE node type. The method uses the following format: [label] {object}.GetName [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the name string value for the DOM_DOCUMENT_TYPE_NODE node type. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If the name string exists for the current node, the {return} contains the name string data. Otherwise, the {return} variable is set to be NULL. ............................................................... . GetPosition Method for XDATA Object . The GetPosition method returns the numeric position of the current node. This position value is unique value for each existing node. The method uses the following format: [label] {object}.GetPosition [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives the position of the current node. Flags Affected: EOS, 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 position value is too large to be stored in the {return} numeric variable. 3. The EOS flag is always set to FALSE. 4. The MoveToNode method can be used to reposition to the value returned by the GetPosition method. ............................................................... . GetPubId Method for XDATA Object . The GetPubId method returns the 'pubid' string value for the DOM_DOCUMENT_TYPE_NODE node type. The 'pubid' string of the DOM_DOCUMENT_TYPE_NODE is found in the node data. The method uses the following format: [label] {object}.GetPubId [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the pubid string value for the DOM_DOCUMENT_TYPE_NODE node type. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. The pubid data string is found in the DOM_DOCUMENT_TYPE_NODE follows: DOM_DOCUMENT_TYPE_NODE Example: ............................................................... . GetSysId Method for XDATA Object . The GetSysId method returns the 'sysid' string value for the DOM_DOCUMENT_TYPE_NODE node type. The 'sysid' string of the DOM_DOCUMENT_TYPE_NODE is found in the node data. The method uses the following format: [label] {object}.GetSysId [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the sysid string value for the DOM_DOCUMENT_TYPE_NODE node type. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. The sysid data string is found in the DOM_DOCUMENT_TYPE_NODE follows: DOM_DOCUMENT_TYPE_NODE Example: ............................................................... . GetText Method for XDATA Object . The GetText method returns the text string value for the DOM_TEXT_NODE and DOM_ATTRIBUTE_NODE node types. The method uses the following format: [label] {object}.GetText [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the text string value for the DOM_TEXT_NODE and DOM_ATTRIBUTE_NODE node types. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If a text string exists for the current node, the {return} contains the text string data. Otherwise, the {return} variable is set to be NULL. ............................................................... . GetTarget Method for XDATA Object . The GetTarget method returns the target string value for the DOM_PROCESSING_INSTRUCTION_NODE node type. The method uses the following format: [label] {object}.GetTarget [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Character String Variable that receives the target string value for the DOM_PROCESSING_INSTRUCTION_NODE node type. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is set to FALSE. 2. The OVER flag is set to FALSE. 3. The EOS flag is set to TRUE if the returned data is truncated. 4. If a target string exists for the current node, the {return} contains the target string data. Otherwise, the {return} variable is set to be NULL. 6. The DOM_PROCESSING_INSTRUCTION_NODE 'target' is defined as follows: DOM_PROCESSING_INSTRUCTION_NODE . Example: target -> 'xml-stylesheet' data -> 'type="text/css" href="style.css"' ............................................................... . GetType Method for XDATA Object . The GetType method returns the node type of the current node. The method uses the following format: [label] {object}.GetType [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives the node type of the current node. Flags Affected: EOS, 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 position value is too large to be stored in the {return} numeric variable. 3. The EOS flag is always set to FALSE. 4. The expected node type values are defined as follows: DOM_ELEMENT_NODE EQU 1 DOM_ATTRIBUTE_NODE EQU 2 DOM_TEXT_NODE EQU 3 DOM_CDATA_SECTION_NODE EQU 4 DOM_ENTITY_REFERENCE_NODE EQU 5 DOM_ENTITY_NODE EQU 6 DOM_PROCESSING_INSTRUCTION_NODE EQU 7 DOM_COMMENT_NODE EQU 8 DOM_DOCUMENT_NODE EQU 9 DOM_DOCUMENT_TYPE_NODE EQU 10 DOM_DOCUMENT_FRAGMENT_NODE EQU 11 DOM_NOTATION_NODE EQU 12 ............................................................... . LoadJson Method for XDATA Object . The LoadJson method loads JSON data into an XDATA object. The input data can be loaded directly from a DIM variable or from a specified file that contains a valid JSON stream. The new JSON data replaces all currently existing data in the XDATA object. The method uses the following format: [label] {object}.LoadJson [GIVING {return}]: USING [*DATA=]{data}[: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {data} A Character String Variable or literal that specifies a fully qualified path and file name that contains the JSON data stream. Additionally, the {data} string value can be the actual JSON data stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value indicates that the {data} method parameter contains a path and file name which contains the JSON data to be loaded. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_OPEN_FAILED EQU 12 XDATA_ERR_PARSE EQU 14 XDATA_ERR_BAD_READ EQU 15 XDATA_ERR_BAD_LSEEK EQU 19 ............................................................... . LoadXml Method for XDATA Object . The LoadXml method loads XML data into an XDATA object. The input data can be loaded directly from a DIM variable or from a specified file that contains a valid XML stream. The new XML data replaces all currently existing data in the XDATA object. The method uses the following format: [label] {object}.LoadXml [GIVING {return}]: USING [*DATA=]{data}[: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {data} A Character String Variable or literal that specifies a fully qualified path and file name that contains the XML data stream. Additionally, the {data} string value can be the actual XML data stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 5. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value indicates that the {data} method parameter contains a path and file name which contains the XML data to be loaded. 0x00000002 Open an XML file in read only mode. 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_NO_MEM EQU 1 XDATA_ERR_OPEN_FAILED EQU 12 XDATA_ERR_PARSER_CREATE EQU 13 XDATA_ERR_PARSE EQU 14 ............................................................... . MoveToNode Method for XDATA Object . The MoveToNode method sets the current node position specified by the {position} value. The method uses the following format: [label] {object}.MoveToNode [GIVING {return}]: USING [*POSITION=]{position} Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {position} A decimal number or Numeric Variable that specifies the position in the node tree where the current node is set. Flags Affected: EOS, 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 position value is too large to be stored in the {return} numeric variable. 3. The EOS flag is always set to FALSE. 4. The {position} values can be specified in one of three formats as follows: Static Pre-Defined Position Values MOVE_CURRENT_NODE EQU 0 MOVE_PARENT_NODE EQU 1 MOVE_FIRST_CHILD EQU 2 MOVE_PREVIOUS_SIBLING EQU 4 MOVE_NEXT_SIBLING EQU 5 MOVE_DOCUMENT_NODE EQU 6 GetPosition Direct Values The {return} position value from the 'GetPosition' method identifies a unique number assigned to each node in the node tree. This 'GetPosition' value can be used in the MoveToNode {position} to position directly to a node in the node tree. Combined Pre-Defined Plus GetPosition Direct Values In this case, the MoveToNode operation is performed in two steps as follows: 1) The first step is to use the to position directly to a node. 2) The second step is to use the position value to perform the final positioning action starting from the position in the first step. Example Combination Position: {position} = + 5. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_INVALID_POSITION_TYPE EQU 2 XDATA_ERR_NODE_NOT_FOUND EQU 4 XDATA_ERR_INVALID_POSITION EQU 11 ............................................................... . Reset Method for XDATA Object . The Reset method deletes all of the data in an XDATA object. The method uses the following format: [label] {object}.Reset [GIVING {return}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that is always set to zero. Flags Affected: EOS, OVER, ZERO Note the following: 1. The ZERO flag is always set to TRUE. 2. The OVER flag is always set to FALSE. 3. The EOS flag is always set to FALSE. 4. All of the current data in the XDATA is delete\lost when this method is executed. ............................................................... . SaveJson Method for XDATA Object . The SaveJson method stores the XDATA nodes as a JSON formatted string into a file. The method uses the following format: [label] {object}.SaveJson [GIVING {return}]: USING [FILENAME=]{filename}[: [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {filename} A Character String Variable or literal that specifies the path and file name used to write the JSON data stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000002 This bit value causes JSON constructs to be indented. 0x00000004 This bit value causes the JSON lines to output with a terminating + end of record sequence. 0x00000040 This bit value causes the TAB (0x09) character to be used when the indent mask bit (0x00000002) is being used. IF this bit is turned off, a blank (0x20) character is used for the indent operations. 5. The XDATA is converted to a JSON stream using the following rules: - JSON only uses the DOM_ATTRIBUTE_NODE, DOM_ELEMENT_NODE, and DOM_TEXT_NODE nodes from the XDATA. Any other DOM node types are ignored. - A JSON array is a DOM_ELEMENT_NODE with a label of array and jsontype of JSON_TYPE_ARRAY. It can have multiple DOM_TEXT_NODE as values and multiple DOM_ELEMENT_NODE as object values. - A JSON object is a DOM_ELEMENT_NODE with a label of object and jsontype of JSON_TYPE_OBJECT. It can have multiple DOM_ATTRIBUTE_NODE and DOM_ELEMENT_NODE nodes as key value pairs. - See the following link for basic JSON syntax elements and rules: http://www.w3schools.com/js/js_json.asp 6. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_FILE_CREATE EQU 16 XDATA_ERR_FILE_TOO_BIG EQU 17 XDATA_ERR_BAD_WRITE EQU 18 ............................................................... . SaveXml Method for XDATA Object . The SaveXml method stores the XDATA nodes as an XML formatted string into a file. The method uses the following format: [label] {object}.SaveXml [GIVING {return}]: USING [FILENAME=]{filename}[: [*OPTIONS=]{mask}][: [*ROOTNAME=]{name}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {filename} A Character String Variable or literal that specifies the path and file name used to write the XML data stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. {name} A Character String Variable or literal that specifies the tag name to be used to output the root name. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value prevents the output of the XML Processing Instruction declaration at the beginning of the XML data. 0x00000002 This bit value causes XML constructs to use indenting. 0x00000004 This bit value causes the XML lines to output with a terminating + end of record sequence. 0x00000008 This bit value causes leading and trailing spaces to be suppressed when outputting the XML data. 0x00000010 This bit value causes double-quote (") and single-quote (') characters to always be escaped when outputting XML element data. 0x00000020 This bit value causes any character less than 0x20 to be converted to 0x20 for the XML data being output. 0x00000040 This bit value causes a tab character to to be used to indent XML tags when outputting the XML data. 0x00000080 This bit value causes encoding to be set for ISO8859. This allows 8-bit character values in the XML data being output. 5. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the PL/B Runtime Reference under the 'I(I/O) Errors' in the 'XML base handler subcodes' table for details where the {return} value can be defined as follows: XDATA_ERR_NONE EQU 0 //Successful! '5nn' Where 'nn' is a value found in the 'XML base handler subcodes' found in the PL/B Runtime Reference under the 'I(I/O) Errors' section. ............................................................... . StoreJson Method for XDATA Object . The StoreJson method stores the XDATA nodes as a JSON formatted string into a Character String variable. The method uses the following format: [label] {object}.StoreJson [GIVING {return}]: USING [*OPTIONS=]{mask} Where: {label} An optional Program Code Label. {object} An XDATA object. {return} is a Character String Variable that returns the result as a formatted JSON string. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, OVER, ZERO Note the following: 1. The EOS flag is set to TRUE if the returned data is truncated. 2. The ZERO flag is set to FALSE. 3. The OVER flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000002 This bit value causes JSON constructs to be indented. 0x00000004 This bit value causes the JSON lines to output with a terminating + end of record sequence. 0x00000040 This bit value causes the TAB (0x09) character to be used when the indent mask bit (0x00000002) is being used. IF this bit is turned off, a blank (0x20) character is used for the indent operations. 5. The XDATA is converted to a JSON stream using the following rules: - JSON only uses the DOM_ATTRIBUTE_NODE, DOM_ELEMENT_NODE, and DOM_TEXT_NODE nodes from the XDATA. Any other DOM node types are ignored. - A JSON array is a DOM_ELEMENT_NODE with a label of array and jsontype of JSON_TYPE_ARRAY. It can have multiple DOM_TEXT_NODE as values and multiple DOM_ELEMENT_NODE as object values. - A JSON object is a DOM_ELEMENT_NODE with a label of object and jsontype of JSON_TYPE_OBJECT. It can have multiple DOM_ATTRIBUTE_NODE and DOM_ELEMENT_NODE nodes as key value pairs. - See the following link for basic JSON syntax elements and rules: http://www.w3schools.com/js/js_json.asp 6. The {return} value returns a NULL Character String variable if there is a memory allocation error creating a working buffer to hold the JSON output. ............................................................... . StoreJsonSize Method for XDATA Object . The StoreJsonSize method returns the size of the Json data stream to be generated using the specified OPTIONS mask settings for the current contents in an XDATA object. The method uses the following format: [label] {object}.StoreJsonSize [GIVING {return}]: [USING [*OPTIONS=]{mask}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives the size of the XDATA contents rendered as a Json stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is always set to FALSE. 4. The *OPTIONS {mask} values are the same as defined by the XDATA 'StoreJson' method. ............................................................... . StoreXml Method for XDATA Object . The StoreXml method stores the XDATA nodes as an XML formatted string into a Character String variable. The method uses the following format: [label] {object}.StoreXml [GIVING {return}]: USING [*OPTIONS=]{mask}}[: [*ROOTNAME=]{name}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} is a Character String Variable that returns the result as a formatted XML string. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. {name} A Character String Variable or literal that optional specifies the tag name to be used to output the root name. Flags Affected: EOS, OVER, ZERO Note the following: 1. The EOS flag is set to TRUE if the returned data is truncated. 2. The ZERO flag is set to FALSE. 3. The OVER flag is set to FALSE. 4. The *OPTIONS {mask} values are defined as follows: Mask Value Description 0x00000001 This bit value prevents the output of the XML Processing Instruction declaration at the beginning of the XML data. 0x00000002 This bit value causes XML constructs to use indenting. 0x00000004 This bit value causes the XML lines to output with a terminating + end of record sequence. 0x00000008 This bit value causes leading and trailing spaces to be suppressed when outputting the XML data. 0x00000010 This bit value causes double-quote (") and single-quote (') characters to always be escaped when outputting XML element data. 0x00000020 This bit value causes any character less than 0x20 to be converted to 0x20 for the XML data being output. 0x00000040 This bit value causes a tab character to to be used to indent XML tags when outputting the XML data. 0x00000080 This bit value causes encoding to be set for ISO8859. This allows 8-bit character values in the XML data being output. 5. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the PL/B Runtime Reference under the 'I(I/O) Errors' in the 'XML base handler subcodes' table for details where the {return} value can be defined as follows: XDATA_ERR_NONE EQU 0 //Successful! '5nn' Where 'nn' is a value found in the 'XML base handler subcodes' found in the PL/B Runtime Reference under the 'I(I/O) Errors' section. ............................................................... . StoreXmlSize Method for XDATA Object . The StoreXmlSize method returns the size of the XML data stream to be generated using the specified OPTIONS mask settings for the current contents in an XDATA object. The method uses the following format: [label] {object}.StoreXmlSize [GIVING {return}]: [USING [[*OPTIONS=]{mask}][: [*ROOTNAME=]{name}]] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives the size of the XDATA contents rendered as an XML stream. {mask} A decimal number or Numeric Variable that optional specifies a bit mask value to control the operations of this method. {name} A Character String Variable or literal that optional specifies the tag name to be used to output the root name. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is always set to FALSE. 4. The *OPTIONS {mask} values are the same as defined by the XDATA 'StoreXml' method. ............................................................... . UpdateNode Method for XDATA Object . The UpdateNode method updates the current node using the specified parameters. Any keyword parameters not specified remain unchanged. The method uses the following format: [label] {object}.FindNode [GIVING {return}][: USING [LABEL=]{labelname}[: [*TEXT=]{text}][: [*JSONTYPE=]{type}][: [*NAME=]{name}][: [*SYSID=]{sysid}][: [*PUBID=]{pubid}][: [*COMMENT=]{comment}][: [*TARGET=]{target}][: [*DATA=]{data}] Where: {label} An optional Program Code Label. {object} An XDATA object. {return} A Numeric Variable that receives a value to signify a pass or fail condition for the method execution. {labelname} A Character String Variable or literal that optional specifies the label string value of the node. {text} A Character String Variable or literal that optional specifies the text string value of the node. {type} A decimal number or Numeric Variable that optional specifies the a jsontype value used when outputing a document for JSON. See the 'CreateElement' XDATA method for details. {name} A Character String Variable or literal that optional specifies the name string value of the node represented as %name% as described in the 'CreateDocType' XDATA method. {sysid} A Character String Variable or literal that Optional specifies the sysid string value of the node represented as %sysid% as described in the 'CreateDocType' XDATA method. {pubid} A Character String Variable or literal that Optional specifies the pubid string value of the node represented as %pubid% as described in the 'CreateDocType' XDATA method. {comment} A Character String Variable or literal that optional specifies the comment string value of the node. {target} A Character String Variable or literal that optional specifies the target string value of the node. The {target} string value replaces the %target% field in the PI. See the 'CreatePI' XDATA method for details. {data} A Character String Variable or literal that optional specifies the data string value of the node. The {data} string value replaces the %target% field in the PI. See the 'CreatePI' XDATA method for details. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. The {return} value returns a zero if the method was successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA returned error descriptions for more details. This method can return these values: XDATA_ERR_NONE EQU 0 //Successful! XDATA_ERR_INVALID_UPDATE_DATA EQU 5 XDATA_ERR_NO_CURRENT_POSITION EQU 6 XDATA_ERR_DOCUMENT_POSITION EQU 7 *********************************************************************** End of XDATA Methods *********************************************************************** - Modified to prevent an unexpected I57 error for a FILELIST UPDATE or DELETE operation that followed a READKS when a FILTER was being used. - Added an I86 subcode 53 error when a SQLIO creation of a SQL user table error was encountered. See the 'I (I/O) Errors' description for more details. - Corrected a problem where the FPOSIT current file pointer value was invalid after a READKS when a FILTER was being used and a record meeting the FILTER expression was found. In this scenario, the FPOSIT current file pointer value actually pointing to the next record that follow the record returned by the FILTERed READKS. - Corrected an unexpected I86 subcode 5 error for SQLIO using MySql when a PLB Write operation was performed and a '\' character was in one of the variables being written. - Corrected a SQLIO MySql problem where a PREPARE was not creating a SQL Table in a database when a Table with that same table name existed in a different database on the MySql server. - Corrected a data record corruption problem when using an IFILE with a FILTER expression and the program is performing a repeating READKS and UPDATE instruction sequence. Also, note that this same corruption issue could occur using a repeating sequence of READKP with a FILTER expression and an UPDATE instruction. This problem ONLY occurred when using a FILTER expression on the IFILE as described. - Corrected an HTTP error 17 (receive timeout) that might occur when using SSL operations. - Corrected a MAILSEND Mxx error with a subcode 81 (receive timeout) that might occur when using SSL operations. - Corrected a problem where the LOWERCASE\UPPERCASE instructions WAS NOT setting the Destination variable to be NULL if the source variable was a NULL DIM variable. - Corrected an issue where the OCCURS instruction DID NOT zero the {result} variable when the {source} or {search} operand was NULL. With this change, the {result} variable value is now set to zero if either the {source} or {search} is NULL. - Corrected a problem where the 'INDEX "file -C"' operation would hang indefinitely if the 'file.txt' data file was locked in an active FILEPI in the same program processing the INDEX instruction. - Corrected a problem where the SQLIO debug log date was reporting an invalid month value. The bad month was larger than expected by 1 month. - Corrected a problem where the 'SCHEMA {database}, IMPORT={svar}' DID NOT allow XML schema data to be specified in the {svar} input variable. With this change, XML schema data can be specified in the {svar} as documented for the SCHEMA IMPORT operation. - Corrected a problem for SQLIO using MySql database engine, where a 'Rollback' operation was being processed twice after a SQL error occurred. - Corrected COUNTKEYS problem where the SQLIO operation did not give expected results when the IFILE key was composed of multiple SQL numeric columns. - Corrected a memory leak where a SQLIO close operation was not cleaning all allocated buffers. This problem could allow a FILTER to take affect on a file variable that was OPENed without using a VIEW when an I85 subcode 123 should have been generated. - Corrected a problem where the EOR rendering for XFILE output might not work as expected. This could cause some XML source lines to be combined into a single source line. ------------------------------------------------------------------------------- PLBWIN, PLBNET, PLBSERVE, ALL GUI CLIENTS - Added a new keyword named '*PDFDIALOGDIR={svar} to the GETMODE and SETMODE instructions as follows: SETMODE *PDFDIALOGDIR={svarslit} This keyword causes the target directory for the PDF file selection Dialog to be set to the {svarslit} directory path. The *PDFDIALOGDIR string setting can be cleared by specifying a NULL DIM variable for the {svarslit} variable. Note, the *PDFDIALOGDIR path setting ONLY takes affect when the PDF DIALOG is presented to the end-user. GETMODE *PDFDIALOGDIR={svar} This keyword retrieves the last *PDFDIALOGDIR setting that was processed using the 'SETMODE *PDFDIALOGDIR' keyword operation. ------------------------------------------------------------------------------- PLBWIN, PLBNET, ALL GUI CLIENTS - Modified the PICT object to support the 'DoubleClick Event'. This change allows a PLB program to process the a 'Click Event' and a 'Double Click Event' using two separate event processing routines. This simplifies the event process without having to overload the logic in a single event processing routine. Note: 1. When the PICT 'Double Click Event' is registered and being used, a Double Click action DOES NOT generate\dispatch the PICT Default (i.e. ACTIVATE) and single 'Click' events. 2. The 'DoubleClick Event' is NOT supported for the PL/B Web Server (PWS) PICT object. This restrict exists because there are inconsistent behaviors for different client Browsers. In addition, some mobile devices CAN NOT perform any double clicking actions. - Added a method named 'GetLastDropXY' for a LISTVIEW object. This method retrieves the last mouse coordinates where a mouse drop action occurred on a LISTVIEW object during a drag\drop user operation. This method are described as follows: ............................................................... . GetLastDropXY Method for LISTVIEW Object . The GetLastDropXY method can be used to retrieve the mouse coordinates where a mouse drop action occurred on the LISTVIEW object during a drag\drop user operation. These mouse coordinates can be used to determine which LISTVIEW item where the mouse drop action occurred using the 'SubItemHitTest' method. The method uses the following format: [label] {object}.GetLastDropXY GIVING {return}[: USING [Flags=]{flagmask}] Where: {label} is an optional Program Code Label. {object} A LISTVIEW object. {return} is a Numeric Variable that receives the mouse X and Y coordinate values. {flagmask} is an optional decimal number or Numeric Variable that is a bit mask to control behaviors of the method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. If the {flagmask} parameter is NOT used, the default behavior is to return the X and Y mouse coordinates as follows: {return} = (X * 65536) + Y 5. If the {flagmask} parameter is used, the bit mask values can be used as follows: Bit Mask Value Comment 0x00000000 - Return X and Y coordinates. 0x00000001 - Only return the X coordinate. 0x00000002 - Only return the Y coordinate. 0x00000004 - Zero both X and Y coordinates. - Added a method named 'GetLastDropXY' for a TREEVIEW object. This method retrieves the last mouse coordinates where a mouse drop action occurred on a TREEVIEW object during a drag\drop user operation. This method are described as follows: ............................................................... . GetLastDropXY Method for TREEVIEW Object . The GetLastDropXY method can be used to retrieve the mouse coordinates where a mouse drop action occurred on the TREEVIEW object during a drag\drop user operation. These mouse coordinates can be used to determine the TREEVIEW item where the mouse drop action occurred using the 'ItemHitTest' method. The method uses the following format: [label] {object}.GetLastDropXY GIVING {return}[: USING [Flags=]{flagmask}] Where: {label} is an optional Program Code Label. {object} A TREEVIEW object. {return} is a Numeric Variable that receives the mouse X and Y coordinate values. {flagmask} is an optional decimal number or Numeric Variable that is a bit mask to control behaviors of the method. Flags Affected: EOS, 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 returned data is truncated. 3. The EOS flag is set to FALSE. 4. If the {flagmask} parameter is NOT used, the default behavior is to return the X and Y mouse coordinates as follows: {return} = (X * 65536) + Y 5. If the {flagmask} parameter is used, the bit mask values can be used as follows: Bit Mask Value Comment 0x00000000 - Return X and Y coordinates. 0x00000001 - Only return the X coordinate. 0x00000002 - Only return the Y coordinate. 0x00000004 - Zero both X and Y coordinates. - Corrected a problem where a 'PRTPAGE *PICT=...' control did not resize an image up to fit the rectangle when the output device was the Sunbelt 'pdf:' device. - Corrected a problem where a 'CREATE PICT' instruction was NOT generating an O103 error when using a '.png' image. This problem was caused by a change made in release 9.7A. With this correct, the - Modified the MINSCROLLH and MINSCROLLV properties to force the scrollbars to be redrawn. This is being done to work around a problem where the scrollbars might not appear when these properties were changed multiple times. ------------------------------------------------------------------------------- PLBNET, PLBCLINET - Corrected a FASTEVENT problem when an ARGn event result to a NETOBJECT was being used. This FASTEVENT problem was caused by a PLF form loading issue\correction that was made in release 9.6B. ------------------------------------------------------------------------------- PLBCMP - Added new instruction named 'MOVEVARADDR {source}{sep}{dest}'. See detailed descriptions in the runtime descriptions. - Modified the compiler to support the following keywords for the GETFILE instruction. These new keywords are ONLY used for file variables opened for SQLIO operations. SQLIODATABASE={svar} SQLIOTABLE={svar} SQLIOHOST={svar} SQLIOUSER={svar} SQLIOPASS={svar} SQLIOCONN={svar} SQLIOEXT={svar} See above descriptions for more details. - Added a new keyword named '*PDFDIALOGDIR={svar} to the GETMODE and SETMODE instructions. See details in runtime descriptions. - Modified the LOWERCASE and UPPERCASE instructions to support the {sep} preposition separator between the operands as follows: [label] LOWERCASE {source}[{sep}{dest}[{sep}TABLE={table}]] [label] UPPERERCASE {source}[{sep}{dest}[{sep}TABLE={table}]] Examples: LOWERCASE A to B LOWERCASE A to B USING TABLE=C - Modified the compiler to give a compilation error if the ACTIVATE instruction uses a LABEL code pointer for {routine} parameter. The ACTIVATE DOES NOT support the LABEL code pointer. - Modified to give a compiler error for a CREATE or DESTROY of a CLIENT, RUNTIME, or XDATA object. - Corrected a print listing problem where the first print line did not show the address of a variable if the variable was the first source line in a program. - Corrected a problem where the logical 'ELSE' construct was not checking for user comment verification as specified by the '-zr' compiler option. Also, modified the syntax checking to detect the 'ELSE (' syntax and give a warning that a possible expression is not being used. Example compiler command using all defaults: cmd: 'plbcon plbcmp prog' IF (1=1) MOVE "1",s$cmdlin ELSE (2=2) //Modified 9.8A compiler gives warning!! MOVE "2",s$cmdlin ENDIF Example compiler command using '-zr' comment delimiter option: cmd: 'plbcon plbcmp prog -zr="//" IF (1=1) MOVE "1", s$cmdlin ELSE (2=2) //Modified 9.8A compiler gives warning!! //Also, user comment error generated!! MOVE "2", s$cmdlin ENDIF ------------------------------------------------------------------------------- PLBDBUG - Modified to support enhanced 'plbdbug' interface to DBGIFACE GUI debugger. - Corrected a problem where the debugger would cause a GPF at the 'plbclient' when a 'DV COLLECTION' command was processed. - Modified to allow the debugger to understand the XDATA data type. - Corrected an F01 error that could occur after a CHAIN operation is processed. ------------------------------------------------------------------------------- ADMEQU.INC - Reviewed for 9.8A release. ------------------------------------------------------------------------------- PLBEQU.INC - In release 9.8, the $SORTORDER property value equate names were changed to be '$SORTASC' and '$SORTDSC' which are consistent with the PL/B Language Reference manual documentation. - Added $MB_ICONQUESTION which is the same as the $MB_QUESTION for the ALERT instruction. ------------------------------------------------------------------------------- PLBMETH.INC - Updated the XDATA method descriptions. - Added new methods for CLIENT and RUNTIME object. ------------------------------------------------------------------------------- SUNWADO.DLL - Corrected a random GPF error that could occur in the when doing a DBFETCH instruction. ------------------------------------------------------------------------------- DESIGNER.PLC - Corrected the application of a form's object prefix property to all existing form objects. - Corrected setting of the form modified flag during cut operations. - Corrected setting of the modified flag during a cut operation. - Corrected an issue that occurred when the designer's ini file did not define a default screen font. - Added logic to prevent attempts to position to a line that is less than the calculated starting line number. - Added logic to allow a "GoTo" in the SunIDE program when a form object is selected to open the form and select the object. - Corrected an XML read error during initialization. - Corrected an XML read error that occurred when an empty new form was closed and the designer was running as an IDE loadmod. - Corrected an issue in saving a form that has panels nested more than 10 deep. ------------------------------------------------------------------------------- EDITOR.PLC - Modified the "Go to" menu item checking to correctly detect undefined variables. - Corrected scope keywords for SELECT/WHEN/DEFAULT/ENDSELECT structures. ------------------------------------------------------------------------------- SUNIDE.PLC - Added logic to place functions and function variables in the browse labels list and thus be accessible to the "Go to Label" function. - Modified the PosToError routine to correctly locate a "short" file name regardless of case. - The IDE is now disabled while a build is in process. - Selecting "GO TO" for an object defined in a plform will now start the designer and select the object. - Corrected the GOTO label function when the label list contained more than 10,000 entries. - Corrected form file detection in Find In Files function. - Corrected an issue that would cause the IDE to no longer be the active program after a build command. - Added a "Labels Only" option to the Find In Files function to search for matching values in only the first column. ------------------------------------------------------------------------------- SUNCS21.OCX - Corrected an issue that resulted in the ReplaceAll method hanging. ------------------------------------------------------------------------------- SCHEMAEDITOR.PLC - Corrected the offset calculation when importing named io columns into Sqlio columns. - Enlarged the AAMDEX file name field from 32 to 100. - Enlarged the ISAM file name field from 50 to 100. - Added a description column identifier field used during the PL/B code import. - Added validation logic for SQLIO index columns. - Added Test Prep functions for SQLIO files, indexes, and aamdexes. - Modified to assume extensions for for SQLIO files, indexes, and aamdexes if not specified. ------------------------------------------------------------------------------- WATCH.PLC - Modified the config file processing to use smaller variables to work around a runtime issue when the PLB_OPENUSEIP runtime keyword is defined. ------------------------------------------------------------------------------- DBEXPLORER.PLC - Corrected an update issue on the Data tab. -------------------------------------------------------------------------------