piXie V2.2b Release Notes January 13, 1993 What is piXie? piXie is a simple X.500 directory user agent for Microsoft Windows. It was written in response to the need for a simple, inexpensive (that is, free...) application which could be provided to NASA Headquarters users to access the NASA-wide X.500 directory implementation. The emphasis was to produce a simple user agent that can meet most users' needs. Users seeking more advanced features should consider one of a number of commercially available products. piXie was written under contract to the NASA Science Internet Advanced Network Applications group with the participation of the NASA Headquarters network group. The binary software may be freely distributed as long as all components, including this document, the following copyright, and disclaimer, are distributed together. piXie Copyright (c) 1993 by Michael C. Newell. LDAP Copyright (c) 1990 by the Regents of the University of Michigan. All rights reserved. Redistribution in source and binary form is permitted providing (1) redistributions of source code must retain this copyright notice and disclaimer, (2) redistributions in binary form must reproduce the above copyright and the disclaimer must be included in the package, (3) neither the names of the authors nor their sponsors may be used to endorse or promote products derived from this software without specific prior written permission, and (4) distributors may not charge recipients for the distribution or use of this software except to recover direct reproduction costs. DISCLAIMER: This software is provided "as is" and any express or limited warranties, including but not limited to the implied warranties of merchantability and fitness for a particular purpose, are hereby disclaimed. In no event shall the authors or their sponsors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, wether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. Any opinions expressed in this document or in the piXie code are my own and do not reflect the opinions of my management, the company I work for, NASA, or the United States Government. Your comments are appreciated. Please e-mail them to "mnewell@nsipo.nasa.gov" and they will be given due consideration. We are interested in minor extensions to the softare; if you see something we glaringly forgot, please let us know. piXie has some known problems which we may fix in the future, providing we have time. We really look at piXie as an interrum solution; there are a number of very nice commercial products being developed and we feel those are more appropriate for most people. Given that, the known problems are: - piXie will only reliably bind with LDAP servers at Version 3.0, although it seems to work with V2 servers most of the time. - You can use LIBLDAP.DLL files that are of later vintage than the one supplied, however the one supplied fixes an allocation bug in the LDAP library that causes memory buffers greater than 64K to be allocated (actually, it's not really a bug, just a SEVERE limitation of Windoze.) - I can't get the minimized icon to display correctly. I'm dabbling with it, but I want to get a version of this code out that doesn't cause machines to reboot, and icon displays seemed a pretty minor nit to hold that up. Please don't repeat these shortcomings to us... :{) (One last note: I appologize for the bad spelling, but Write does not have a spell checker and I wanted to do this in a form that would be readable on all Windows platforms. Much to Mr. Gates' dismay, not all platforms have Word available... Also you may see a stray "|" here and there; my left shift key generates them randomly and I don't always catch them.) Requirements piXie was written in Visual C++ using the University of Michigan Lightweight Directory Access Protocol (LDAP) library implementation V3.0. This implementation requires a Winsock (Windows Socket) implementation accessing a full TCP/IP stack. piXie was written using Frontier Technologies SuperTCP, but it has been tested successfully on other Winsock stacks. Basically if your TCP/IP provides something called "WINSOCK.DLL" and you have it installed properly then piXie should work. piXie has also worked on OS/2 and Windows NT. Surprise!! Some of the dialog boxes are fairly large, so you may have trouble on low resolution screens. I wrote it on a machine that does 800x640 (it does higher, but I can't read it) and some of the boxes almost fill the screen. However, it should run fine on lower resolutions; you may have a lot of window moving though. Installation In keeping with it's "simple" requirement, there is no installation program for piXie. You should have received the following files as part of the kit: PIXIE.EXE the application program. LIBLDAP.DLL the LDAP dynamic link library. RELEASE.WRI this file. PIXIE.INI an initialization file. It is suggested that you edit and use this one X500WDUA.DLL the Browsing and Viewing dynamic link library X500WDUA.WRI explains about the DLL and some of the things you can do with it If you didn't get all of these files please contact me; I'll get you replacements. To install piXie, do the following: 1. Copy the above files into a directory. For best results, put all of them in the same directory. 2. Invoke the Program Manager, and open the program group in which you want to include piXie. 3. From the Program Manager "File" menu, select "New" to create a new program group. 4. Enter an appropriate label for the description (I used "piXie") and the full path designation for the PIXIE.|EXE| file for the program name (usually "C:\WINDOWS\PIXIE.EXE".) The really cool piXie icon should appear in the group. Operation It is beyond the scope of this document to describe the X.500 system and the world-wide directories accessible via the Internet. There have been a number of papers published recently on this subject, and more are expected as X.500 directories become more prevelent. In summary, the X.500 directory system consists of levels of directories, with countries at the top followed by successive levels down through states, organizations, and organizational units. At NASA this looks like c=US : other groups o=National Aeronautics and Space Administration ou=Ames Research Center ou=Headquarters : other sites within NASA thus a typical name for a person at NASA Headquarters might be cn=Mike Newell,ou=Headquarters,o=National Aeronautics and Space Administration,c=US where "cn" means "common name", "ou" means "organizational unit", "o" means "ogranization", and "c" means "country". piXie breaks this up into two parts; the person part is "cn=Mike Newell" and the rest is the directory part. The directory system is comprised of a number (a BIG number) of hosts which distribute the directory around the world. These hosts are called Directory Service Agents (or DSAs), and it is their responsibility to insure that their local data is reachable by others in the world. The DSAs all talk to each other, so you can ask any DSA about any person anywhere in the world. At least that's the theory. The original X.500 system was based on the ISO OSI network stack (if you don't know, don't ask!) The Univeristy of Michigan created a method of accessing DSAs using TCP/IP called LDAP. LDAP is MUCH better suited for small computers than OSI, and I have used the University of Michigan code; thus piXie requires you have access to a directory on a TCP/IP network which runs LDAP (there are many such directories.) That said, on to piXie. To invoke piXie, simply double-click its icon. The main dialog window will appear. This window has three fields for entering data: Search for: this is the name of the person you want to search for. You may specify the first and last names, or just the last name. If you are learned in the ways of X.500 querying, you may specify any filter for which you wish to search by using the format 'attribute=value'. For example, to find only those people whose last name is "smith", you could type 'sn=smith'. Or, if you want to find only those people who have photos, you could type 'jpegPhoto=*'. As you can see, wildcards are acceptible. in directory: this is the name of the directory in which to look for the person. It is tempting to set your directory to a high level; for example, setting it to "c=US" will look for the person in ALL of the US directories! This is EXCEEDINGLY time consuming, however, and people may start noticing you (and in this world it's best not to be noticed... Especially by system management types!) You should specify your directory as narrowly as possible to avoid long lookups. using server: this is the TCP/IP name of your LDAP server. It has nothing to do with the actual directory you will be looking in; all the DSAs talk to each other so all you need is access to one. All of these fields are case-insensitive. Once you've filled in these fields, you can press the "Do Search" button to look for the person. You will notice that the title bar changes; that tells you what piXie is up to. piXie tries to look up the person by both common name and surname; so if you specify "newell" in directory "ou=Ames Research Center,o=national aeronautics and space administration,c=us" you should find me. piXie first tries to find an exact match; if that fails, piXie will try approximate matches. The approximate matches are pretty amusing sometimes... You can disable the approximate match feature by clicking the "Retrieve only exact matches." checkbox. Once piXie finds a unique match, it displays all the information about the person in a new window. You can copy data out of the fields in this window and into other applications; to do so, highlight the data you want to copy with the mouse, then press the "CNTL-C" button. Switch to your other application and select the paste feature, usually "CNTL-V". You cannot use piXie to change any of the data in the database. This feature MAY be added at a later date. Sometimes (like when you search for "smith") piXie will get a lot of responses. piXie currently will accept up to 100 matches. If multiple matches are received, piXie will list just the names and directory information in a separate list window. To view an entry, just double click it. When you are done, press the "Done" box to return to the main menu. You may have noticed that the directory names are a bit, uh, annoying to have to type. piXie has two features to help you deal with directory names. The first feature is the small down-arrow box on the right side of the directory name field. When you press this piXie will drop down a list of all the directories you have successfully queried in the past (these are stored in the PIXIE.INI file mentioned above.) You can select one of these by simply scrolling to the appropriate one and double clicking it. piXie will copy it into the directory field for you as if you had typed it in. The second feature is the "Browse" button. This button relies on the fact that the directories themselves are entries in the next higher-up directory; thus "National Aeronautics and Space Administration" is itself an entry in the "US" directory. When you click the "Browse" button piXie will present you with a new window which contains all the items in the current directory. At the top is a pulldown list that shows you where you are from the very beginning (e.g. 'Earth'). You may move freely in 'X.500-Space' and when you reach the place where you want to start searching, you can hit select. There are two possibilities for this selection. If you select an item from the list of choices, the 'Select' button will choose that item. If no item is selected from the list, the 'Select' button will use the currently shown item from the pulldown list mentioned above. In either case, the 'Select' button causes the selected item to be placed in the 'in directory' field of the main pixie window. When you are done, press the "Quit" button. You don't have to worry about leaving piXie up; it only connects to the server as needed so you won't have to worry about rabid system managers beating on your door. You can also minimize piXie for later use without quitting. (Appologies about the lack of a neat icon - I'm still confused on that one!) Also, be sure to press the "About" button so you can see the acknowlegements!! A note to seXie users... The initial incarnation of piXie was called "seXie". This was because one of the network managers asked for a "sexy Windows application" to access DSAs. The name "seXie" stood for "Simple Experimental X.500 Inquiry Enabler". Some persons (quite reasonably) felt this name was inappropriate for a released product; hence the name change to piXie. It still pretty much works the same; please excuse our dust... Changes since the release of seXie. This version includes a number of changes and corrections to problems previously noted in seXie. In brief, these are: - Changed the item returned limit to 1000 items. There really needs to be a properties dialog... - Fixed the directory code so that it now saves the directories searched as "directory_n" in the ini file, and also it now keeps the last directory searched at the top of the list. Old configuration files will be automagically cleaned up. - Fixed the word "Received" in the result selection dialog box. - Removed the minimize box from all the subsidiary dialog boxes. - Rationalized the tab ordering for the main dialog box. - Changed the name to piXie at management request. - Added an icon. I'm still having problems displaying it, but I don't have any more time to mess with it and I want to release this code because of the GP faults. Acknowlegements piXie was originally written by Mike Newell (See his acknowledgements below). I have taken it over to provide a little more functionality and support if needed. I have changed little of Mike's code for the main window and for searching. I have totally rewritten the browse and view information windows and put them into a DLL (windows Dynamic Link Library). I did this mainly to test my DLL to see if it would be easy to incorporate into programs. The DLL is theoretically reusable by any application, thus allowing developers to easily create 'X.500-Enabled' applications. It also includes a main search window and soon a modification window to allow users to change their X.500 information. Kevin Lussier Sterling Software NASA Ames Research Center klussier@atlas.arc.nasa.gov piXie actually comprises surpirsingly little code; most of the work is in the LDAP libraries. Thanks to the University of Michigan LDAP group for a nice programmer interface and for all the support they have provided during piXie's implementation. piXie was written under contract to the NASA Science Internet Advanced Network Applications Group, of which I am a member. Not only did this group provide help (and act as guinea pigs for the first alpha release), but the Project allowed me to slip other work to produce this program. In all probability others of my group will be taking over the code (yes guys, I heavily commented it!) piXie was extensively tested against the NASA Headquarters DSA; thanks to the Headquarters networking group for their help (they too were guinea pigs...) Also the name comes from this group; they wanted a "sexy Windows interface" and they got one! (Ok, guys - can I get back into the directory now????) Mike Newell NASA Advanced Network Applications Sterling Software 700 13th St. NW Suite 950 Washington DC 20005 mnewell@nsipo.nasa.gov