note

OpenVMS process servers are only available when your license includes a non-zero value for the key ProcessServerService.VMS.limit. Process servers that include the DCL job definition type will not be counted towards the ProcessServerService.OS.limit and ProcessServerService.External.limit license keys.

Prerequisites

A running Redwood Server system
An HP OpenVMS 8.2 or higher ia64 server with appropriate access to the server (including root password).
The VMS Internationalization Kit must be installed.
An UNZIP program must be installed.
An OpenVMS account with (at least) the following VMS system privileges:
- TMPMBX to create temporary mailboxes for communication between processes.
- NETMBX to create a network socket for the server to communicate with the agent.
- Optional: IMPERSONATE to run processes as other VMS users.
- Optional: CMKRNL to monitor the system load (page rate, CPU usage).
- Optional: SYSPRV privilege to add a new nametable to LNM$SYSTEM_DIRECTORY
- Optional: BYPASS privilege to manipulate files created by processes running as other users and to create a new nametable in LNM$SYSTEM_DIRECTORY.
Connectivity from the central Redwood server to the HP OpenVMS host on agent's port

Procedure

Installing the "VMS Internationalization Kit" Layered Product

The Redwood Server platform agent communicates with the central Redwood Server using the UTF-8 character set. To convert this to/from the usual DEC International Character Set (of which ISO-8859-1 is a superset) you need additional Internationalization Data.

If you are unsure whether the VMSI18N kit has already been installed, you can verify this by typing the following command:

$ product show prod *i18*
----------------------------------- ----------- ------------
PRODUCT                             KIT TYPE    STATE
----------------------------------- ----------- ------------
DEC AXPVMS VMSI18N V8.2             Full LP     Installed
----------------------------------- ----------- ------------

1 item found

You can also wait until you try to run one of the images supplied as part of the Redwood Server platform agent kit; all images attempt to access the necessary API's for character set conversion when they start. If you run it on a system that does not have the kit installed, you will see an error message such as this immediately upon starting the image:

$ run jsleep.exe
error 2023-10-02 00:00:00,000 GMT [154-Main tid=2075815240] opsys.conv - Unable to determine proper UTF-8 character set
error 2023-10-02 00:00:00,000 GMT [154-Main tid=2075815240] opsys.conv - Make sure the VMSI18N kit from the OpenVMS media set is installed

To install the OpenVMS Internationalization Data Kit follow the instructions in the OpenVMS Upgrade and Installation manual. In short:

Mount the "Operating System" DVD or the "Layered Products" CD of the OpenVMS media kit
run PRODUCT INSTALL VMSI18N /SOURCE=dev:[dir]

Exact CD/DVD locations in the HP media kits are:

Release	Processor	Media label	Directory
8.2	ia64	I64082	[VMSI18N_I64082.KIT]
8.3	ia64	I64083	[VMSI18N_I64083.KIT]
8.4	ia64	I64084	[VMSI18N_I64084.KIT]

Until you install the internationalization kit you can also run the software, but you will have to set the characterset to UTF-8. This will mangle content that uses codepoints that are not at the same location as in UTF-8, but these seldom occur in OpenVMS DCL files. You can set the characterset of the software to UTF-8 by setting a logical LANG to UTF-8, or add the following command line arguments: --filesys UTF-8 --filedata UTF-8. Although this should work, it is not recommended by Redwood.

Create an account

We recommend that you create a new account to contain the platform agent that satisfies your local naming requirements.

This documentation uses the account REDWOOD with UIC [377,200] as an example.

To add the account

