PC2 Contest Administrator’s Guide

Version 8.2  Supplement

 

This document provides instructions on setting up and running Version 8.2 of the PC2  Programming Contest Control system.  It concentrates primarily on differences between V8.2 and Version 7.6, the most wide-spread version of the system.  Readers should obtain a copy of the PC2  V7.6 Contest Administrator’s Guide before attempting to follow the steps in this supplement; that Guide is available both online and in downloadable form from http://www.ecs.csus.edu/pc2. (It can also be found in the “doc” subdirectory of the V8.2 distribution download file.)   The sections of this supplement correspond precisely with the layout of the V7.6 Guide; many of the following steps make direct reference to that Guide.

Overview

The overall architecture and organization of PC2 Version 8.2 is the same as that of Version 7.6 in most regards.  The only substantial external difference is that in V8.2 there is no longer a Registry module – there are simply Server and Client modules.  Each contest site first starts one Server, whose job it is to manage overall site operations, and then starts one Client module for each operational contest entity – each Team, Judge, Administrator, Scoreboard, etc..  Each Client module must have TCP/IP communication capability with its site Server; no module (Client or Server) needs to have any direct communication with any module at any other contest site.

Installation

The installation process for V8.2 is for the most part the same as described in the V7.6 Guide (except that you will download and unzip the pc2v82.zip or .gzip file instead of the pc2v76.zip or .gzip file).  However, there are several important differences for installing V8.2.  You should read through the V7.6 Installation steps, then make the following changes:

·       V8.2 requires Java Version 1.3.1 (or higher).  It will not work correctly with Java versions below 1.3.1.  Be sure to install JDK (or JRE) 1.3.1 or higher on all contest machines.

·       It is no longer necessary to add the “swing.jar” and “s_mclb.jar” entries to the CLASSPATH variable (however, it is still necessary to add  the “$PC2HOME” variable – i.e. the PC2 installation directory, as well as the Java class library,  to the CLASSPATH).  There is a batch file named “setjava.bat” in the PC2 distribution which can be edited to conform to the local environment and then used in a Windows system to automatically set the necessary PATH and CLASSPATH values. 

·       It is no longer necessary to edit any java.policy files; V8.2 uses the contents of the file “all.policy”, which is part of the standard PC2 V8 distribution, to set the Java policy (permissions) as needed.

·       Once the distribution is downloaded and unzipped, the installation directory contains an index.html file which contains links to a variety of local documentation.  We are still updating this distribution documentation for V8.2, but you may find a lot of useful information there even in its current form.  You also may be interested in the variety of sample and test programs in the “samps” directory…

 

Initialization Files

PC2 V8.2 Server and Client modules read a series of “.ini” files when they start up, just as V7.6 did.  The required “.ini” files for V8.2 are listed and described here, followed by a set of instructions giving details of the individual file contents.

 The “pc2v7.ini” file required by each module (Server and Client) has been replaced by a “pc2v8.ini” file whose basic layout is similar: it contains initialization values in sections delimited by [  ] dividers.  Each module also needs a  “sitelist.ini” file containing a list of the sites in the contest. 

In addition, the Server module is normally provided with a “reject.ini” file, used to give the Contest Administrator control over the text of the “Rejected Run” messages sent from Judges to Teams when a Judge determines that a submitted run did not solve a problem correctly.   Note: Client modules for Teams in V8.2 no longer require a “team.ini” file as they did in V7.6.  

Follow the instructions listed below to create the appropriate V8.2-specific “.ini” files for your contest.

1.     Edit the file “pc2v8.ini” in the “$PC2HOME” directory on each machine.  The general layout of this file is similar to that of the “pc2v7.ini” file described in the V7.6 Contest Administrator’s Guide.   The pc2v8.ini file needs  only  the following  “sections”: 

[global]

debuglevel=13

[client]

server=<IP>:2005

site=<site name string>

[server]

site=<site name string>

#remoteServer=<remoteIP>:2005

 

 

The value <IP> should be replaced by the IP address of the machine which will be running the PC2 Server for the site.  The values <site name string> should be replaced with the exact character string identifying the Site (i.e., one of the lines from the “sitelist.ini” file; see below).  Lines which begin with a “#” character are comments.

