JRButils v9.0 Readme

Contents

o Points to Note and Known Issues
o Incompatibilities with Previous Versions
o Year 2000 Compatibility
o Documentation
o Which Program to Use
o Contact Details
o Acknowledgements

-----------------------------------------------------------------------
Points to Note and Known Issues
-----------------------------------------------------------------------

General

1.   The documentation is best viewed with version 4 of the Adobe
     Acrobat reader. This will be automatically installed if acrobat
     is not present on the installing machine. But if an earlier
     version is present, it will not be replaced with version 4.
     Uninstall the earlier version, reboot, then install version 4
     by running rs405eng.exe in the acroread directory on the CD, or
     from the acroread subdirectory of the directory JRButils was
     installed into.

2.   The full graphical versions in Part E have been developed using
     Borland's C++ Builder. The move from command line to GUI
     involves a huge amount of new development and C++ Builder has
     not simplified this as much as expected. Only a selection of
     utilities are provided with a full GUI interface. We have
     developed these as far as time has permitted but there is
     obviously much more to be done. For example, while all programs
     have tool tips, only jrbpass and requests have inbuilt help.
     During 2003, we expect to further refine these utilities, to
     provide a GUI interface to more utilities, and to combine some
     (e.g. grplist, grpadd and grpdel) into single programs. We
     would appreciate feedback on the GUI interface.

2.   The 32 bit versions cannot make changes to the environment of
     the command prompt in which they are running under Windows
     95/98/ME. This affects the jrbmap and setcx programs.

4.   The 32 bit versions of home2, jrbmap and setcx can make changes
     to the environment or the current directory of their parent
     process (cmd.exe) under Windows NT, 2000 and XP. To do this,
     they need psapi.dll on NT which is not part of the standard
     installation of NT. A copy of psapi.dll is in the Part_c and
     Part_d directories on the CD and must be copied to the
     winnt\system32 directory.

