STARQUEST CLIENT ACCESS FOR UNIX(R) OS Version 1.0.4.4 Copyright (c) 1996-2005 StarQuest Ventures, Inc. [081505] All Rights Reserved. StarQuest Ventures, Inc. PO Box 146 Inverness, CA 94937 Telephone: 415-669-9619 FAX: 415-669-9629 Sales: sales@starquest.com Support: support@starquest.com URL: http://www.starquest.com **Installation Instructions **About API Documentation **Known Problems **What's new NOTICE: LOCALIZATION and FOREIGN LANGUAGE TRANSLATIONS If you are using translated versions of online HELP, please also see the READNLV file on the product CDROM for online HELP changes since the translations were done. NOTES: * Refer to the platform-specific readme (e.g. aix/aixinst.txt) for additional considerations and instructions for your platform. * Licensing procedures have changed; you must install and configure the StarLicense package. Contact StarQuest support for information about licensing. Ignore all references to STARLM in the documentation. * Some obsolete company contact information may appear in dialogs, error messages, and online documentation, especially when using non-English environments. The current company information is displayed above. * This is the core installer for Client Access for UNIX, which contains the 5250 terminal emulator for character-oriented terminals and X-Windows, file transfer, remote execution, and the classic Client Access API's, including dataqueue and optimized SQL API's. For ODBC or JDBC support, please install the companion products StarSQL for iSeries or StarSQL/Java for iSeries; you may use your Client Access licenses for any of these functions. #################################################### **INSTALLATION INSTRUCTIONS * Mount CDROM, or extract the compressed tar file. * Run setup: Solaris 8 and above: Assuming your CD is mounted at the mount point /cdrom/cdrom0, type: /cdrom/cdrom0/caunix/setup AIX 4.3.3 and above: Assuming your CD is mounted at the mount point /cdrom, type: /cdrom/caunix/setup HP-UX 11.1 and above: NOTE: If you have not done so already, please remount the CDROM using this command: mount -o cdcase /dev/dsk/c0t5d0 /cdrom The "-o cdcase" option suppresses the display of version numbers and the semicolon. It converts file names to lower case. Assuming your CD is mounted at the mount point /cdrom, type: /cdrom/caunix/setup Red Hat Linux 7.3 and above: Assuming your CD is mounted at the mount point /mnt/cdrom, type: /mnt/cdrom/caunix/linux/setup For all platforms: The setup script will install Client Access for UNIX to the default location for the platform and run post_install, which creates symbolic links and creates desktop items. You will be prompted if you wish the install the NLS (National Language Support) packages for localized user interfaces. The installer will also check for the presence of StarLicense, and notify you if these appear to be missing. SET A BROWSER ------------------- A browser is needed for viewing the Post-installation Instructions (Menu item 5). Set a browser before making any selections from the Menu. If you do not set a browser, the default Client Access "cabrowser" is used. SET YOUR OWN BROWSER Follow this example to set the Browser environment variable: BROWSER=BROWSERNAME [e.g., netscape] export BROWSER RUN THE PROGRAM --------------- Run StarQuest Client Access for UNIX OS by changing to the Client Access directory and using one of these commands: X Window: xcamenu Character-oriented terminals: camenu Select 'Help' from the Main Menu for online HELP. #################################################### **ABOUT API DOCUMENTATION - CDROM Version API files are on the CDROM in .HTML format in two versions: 1) Low-level version for browsers provided with Client Access (basic HTML without indented formatting). 2) Better version for commercial browsers (e.g., Netscape, Internet Explorer, etc.) provides a more readable format. - Access Low-level Version of API The low-level version is installed with the Client Access product in the directory ${CA400}/nls/C/ Examples of commands to load the API files: Client Access Browsers: X Window browser: xcabrowser ${CA400}/nls/C/toc_2.html Character-oriented browser: cabrowser ${CA400}/nls/C/toc_2.html Commercial Browsers: browser_name ${CA400}/nls/C/toc_2.html - Access Better Version of API The better version for commercial browsers is available as extras/apidocs.tar. Create a target directory and extract the tar file. Example: # mkdir ${CA400}/apidocs # cd ${CA400}/apidocs # tar xf /cdrom/caunix/extras/apidocs.tar Point your browser at the file toc_2.html in that directory: $ netscape ${CA400}/apidocs/toc_2.html #################################################### **KNOWN PROBLEMS Known problems with Client Access for UNIX OS and workarounds: 5250 EMULATOR (all platforms) ------------- X Window terminals:xca5250 Problem: When you select 27 x 132 Single Byte Character Set from the Session/Settings/Display Type menu, 132 columns are not fully displayed when resizing the emulator. Workaround: Resize the emulator back to the default start-up size. Or, resize the window until the full 132 column width is displayed. 5250 EMULATOR (HP-UX only) ------------- X Window terminals: xca5250 Problem: Keymapping -> Add New Local Keymapping window is blank when selecting Add Mapping. This rarely occurs, but if it does, it indicates a corrupted resource file for xca5250. Workaround: Remove the xca5250rc file in your $HOME/.ca400 directory. Restart xca5250; a new xca5250rc file is written. The Add Mapping function should now work. ********************************************************************* ****What's new in 1.0.4.4 * StarLicense licensing (platforms other than Linux) * API Samples * revised AIX header files ****What's new in 1.0.4.3 * tn5250 device naming (see below for details) * StarLicense licensing (Linux) DOCUMENTATION ERRATA: new feature introduced in 1.0.4.1d: 6344: change default record size of a Source Physical file created by upload You can now specify the record size of a newly created Source Physical file by setting the environment variable RECLEN. This value should be in the range of 13 through 32766. cash will use this value in the API call cwbDB_SetRecordLength(). The default behavior (no environment variable setting) is to use the AS/400 default record length, which is 92. Note that this fix also affects caftp and xcaftp, which use cash. 4701: cwbDB_SetDateFormat() When using the API's to download an AS/400 file containing dates outside the range 1940-2039, you must call the cwbDB_SetDateFormat() API. This has been implemented in the supplied applications caftp, xcaftp, or cash, but you will need to make this API call if you are writing your own application to perform the file transfer. The cwbDB_SetDateFormat() API is not documented in the CAUNIX API documentation, but it can be found in the Client Access for Windows 95/NT API and Technical Reference Version 3 Document Number SC41-3513-03. DEVICE NAMING: ============== The 5250 emulators (ca5250 & xca5250) now support tn5250 device naming (workstation ID), the ability to request a particular virtual terminal device on the AS/400. This function is useful for security, customized menus, and hardware allocation. If you do not supply a value, the AS/400 will use an arbitrary device. Configuration: ca5250: Edit the file $HOME/.ca400/ca5250rc and add the keyword "TNDeviceName". Values are as described below. xca5250: Select Settings... from the Session Menu Choose the feature "Device Name" from the dropdown menu Enter the value in the field for TN5250 Device Name This will add the keyword "TNDeviceName" to the file $HOME/.ca400/xca5250rc. NOTE: This new dialog is available when using English localization. If you are using the localized environment for non-English languages, add the TNDeviceName keyword to the file $HOME/.ca400/xca5250rc. You must disconnect and reconnect before the value takes effect. Value: This option defines the device name (DEVNAME) of this workstation and consists of up to 10 characters. To avoid conflicts from multiple sessions, you can use special keywords in the value to generate unique device names: * Collision Avoidance ID (CAID) - use the special character equals sign ("=") The Collision Avoidance ID will be used to create a new device when the old name was rejected is the Telnet server as already in use. When this occurs, the CAID is incremented and sent to the server as part of a new DEVNAME. The Collision Avoidance ID has a value in the range 1-9 or A-Z. Example: Device Name: MYDEV= The emulator will first try to use MYDEV1; if that is rejected by the AS/400 because it is already in use, then it will try MYDEV2. Note: Because device name must begin with an alphabetical character, do not place the CAID at the beginning of the device name. If you do, the AS/400 will replace the CAID with a "#" character and your session names will not be unique. * Client name - keywords used are "&COMPN" and "&USERN". The Client Naming keywords specify which name associated with the client will be inserted into the generated DEVNAME. No more than one of these keywords may be specified. Other characters present in the Workstation ID (except the Collision Avoidance ID) will be ignored. The keywords are: * &COMPN is the UNIX hostname with domain qualifiers stripped. * &USERN is the UNIX user name If the length of the a client name exceeds the space remaining in the 10-character DEVNAME field, the excess is trimmed from the left side by default. To trim from the right side, place a plus sign ("+") before the Client Name keyword (e.g., +&COMPN). Example: if the hostname is myhost.mydomain.com, defining the device name &COMPN= would generate device names MYHOST1, MYHOST2, etc.