In a multi-site contest, Version 8.2 assumes the server at one site will be the “primary” server and servers at all other sites will be “secondary” servers.  (The only difference is that secondary servers attempt to contact the primary server when they start, whereas primary servers start up passively and wait to be contacted).  If this machine is going to be a server, but is not the primary server, uncomment (remove the “#” character from) the  remoteServer=  line in the [server] section and put the IP address of the primary server in place of the string “remoteIP”.  This is what causes a server to contact another contest server[1].  Leaving the line commented-out makes a server the primary server for the contest.

Note that there is no longer a  [registry]  section as there was  in V7.6, and that the other section names and attributes listed in the V7.6 Guide do not apply in V8.2.

2.     Edit the file “sitelist.ini” in the $PC2HOME directory on each machine.  Delete the default information in the file if it is there, and replace it with one line for each Site in the contest, giving each Site Name (one Site per line).

Ø     NOTE:  it is VERY IMPORTANT that ALL SITES IN THE CONTEST HAVE IDENTICAL “sitelist.ini” FILE CONTENTS  --  i.e. the Sites must be listed in the same order in the “sitelist.ini” file at all Sites, and the spelling and  spacing of Site names, including any embedded blanks, must be the same in all “sitelist.ini” files.   

Ø     To avoid errors due to mismatched “sitelist.ini” files, it might be desirable to have the Head Judge or Contest Administrator create one “sitelist.ini” file and transmit identical copies to each of the separate Contest Sites (taking into account different line terminators for different OS environments).

3.     Edit the file “reject.ini” in the $PC2HOME directory on the Server machine so that it contains one line of text for each “NO” message to be sent from the Judges to Teams when a run is rejected.  For example, if the Contest rules specify that the Judges will return one of the three messages “Runtime Error”, “Time Limit Exceeded”, or “Wrong Answer” for failed runs, put each of these messages on a separate line in the “reject.ini” file.

Execution Scripts

V8.2 eliminates the need to write external “execution scripts” in order to execute team runs.  Instead, the commands and parameters needed to specify how programs in each language are to be compiled and executed are entered directly into the PC2 via the Administrator Client interface after PC2 is started (see below).  Therefore, the V7.6 Guide section on Execution Scripts, as well as Appendix 3 (details on PC2 Execution Scripts) no longer applies under most circumstances. 

Note that compiler-invocation commands which are input to PC2 via the Administrator interface should be “relative” commands; that is, they should not have any “absolute path names”.   It is expected that each site will configure the “environment variables” on each machine so that paths to language tools (compilers, etc.) are set appropriately so that the tools can be invoked using “relative path” names. 

It is still possible to use the V7.6 “execution script” approach if desired.  To do this, simply create the desired script file, and enter into the Administrator interface the appropriate command to invoke the script, passing the appropriate parameters on the command line.  It is even possible to get PC2 to pass parameters to the script:  V8.2 supports a variety of “command parameter substitution” templates which allow specification of run-specific parameter values into command lines.   These “substitution templates” have the form  {:keyword} , where “keyword” is mainfile,  basename, or one of a number of other possibilities as shown in the PC2 Administrator screens.  For example, putting the template  {:mainfile} on a command line will cause PC2 to substitute the name of the main program file into the command at that point.

Startup Procedure

The section under “Startup Procedure” in the V7.6 Guide does not apply to V8.2.  First, there is no longer a “Registry” module to be started.  In addition, the startup commands for the Server and Client modules have changed, due to the need to specify “security policy” parameters.  The entire “Startup Procedure” section of the V7.6 manual is superceded by the following instructions.

The normal startup procedure is to start a server, then start an Admin client which is used to configure the contest.  To simplify startup in a Windows environment, the V8.2 distribution comes with a batch file named “startpc2.bat”.   To start PC2 V8.2 on a Server machine  under Windows and then begin configuring a contest, execute the “startpc2.bat” file. 

The batch file executes the appropriate command to start a PC2 Server, then pauses and waits for a keystroke at the console.  The Server reads its initialization files, displaying a series of log messages on the screen.  If  the pc2v8.ini file indicates this is a secondary Server (i.e., it has an active “remoteServer=xyz” entry) the Server will attempt to connect to its primary server (as specified by “xyz”).  When the Server is fully initialized it will display the message

Server at Site “xxxxxxx” is ready

where “xxxxxxx” is the name of the Site as it appears in the “sitelist.ini” file.  If any errors occur or the Server fails to produce the “Server is Ready” message, check the files “pc2.log” and “pc2serv.log” for further details.  Note that the Server no longer displays an interactive screen such as the one shown in the V7.6 Guide when it starts.

Once a PC2 Server is running at a site, users (Administrators, Judges, Teams, etc.) at the site can start PC2  “Clients” to login and use the system.  The normal procedure is first to start a Client and login as the “root” administrator in order to configure the contest.   To automatically start a Client, press a key in the console window (the one in which the “startpc2.bat” file was executed).  This will cause the startpc2.bat batch file to continue, at which time it will execute the command to start a Client.  Once a Client has been started it should display a PC2 “Client Login” screen, which looks the same as that shown in the V7.6 Guide.

Under Windows, a new V8.2 client can also be started by executing the batch file “c.bat”, which simply executes the command needed to start a Client.  Since this batch file only starts a Client (but not a Server) it can be used by Judges, Teams, etc. to start PC2 running.  (Note that the simple startup commands shown in the V7.6 Guide will not properly start PC2 V8.2.)

 

 

Contest Configuration

The process of configuring PC2 to run the Contest is basically the same in V8.2 as it was in V7.6.  The following list of steps is provided to help clarify the few differences.  Follow these steps to configure the Contest, referring to the V7.6 Guide for details where necessary.

1.     Login to PC2 using the login account name “root” and the default password “root” (this replaces the initial master login/password values “pc2/pc2” from V7.6).  This will display the PC2 “main Administrator screen”, which is essentially identical in both appearance and function to that described in the V7.6 Guide.  [The V8.2 main Administrator screen has one additional “tab” at the top, and a few of the tabs have additional functions on them; these are described below.]

2.     Follow the instructions under “Contest Configuration” in the V7.6 Guide to configure the contest for your Site.  However, note the following areas which have changed under V8.2:

Þ    The “Accounts” tab screen is still used as described in the V7.6 Guide to create Administrator, Judge, Team, and Scoreboard accounts as needed.  However, except for the single “root” Administrator account, which is contest-wide, accounts in V8.2 are no longer “global” across the entire contest; they are specific to each site (that is, there will be a Team1 at Site1 and a Team1 at Site2).  Thus, each site must configure its own set of accounts.  It is not necessary for different sites in the Contest to configure the same number of accounts. 

The Accounts screen contains an additional button, “Import ICPC Data”.  If your contest is using the ACM-ICPC Registration system, you can login to that system and use the “Export PC2 Data” function to generate a file containing the Registration data in PC2-compatible form.  Downloading and unzipping this file will allow you to import the Registration system data into PC2  for use in your contest.

The Accounts screen also contains a “Load” button which can be used to initialize various features associated with PC2 accounts (for example, to set different passwords with one operation rather than editing each one manually).  This feature is not documented in the V7.6 Guide, but it is covered on the PC2 “FAQ” on our web page (of which there is a local copy in the distribution).

The additional account type “Custom/External User” is intended for use with a new PC2 Version 8 external interface feature which will eventually be documented in the complete Version 8 Administrator’s Guide.

Þ    The “Add Problem” screen has been substantially redesigned from what is shown in the V7.6 Guide.  In particular, the “subjective judging” categories have been eliminated, and PC2 now supports the ability to select an “Automated Judging Validator” for each problem.

V8.2 provides a variety of internal validator capabilities (variations of “diff”) which can be used to compare the output of a team program to an Administrator-provided “Answer File” giving the “correct” output for the problem.  

V8.2 also provides support for the invocation of an arbitrary external (user-written) program designed to “validate” a team’s output.  Validator programs are expected to comply with the international standard validator interface developed in conjunction with a variety of groups working with the ACM-ICPC.  Interested parties are invited to contact the PC2 development team for further information.

In addition, Version 8 is intended to support the ability to test a run against multiple distinct data sets in different files, and the Problems screen implies the ability to list multiple such files.  However, in V8.2, it will not accept more than one data set file name. 

Note:  the number of problems entered into the system MUST be the same at all sites, and the ORDER in which the  problems are entered must be the same.  The Contest Administrator should identify ahead of time a fixed order for the Problem set, and insure that each Site enters the problems in that fixed order.

Þ    The “Languages” tab screen is still used to define the languages to be used at the Site.  Note however that, like the Add Problem screen, the Add Language screen has been substantially revised from what is shown in the V7.6 Guide.  In particular, the Administrator now enters the exact compiler command call (in place of the string <compiler>), the form of the executable file name generated by the compiler, and the form of the command required to invoke the executable file.  The substitution parameter strings  {:mainfile} and  {:basename} represent, respectively, places where PC2 will substitute the main program file name from the run, and the “basename” of the file (the main file name minus any extension). 

It is not necessary for different sites in the Contest to define the same languages, or even the same number of languages.  However, if runs from one site are to be judged on machines at another site, the languages must match in ordinal position (order of definition) between the two sites.  That is, if a Team submits a program in “language #2” as defined at their site and it is transferred to a judge machine at another site, the judge machine will compile it using “language #2” at the judge’s site.  Caveat Emptor.

Þ    Select the “Sites” tab and verify that every site in the contest is listed as “Active” (all Servers have made a connection into the contest).

Þ    In the section about Startup Status, the caveats regarding the screen’s inability to dynamically update should be ignored; this problem has been fixed in V8.2.

Except for the new “Remote” tab on the main Administrator screen (see below), the other Administrator screens in V8.2 function as described in the V7.6 Guide.   

 

Starting the Contest

Once PC2 has been configured, the following steps should be taken in order to insure Contest security and integrity:

1.     Change the root account password:  go to the “Accounts” tab, select “Manage Accounts”, select “Account Type = Admin” in the drop-down list box, select the “root” account in the account display grid, push the “Edit” button, and enter a new password and verification.

2.     Change other account passwords as desired.  It may also be desired to change various account “Display Names”, as described in the V7.6 Guide under “Account Names and Passwords”.  Also see the PC2 “FAQ” for information about using the “AccountàLoad” button to set Account data.

3.     Recommended:  send a “Configuration Report” for your site to the primary site.  To do this, go to the “Reports” tab screen, enter any desired file name in the “Report File Name” box, select the “-all” option in the “Report Option” drop-down list, and click the “Generate” button (or click “Generate and View” if you are interested in seeing the Report contents).  Then, arrange to transfer the Report File for your site, by ftp or email or other means, to the Contest Administrator at the primary site.  The Contest Administrator will use the Configuration Reports from all sites to verify consistency of the Contest setup.

When every site in the Contest is properly configured and verified by the Contest Administrator at the primary site, the Contest can be started by pushing the “Start Contest Time” button on the “Time/Reset” screen, as described in the V7.6 Guide under “Starting the Contest”.   The Contest Administrator will establish a coordination procedure by which all sites will be prepared to start simultaneously (for example, to make sure all teams at all sites receive the problems at the same time).  However, the official contest time can be started simultaneously in PC2  at all sites by a single button-push in the Administrator. 

PC2 Scoreboard

Once the Contest is running, each Site can set up its own PC2 Scoreboard; this is done as described in the V7.6 Guide under “PC2 Scoreboard”.   In a networked contest, each such Scoreboard will reflect the contest-wide standings.    The mechanism for generating (local) HTML scoreboard displays described under “HTML Scoreboard” in the V7.6 Guide also applies, except that there is an error in the Guide:  Scoreboard HTML files are placed in the "html” directory beneath the Scoreboard startup directory (not the PC2  installation directory).

Loosely-Coupled Multi-Site Contests

Overview

PC2 V8.2 is designed to support multi-site contests in either “tightly-coupled” or “loosely-coupled” mode.  Tightly-coupled mode means that there is an active network connection between sites, whereas loosely-coupled mode means that there are separate sites running the same contest but with no direct network connectivity between the sites.  In either mode, each site is always running its own PC2 Server (in fact, the definition of “site” in PC2 is a locale running a PC2 Server.)

In tightly-coupled mode, all PC2 events which occur at any site are automatically transmitted by the system to all connected sites.  For example, runs submitted by a team at one site automatically appear by default on the screens of judges at all sites (although this is configurable); changes in the scoreboard state at one site are automatically displayed at other sites; etc.  A tightly-coupled contest is established by setting up one primary server together with one or more secondary servers configured with pc2v8.ini entries which cause the secondary servers to connect with the primary server at startup (see the section on Startup, above).

In loosely-coupled mode, each site is running its own separate PC2 Server, and further the Servers do not directly communicate with each other.  If a contest is initially configured in tightly-coupled mode and then during the contest there is a loss of network connectivity to one or more sites, PC2 automatically “falls back” into loosely-coupled mode for the disconnected site(s).  If network connectivity is later restored, PC2 recognizes the reconnection and automatically brings all connected sites into sync with each other.

A multi-site contest is normally set up in tightly-coupled mode – that is, PC2 is designed to expect network connectivity between sites under normal circumstances.  However, it is possible to set up PC2 to start initially in loosely-coupled mode (that is, PC2 can be made to support a multi-site contest in the absence of any network connections between the sites).  

In order to set up a loosely-coupled multi-site contest, the Server at each site must be made aware of the other sites, without being told to attempt a network connection to the other sites.  This is done by including in each Server’s “sitelist.ini” file a listing of ALL Servers (sites) in the Contest, while at the same time NOT including a “remoteServer=xxx” entry in any Server’s pc2v8.ini file.  In this way it is possible to arrange for “off-line” communication and sharing of standings data between the sites –  including the ability to generate a “merged scoreboard” showing the combined results of competition taking place at multiple loosely-coupled contest sites.

Master Site

To support loosely-coupled multi-site operation, it is also necessary to have one site in the Contest acting as the “Master Site”.  The Master Site is responsible for off-line acquisition of standings data from each of the other sites, for merging the data into a “single contest” view, and for generating the “combined standings scoreboard(s)”.  PC2 V8.2 has built-in functions to perform these operations automatically.

While it is theoretically possible to have one of the active competition sites in the Contest also act as the Master Site, we recommend instead that a completely separate PC2  “site” be set up strictly for purposes of acting as the Master Site.  From the point of view of other sites, this Master Site is just another site in the contest; it should be listed in the “sitelist.ini” file of all sites, just as all other sites must be listed. (The Master Site can be physically located at one of the actual contest sites; however it is generally less confusing – and less error prone – if the Master Site is logically distinct from an active competition site.)

PC2  must be installed and configured at the Master Site just like it is at all the sites where Teams are competing. The procedure for installation and configuration of PC2 at the Master Site is basically identical to that of any other site.  The Master Site must have the same PROBLEM configuration; but it should NOT have any languages defined (since those differ between sites), nor should it have any Team or Judge accounts (it should have Scoreboard and Admin accounts).

Loosely-Coupled Startup:  A  WARNING

When a contest is run in tightly-coupled mode, an Administrator at one site can effectively “start” the contest at all sites simultaneously – by pressing the “Start All Sites” button on the Administrator “Time” screen.  This causes PC2 to automatically start the “Contest Clock” on all Servers, thus synchronizing all sites.  However, in loosely-coupled mode, there is no way for the clock to be started simultaneously in PC2 since the Servers by definition cannot communicate with each other in loosely-coupled mode. This can create a very bad situation if the humans involved do not take care to avoid it.

Specifically, if the contest data from various loosely-coupled sites is to be transported to other sites using the Export/Import and Merge functions (for example, in order to produce an “overall scoreboard; see below), it is critical that all sites start their PC2 contest clock at the same time – meaning, some human at each site must push the “Start Contest” button at the moment the contest problems are handed out and the contest begins at that site.  Otherwise, even if all teams receive the contest problems at precisely the same moment and have precisely the same amount of time to work on them, the merged scoreboard results will be inaccurate! 

For example, if all sites hand out the problems at the same instant but one site doesn’t start the PC2  clock for another 30 minutes, then every run submitted at that site will have a timestamp which is off (by 30 minutes) from the other sites.  Since scores are computed based on times (and hence timestamps), the merged scores will be wrong.  We have seen this happen – more than once – at loosely-coupled contests, and there is no way to fix it except to edit all the run timestamps manually through the Administrator interface at the Master Site.     Therefore we offer the following….

WARNING:  The Contest Administrator needs to make sure there is someone at each loosely-coupled site that is responsible for pushing the PC2 “Start Contest Time” button at the moment the contest starts.    You’ve been warned….

 

Export/Import

To generate a merged scoreboard, each site must “Export” its current standings to the “Master Site”, which merges the standings and generates a single scoreboard.  This Export and Merge operation can be done on the fly, at any time (and multiple times) during a contest. 

To do the Export, an Admin at each site must select the “Remote” tab, insure the “Contest Configuration” and “Standings” items under “Items to Export” are selected (checked), and then click the “Export” button.  This will pop up a dialog prompting for a file name into which the export data should be written.  Once the file is created it must be transferred by external means (ftp, email, etc.) to the Master Site.  The “Select Export Target” list on the Remote screen is not used and should not be changed.

Once the Contest Administrator at the Master Site has received an exported file from a site, the file must be “Imported” into the Master Site by clicking the Import button and selecting the file which was received from the remote site.  The data in the file will be merged with the current standings in the Master.  

Merged Standings Scoreboard

To generate the merged scoreboard (that is, a single scoreboard reflecting the combined standings of teams competing at all “loosely-coupled” sites), start a PC2 Client on the Master Site and login to a Scoreboard account.  This will generate both standard PC2 scoreboard displays and HTML displays as described in the V7.6 Guide.  However, the data in the scoreboard displays will reflect the combined standings of all sites whose data has been “exported” by the site and then “imported” into the Master Site.   The HTML files can of course then be published via a web server, from which they can be accessed by teams at all sites.

Head Judge Operations/Rejudging Runs

In some contests it is desired to have a “Head Judge” overseeing the Judging operations – for example, with the ability to selectively “rejudge” (re-execute) runs as the contest proceeds.  Another reason for a “rejudge” capability is for post-contest verification of results.   PC2 V8.2 provides a mechanism for such rejudging of runs.  To rejudge a run at a site:

1.     Start a PC2 Admin Client connected to the Server for the site at which the runs to be rejudged are located  (that is,  edit the Client’s “pc2v8.ini” to point <IP> and <site name string> to the site of interest; start a Client and login as an Administrator (e.g. “admin1”)).  NOTE:  this implies that the machine on which the Admin Client is running must have TCP/IP access to the machine on which the site’s Server is running. Specifically, it must be arranged that any “firewalls” between the Client machine and the Server allow such communication.)