5.   Programs such as deladdr and users, which process a list of
     server names, may appear to hang when an invalid server name is
     given, and the client is configured to use Novell's Service
     Location Protocol (SLP), but no Directory Agent (DA) is present on
     the network. They will in fact time out from waiting for a response
     from a DA after around 15 seconds. The solution is to turn off SLP
     at the client (under the NetWare client's advanced settings), or
     to enable a Directory Agent.

6.   The lscripts and edit_pjc programs cannot perform any actions
     requiring access to print job configurations stored in mail
     directories. This problem has been reported to Novell, they have
     acknowledged the fault, but at the time of release of this version
     of JRButils, no solution was available.

7.   Novell's client software must be running on the workstation.
     The Microsoft client for NetWare does not support Novell's
     32 bit APIs.

8.   When running on an NT workstation client, some programs in
     JRButils (both 16 and 32 bit versions) may fail to execute and
     report that "the directory handle table is full". This problem
     arises because an application is allocating directory handles
     then failing to release them. Each connection to a NetWare server
     has an associated connection handle table that can hold up to
     255 entries. Normally a few handles are allocated to permanent
     drive mappings and the rest are available for temporary use by
     applications. This problem is not caused by JRButils. It has been
     experienced by organizations which do not use JRButils when
     attempting to run Novell's programs such as auditcon in
     sys:public. At the time of writing, the offending application is
     unknown. The problem can be worked around by logging out and
     logging in again.

9.   If a program is producing output and control-c is pressed under
     NT 4.0 with service pack 6 installed, or under Windows 2000, a
     blue screen of death may result, or the machine may just reboot.
     This is a Windows bug. Pausing the output before pressing
     control-c seems to avoid the problem.

10.  Windows NT, 2000 and XP allow multiple commands to be given on a
     line with "&" being used as the command separator. This treatment
     of "&" as a command delimiter affects a number of programs in
     JRButils which make use of "&". Grplist and wgrplist use "&" as
     an "and" operator, and other programs such as trstlist allow "&"
     to precede a group name to indicate that the action should be
     performed on the group?s members and not the group object. To
     prevent "&" being intercepted by the windows command interpreter,
     it must be enclosed in double quotes e.g. trstlist "&group" or
     grplist g1 "&" g2.

11.  All programs accept substitution identifiers denoted by "%"
     characters in log and error file names, and some programs such
     as dquota and getname make other uses of "%" characters on the
     command line. When these programs are run from a batch file, the
     batch command interpreter assumes that "%" characters are present
     to denote environmental variables whose name should be replaced by
     the variable's value. To prevent interpretation of the "%"
     characters use two consecutively e.g.
     getname * /a="%%login_name\30 %%telephone".

NDS Issues

1.   This release of JRButils has limited support for Z.E.N. Works
     related objects. Novell have yet to release to developers, the
     information required to develop programs for managing these
     objects.

2.   This release of JRButils works correctly with NDS v8.x with one 
     exception. The sole known problem with JRButils is due to an NDS 
     v8 bug where the function NWDSSearch fails to return any objects 
     when the search pattern includes an underscore. For example 
     'getrest s_* lld' returns no matching objects even when,
     for example, s_jones exists in the current context. The bug was
     acknowledged by Novell in July 2000 and has been fixed in eDirectory 
     8.5 but it appears that the fix will not be incorporated into NDS 8.

3.   It is not possible to specify NDS tree names in NDS aware
     programs. Object names and paths may be separated by server
     names, but not by tree names. However, it is possible to change
     the default tree using jrbcx prior to running some other program
     such as listobj.

4.   The NDS aware programs may give incorrect relative names when
     you have two containers with the same name, one immediately
     below the other e.g. test.test.jrb. When names are expressed
     relative to test.jrb, the lower test container name may be
     omitted e.g. john.test.test.jrb is output as 'john' instead of
     'john.test'. This is due to a bug in the SDK.

5.   Partial names using a trailing period may not be expanded
     correctly again due to an SDK bug. This happens intermittently,
     sometimes it works, sometimes it doesn't.

6.   A feature of NDS is that in general, it is not necessary to know
     on which file servers an object exists. A server receiving a
     request for information about an object which is not in a replica
     held on that server, will contact other servers to obtain the
     information. The programming interface to NDS was designed on the
     assumption that requests do not need to be directed to specific
     servers, but this has caused a problem during object creation
     where the creation request can be sent to one server, and a
     subsequent request to add an attribute to the new object can be
     sent to another. The second request will fail when insufficient
     time has elapsed for replication to occur. The server receiving
     the request will recognise that it holds a replica in which the
     object should exist, therefore it wont contact other servers, and
     returns an error corresponding to "no such object". Novell have
     provided a work around to this problem which is implemented in
     JRButils. Any NDS object name given on the command line or in
     an input file may be preceded by a file server name e.g.
     moki/.barney.sales.xyz. Each program will attempt to direct
     all NDS requests to that server. A batch file being used to
     create objects should make use of this e.g.

        creatobj moki/.%1.admin.xyz
        grpadd moki/.dialin.admin.xyz .%1.admin.xyz
        setacl moki/.%1.admin.xyz full_name [root] r

File System Issues

1.   The version of NSS included in support pack 1 for NW 5.1, support
     pack 5 for NW 5.0, and nss5a.exe contains a bug preventing the
     change of ownership of files when volume restrictions (quotas) are
     enabled on the volume, the user to which ownership is being
     assigned does not have a volume restriction and does not own any
     files on the volume. This affects setowner, and both netcopy and
     fsupdate which will report that they are unable to set the file's
     attributes. The easiest solution is to assign the user a
     restriction. The bug has been fixed in subsequent NSS releases.

2.   The version of NSS included in support pack 1 for NW 5.1, support
     pack 5 for NW 5.0, and nss5a.exe contains a bug where the function
     NWAFPGetFileInformation may fail. This affects netcopy and fsupdate
     when copying Mac files to an NSS volume. Both have been updated to
     attempt to work around the problem, but they cannot do so in all
     circumstances. The bug has been fixed in subsequent NSS releases.

3.   Setting large numbers of directory quotas via setquota on NSS
     volumes when the directories contain many files, may lock the
     server. The problem may be avoided by changing the default value
     for the NSS numWorkToDos parameter at the server console e.g.
     nss/numWorkToDos=100.

4.   The version of NSS in support pack 2 for NW 5.1 and in support
     pack 6 for NW 5.0 implements directory quotas. However, there is
     a significant bug in the implementation where the space used in
     a directory is shown as zero after setting a quota regardless of
     the actual usage. Only files added to the directory after the
     quota is set contribute to the usage reported by the SDK functions
     returning the quota and usage. This problem has been fixed in later
     versions of NSS.

5.   On traditional file system volumes, NetWare keeps track of the
     total space occupied by files in every directory and its
     subdirectories. On NSS volumes, NetWare does this only when a
     directory quota is set. This is a significant disadvantage as
     without a quota set, the only way to determine the usage is to sum
     the space used by every file in the directory and its subdirectories,
     and this may be time consuming where there are large numbers of
     files and subdirectories. Getquota, dquota and whodidit are affected
     by this. They will sum the space used when no quota is set.

6.   NSS volumes behave differently from traditional volumes with
     respect to extended characters in file names. Extended characters
     are not allowed in DOS file names under NSS and will be removed
     from the name. This may lead to unexpected changes in DOS file
     names when files are copied to an NSS volume. On traditional
     volumes, some extended characters will differ between name
     spaces. For example if a Mac file is created containing the
     character represented by ASCII value 0xF9, the character 0xC4
     will appear in its place in the long name. On NSS volumes, the
     0xF9 character will also appear in the long name. These
     differences in behaviour may cause problems with applications
     using affected files.

7.   The total reads and writes by connection displayed by the users 
     and requests programs may be incorrect. Due to a bug in NetWare, 
     under NW 5.0, NW 5.1 prior to SP5, and NW 6 without a support pack 
     installed, the total reads and writes apply to traditional volumes 
     only. The values displayed do not include reads and writes from NSS 
     volumes. However, this problem was fixed in SP1 for NW 6.0, and SP5 
     for NW 5.1.

8.   Netcopy and fsupdate may fail to set file attributes on servers with 
     anti virus software installed and which is configured to scan files 
     after they have been written. Setting attributes requires that the file
     is closed, but the anti virus software may re-open it after netcopy and 
     fsupdate have closed it and before they have set the attributes. Both
     have been updated to minimize the delay between closure and setting the 
     attributes. Macintosh files are even more susceptible to this problem 
     as there may be a resource fork to copy, and macintosh specific fields 
     such as the finder information must be copied separately from the DOS
     attributes.
     
9.   Novell's August 1998 document entitled "Troubleshooting High
     Utilization for Novell NetWare 4.1x" records an issue with an
     SDK function named NWScanObjectTrusteePaths which is used to
     scan for trustee assignments belonging to both bindery and NDS
     objects. When the volume being scanned has more than 2.5 to 3
     million directory entries, the search process scanning the
     directory entry table may lock the volume until the search is
     completed. This excludes any other activity on the volume such
     as reading and writing from taking place. The high utilization
     caused by the search process together with the volume lock may
     cause users to lose connections, logins to be very slow, and in
     extreme cases the server may hang or abend. This problem is
     limited to NW 4.11 onwards, as earlier versions had a maximum of
     2 million directory entries per volume. Programs in JRButils
     potentially affected by this problem are trstlist, settrust,
     copy_obj, and copyuser. Currently Novell do not have a solution
     to this problem.

10.  A bug in some versions of NFS.NAM (the server loadable module
     implementing NFS name space support) will cause the server to
     crash when nsrename is used to rename a file in only the NFS
     name space. The problem has been confirmed on NW 4.11 and
     NW 5.0. NFS.NAM v7.14 or later for NW 5 fixes the problem.
     A corrected version of NFS.NAM for 4.11 is available from
     support.novell.com in nfsnam23.exe.

11.  Netcopy, fsupdate and copyuser will in most cases attempt to
     retain the same DOS names for LONG, MAC, NFS and FTAM files.
     They cannot do so under NW 3.11, and do not attempt to do so
     when copying from NW 3.x or 4.x, to 5.x or 6.x, or vice versa.
     NW 5.x and 6.x use the Microsoft convention for DOS names,
     whereas earlier versions used the first 8 characters of the long
     name with spaces removed if necessary, and replaced the eighth
     character with a digit in the event of the name being already
     used. The following illustrates the different naming conventions
     assuming the 3 files are in the same directory.

          Long name           Dos name        Dos name
                              (NW 4.x)        (NW 5.x)
          Photograph1         PHOTOGRA        PHOTOG~1
          Photograph2         PHOTOGR0        PHOTOG~2
          Photograph3         PHOTOGR1        PHOTOG~3

12.  Netcopy, fsupdate and copyuser can retain compression when
     copying compressed files to a volume supporting compression.
     One exception, is they cannot retain compression on Macintosh
     files with a '/' or '\' in the name. The functions allowing
     a file to be opened in compressed mode, do not support '/' or
     '\', and the Mac specific functions which correctly handle '/'
     and '\' do not support compression! There are also problems when
     the Mac name includes '*' or '?' which are not valid in other name
     spaces. The name of the copied file may change, so the above
     programs do not attempt to retain compression, allowing the Mac
     routines to be used.

DOS Issues

1.   Under DOS, the maximum length of any command is 128 characters,
     and the computer will beep when you attempt to enter a longer
     command. Under NT, commands can range up to 2048 characters.
     However, when running a 16 bit program, NT will allow commands
     longer than 128 characters to be entered but will then fail to
     run the program reporting "The system cannot execute the
     specified program".

2.   The NDS aware programs in Parts B through E require access to the
     unicode files appropriate to your country and code page settings.
     These are usually located on the server in the nls subdirectories
     of sys:public and sys:login. For those running Win95, Win98 or
     WinNT, they are also located on the hard drive and JRButils will
     locate them there as the relevant directory is included in the
     search path. However, the 16 bit utilities in Part B may have
     difficulty locating the unicode files when run from DOS. The
     Novell-supplied code in the development kit searches for the
     unicode files as follows:
       o  The directory from which the application is run
       o  An nls subdirectory of the directory from which the
          application is run
       o  The search paths
     As the NDS aware programs will not perform NDS operations without
     the unicode files, you must place the unicode files in a location
     where they will be found. For each country and code page
     combination, four files are required. For example, for country
     001 (USA) and code page 437, the files are:

         uni_437.001
         437_uni.001
         uni_mon.001
         uni_col.001

3.  Novell no longer support the 16 bit environment and the DOS
    utilities are built using the last version of the 16 bit
    development kit released in 1999. There are a couple of known
    issues:
      1. The SDK function NWParsePath which is used in all programs
         accepting a path as a parameter, appears to fail when the
         workstation has two CDROM drives. The programs work
         perfectly when MSCDEX is not loaded, or the second CDROM
         drive is disconnected.
      2. A report was received of grpmemb working correctly on some
         workstations but not others. An older version built using
         SDK V6 worked correctly on all machines. The reason for this
         was not determined, but whatever the problem is, it may
         affect other programs.

4.  The users and killconn programs cannot identify NOT-LOGGED-IN 
    connections on NW 6 due to a bug in the function call used under 
    NW 6. The 32 bit versions of these programs have been updated to 
    use a newer function which behaves correctly but which is not available 
    for 16 bit programs.

-----------------------------------------------------------------------
Incompatibilities with Previous Versions
-----------------------------------------------------------------------

Every attempt is made to ensure compatibility with earlier versions
of JRButils. But occasionally there are good reasons to make changes.
V9.0 contains the following changes which should be noted.

o   The function of /f in getname has changed. Previously this was an 
    alternative to preceding an input file name with @. Now, it allows 
    an attribute to be specified for which filtering via /n is applied.

o   In listobj, /^ has been changed to /+ because the ^ character is used 
    by the Windows command line parser, and so was stripped from the command 
    unless it was enclosed in double quotes.

o   The function of /o in sethome2 has changed. Previously it indicated that 
    the input file contained home directory paths as well as object names, 
    but this has now been assigned to /v. Now, /o may be used to indicate 
    the object class for <entity>. This is consistent with most other programs 
    which use /o for this purpose.

o   The function of /m in setname has changed. Previously it indicated that 
    the input file was a NW 3.x makeuser file and that setname should 
    convert the full names to mixed case. This functionality is no longer 
    available. Now, /m is used to specify the Path value when setting 
    attributes using the Path syntax.

o   The function of /f in setpword has changed. Previously this was an 
    alternative to preceding an input file name with @. Now, it may 
    be used to force setpword to require the old NDS password before 
    setting a new one.

o   In programs such as getname and setname, city could be used as an 
    alternative name for the Physical Delivery Office Name attribute. 
    However, an attribute named city was introduced in eDirectory 8.5. 
    Now, any program given city as an attribute name will check for the 
    existence of this in the schema. When the attribute is defined, it is 
    used instead of mapping city to Physical Delivery Office Name.


-----------------------------------------------------------------------
Year 2000 Compatibility
-----------------------------------------------------------------------

For those still concerned about Y2K, JRButils have undergone
extensive Y2K testing including examination of the source code, and
nearly three years of usage since 1 January 2000. There are no known 
Y2K issues in the v9.0 release. The year 2000 is treated as a leap year, 
and for those planning ahead, 2100 is not. It must be noted that while 
there are no known Y2K issues in JRButils, their compliance is in part
dependent on the compliance of Novell's SDK, the workstation OS, the
NetWare client running in the workstation, the workstation hardware,
the NetWare OS and the server hardware, all of which could potentially
result in incorrect date information being retrieved and displayed by
programs in JRButils.

-----------------------------------------------------------------------
Documentation
-----------------------------------------------------------------------

The manual for JRButils is shipped as an Adobe Acrobat PDF file. This
is encrypted on the CD, and may be de-encrypted and installed when
using the setup program. For those who purchased documentation, a
key is provided on a label on the rear of the CD case. Customers who
did not purchase documentation and require it subsequent to purchase,
will be provided a key upon payment of the $US100 fee per license for
documentation.

Note that every program contains in-built help giving basic details on
how to use it. The help may be displayed by running any program with '?'
as the first parameter.

-----------------------------------------------------------------------
Which Program to Use
-----------------------------------------------------------------------

The number of programs in JRButils and their extensive range of
capabilities may lead to those new to the product having difficulty
determining which program to use to perform a particular task. For
those who have purchased documentation, the index to the manual may
be used, and the Acrobat reader has a search facility to locate
keywords or phrases. An alternative is jrbguide.pdf in the PART_A and
INFO directories on the CD. This contains a section entitled "Which
Program to Use" indicating the program to use for a very wide range
of tasks. Finally, feel free to contact support@jrbsoftware.com for
advice. If JRButils does not incorporate the functionality you
require, let us know as we appreciate suggestions for new features.

-----------------------------------------------------------------------
Contact Details
-----------------------------------------------------------------------

Email:   support@jrbsoftware.com
Fax:     NZ +64 3 332 8947
         US (708) 575 1724
Phone:   NZ +64 3 332 5996. This is least preferred option. Please note 
         that this is a New Zealand number, and we are at GMT+1200 in winter
         and GMT+1300 in summer, so take into account time zone
         differences. We make no apologies for sounding half asleep and
         only semi-coherent when phoned at 3 am.
Web:     www.jrbsoftware.com
Postal:  JRB Software Limited
         PO Box 28118
         Christchurch 8000
         New Zealand

-----------------------------------------------------------------------
Acknowledgements
-----------------------------------------------------------------------

1.   Dr Alan McKinnon, Director of the Centre for Computing
     and Biometrics at Lincoln University for assistance in
     obtaining ownership of the original utilities from Lincoln
     University.

2.   David Harris for permission to include his SETHOME and
     HOME utilities, for permission to write SETHOME2, for
     lots of sound advice, and for the use of David's Readme
     Compiler (a great product!).

3.   Mark Cramer for his meticulous testing of JRButils. The product
     has benefitted enormously from his attention to detail and
     suggestions for enhancements.

4.   Craig Saunders and the team at DigitalFusion, Christchurch,
     NZ, for production of the setup programs and other projects.

5.   Craig Benbow for his work on the fully graphical utilities in
     Part E.

6.   Lots of people for their support and for providing invaluable
     feedback including bug reports and suggestions for new features
     and new programs. In particular, Brian Cassidy, Al Lowe-Norris,
     Herb McBride, Juergen Rosemeyer and Jaap van Ginkel.