Log in as SYSTEM.
Change to the system directory and start the authorization image: $ MC AUTHORIZE.
Create the account: ADD REDWOOD /UIC=[377,200].
Set password and login flags: MODI REDWOOD /PASSWORD=XXXX /FLAGS=NODISUSER.
Set the account privileges: MODI REDWOOD /PRIV=(NETMBX,TMPMBX,IMPERSONATE,CMKRNL,SYSPRV,BYPASS).
Set the account default privileges: MODI REDWOOD /DEFPRIV=(NETMBX,TMPMBX,IMPERSONATE,CMKRNL,SYSPRV,BYPASS).
Set the home directory: MODI REDWOOD /DEVICE=SYS$USER /DIR=[REDWOOD].
Set the proper quotas for the new account: MODI REDWOOD/JTQUOTA=0/MAXDETACH=0/MAXJOBS=0/BYTLM=0.
Set the quota to (at least) these values:
MODI REDWOOD/BIOLM=150/DIOLM=150/ENQLM=2000.
MODI REDWOOD/WSDEF=4096/WSQUO=32768/WSEXTENT=65536/PGFLQUOTA=100000.
Exit authorize: EXIT.
Create the home directory: $ CREATE/DIR SYS$USER:[REDWOOD] /OWNER=REDWOOD.

If running the redwood account with reduced privileges:

If you have not granted the SYSPRV (or write access to LNM$SYSTEM_TABLE) and BYPASS privileges, create a name table: CREATE/NAME/ATTR=NO_ALIAS/PARENT_TABLE=LNM$SYSTEM_DIRECTORY/EXE/PROT=(O:RWD,S:RWD,G:RW,W:RW) LNM$SCHEDULER.

Installing the Platform Agent Software

Install 'unzip', either from OpenVMS Freeware CD-kit, or if you have the Java SDK installed, you can use jar ($ jar xvf <zip_file>).
Log in using the designated account.
Create a directory (preferably "AGENT").
Unpack the zip file to this directory.

$ unzip openvms-<CPU>.zip

The [AGENT] directory is called the InstallDir and the [BIN] directory is called the ExecutableDir.

Creating Symbols

We recommend that you create symbols for the jtool programs so that they can be executed from within processes, for instance in a procedure that is set up in SYLOGIN.COM. We recommend you add the following:

$ !
$ ! Example, replace SYS$USER with your own logical or path to redwood directory.
$ !
$ !
$ JTOOL=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE TOOL"
$ JLINK=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE LINK"
$ JSLEEP=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE SLEEP"
$ JREGISTER=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE REGISTER"
$ JEVENT=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE EVENT"
$ JMESSAGE=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE MESSAGE"
$ JDESCRIPTION=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE DESCRIPTION"
$ JSECRET=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE SECRET"
$ !
$ ! In case you need to pass arguments, for example, non-default instance
$ !
$ NETWORKPROCESSOR=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]NETWORK-PROCESSOR.EXE"

Further platform independent configuration instructions can be found in the Configuring Platform Agents section. In particular, if you want to guard the platform-agent against intruders and use by different server instances we suggest that you create a SharedSecret using the instructions found there.

Starting the platform agent interactively

For debugging and initial testing purposes it can be useful to start the network-processor interactively. For instance, to enable debugging until the process server is configured, run the following whilst logged in as redwood:

$ DEFINE RW_LOGLEVEL DEBUG
$ RUN [.AGENT.<version>.BIN]NETWORK-PROCESSOR

Starting the platform agent at startup

Starting the platform agent at system startup is recommended. For OpenVMS, we suggest starting with a single instance ('Default') running on port 1555. To do this, simply create a STARTUP_DEFAULT.COM script that you call from SYSTARTUP_VMS.COM. Suggested content is:

$ RUN/UIC=[REDWOOD] SYS$USER:[REDWOOD.AGENT.<version>.BIN]NETWORK-PROCESSOR.EXE /OUTPUT=.... /PROCESS_NAME=NWP-DEFAULT

Working Directory

The default working directory is set to ${JobFilesDirectory}; by setting the process server parameter JobWorkingDirectory this default initial directory can be changed. You can use the following variables:

${JobFilesDirectory}
${HomeDirectory} (translated to SYS$LOGIN)
${JobID}
all logicals set up by the LOGIN.COM procedure.

Product Documentation

Installing the Platform Agent on HP OpenVMS