# PxServer

Using PxServer |

## Running PxServer

Information for running PxServer on Windows and on UNIX is provided below.

#### Important Note:
PxServer is installed as part of PxPlus and requires the Web bundle to run.
(The installation of PxServer as part of PxPlus (Web bundle only) was added in PxPlus 2019 Update 2.)

Windows

PxServer can be run as a Windows service in the background. You can install PxServer as a service using the Service tab in the PxServer Configuration application (PxServerConfig.exe). See Configuring PxServer. Once it is installed as a service, you can control the service using either the Service tab or the Windows Services dialog that is accessed through the Windows Start menu by searching for "Services".

You can start PxServer to run interactively from the IDE Main Launcher (expand the Data Management category and select Launch PxServer) or from the Start menu entry. You can also double click the executable file name (PxServerConfig.exe) from within the PxPlus installation folder.

(PxServer capability to run as a Window service was added in PxPlus 2019.)

UNIX

On UNIX, run PxServer from the Command line using the following syntax:

> dir/pxserver[-f configfile][-p tcpport]

Where:

dir | Directory path (e.g. /usr/pxserver).
-f or --file configfile | Path and file name of the PxServer configuration file. If no configuration file is located, the server will not start, and an error message will be displayed or printed to the log file (if debug is enabled). See Configuring PxServer. If this option is not specified, the PxServer defaults to ./pxserver.conf.
-p or --port tcpport | TCP/IP port number on which the server is to listen. This overrides the port number specified in the pxserver.conf file.

Other Server Arguments

The following arguments can also be used with the PxServer executable at the Command line:

-h or --help | Display a message listing the available Command line options with brief descriptions.
-v or --version | Display the server version information.
-s or --shutdown | Standard PxServer shutdown. If there are clients connected, PxServer will wait until they disconnect and then shutdown. See Shutting Down PxServer below.
--immediate-shutdown | Forced PxServer shutdown. If there are clients connected, they will be disconnected safely and then PxServer will be shutdown. See Shutting Down PxServer below.

## Shutting Down PxServer

A detailed explanation for shutting down PxServer on Windows and on UNIX is provided below.

Windows

To shutdown PxServer running as a Windows service on Windows, use one of the following:

• Use the Stop button in the Windows Services dialog accessed through the Control Panel (in the Administrative Tools sub-folder).

OR

• Use the Stop button on the Service tab in the PxServer Configuration application (PxServerConfig). See Configuring PxServer.

You can also shutdown a manually run interactive PxServer by clicking the Shutdown button on the PxServer window.

If you need the server to shutdown quickly and there are active connections, click the Force Immediate Shutdown check box and then click the Shutdown button. PxServer will shutdown immediately.

(PxServer capability to run as a Window service was added in PxPlus 2019.)

UNIX

To shutdown PxServer on UNIX, run PxServer from the Command line using one of the shutdown arguments:

> pxserver -s OR

> pxserver --shutdown OR

> pxserver --immediate-shutdown

The PxServer records the process ID (pid) of the server in the pxserver.pid file to assist in shutting down the server. Provided that the server can locate the pxserver.pid file, the running server will be shutdown properly; otherwise, an error message will be displayed on standard out.

Alternately, the server can be shutdown using a SIGHUP signal:

> kill -1 pid

Where:

| pid | Process ID of the PxServer pxserver.

## PxPlus Remote File I/O

The process of interfacing with a file on PxServer is very easy and is similar to doing so with the PxPlus RPC protocol. Attaching to a server is done using the PROCESS SERVER directive:

> PROCESS SERVER "server" ON "[pxs]host;port"

Where:

| server | Similar to the RPC dialog, the term "server" is a logical name that will be associated with this server for the duration of the connection. Maximum length is 12 characters.

The address string following the ON keyword is composed of three components:

| [pxs] | The initial "[pxs]" is obligatory and never changes. Its presence identifies the server as an instance of PxServer.
| host | The second section of the string identifies the machine on which the PxServer is running. If PxServer is running on the same machine as PxPlus, the name "localhost" can be substituted. This section will also accept an IPv4 address.
| port | The third section after the ; (semi-colon) is the port number on which the PxServer is listening. The default port is 4193 (see Note below); however, this can be changed in the PxServer configuration.

#### Note:
This port number has been registered with the Internet Assigned Numbers Authority (IANA) for this application.

Therefore, if you are running PxServer on the same machine as PxPlus, this will initiate a connection:

> PROCESS SERVER "myserver" ON "[pxs]localhost;4193"

Additional options, which correspond to PxServer permissions (and are separated by ; semi-colons), may be added to the end of the address string:

| "SSL" | Use secure sockets
| "CAFILE=" | Specify the path and file name of the certificate authority file
| "USERID=" | User identification
| "COMPANY=" | Company code

Example:

The following example makes use of all of these options:

> PROCESS SERVER "myserver" ON "[pxs]localhost;4193;SSL;CAFILE=C:\certificate; USERID=me;COMPANY=mycompany"

As with RPC, the PROCESS SERVER directive is also used to disconnect:

> PROCESS SERVER "server" CLOSE

Where:

| server | The name assigned earlier when connecting to PxServer

To open a file on PxServer, the OPEN directive syntax is as follows:

> OPEN(1)"[PXS:server]filename"

Where:

Within the sub-string surrounded by square brackets is the required "PXS:", followed by the server name assigned earlier with the PROCESS SERVER directive. From this point onwards, PxPlus file I/O commands should behave exactly the same as regular file I/O. There are no verboten file I/O commands. All file creation directives can be executed using PxServer. Insert the "[PXS:server]" substring before the filename.

Example:

To create a keyed file named "myfile" on PxServer to which you are currently connected with a name of "myserver", use the following syntax:

> DIRECT "[PXS:myserver]myfile",10