Starting AcuConnect on a UNIX Server

To start AcuConnect on a UNIX server, log in as root or superuser, then issue the acurcl -start command on the server command line. Valid options to -start are listed in the following table.

Option   Description
-c

Specifies the name and path of the server configuration file. The -c must be followed by a space and then the path and name of the server configuration file.

When -c is not used, acurcl looks for the configuration file in its default location: /etc/acurcl.cfg for UNIX or \etc\acurcl.cfg for Windows.

-d

Starts AcuConnect on the server machine in debug mode. AcuConnect runs in the foreground. Note that you are limited to one UNIX client connection when you use this option.

-e Causes error output from acurcl to be placed in the named file. Follow -e with a space and then the path and name of the error output file (use this same syntax for the -ee and +-e options listed below).
  • If -e is not specified, acurcl attempts to direct error output to /dev/console.
  • If /dev/console cannot be opened, acurcl attempts to append to a file named acurcl.err in the current directory.
  • If the acurcl.err file doesn't exist, or the file append fails, acurcl prints the message acurcl: can't open error output file to standard output, and acurcl terminates.

You can use -ee to redirect the contents of stderr into the new error file. You can use +-e to append error output from acurcl to the named file.

-f

By default, acurcl runs in the background. Use the -f option to run acurcl in the foreground. When run in the foreground, the acurcl process traps normal keyboard signals, such as Ctrl+C.

If combined with the --t option, the -f option causes acurcl to display tracing and transaction messages directly to the screen. However, if the -e switch is used, all messages are placed in the named log file.

-g Causes the file specified by the -e option to be compressed using the gzip compression method. Because the error file name is not modified to reflect the compression, specify a different file extension for the error file (for example, .gz) when you use this option. To read the file, you must decompress it with gzip.
-l

Causes a listing of the server configuration file to be printed to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables.

When this option is combined with the -e option, the listing is captured in the error output file.

-n

Assigns a port number to one instance of the acurcl daemon. The -n must be followed by a space and then an integer, for example, 5633. This overrides the ACURCL_PORT value set in the server configuration file.

Thin client applications can be assigned to a particular instance of the acurcl daemon via the <server:port> notation on the acuthin command line. Thin clients launched from a Web page can have the port number specified by the atc-port variable in the thin client command-line file. See Thin Client Command-line Files for more information.

The acurcl daemon can work with privileged port numbers (from 0 to 1023), and with non-privileged port numbers (1024 and higher). Privileged port numbers are useful for external, secure applications.

Note: If you start acurcl on two ports, you must also specify all startup arguments, including the configuration file, as in:
acurcl -start -n 5632 -c
c:\etc\config1 [other options] 
acurcl -start -n 5633 -c c:\etc\config2 [other
options]
-t #

Turns on the tracing function. When combined with the -e option, trace information is placed in the named error file. The # symbol represents the type of tracing or logging to be performed, as described below:

  • 1 provides information about access file match attempts. The trace information buffer is flushed to the error file when the buffer is filled or acurcl terminates.
  • 2 provides information about runtime requests. The buffer is flushed to the error file when the buffer is filled or acurcl terminates.
  • 3 provides the information described for 1 and 2.
  • 5 is equivalent to 1, but the tracing buffer is flushed to the error file each time an access file match is requested. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable. See Creating a Server Configuration File for more information.
  • 6 is equivalent to 2, but the tracing buffer is flushed to the error file each time a runtime is requested.
  • 7 provides the information described for 5 and 6.

You can stop AcuConnect at any time by issuing the acurcl -kill command. See acurcl -kill for a discussion of the -kill command options.

AcuConnect returns a status code of 0 after a successful start. When AcuConnect fails to start, it returns one of the following status codes to the operating system, indicating the reason for the failure.

Code   Reason for Failure
1 Invalid argument
2 Missing license
3 Expired license
4 Unable to open the error log file
5 Unable to open the configuration file (writable by other than root)
6 Unable to open the AcuAccess file (missing or writable by other than root)
7 Unable to create a child process
8 Too many servers running
9 Unable to create a socket, because the socket is used by something other than AcuConnect
10 AcuConnect is already running on this port

How you get this status depends on your shell. When you use the Bourne shell (or a compatible shell), enter echo $? to see the return status of any program executed from the shell.

Setting the User Environment in UNIX

With the use of the USE_UNIX_SHELL configuration variable, you can direct AcuConnect to attempt to read your UNIX shell login files based on the shell named in /etc/passwd when AcuConnect starts a runtime. Setting this variable to "true" means that AcuConnect can start a runtime through your login files, and the environment variables you set in these files are therefore available to the runtime.

AcuConnect tries to convince the shell to read the startup files by making the first character of argv[0] = `-', just as login(1) does. As a result, the following environment variables are set:
  • HOME (from /etc/passwd)
  • SHELL (from /etc/passwd)
  • PATH /usr/local/bin:/bin:/usr/bin:
  • TERM dumb
  • LOGNAME $USER

Your startup files may modify these variables or set other variables.

AcuConnect starts the shell as shown:

shell -c "'runcbl' . . ." 

where shell is the user's shell and the ellipsis (". . .") designates the position of the arguments that AcuConnect would normally use to start the runtime. The full path to runcbl is also given. Make sure that the shell used supports the -c option and the ability to set argv[0] to "-". For example, the following shells can be used: sh, ksh, and bash. The csh and tcsh shells are not supported.