$Header: /cvsroot/arsperl/ARSperl/RELNOTES,v 1.13 2003/04/24 18:39:18 jcmurphy Exp $ Release Notes for ARSperl --------------------------------------------------------------------------- ARSperl - An ARS v2 - v5 / Perl5 Integration Kit Copyright (C) 1995-2003 Joel Murphy, jmurphy@acsu.buffalo.edu Jeff Murphy, jcmurphy@acsu.buffalo.edu This program is free software; you can redistribute it and/or modify it under the terms as Perl itself. Refer to the file called "Artistic" that accompanies the source distribution of ARSperl (or the one that accompanies the source distribution of Perl itself) for a full description. Comments to: arsperl@arsperl.org (this is a *mailing list* and you must be a subscriber before posting) Home Page: http://www.arsperl.org --------------------------------------------------------------------------- 1.80 Notes ---------- The 1.80 release includes ARS 5.x integration. When compiling against ARS 5.x APIs, the ars_NT* functions (notifier library) will no longer work. The notifier system has completely changed in release 5.0 of ARsystem. Regardless of what version of API you compile against, the following functions have had their parameters altered which means that scripts will need to be editted (unless you are using the OO layer). Function What's Changed -------------------------------------------------------------- ars_GetListEntry additional required parameter ars_GetListEntryWithFields additional required parameter The following functions have altered return values. Function What's Changed -------------------------------------------------------------- ars_GetCharMenu for query menus, the labelField is no longer a scalar. it's now an array ref. 1.68 Notes ---------- The 1.68 release includes ARS 4.5 integration. When compiling against ARS 4.5 APIs, the following data structures will change which _might_ break existing scripts. You might need to update those scripts when recompiling ARSperl against the 4.5 (or later) libraries. Data Structure Used/Returned By -------------------------------------------------------------- Active Link Hash ars_GetActiveLink() Active Link Hash ars_CreateActiveLink() Filter Hash ars_GetFilter() Escalation Hash ars_GetEscalation() The majority of users should be unaffected by this since most probably don't retrieve the actual definitions of these objects in their scripts. In addition, ars_Import() has changed. It now has a different parameter list. This means that existing scripts will need to be updated. See the documentation on this function for details. When compiling against an API revision prior to ARS4.5, the hashes returned by the above functions include a "schema" key which denotes which schema the object is "attached" to. As of 4.5, it is possible to attach an object to multiple schemas. The hash key has changed from a scalar (string) to an array of (one or more) scalars and the name of the key has changed to "schemaList". On an unrelated note, the ars_GetCharMenu() call now decodes the "menuType" hash key. Previously it was returned as a number (a raw enumeration value) and you had to figure out on your own what that number meant. Now we decode it so you get a string telling you what sort of menu it is. This change was made to bring this function inline with how the other ARSperl functions operate. Again, you might need to update some of your scripts. This change is true regardless of what revision of the ARS API you compile against. 1.62 Notes ---------- The 1.62 release includes ARS 4.0 integration. There are a few things that have changed regardless of what version of ARS you compile against and there are things that have changed only if you are compiling against v4.0 (or greater). First, regardless of what version of ARS you are compiling this against, ars_perl_qualifier now takes a control struct (in addition to the encoded qualifier). When compiled against pre-4.0 APIs, the control struct parameter is still required, but is ignored. IF YOU USE THIS ROUTINE IN EXISTING SCRIPTS, THEY WILL NEED TO BE CHANGED. Previously, when perl executed "use ARS;" it would automatically trigger a call to ARS::__ars_init(). This routine was im`ortant for setting up system specific stuff as well as preparing to connect to a private server. Now this routine is part of ars_Login() because, as of 4.0, we need the control structure that ars_Login() generates in order to call ARInitialization (a.k.a. __ars_init). The __ars_init() routine is still there and is callable, but doesn't do anything if you compile against ARS>=4.0 Similiarly, when your perl script exitted, ARS::__ars_Termination() was automatically called for you. This can no longer be done because we, once again, need the control structure when we are cleaning up (to release licenses, etc). So, the functionality of this routine is now rolled into ars_Logoff(). This means that if you don't call ars_Logoff when your script completes (or when it prematurely exits) you might not release your license. This shouldn't affect too many things, but is something to keep in mind. You might want to place END{} clauses in your scripts that can call ars_Logoff() if/when your script(s) die(). Also note that, as of v4.0, the ARS API is now multithreaded. This means that you must linking the POSIX threads library when compiling ARSperl. I have not determined what impact this has under Windows NT. I would guess none since NT is normally a threaded environment - you probably get the appropriate thread routines either way. 1.6 Notes --------- The 1.6 release marks the first real NT port. v1.5x attempted a port to Active State's Perl for Windows, but wasn't successful. Bill Middleton re-worked the source code and merged it into Gurusamy Sarathy's version of perl for windows. 1.5 Notes --------- This release contains serveral bug fixes and minor feature additions. An effort was made to implement the remaining ARS functions, however, it proved to be very time consuming to implement and test them. Therefore, in this release most of the remaining functions have been implemented. The rest will likely be implemented in a future release. See TODO for a list of remaining functions. 1.4 Notes --------- The notifier functions have been added to the main package. This allows a script to connect and register itself as a user and then receive notifications (examples are included). You can also send notifications from a script. Joel made all the changes to get it to compile and work against ARS3.0 So the current distribution will compile against 2.0, 2.1 and 3.0 libraries. Everything basically remains the same so you don't need to modify your scripts. The only things that change are the NT (notification) routines to a certain extent. However, since NT (notification) support is new to this release, this shouldn't be a problem. The doc has been reorganized as well. 1.3 Notes --------- We've added some features for performance analysis. In particular, we've added the "profiling" feature to ARSperl. Now, when you call ars_Login() it initializes a profiling variable that will track the number of queries your script makes against the server. You can then access this information using the ars_GetProfileInfo() call. We send this information to syslog() automatically at the end of each script and then process the syslog file later on to keep stats on our API scripts. In this fashion, we can quickly determine which scripts are triggered the most, and which make the most queries. We can then concentrate out optimization efforts on those particular API scripts. In addition, a few new functions were added (GetFilter, GetCharMenu and GetServerStatistics, ars_Export). The first two are used by the WhoUsesIt.pl utility. This utility (found in the "examples" directory) is handy for locating which filter or menu is referencing a particular file, or seeing exactly what filters a particular schema uses.. etc. This cuts down the amount of time it takes to figure out a poorly documented system (what? poor documentation? not us!! :) The GetServerStatistics function was added to provide a simpler method for checking server health. I might provide a server analysis tool built around this function in a future release. Joel added a cache to the internal GetField routine. This should cut down on the number of queries made by some of the functions like GetFieldTable and such. In addition, doing ars_SetEntry($ctrl, ..., $fieldId, undef) will now correctly set a field to $NULL$ 1.0 Beta User Notes ------------------- o The library and extension seem fairly stable. However, bugs and memory leaks might still occur. We've only been able to build it under Solaris 2.x (4 and 5 to be specific) because that is what we run ARS under. Users who attempt builds on other systems and are successful should submit diffs back to us so that they can be incorporated into the distribution. o The WEB client example works (more or less) but there is much room for improvement. o There is a mailing list available for people to share their thoughts concerning ARSperl. --------------------------------------------------------------------------- arsperl@arsperl.org