Page edited by Dave SmithWelcome to the SSDT Public Wiki
This is the SSDT Public Wiki for topics related to software developed by the SSDT on behalf of the Ohio Department of Education. OECN ITC personnel and state software users are welcome to participate in the Wiki.
Please see the "About" page for more information about the purpose of the Wiki and how to participate.Spaces
SSDT Public Wiki Documentation CNDC Documentation EIS Documentation EMIS Flat File Editor EMIS V3.0 OECN Documentation OpenVMS Technical Documentation SOES Documentation USAS Documentation USAS-R Documentation USAS Web Documentation USPS Documentation USPS Web Documentation SSDT Developers Wiki CNDC Project USAS Team USPS Team OECN DNS Services Ohio SOAP SIF Agents Software Advisory Committee SSDT Meetings and Trainings State Software Redesign USAS Redesign USPS Redesign
View Online · View Changes Online Dave Smith 2014-04-10T20:01:17Z
Page edited by Matthew Calmes/**/
This page contains information regarding the March 2014 release of State Software.
Please see Acquiring the Release for information on downloading the release.OECN Package Release
The March 2014 release of USPS42 includes the addition of two new programs: SERSHIRE and STRSHIRE. These programs were created to support the electronic reporting of new hire information to the SERS and STRS retirement systems. These programs are both located on the RETIRE program menu.
SERS recently revised the initial guidance they gave us concerning the mapping of EMIS position codes to their SERS specific job classification values. We are working with SERS to get the information we need to update SERSHIRE to comply with their job classification definitions. Unfortunately, this information was not available in time to update the version of SERSHIRE included on the March 2014 release. As a result we are advising you not to use the SERSHIRE program until we provide a patch via OECN_OOPS.
The code changes required to implement this are relatively minor, so the turn around time on the patch will be quick once we have the required information from SERS.
The STRSHIRE program is not affected by this issue and can be used now.
View Online · View Changes Online Matthew Calmes 2014-03-21T12:00:20Z
Page edited by Dave Smith/**/
- 1 Overview
- 2 Platform Software Requirements
- 3 Installation and Setup
- 4 Monitoring and Management
- 5 Web Application Configuration
OECN VXS (VMS XML Service) is a replacement for the USP middleware used by the OECN RPC Service. VXS supports both OpenVMS/Alpha and OpenVMS/I64 platforms. VXS is based on HTTP and uses a REST-like interface for transferring XML between Java clients and the back-end (COBOL) RPC services.Icon
The USP based version of the OECN RPC Service is considered obsolete and unsupported. All ITC's should be upgraded to the OECN VXS version of the RPC service.
- Uses standard HTTP protocols instead of a proprietary TCP protocol.
- Uses HTTP "keepalive" to reduce TCP/IP stack resources for idle client connections.
- The connection listener and server processes are isolated. Failure or restarting of the listener does not affect established server processes. Likewise, failure of a server does not affect the listener or other servers.
- Requires Java installed on the OpenVMS server.
- Slightly slower connection start up times. Users may notice a longer delay when first logging in.
VXS consists of three major components:
- VXS Listener: A Java-based HTTP process which listens for incoming connections on a defined port (defaults to 8099). The listener is responsible for validating the client connection request, launching the server process and directing the initial handshake between the client and server process.
- VXS Server: A Java-based HTTP process which handles requests for a single client. The Server is launched by the Listener after a valid connection request. After a successful connection, the server is entirely independent of the Listener.
- *VXS Client: A Java-based HTTP client which handles the transport of OECN RPC messages to the VXS Server. The VXS client software is embedded into the SSDT Web Applications and SOAP services.
The basic connection process is as follows:
- The Client requests a connection by contacting the VXS listener on the configured port
- The Listener validates the request and launches a VXS Server process to handle the connection
- The Server allocates an ephemeral port from the TCP/IP stack, initiates an HTTP listener on the port and sends the allocated port to the Listener
- The Listener redirects the Client to the port allocated by the Server
- The Client and Server handshake to validate the connection and then begin normal OECN RPC operations
Note that OECN VXS is strictly a connection manager and message transport service. It does not perform authentication or any other RPC function. Authentication is handled in the OECN RPC layer after the connection is established.
Because VXS's server allocates an ephemeral port it does not, and is not intended to, function through a firewall. VXS is intended to be used on an OpenVMS server which is near the web application servers it supports.Platform Software Requirements
- OpenVMS/Alpha 8.3 or OpenVMS/I64 8.3 or higher
- Java JDK 5.0-7 (Alpha) or Java JDK 5.0-6 (I64) or higher (http://h18012.www1.hp.com/java/download/index.html)
- OpenVMS ECO's as required by Java
The OpenVMS kit containing the VXS Listener and Server is available to OECN ITC's via OECN_DOWNLOAD. The kit is called VXS-n-n-n.BCK where "n-n-n" is the version number. The first production release is VXS-2-2-0.BCK.Installation
- Install the appropriate JDK version
Unpack the VXS-n-n-n.BCK saveset with the following command:$ BACKUP VXS-n-n-n.BCK/SAVE device:[*...]
- The above command will create device:[OECN_VXS]
The kit contains binaries for both OpenVMS/Alpha and OpenVMS/I64.Configuration
The VXS distribution contains VXS_CONFIG.COM which handles the configuration, startup and shutdown of the VXS Listener. Execute the procedure and choose the "Configure" option. The procedure will prompt for the following options:ParameterDescriptionTCP port for VXS/HTTP ListenerEnter the port to use for the HTTP listener. The default is 8099Service Inactivity TimeoutEnter the number of minutes of client inactivity before the server shuts down. This should be less than the inactivity of the SOAP and web applications. The default is 20 minutes.Service usernameThe VMS UAF username the VXS Listener and Services will run under. This defaults to SYSTEM. The quotas and privileges available to the VXS processes will be determined by this account. See below if you wish to use a non-SYSTEM account for the VXS processesVMS startup batch queueThe batch queue to use to startup the VXS Listener. This must be a batch queue started during SYSTARTUP_VMS.COM and available whenever the Listener is restarted.Service Username Requirements
In order to run VXS under a non-SYSTEM account, the account must meet the following requirements:
- Default privileges: NETMBX, TMPMBX, IMPERSONATE, SYSPRV
- Minimum Quotas:
- Fillm: 4096
- BIOlm: 4000
- Enqlm: 4000
- Bytlm: 2000000
- Pgflquo: 700000
- WSquo: 16000
- WSextent 32767
- JTquota: 5128
These should be considered minimum quotas. Quotas may need be be increased in some environments.Logicals affecting OECN RPC
Several logicals affect the behavior of the OECN RPC service.OECN$RPC_DEBUG_username
Enables RPC debug mode for the specified user. Causes additional debug messages to be logged to the session log file (OECN$VXS_LOGS:VXS_*.LOG) and causes request and response XML files to be written to user's SYS$LOGIN. Must be defined system-wide or as a process logical in an OECN RPC prologue file.
For example:$ DEFINE OECN$RPC_DEBUG_SMITH "YES"
Enables debugging mode for the VMS user "SMITH".OECN$ACME_PROCESS_TYPE
The OECN RPC service uses the ACME system services to authenticate and impersonate users. This logical determines the type of VMS process (NETWORK or REMOTE) to use for authentication. The choice of process type determines which SYSUAF and VMS security policies apply to the process.
NETWORK will apply the SYSUAF /NETWORK access restrictions and will ignore expired passwords.
REMOTE will apply SYSUAF /REMOTE access restrictions and will prevent login with expired passwords.
This logical must be defined as a system-wide logical or in an OECN RPC Prologue procedure. For example, to treat OECN RPC processes as REMOTE:$ DEFINE/SYSTEM OECN$ACME_PROCESS_TYPE "REMOTE"
The default is "NETWORK" for compatibility with previous releases.
This features has been available since the March 2007 release.Startup
Add the following line to the SYSTARTUP_VMS.COM procedure:$ @SYS$SYSDEVICE:[OECN_VXS]VXS_CONFIG START Shutdown or Restart
To shutdown or restart the VXS Listener, use:$ @OECN$VXS:VXS_CONFIG STOP or RESTART
Stopping or restarting only affects the VXS Listener. It does not affect Server processes that are already connected.Monitoring and ManagementLogicals
VXS_CONFIG creates the following logicals:
- OECN$VXS_ROOT: A rooted logical defining the top-level installation directory of VXS
- OECN$VXS: The execution directory for VXS
- OECN$VXS_LOGS: Directory where Listener and Service log files are written
The Listener Startup log file is named VXS_LISTENER_STARTUP.LOG in OECN$VXS_LOGS. This is the log file for the batch job submitting when the startup procedure is run by other than the "Service username".
The Listener log file is VXS_LISTENER.LOG. This file contains console messages for the listener. Check this log file if the Listener fails to start or will not accept connections.
Log files for each Server are named: VXS_nnn_xxx.LOG in OECN$VXS_LOGS. A log file is created for each successful connection by a VXS Client. "nnn" is a hexidecimal number representing the Listener instance and "xxx" is a hexidecimal number unique to each client. Check this log file if the client is unable to connect and for RPC (COBOL) errors during the user's session.Verifying Listener is Running
Since the VXS Listener is an HTTP server, it will respond to HTTP requests from a web browser. To check the that the Listener is running, use a web browser to go to http://yourhost:8099/. If the VXS Listener is functioning, it will display it's version and build information and a status message indicating the state of the listener.VMS ProcessesListener
The VXS Listener process is named "VXS$LST-1". The process can be stopped and started using VXS_CONFIG.Servers
Prior to authentication by the user, server processes operating on behalf of a VXS Client will be named VXS_nnn_xxx (using the same naming convention as the log files). After successful authentication, the Server process will impersonate the authenticated user and the process name will be changed to the username being impersonated.
The Server processes will have the following characteristics:
- The process name will be the username of the authenticated user
- The image will be JAVA$JAVA
- The username will be the "Service username" that the VXS service is running under
Using FSYS (from NWOCA'S Pubdom), you could list the VXS process with a command like:$ FSYS/IMAGE=JAVA/ALL/SHOW=(PID,PROC,USER,IMAGE)
If you have other Java applications running, you could filter the list by the username VXS is running under, for example:$ FSYS/IMAGE=JAVA/ALL/SHOW=(PID,PROC,USER,IMAGE) OECNVXS Web Application Configuration
Each SSDT Web Application or SOAP service which is to use VXS, must be configured with an appropriate URL to use VXS. This is done by changing the appropriate properties file for the application. See the application's installation guide for detailed instructions on configuring each application's connection string.
For VXS connection strings, the URL must be in the following format:vxshttp://server:port/OECN_RPC
Where "server" is the domain name or IP address of the OpenVMS server running VXS and "port" is the port where VXS is listening (default is 8099).
For example, to configure the USAS SOAP service to use VXS, edit the UsasService.properties file and change the USPConnectionString to:USPConnectionString=vxshttp://yourserver.org:8099/OECN_RPC
After restarting or reloading the SOAP service, subsequent connections will use VXS.
Note: For historical reasons, the connection string parameter in the applications is called "USPConnectionString". Future releases will rename this parameter to a more appropriate name.Web Application Compatibility
Web applications released by the SSDT after 1-Sep-2008 are fully compatible with VXS. Applications released prior to that date must have a "Build Date" after 1-Sept-2008 to work with VXS. You can check the Build Date by viewing the "version.properties" file of the application in question, or use the "Admin/Configuration" option in the application.
If the "Build Date" of the application is less than 1-Sep-2008, then you must install a newer build prior to using VXS. The SSDT has placed recent builds of all current versions in OECN_DOWNLOAD as of 1-Sept-2008. If you need an older version of a Web Application or SOAP service (perhaps to support a third-party vendor), then you can request a fresh build of the specific version from the SSDT.
The following web applications are dependent on OECN RPC and will need a recent build date to work with VXS:
- USAS SOAP Service
- USAS Web (if Standalone mode)
- USAS SOAP Service
- USAS Web (if Standalone mode)
- EMIS SOAP
Note: The EMIS Web Applications (emisweb*.war) are not directly dependent on OECN RPC.USP Coexistence
USP and VXS can both be used on an OpenVMS server. It is not necessary to switch all SSDT web applications to VXS at the same time. That is, you can use VXS for one web application while continuing to use USP for the others, or use USP for older applications and use VXS for new installations.View Online · View Changes Online Dave Smith 2014-02-28T22:23:42Z