____________________________________________________ BASEstar Graphics Enabler Release Notes Version 2.3 ________________________________________________________________ March 1996 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1996. All Rights Reserved. Printed in U.S.A. The following are trademarks of Digital Equipment Corporation: BASEstar, DEC, DECnet, DECwindows, VAX, VAXstation, OpenVMS, and the DIGITAL logo. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. This document was prepared using DEC DOCUMENT Version 2.3. _________________________________________________________________ Contents Preface................................................... v 1 BASEstar Graphics Enabler Release Notes 1.1 Software Licensing............................ 1-1 1.2 Software Compatibility........................ 1-1 1.2.1 Binding files not compatible.............. 1-1 1.2.2 Prerequisite software..................... 1-2 1.2.3 DECwindows/Motif V1.2 note................ 1-2 1.2.4 Motif V1.2 Window Manager note............ 1-3 1.3 Corrections to the Documentation.............. 1-3 1.3.1 Undocumented create binding qualifer nodepends................................. 1-3 1.3.2 Undocumented default value for mode qualifier................................. 1-3 1.3.3 Range for interval qualifier incorrectly specified................................. 1-3 1.3.4 Interaction between qualifers interval and mode...................................... 1-3 1.3.5 Undocumented logical name WSOPT........... 1-3 1.3.6 Clarification concerning values for the datatype qualifier........................ 1-4 1.3.7 Clarification concerning binding to BCCDS arrays.................................... 1-4 1.4 New and Changed Features...................... 1-4 1.4.1 Control of update "batch" size............ 1-5 1.4.2 Enhancements to bge_sql function.......... 1-5 1.4.2.1 Support for database date/time formats................................. 1-5 1.4.2.2 New arguments to bge_sql................ 1-6 1.5 Problems Fixed................................ 1-8 1.5.1 GMS color 0 now used as background color..................................... 1-8 iii 1.5.2 Problem with BASEstar Open objects in root domain fixed.............................. 1-8 1.5.3 Problem with length of BASEstar Open object names improved..................... 1-9 1.5.4 bge_msg problem with long strings fixed..................................... 1-9 1.5.5 Problems with the GUI Event Binding Editor fixed..................................... 1-9 1.5.6 Individual windows may be closed via the Window Manager menu....................... 1-10 1.5.7 SL-GMS demo linker options files in OpenVMS Alpha kit corrected............... 1-10 1.5.8 Wildcard matching in CLI commands corrected (UNIX only)..................... 1-10 1.5.9 OpenVMS installation IVP for Runtime component corrected....................... 1-10 1.5.10 Path lists may be usd in BGE_MODELS....... 1-10 1.5.11 UNIX: Links to bgeusers scripts placed in /etc...................................... 1-10 1.6 Known Problems................................ 1-11 1.6.1 UI: Write-access not supported............ 1-11 1.6.2 UI: (UNIX only) Warnings may be displayed when dialog boxes appear.................. 1-11 1.6.3 CLI: No error for negative array sizes.... 1-11 1.6.4 CLI: (BSTRDS only) No error if parameters used with a Datapoint..................... 1-11 1.6.5 Runtime: (BCCDS only) Large structures cannot be updated rapidly................. 1-11 1.6.6 SL-GMS: Model files not compatible with some OpenVMS utilities.................... 1-12 iv _________________________________________________________________ Preface This document provides installation and upgrade information for the BASEstar Graphics Enabler, Version 2.3 kit. It describes changes to the BASEstar Graphics Enabler software, problems, and restrictions related to this release. Intended Audience This document is intended for system managers and application programmers. Read this document before you install or use the BASEstar Graphics Enabler. Associated Documents For more information on BASEstar Graphics Enabler, refer to the BASEstar Graphics Enabler User's Guide. v 1 _________________________________________________________________ BASEstar Graphics Enabler Release Notes The BASEstar Graphics Enabler release notes discuss the following topics: o Software Licensing o Software Compatibility o Corrections to the Documentation o New and Changed Features o Problems Fixed o Known Problems 1.1 Software Licensing This product has several license options, one of which (on OpenVMS) is Personal Use licensing. If you are using a Personal Use license, it must be reserved to a VMS username before it is loaded. Unlimited System Use (capacity-based) licensing and Concurrent licensing are also available. 1.2 Software Compatibility 1.2.1 Binding files not compatible Binding files (type d1) created with releases of BASEstar Graphics Enabler earlier than Version 2.0 are NOT compatible with this release. A utility is included which will convert binding files created with earlier versions to binding files created with this version. The conversion utility, bgecvt, is invoked as follows: o VMS: BGECVT binding_file [/keep] [/noexecute] [/noquery] BASEstar Graphics Enabler Release Notes 1-1 BASEstar Graphics Enabler Release Notes 1.2 Software Compatibility o UNIX: bgecvt binding_file [-keep] [-noexecute] [- noquery] Note that the binding file name must be specified without the d1 extension. The conversion utility will read the binding file and write a command file containing BASEstar Graphics Enabler CLI commands. These commands will recreate the bindings in the original binding file. The conversion utility will then execute this command file and create a new version of the binding file, unless the optional qualifier noexecute is specified. After executing the command file, the conversion utility will delete it, unless the optional qualifier keep is specified. If the optional qualifier noquery is specified, the binding commands will include the noquery qualifier and will include datatype specifications. 1.2.2 Prerequisite software The Version 2.3 release is compatible with the following prerequisites and platforms: o BASEstar Classic V3.1 or higher o BASEstar Open V2.0 o OpenVMS/VAX V5.5-2 or higher o OpenVMS/AXP V2.0 or higher o Digital UNIX V3.0 or higher o Oracle RDB V6.0 or higher (VMS) o Oracle DBMS 7.1.4 (UNIX) Note that with this release of BASEstar Graphics Enabler, it is no longer required that BASEstar be installed before BASEstar Graphics Enabler can be installed. 1.2.3 DECwindows/Motif V1.2 note The OpenVMS versions of this release of BASEstar Graphics Enabler were compiled on a Motif 1.1.3 system. They may be linked and run on a Motif 1.2 system, since the 1.1.3 shareable images are included in the 1.2 kit. However, if any new code is developed to be linked with the runtime component, that code must be compiled on a 1.1.3 system. Note that the installation procedure for DECwindows Motif 1-2 BASEstar Graphics Enabler Release Notes BASEstar Graphics Enabler Release Notes 1.2 Software Compatibility V1.2 gives the installer the option of saving the 1.1.3 programming environment. 1.2.4 Motif V1.2 Window Manager note In order for window positioning to work correctly, BASEstar Graphics Enabler requires the Motif Window Manager resource Mwm*clientAutoPlace to have a value of False. This resource is given a value of True in the default resource file shipped with Motif V1.2. This should be corrected by inserting the following line in a system-wide or per-user MWM resource file: Mwm*clientAutoPlace: False 1.3 Corrections to the Documentation 1.3.1 Undocumented create binding qualifer nodepends The qualifer nodepends may be used with the create binding and modify binding commands to remove the depends-on variable from the binding definition. 1.3.2 Undocumented default value for mode qualifier The default if mode is not specified is asynchronous. 1.3.3 Range for interval qualifier incorrectly specified The range is specified as 0 - 60, but values greater than 60 may be used. 1.3.4 Interaction between qualifers interval and mode If you wish to set the interval of a binding to a value greater than zero, the mode must be set to synchronous. 1.3.5 Undocumented logical name WSOPT If the VMS logical name BGE$WSOPT or UNIX environment variable BGE_WSOPT is set to a decimal number, BASEstar Graphics Enabler will use that value as the "wsopt" parameter in the call to gmsWorkst(). For a description of the "wsopt" parameter and the values it can take, refer to the SL-GMS Reference Manual. BASEstar Graphics Enabler Release Notes 1-3 BASEstar Graphics Enabler Release Notes 1.3 Corrections to the Documentation 1.3.6 Clarification concerning values for the datatype qualifier The list of datatype keywords for the GMS (Internal) data source (GMSDS) was omitted from the documentation. That list is as follows: ___________________________________________________________ GMSDS_Data_Type____________SL-GMS_Type_____________________ char G_CHAR short G_SHORT integer G_INTEGER float G_FLOAT double G_DOUBLE string_____________________G_STRING________________________ When specifying a datatype for a variable in a given data source, you may use datatype keywords from that data source or any other data source, provided the SL-GMS type is equivalent. For example, the keywords integer_32, longword, and integer may be used interchangeably. Also please note an error in Table 2-1, page 2-2, of the BASEstar Graphics Enabler User's Guide. The SL-GMS type which maps to the BSTRDS data type listed as "Array datatype of VISIBLE CHAR" is G_STRING, not G_CHAR | G_ ARRAY. 1.3.7 Clarification concerning binding to BCCDS arrays When binding to an element of an array variable in the BCCDS data source, note that the first element of the array variable has the index 1, whereas the first element of an array in the GMSDS data source has the index 0. 1.4 New and Changed Features This section describes the new features of the current software release and features that have changed from previous releases. For more information on these features and functions, refer to the BASEstar Graphics Enabler User's Guide. 1-4 BASEstar Graphics Enabler Release Notes BASEstar Graphics Enabler Release Notes 1.4 New and Changed Features 1.4.1 Control of update "batch" size The BASEstar Classic and BASEstar Open datasources have been enhanced to retrieve value notifications in "batches", with the batch size controlled by an environment variable. This will allow some degree of tuning the application's response in a situation involving high data update rates. A new logical name BGE$UPDATE_BATCH for VMS, and environment variable BGE_UPDATE_BATCH for UNIX, can be used to control this feature. If this is set to a non-negative integer N, it will have the following effect: o In the BASEstar Classic datasource, BASEstar Graphics Enabler will retrieve up to N messages from the BASEstar Classic message port each update cycle (200 milliseconds by default), and no asynchronous read will be posted on the port (hence no AST routine will be used). The default behavior is to post an asynchronous read and process one message each time the AST routine is invoked. o In the BASEstar Open datasource, BASEstar Graphics Enabler will retrieve up to N events from the BASEstar Open enbox each update cycle. The default behavior is to retrieve events until the enbox is empty. 1.4.2 Enhancements to bge_sql function 1.4.2.1 Support for database date/time formats If you set up your database environment to use an international date/time format, you can also set up BASEstar Graphics Enabler to use that format for bge_ sql SELECT statements. You can also select between two alternative date/time formats. A new logical name BGE$DATE for VMS, and environment variable BGE_DATE for UNIX, may be used to control this feature. If this is set to a two-digit number, BASEstar Graphics Enabler will use that value to set up the date/time format used by the database. BASEstar Graphics Enabler Release Notes 1-5 BASEstar Graphics Enabler Release Notes 1.4 New and Changed Features The first digit selects alternate date/time formats as follows: ___________________________________________________________ Value___Format_____________________________________________ 1 DD-MON-YYYY HH:MM:SS 2_______YYYY-MON-DD_HH:MM:SS_______________________________ Note that RDB appends centi-seconds (.XX) to the time format. The second digit selects international formats as follows: ___________________________________________________________ Value___Format_____________________________________________ 1 American English 2 German 3 Austria German 4 French 5 Italian 6_______Portugese__________________________________________ If the logical name or environment varialbe is undefined, the value 11 will be used as the default. Note that, depending on your database, you may need to pass formatting information via database-specific logical names or formatting functions in the SELECT statement. Consult your database documentation for further information. 1.4.2.2 New arguments to bge_sql Options for the third argument to bge_sql now include the following (note that the options may be abbreviated to their first three characters): o reset If you pass this option with a normal SQL select query, the result variables will be set to 0, 0.0 or "" as appropriate. o tostring 1-6 BASEstar Graphics Enabler Release Notes BASEstar Graphics Enabler Release Notes 1.4 New and Changed Features If you pass this option together with a normal SQL select query, all the result data will be moved to the result variable(s) as strings, regardless of the actual type. This is useful to fill lists with a mixture of strings, floats and integers, because everything will be moved to string result variables. o todate If you pass this option with a normal SQL select query where one of the result variables varname will be date/time, this option will create two additional variables varname_xd (type integer) and varname_xt (type d_float) which will be set to the corresponding GMS date/time format. Note that you must define bindings for these variables in order to use them in a model. This option depends on the BGE$DATE logical name or BGE_ DATE environment variable) for the language-specific information. o noeos If you pass this option with a normal SQL select query which will not return any rows of data, the "no row" warning message will be supressed. In this case the result variable varname_0 will be set to 0, and you may use this to introduce your own error handling. o noinquery This will supress the setting of the "in bge_sql" variable (varname without _x) to 1 on entering bge_ sql and to 0 on exiting. o norow If you are executing select queries, this option will supress setting the row index variable varname_0. Only the result variables (varname_x, x = 1 to number of rows selected) will be updated. o noupdate This will prevent the bge_sql function from calling gmsDynUpdate internally. This is useful when a single dynamic property has multiple calls to bge_sql, which otherwise would cause recursive calls to bge_sql and may prevent it from returning normally. BASEstar Graphics Enabler Release Notes 1-7 BASEstar Graphics Enabler Release Notes 1.4 New and Changed Features For example: variable = x call bge_sql("select * from xx","var1","last noupdate noinquery") call bge_sql("select * from yy","var2","last noupdate noinquery") Note that this option should only be used with the first and last option and with the noinquery option. To execute mutiple SQL statements with the all and array options, it is recommended that you write a user function which in turn makes the calls to bge_sql, because the all and array options require the internal call to gmsDynUpdate. o waiting, inhibit The waiting option will turn on and off the watch cursor by calling bge_waiting (equivalent to bge_waiting(1,0). If in addition the inhibit option is used, the pointer and keyboard will be locked until bge_sql returns (equivalent to bge_waiting(1,1)). Prior to its return, bge_sql will make an internal call to bge_waiting(0,0) to cancel these effects. 1.5 Problems Fixed This section describes problems fixed in the current software release. 1.5.1 GMS color 0 now used as background color If a custom "colordef.dat" file was used which specified a color other than white for the background (color 0), BASEstar Graphics Enabler would ignore it and use white as the background. This has been fixed. 1.5.2 Problem with BASEstar Open objects in root domain fixed. If a datapoint object was located in the root domain and name was given to BASEstar Graphics Enabler as an absolute pathname, BASEstar Graphics Enabler would not correctly create the associated trigger and filter objects. This has been fixed 1-8 BASEstar Graphics Enabler Release Notes BASEstar Graphics Enabler Release Notes 1.5 Problems Fixed 1.5.3 Problem with length of BASEstar Open object names improved. In the BASEstar Open datasource, when creating trigger and filter objects associated with a datapoint, BASEstar Graphics Enabler forms their names by adding prefixes to the datapoint name. If the length of the datapoint name was close to BASEstar Open's limit on object names (BSTR_C_ OBJNAME_LEN, currently 32), BASEstar Graphics Enabler would be unable to create the trigger and filter objects. This has been improved as follows: normally the prefix used by BASEstar Graphics Enabler is of the form "_bge_xx" where "xx" is a two-letter code for the type of object. BASEstar Graphics Enabler will now use a shorter form of the prefix if the longer one would make the resulting name too long. The shorter prefix is of the form "_x_" where "x" is a one- letter code for the object. 1.5.4 bge_msg problem with long strings fixed. If the function bge_msg was called with a string longer than 256 characters, the program would terminate with an access violation. The bge_msg function will now truncate the string with which it is called to 256 characters if necessary. 1.5.5 Problems with the GUI Event Binding Editor fixed If the variable list in an event binding was empty, attempting to save the binding list would cause the program to terminate. This has been fixed. The binding list was not updated when an event binding was created; this has been fixed. Note that if model variables are associated with event parameters in the event editor, these associations are not displayed in the binding list. This is intentional, because the same model variable can be associated with any number of event parameters, as well as bound directly to a source variable. Only a source variable binding will be displayed in the binding list. BASEstar Graphics Enabler Release Notes 1-9 BASEstar Graphics Enabler Release Notes 1.5 Problems Fixed 1.5.6 Individual windows may be closed via the Window Manager menu. If one window of an application was closed by using the "close" item on its Window Manager menu, all the windows would be closed and the application would exit. This has been fixed so that individual windows may be closed with the "close" menu item. 1.5.7 SL-GMS demo linker options files in OpenVMS Alpha kit corrected. The linker options files distributed in the GMS$HOME:[LIB] directory that are used to build the SL-GMS demo applications were incorrect in the OpenVMS Alpha kit. They have been corrected. 1.5.8 Wildcard matching in CLI commands corrected (UNIX only) The BASEstar Graphics Enabler CLI "show" commands allow the use of wildcard patterns. On Digital UNIX, a pattern could potentially match strings for which it was not intended. For example, a pattern such as "A?" would incorrectly match a string such as "ABC". This has been fixed. 1.5.9 OpenVMS installation IVP for Runtime component corrected. The IVP for the Runtime component did not actually verify that the installation was successful. This has been fixed. 1.5.10 Path lists may be usd in BGE_MODELS The logical name BGE$MODELS for VMS can now be set to a logical name search list, and the environment variable BGE_ MODELS for UNIX can now be set to a blank-separated list of pathnames. In either case multiple directories will be searched for model and binding files. 1.5.11 UNIX: Links to bgeusers scripts placed in /etc The Digital UNIX installatio procedure now places links to the user setup scripts bgeusers.csh and bgeusers.sh in the /etc directory. Thus these files can be invoked as "/etc/bgeusers.[c]sh". 1-10 BASEstar Graphics Enabler Release Notes BASEstar Graphics Enabler Release Notes 1.6 Known Problems 1.6 Known Problems 1.6.1 UI: Write-access not supported The CLI supports the specification of a binding as "no- write", or as writable by a specified list of users. This specification is not yet supported by the UI. 1.6.2 UI: (UNIX only) Warnings may be displayed when dialog boxes appear When run on UNIX, the UI may display "unaligned access" warnings whenever a dialog box appears for the first time. These messages should be ignored. 1.6.3 CLI: No error for negative array sizes If you use the array_size qualifier to the create binding command with a negative value, the value will be taken as zero and no message will be issued. 1.6.4 CLI: (BSTRDS only) No error if parameters used with a Datapoint If you use the parameters qualifier to the create binding command and the source variable is a Datapoint in the BSTRDS data source, the qualifer will be ignored and no error message will be issued. 1.6.5 Runtime: (BCCDS only) Large structures cannot be updated rapidly The current implementation of the BASEstar Classic (BCCDS) data source does not use Field Notification. Whenever a structure point value notification is received, the data source must break the structure data up into its component fields before updating any variables whose values have changed. If the structure is large (e.g. 1000 fields or more) and the data update rate is moderate to high (e.g. 10 updates per minute or more) the time taken to deal with each structure point notification may cause the data source to "fall behind". The result will be an "update stack overflow" error. BASEstar Graphics Enabler Release Notes 1-11 BASEstar Graphics Enabler Release Notes 1.6 Known Problems Workarounds to this problem include: making the structures smaller, using lower update rates, and using synchronous bindings instead of asynchronous. This problem will be addressed in a future version of the BASEstar Graphics Enabler. 1.6.6 SL-GMS: Model files not compatible with some OpenVMS utilities The SL-GMS binary model files (file type m1 and m2) are not completely compatible with the RMS standard. This does not have any effect on most OpenVMS utilities, including COPY, BACKUP, etc. However if such a file is processed with a utility such as CMS that attempts to "correct" the RMS incompatibility, the resulting file will no longer be acceptable to SL-GMS. If model files are to be archived in CMS, it is recommended that the text form (file type g) be used. It is also recommended that the text form of models be used whenever the model must be copied to a system of a different architecture or operating system, e.g. from OpenVMS VAX to OpenVMS Alpha or from OpenVMS Alpha to Digital UNIX Alpha. 1-12 BASEstar Graphics Enabler Release Notes