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 1076
Point Reyes Station, CA 94956
Telephone: 415-669-9619
FAX: 415-669-9629
Sales: contact@starquest.com
Support: contact@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.