2.     Select the RUNS tab to view runs at the Site; click on the desired run in the grid and click “Edit” to edit the run.

3.     Click the “Execute” button to re-execute the run.  NOTE:  an Admin Client cannot “re-execute” a run until it has first been “executed” and “judged” by a Judge.   NOTE ALSO: in order to re-execute a run on an Admin Client machine, that machine must be set up in the same configuration as that of the Judge’s machines for the site – it must have the same compilers, paths, etc.

4.     If it is desired to CHANGE THE JUDGE’S RESPONSE to the run, select the new response and click “OK”.  If on the other hand it is desired to RETURN THE RUN TO THE JUDGES FOR REJUDGING, exit the “EDIT” screen, select the Run again on the RUNS grid, and click the “GIVE” button to give (distribute) the run to the Judges again.

Warning:  while logged in to a Site as an Administrator, be careful not to change any Contest configuration items without coordinating with the Site Administrator.  

In the “loosely-coupled mode” of multi-site contests in PC2 V8.2 it is not possible for a single Admin Client to switch smoothly between different sites (this is the nature of “loose coupling”).  If a Head Judge wishes to have rejudging access for multiple sites it will be necessary to either shut down the Admin connected to one site, re-edit the “pc2v8.ini” file to point to a new site, and restart the Admin; or else (much easier) to simply have a separate Admin Client (running from its own separate home directory and with its own PC2 “ini” files) connected to each separate site. 


[1] This presumes the normal mode of operation, where sites have network connectivity to each other.  See the subsequent section “Loosely-Coupled Multi-Site Contests” for a discussion of running contests in the absence of network connectivity between sites.