Pc2v9AdminGuide Pc2v9Admin Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 132
| Download | |
| Open PDF In Browser | View PDF |
ACM INTERNATIONAL COLLEGIATE PROGRAMMING CONTEST California State University, Sacramento’s PC2 Version 9.4 Contest Administrator’s Installation and Configuration GuideTable of Contents 1 2 3 4 5 Introduction ............................................................................................ 5 1.1 Overview ......................................................................................................5 1.2 Compatibility Note ......................................................................................6 1.3 References ..................................................................................................6 Getting Started ....................................................................................... 7 2.1 Server Startup .............................................................................................7 2.2 Admin Startup .............................................................................................7 2.3 Contest Configuration ................................................................................8 2.4 Team Startup ...............................................................................................8 2.5 Judge Startup ..............................................................................................9 2.6 Scoreboard Startup ....................................................................................9 2.7 Starting the Contest.................................................................................. 10 2.8 Additional Information.............................................................................. 10 Installation Details ............................................................................... 12 3.1 Installation ................................................................................................. 12 3.2 Network / Firewall Requirements ............................................................ 12 3.3 Memory Limits .......................................................................................... 13 3.4 Security Alerts .......................................................................................... 14 3.5 Uninstall..................................................................................................... 14 PC2 Initialization Files ........................................................................ 15 4.1 The pc2v9.ini file ...................................................................................... 15 4.2 Other Initialization Files ........................................................................... 17 PC2 Startup Procedures ..................................................................... 18 5.1 Built-in Commands ................................................................................... 18 5.2 Server Startup ........................................................................................... 19 5.2.1 Non-GUI Server Startup ................................................................ 21 5.3 Server GUI Controls.................................................................................. 21 5.3.1 Adding Sites .................................................................................. 22 5.3.2 Restarting / Reconnecting Servers ................................................ 23 PC2 v9.4 Administrator’s Guide 1 http://pc2.ecs.csus.edu/ 5.3.3 5.3.4 6 7 Connections and Logins ................................................................ 25 Additional Server GUI Controls ..................................................... 25 5.4 Starting Clients ......................................................................................... 25 5.5 Contest Profiles ........................................................................................ 26 Configuring the Contest in PC2 .......................................................... 31 6.1 Administrator Login.................................................................................. 31 6.2 User Accounts .......................................................................................... 32 6.2.1 Account Creation ........................................................................... 32 6.2.2 Account Names and Passwords .................................................... 33 6.2.3 Loading Account Data ................................................................... 35 6.2.4 Importing ICPC Data ..................................................................... 37 6.3 Contest Problems ..................................................................................... 37 6.3.1 Defining a Problem ........................................................................ 37 6.3.2 Multiple Test Data Files ................................................................. 41 6.3.3 Defining Judging Type ................................................................... 43 6.3.4 Assigning Auto Judging to Judge modules ................................... 45 6.4 Contest Languages.................................................................................. 48 6.4.1 Defining a Language ..................................................................... 48 6.4.2 Command Parameter Substitutions ............................................... 51 6.4.3 Language Definition Examples .................................................... 51 6.4.4 Language Definitions In Multi-Site Contests ................................. 53 6.5 Contest Judgments ................................................................................. 55 6.5.1 Defining a New Judgment ............................................................. 55 6.5.2 Changing Existing Judgments ....................................................... 56 6.6 Balloon Notifications ................................................................................ 57 6.6.1 Defining Balloon Notifications ........................................................ 58 6.6.2 Email Server Advanced Settings ................................................... 59 6.7 Options (Settings tab) .............................................................................. 60 6.8 Sites ........................................................................................................... 61 6.9 Configuration via YAML Files .................................................................. 62 Starting the Contest............................................................................. 64 7.1 Clock Control ............................................................................................ 64 7.1.1 Starting the Contest Manually ....................................................... 64 7.1.2 Starting the Contest Automatically ................................................ 65 7.2 Contest Length ......................................................................................... 66 7.3 Multi-Site Clock Control ........................................................................... 67 7.4 Practice Sessions: Resetting A Contest ................................................ 69 PC2 v9.4 Administrator’s Guide 2 http://pc2.ecs.csus.edu/ 8 9 Monitoring Contest Status .................................................................. 71 8.1 Team Startup Status ................................................................................. 71 8.2 The Runs Display ...................................................................................... 72 8.3 Editing Runs .............................................................................................. 73 8.3.1 Extracting Runs ............................................................................. 75 8.4 Filtering Runs ........................................................................................... 76 8.5 Clarifications ............................................................................................. 77 8.6 Reports ...................................................................................................... 78 8.6.1 Automatic Generation of Reports at End of Contest ...................... 79 8.7 Event Feed................................................................................................. 80 8.8 Web Services ............................................................................................ 80 The PC2 Scoreboard ............................................................................ 81 9.1 Overview .................................................................................................... 81 9.2 Scoring Algorithm..................................................................................... 81 9.3 Configuring Scoring Properties .............................................................. 82 9.4 Starting the Scoreboard ........................................................................... 83 9.5 Scoreboard Updates ................................................................................. 84 9.6 Scoreboard HTML Files .......................................................................... 85 9.7 Scoring Groups ......................................................................................... 86 9.8 Adding New HTML Files ........................................................................... 88 10 Finishing the Contest .......................................................................... 89 10.1 Finalizing ................................................................................................... 89 10.2 Exporting Contest Results ....................................................................... 90 10.2.1 Generating a results.tsv export file ................................................ 90 10.2.2 Generating a pc2export.dat export file .......................................... 90 10.3 Shutting Down .......................................................................................... 90 Appendix A – pc2v9.ini Attributes .......................................................... 92 Appendix B – Networking Constraints ................................................... 94 Appendix C – PC2 Server Command Line Arguments .......................... 95 Appendix D – ICPC Import/Export Interfaces ........................................ 97 Appendix E – Validators ........................................................................ 103 PC2 v9.4 Administrator’s Guide 3 http://pc2.ecs.csus.edu/ Appendix F – Language Definitions ..................................................... 112 Appendix G – Using the PC2 API ............................................................ 117 Appendix H – Troubleshooting / Getting Help ...................................... 118 Appendix I – PC2 Distribution Contents ............................................... 119 Appendix J – Log files ............................................................................. 120 Appendix K – Reports Program .............................................................. 121 Appendix L – PC2 Event Feed ................................................................. 124 Appendix M – PC2 Web Services ............................................................ 127 Appendix N – PC2 Team Clients.............................................................. 130 PC2 v9.4 Administrator’s Guide 4 http://pc2.ecs.csus.edu/ 1 Introduction 1.1 Overview PC2 is a dynamic, distributed real-time system designed to manage and control Programming Contests. It includes support for multi-site contests, heterogeneous platform operations including mixed Windows and Unix in a single contest, and dynamic real-time updates of contest status and standings to all sites. This manual describes the steps required to install, configure, and run a contest using PC2. Further information on PC2, including how to obtain a copy of the system, can be found at http://pc2.ecs.csus.edu/. PC2 operates using a client-server architecture. Each site in a contest runs a single PC2 server, and also runs multiple PC2 clients which communicate with the site server.1 Logging into a client using one of several different types of PC2 accounts (Administrator, Team, Judge, or Scoreboard) enables that client to perform common contest operations associated with the account type, such as contest configuration and control (Administrator), submitting contestant programs (Team), judging submissions (Judge), and maintaining the current contest standings (Scoreboard). PC2 clients communicate only with the server at their site, regardless of the number of sites in the contest. In a multi-site contest, site servers communicate not only with their own clients but also with other site servers, in order to keep track of global contest state. The following communication requirements must therefore be met in order to run a contest using PC2: (1) a machine running a PC2 server must be able to communicate via TCP/IP with every machine running a PC2 client at its site; and (2) in a multi-site contest, every machine running a PC2 server must be able to communicate via TCP/IP with the machines running PC2 servers at every other site. In particular, there must not be any firewalls which prohibit these communication paths; the system will not operate if this communication is blocked2. It is not necessary for client machines to be able to contact machines at other sites. Each PC2 module (server or client) reads one or more initialization files when it starts; these files are used to configure the module at startup. The client module also tailors its configuration when a user (Team, Judge, etc.) logs in. In a typical PC2 contest configuration, each Team, Judge, etc. uses a separate physical machine, and each of these machines runs exactly one client module. It is possible to have multiple clients running on the same physical machine, for example by having different users logging in to different accounts on a shared machine. In this case, each user (Team, Judge, etc.) will be executing their own “Java Virtual Machine (JVM)”, and must have their own separate directory structure – including their own separate copy of the PC2 initialization files in their account. 1 Note that “site” refers to a logical grouping of contest participants, not (necessarily) a physical or geographic grouping. It is perfectly possible for participants at physically or geographically separate locations to collectively represent one PC2 “site” and to be served by a single “site server”; it is quite common to run an entire contest using a single site server regardless of whether or not the teams, judges, etc. are physically close. Multi-site operations are primarily supported for situations where network connectivity is highly unreliable. 2 See the Appendix titled “Networking Constraints” for further details on using PC2 over networks. PC2 v9.4 Administrator’s Guide 5 http://pc2.ecs.csus.edu/ Setting up and running a contest using PC2 involves the following steps: (1) installing Java and PC on the contest machines; (2) creating/editing the necessary initialization files; (3) starting the server(s) and clients(s); (4) configuring PC2 for the contest via an Administrator client; and (5) starting the contest so that users (Teams and Judges) can log in. These steps are listed in checklist form in the next chapter, and are described in detail in the remainder of this manual. 2 1.2 Compatibility Note Starting with Version 9.3, the PC2 system contains substantial new enhancements which are incompatible with earlier versions of the system. Users should not “mix” components of PC2 V9.3+ with earlier versions (9.2.x and below). 1.3 References While this manual tries to give a complete description of installing and using PC2, the following web references may provide additional helpful information. In particular, the PC2 Wiki is updated much more frequently than this manual and should be consulted frequently for answers to questions. PC2 home page http://pc2.ecs.csus.edu/ PC2 Wiki – up to date articles and information about PC2 http://pc2.ecs.csus.edu/wiki/Main_Page PC2 Bugzilla - enhancement and defect tracking and reporting for PC2 http://pc2.ecs.csus.edu/bugzilla/ PC2 v9.4 Administrator’s Guide 6 http://pc2.ecs.csus.edu/ 2 Getting Started For those people who hate to read manuals and would rather take a chance with a shortcut list, this chapter provides a (somewhat terse) summary of the steps necessary to install PC2 and get it running for your contest. Please note that this chapter does not provide all the details; it is intended to give readers a general overview of the process of using PC2 to run a contest. Please refer to the subsequent chapters for necessary additional details. Server Startup 2.1 Each contest site is controlled by a “site server” (or just “server” for short).3 Perform the following steps to install and start a PC2 site server (see the chapter on Installation Details, as well as the chapter on Startup Procedures and the Appendices, for further details). Install Java (version 1.7 or greater) on the machine which will act as your PC2 Server; ensure the Java bin directory is in the PATH. Download the latest PC2 distribution from https://pc2.ecs.csus.edu/. unzipping the PC² distribution to a directory of your choice. Add the PC² bin directory to the PATH. Start a PC² server using the command “pc2server”. Install PC² by Login using the name “site1” and password “site1”. Enter a contest password (this contest security password will be required to be reentered for all subsequent server startups). Admin Startup 2.2 Overall contest management is controlled through the PC2 “Administrator Client” or “Admin” for short. Perform the following steps to get the PC2 Admin running. 3 If you are going to run the PC2 Admin on a different machine than the one running the PC2 Server, then on the Admin machine follow the above steps regarding installing Java, downloading/unzipping the PC2 distribution, and setting the PATH values. If the Admin is on a separate machine from the Server, edit the pc2v9.ini file on the Admin machine, replacing “localhost” in the [client] section with the IP address of the Server machine. Start the PC² Admin using the command "pc2admin" and login using the name "root" and password "administrator1" See the previous footnote regarding the definition of “contest site”. PC2 v9.4 Administrator’s Guide 7 http://pc2.ecs.csus.edu/ Contest Configuration 2.3 Use the PC2 Admin to configure at least the following contest items by selecting the correspondingly-named tab on the Admin Configure Contest screen: Accounts: generate the necessary accounts – minimally, you’ll need to generate one account for each team, one or more judge accounts, and a scoreboard account (see the section on User Accounts in the chapter on Configuring the Contest for further details). You may also want to generate additional judge accounts for “auto-judging” (see the section on Contest Problems in the chapter on Configuring the Contest for further details), and you may want to generate a “feeder” account for external tools accessing PC2 (see the Event Feed and Web Services sections in the chapter on Monitoring Contest Status for further details). Problems: define one or more contest problems, specifying the problem input data file(s) (if the problems require input data), the judging type, and the “validator specification” (if the problems are to be “auto-judged”). See the section on Contest Problems in the chapter on Configuring the Contest for further details. Languages: define one or more contest languages, specifying the language name, compile command line, executable filename, and program execution command line. See the section on Contest Languages in the chapter on Configuring the Contest for further details Team Startup 2.4 There are two methods which can be used to allow teams to login to a PC2 contest: the PC2 Team Application client and the PC2 Team Web client. Using the Team Application client requires installing PC2 on each team machine, whereas using the Team Web client allows teams to use a browser to connect to the contest but requires providing an external web server and installing the PC2 Team web pages into the web server. If you are going to use the PC2 Team Application client, perform the following steps to install the client on each team machine: Follow the above steps regarding installing Java, downloading/unzipping the PC2 distribution, and setting the PATH values on each team machine. Edit the pc2v9.ini file on each team machine, replacing “localhost” in the [client] section with the IP address of the PC2 Server machine. Start the PC² Team client using the command "pc2team" and login using the team name and password defined under “Accounts”, above. (The default team name and password are both “teamxx”, where “xx” is the team number.) PC2 v9.4 Administrator’s Guide 8 http://pc2.ecs.csus.edu/ To use the PC2 Team Web client, see the Appendix on PC2 Team Clients. Judge Startup 2.5 There are two methods which can be used for judging team submissions: manual and automated (the two methods are not mutually exclusive; automated judging can be used to send teams a “preliminary result” and can then be followed by manual [human] judging). Selecting the type of judging is part of Contest Problem Configuration, described above and also in more detail in the section on Contest Problems in the chapter on Configuring the Contest. In any case you will want to set up one or more judge machines.4 Perform the following steps to install the PC2 Judge client on each judge machine: Follow the above steps regarding installing Java, downloading/unzipping the PC2 distribution, and setting the PATH values on each judge machine. Edit the pc2v9.ini file on each judge machine, replacing “localhost” in the [client] section with the IP address of the PC2 Server machine. Start the PC² Judge client using the command "pc2judge" and login using the judge name and password defined under “Accounts”, above. (The default judge name and password are both “judgexx”, where “xx” is the judge number.) If your contest is going to use automated judging, see the section Assigning Auto Judging to Judge Modules in the chapter on Configuring the Contest. Scoreboard Startup 2.6 Perform the following steps to install the PC2 Scoreboard client on a machine5: If you are running the Scoreboard client on a different machine (one onto which PC2 has not already been installed), follow the above steps regarding installing Java, downloading/unzipping the PC2 distribution, and setting the PATH values on the scoreboard machine. Edit the pc2v9.ini file on the scoreboard machine, replacing “localhost” in the [client] section with the IP address of the PC2 Server machine. 4 In principle judging can be done on the same machine used to run the PC2 Server or the PC2 Admin, but we don’t recommend it because of the problem of contest administrators and judges colliding with each other trying to use the machine. 5 Unlike the situation with judges, there only needs to be a single PC2 Scoreboard for the entire contest and it rarely needs attention once it is started; for this reason we frequently run the scoreboard on the same machine as the PC2 Server or Admin. PC2 v9.4 Administrator’s Guide 9 http://pc2.ecs.csus.edu/ Start the PC² Scoreboard client using the command "pc2board" and login using the scoreboard account name and password defined under “Accounts”, above. The default scoreboard name and password are both “boardX”, where “X” is the number of the scoreboard account (typically “1”). Arrange for the scoreboard-generated HTML files to be accessible to user’s browsers. See the section Scoreboard HTML Files in the chapter on the PC2 Scoreboard for further details. Starting the Contest 2.7 The contest can be started either manually, or automatically at some scheduled time. The length of the contest can be configured, and contests can be “reset” (e.g., between Practice and Real contests). See the chapter on Starting the Contest for additional information. To start the contest manually, press the "Start ALL" button on the Administrator module Times tab. This will allow teams to submit runs, judges to fetch and judge the runs, and standings to be posted on the scoreboard, and will use the PC2 default contest length of 5 hours. 2.8 Additional Information The above will hopefully provide enough information to allow you to get a contest going under PC2. Note however, that it omits many details, including alternative configuration options, additional features, and so forth. For example, it does not take into account any of the following PC2 capabilities: Use of external interfaces such as the Event Feed and PC2 Web Services Command-line submission of runs by teams Generation of PC2 Reports describing system information Monitoring team status during the contest Examining/editing/judging runs during the contest Importing contest configuration information from data files Exporting final results to other systems Configuring multi-site contests Creating different "scoring groups" on the Scoreboard Creating customized HTML scoreboard output Running PC2 modules in "no-gui" mode Using "Profiles" to switch between contest configurations Handling security alerts PC2 v9.4 Administrator’s Guide 10 http://pc2.ecs.csus.edu/ Details of configuring contest problems (things like validators for automated judging, handling very large data files, etc.) Contest language configuration details Defining judgement messages Sending "balloon notifications" for correct submissions Configuration options such as maximum allowed team output, information displayed to judges, editing scoring properties, etc. Programmatic access to PC2 via the PC2 API These things and many more are covered in the rest of this manual, and also on our Wiki at https://pc2.ecs.csus.edu/wiki. PC2 v9.4 Administrator’s Guide 11 http://pc2.ecs.csus.edu/ 3 Installation Details In the event that the preceding chapter is a bit too terse, the remainder of this manual discusses the details of using PC2 to configure and run a contest. The first step is to install the necessary software, as described in this chapter. The remaining chapters cover initialization files, starting the system, configuring the system for a contest, starting and monitoring the contest, and using the PC2 scoreboard. In addition several appendices cover details of certain topics. 3.1 Installation 1. Install the Java Standard Edition (SE) Software Development Kit (SDK) or Java Runtime Environment (JRE), version 1.7 or later on each machine. The remainder of this manual assumes that “$JAVAHOME” represents the SDK installation directory. We recommend using 64-bit Java, in particular for the PC2 Server and (if used) the EWTeam Client. 2. Ensure “$JAVAHOME/bin” is contained in the PATH environment variable on each machine (i.e., for each user). 3. Go to the PC2 home page (see Chapter 1, under References), navigate to the “Download” page, and download the latest PC2 “.zip” or “.tar.gz” file to the directory where you wish to install PC2 (this can be any directory of your choice). 4. Unzip the downloaded file, being sure to tell the unzip program to “retain directory hierarchy” and “preserve case sensitivity”. This will create a directory named (for example) pc2-9.4.0, which for the remainder of this manual we refer to as the $PC2HOME directory. The $PC2HOME directory contains bin, lib, doc, samps and other directories, plus a default “pc2v9.ini” file (see the following chapter) along with several text files giving basic information such as the system version number. The doc and samps directories contain the system documentation and a variety of sample scripts, files, and other goodies you might want to examine. The file “doc/index.html” can be used to browse the documentation. (NOTE: all files and directories which comprise a PC2 distribution (.zip or .tar.gz file) will unzip into the $PC2HOME directory. See the appendices for a complete description of PC2 distribution contents.) 5. Add the PC2 “bin” directory (that is, the directory $PC2HOME/bin) to the PATH environment variable on each machine. 3.2 Network / Firewall Requirements Here are the PC2 firewall requirements; see also the Appendix “Networking Constraints”. 1. PC2 Clients need to be allowed to make outbound connections to their server; hence servers need to be open to inbound connections from the clients. 2. Servers need to be allowed to make outbound connections to all other servers PC2 v9.4 Administrator’s Guide 12 http://pc2.ecs.csus.edu/ 3. Servers need to be open to inbound connections from all other servers 3.3 Memory Limits PC2 is written in Java and therefore inherits all the features (good and bad) of that language. Although Java is touted as “run anywhere”, the reality is that many things depend on your specific installation – both the version of Java you are using and the underlying OS platform on which it is running. This is particularly true when it comes to memory allocation – primarily, what Java refers to as “Heap Space”. Throughout this manual we describe various “commands” (scripts, batch files) that PC2 provides to invoke different functions. Most of these commands involve starting a “Java Virtual Machine (JVM)”. Each instance of a JVM has a “maximum heap size” value associated with it; if the Java program attempts to use more “heap space” than the maximum allowed, the program aborts with an “out of heap space” error. This can be particularly disconcerting if it is your PC2 server (for example) that crashes in the middle of a contest. It is therefore important to know what can be done to avoid such memory-limit problems. Each of the PC2 commands passes a parameter to the JVM to set the maximum heap size. The form of this parameter is –Xmx$$$$M, where $$$$ represents the maximum heap size in megabytes (‘M’). The heap size values used by the various scripts are conservative, intended to insure that the command will be able to run successfully on the widest variety of platforms. On any particular platform it is possible that the value in the script may be significantly less that the platform is capable of supporting. It is also possible that the command value is actually lower than the default setting which would be applied on a particular platform if no value had been specified. This is particularly true between 32-bit and 64-bit systems. For these reasons, you may want to determine the maximum heap size allowable on your platform and edit the corresponding script to set a larger value (this is particularly important for a large contest – one with a large number of teams, problems, and/or large data files, and is also particularly important for the PC2 Server). Setting the JVM maximum heap size can significantly increase the ability of the corresponding PC2 module to run without problems.6 The maximum heap size can be determined by running the following command on the corresponding platform:7 Windows: java -XX:+PrintFlagsFinal -version | findstr HeapSize Linux/MacOS: java -XX:+PrintFlagsFinal -version | grep HeapSize 6 The pc2server scripts (for both Windows and Linux) attempt to make an intelligent guess as to the type of platform (32- or 64-bit) and set the heap size accordingly. The user can change the heap size values used by these scripts by editing constants at the top of the pc2server script. For all the other scripts, it is necessary to edit the –Xmx parameter in the script. 7 It may also be possible to use the parameter –XX:+AggressiveHeap to instruct the JVM to automatically force the heap to the largest available size. However, this parameter is non-standard, may not be available on all systems, and has not been thoroughly tested in PC2. PC2 v9.4 Administrator’s Guide 13 http://pc2.ecs.csus.edu/ 3.4 Security Alerts There are a number of security features in PC2 Version 9, including disk file encryption, network traffic encryption and security alerts. Security alert windows will automatically appear on server UI and Admin UI when a potential security violation or exceptional condition occurs. For example, a security alert occurs if a PC2 client logs in successfully while the same client is already logged in. Security information is also recorded in a security log in the logs directory. A typical security log file will be named something like: logs/SERVER0@site1.security-0.log. An example of the log entries is: 140812 155846.072|SEVERE|Thread-36|newMessage|SecurityException From: ADMINISTRATOR1 @ site 1 ADMINISTRATOR1 @ site 1: duplicate login request; previous login forced off |edu.csus.ecs.pc2.core.exception.ContestSecurityException: ADMINISTRATOR1 @ site 1: duplicate login request; previous login forced off | at edu.csus.ecs.pc2.core.InternalController.attemptToLogin (Unknown Source) | at edu.csus.ecs.pc2.core.InternalController.receiveObject (Unknown Source) | at edu.csus.ecs.pc2.core.transport.TransportManager$1.run (Unknown Source) | at java.lang.Thread.run (Thread.java:745) 140812 155846.073|SEVERE|Thread-36|newMessage|SecurityException Sec. Message: ADMINISTRATOR1 @ site 1: duplicate login request; previous login forced off ConnHandId Socket[addr=/127.0.0.1,port=53488,localport=50002]2471900182656421556 3.5 Uninstall To uninstall PC2 do the following on each PC2 Server and client machine: 1. Use the pc2reset script to remove the contents of any PC2 directories 2. Remove the pc2v9.ini file and the archive directory. 3. Remove the $PC2HOME directory and its contents 4. Restore the system environment variables (PATH and CLASSPATH) PC2 itself does not make any changes to any machine locations outside those listed above either during installation or execution. In particular, for example, it makes no entries in the Registry on a Windows machine, nor does it copy any files to locations outside the installation directory or the current working directory in any environment. PC2 v9.4 Administrator’s Guide 14 http://pc2.ecs.csus.edu/ 4 PC2 Initialization Files When a PC2 module (server or client) begins running, it reads an “initialization file” named pc2v9.ini from the directory in which it was started.8 The Contest Administrator must ensure this file is present and edited as necessary on each machine prior to starting a PC2 module. This chapter describes the initialization files and their contents (note: some default versions of the initialization files are provided with the PC2 distribution package; these must be edited as necessary). Further descriptions of initialization files and their contents can be found in the Appendices. 4.1 The pc2v9.ini file Every PC2 module reads a file named “pc2v9.ini” at startup. By default each module looks for its pc2v9.ini file in the current working directory; thus for example Team machines would typically need to have a pc2v9.ini file in their “home” directory. (Command-line arguments can be used to point to a different location for the pc2v9.ini file; see the Appendices for details.) The pc2v9.ini file provides key initialization information to the PC2 module. The file is formatted in sections. Each section starts with a section-name in square brackets. The following different section names are recognized: [server] and [client]. Each PC2 module reads the entire file, but silently ignores any information which does not pertain to it (for example, server modules ignore data in all sections except the [server] section, etc.) All lines starting with “#” or “;” are comments and are also ignored, as are blank lines. Each section is made up of lines containing "attribute assignment" statements of the form attributeName=value The “attributeName” is a predefined string chosen from list of PC2 configuration attributes. The “value” is the value to which the corresponding attribute is set when the pc2v9.ini file is read by a module. No spaces are allowed in front of the “value” after the equalsign. Some attribute assignment statements are specific to particular sections and have no meaning for other sections (or for the modules that read them). Other attribute assignments are relevant to multiple sections/modules and can appear in different sections. A complete list of the predefined attributes is given in the Appendices. Most attribute assignments are optional and default values are used if an attribute assignment is not present in the 8 Older versions of PC2 also read files named reject.ini and sitelist.ini. However, the functionality provided by those files is incorporated into interactive screens in the Administrator client in PC2 V9, and their use is deprecated and scheduled for removal in a future version of the system. PC2 v9.4 Administrator’s Guide 15 http://pc2.ecs.csus.edu/ pc2v9.ini file. However, certain attributes must be specified in the pc2v9.ini file in order for the system to function properly. Based on these rules, a minimum sample pc2v9.ini file is shown below. Note that since all modules ignore sections and attributes which do not apply to them, it is permissible to create a single pc2v9.ini file containing all the required entries and put this same file on all machines at a given site. # sample pc2v9.ini file [client] # Tell PC2 clients where to find their server (IP and port) server=198.51.100.50:50002 The sample pc2v9.ini file shown above would be appropriate for both client and server machines in a single-site contest. In a multi-site contest, the server at one of the sites is designated the “primary server” and servers at all other sites are designated “secondary servers”. When a primary server is started, it waits for other servers to contact it. When a secondary server is started, it automatically attempts to contact the primary server; this is how the inter-server communication in a multi-site contest is established. The distinction between whether a server waits to be contacted (is a primary) or initiates remote contact (is a secondary) is in fact the only distinction between “primary” and “secondary” servers. In a multi-site contest exactly one of the servers should be started as a primary server (it does not matter which site has the primary server; once communication is established all sites run as peers). The servers at all other sites should be started as secondary servers. Designation of a server as primary or secondary is controlled by the contents of the pc2v9.ini file. By default (that is, in the absence of any information in the pc2v9.ini to the contrary), a server assumes it is a primary server when it starts. Designating a server as a secondary server is accomplished by providing an additional entry in the [server] section of the pc2v9.ini file of that server. This additional entry, known as the remoteServer attribute, tells the secondary server the IP address and port number at which it should attempt to contact the primary server. If this remoteServer attribute is not present in [server] section of the pc2v9.ini file when a server starts, the server implicitly assumes it is a primary server. Thus for example, the pc2v9.ini file on the primary server in a multi-site contest might look like the sample above (since it does not contain any remoteServer attribute), whereas the pc2v9.ini file on machines at a second site might look like: PC2 v9.4 Administrator’s Guide 16 http://pc2.ecs.csus.edu/ # sample pc2v9.ini for a second site [client] # tell clients where to find their site’s server (IP and port) server=203.0.113.7:50002 [server] # Tell this (secondary) server how to contact the primary server remoteServer=198.51.100.50:50002 Note that the (sample) IP address given in the [client] section of the above pc2v9.ini file for a secondary site is the (hypothetical) IP address of the server for that site, whereas the IP address given in the remoteServer attribute in the [server] section is the address of the primary server – the address which the (secondary) server should use to contact the primary server and “join the contest”. 4.2 Other Initialization Files For backwards compatibility, PC2 still supports two additional initialization files: reject.ini and sites.ini. The reject.ini file was used in older versions of the system to specify the “reject messages” which judges could send to teams when a submission failed to solve a problem, while the sites.ini file was used to specify information for additional sites in a multi-site contest. Both of these functions have been incorporated into the interactive configuration mechanisms described in the chapter on Configuring the Contest, and use of these additional initialization files is deprecated and support for them may be removed in future versions of the system. PC2 v9.4 Administrator’s Guide 17 http://pc2.ecs.csus.edu/ 5 PC2 Startup Procedures 5.1 Built-in Commands Once PC2 has been installed and the necessary “.ini” files have been properly set up (i.e., edited and placed in the appropriate startup directory), the normal PC2 startup procedure is to start a primary server, then start an Admin client connected to that server and use the Admin client to configure the contest details (problems, languages, etc.). Once the contest has been fully configured using the Admin client, secondary servers can be started at remote sites (if any), followed by additional clients at both the primary and (in the case of a multi-site contest) secondary sites. The PC2 distribution comes with a collection of “command scripts” designed to simplify starting the various modules. The available command scripts and their corresponding functions are listed below.9 To invoke the specified function, simply type the corresponding command at a command prompt. The commands reside in the “bin” directory beneath “$PC2HOME” (the root directory of an unzipped PC2 installation), so the normal method of invoking them would be to change to the contest directory (that is, the directory where the contest will be run from, where logs are to be kept, etc.), and type the command name (note that this assumes, as previously recommended, that the $PC2HOME/bin directory has been added to the $PATH). Command pc2server pc2admin pc2team pc2judge pc2aj pc2board pc2submit pc2extract pc2ef pc2nc pc2report pc2reset pc2ver pc2zip Function 2 Starts a PC Server Starts a PC2 Client expecting an Administrator login Starts a PC2 Client expecting a Team login Starts a PC2 Client expecting a Judge login Starts a PC2 Judging Client (“AutoJudge”) in headless (non-GUI) mode Starts a PC2 Client expecting a Scoreboard login Submits a run using a command-line interface Extract various information from a PC2 server Starts a PC2 Event Feed client Starts a PC2 “netcat” client for analytic/debugging purposes Generates various reports without needing the PC2 Server running Resets a contest, deleting all runs and (optionally) other data Displays the current PC2 version Creates a “zip” file containing all the PC2 contest data The normal startup procedure, for example, would be to invoke the command “pc2server” to start a server, then in a separate command window to invoke the command “pc2admin” to start an Administrative client to be used to configure the contest details in PC2. Once the contest details are configured, other clients can be started (as well as servers at other sites) using the appropriate commands. 9 In a Windows environment the command scripts are all “batch files” whose names correspond to the given command name followed by “.bat”. In a Unix environment the command scripts are all Bourne Shell scripts whose names match the given command names. Thus the same command name can be used regardless of the underlying OS. PC2 v9.4 Administrator’s Guide 18 http://pc2.ecs.csus.edu/ Additional details on the various PC2 command scripts can be found at http://pc2.ecs.csus.edu/wiki/PC%C2%B2_scripts. 5.2 Server Startup When a server is started (using the command “pc2server”), the user will see a login window similar to the following: The default login name for the primary (first) site server is site1; the default password is also site1 (the password can subsequently be changed; see below). Entering these values and pressing the Login button on the above screen will initiate the login process. However, there is a second step which must be performed to complete the login process. At the time a server is started for Site 1 for the very first time, there is no contest-specific information stored in the system. All contest information which is subsequently entered will be stored in encrypted form, to protect the integrity of the contest data. In order to manage the encryption and allow authorized access at a later time, the Contest Administrator must provide a contest master password. Thus, on the very first login to a primary (first) server, the following screen will appear: PC2 v9.4 Administrator’s Guide 19 http://pc2.ecs.csus.edu/ The Contest Administrator must enter (and confirm) a password to be used to perform contest data encryption. Note that this password provides access to all contest-related data; it should be well-chosen and well-protected. Note also that there is no default value for this password; it must be set (chosen and confirmed) by the Contest Administrator. Entering and confirming a contest master password (in addition to the login ID and login password) completes the login process. If a first-site server is started again at some later point in time (i.e. after a contest master password has been set), pressing the Login button on the server’s main login screen displays the following screen: At this point the user must enter the Contest Password in order to complete the login process. Only the primary (first) server in a contest prompts for the contest master password. In a multi-site contest the user starts a (secondary) server using the pc2server command as above, and logs in using the default site name (for example, site2) and password (site2). The secondary server contacts the primary server (pointed to by the remoteServer=xxx entry in its pc2v9.ini file) and obtains the current contest master password directly from the remote server. Note that the second server does not display the obtained contest master password; if people at secondary sites need this password for some reason then they must obtain it from the Contest Administrator at the primary (first) site. PC2 v9.4 Administrator’s Guide 20 http://pc2.ecs.csus.edu/ 5.2.1 Non-GUI Server Startup In some environments it may be desirable to run a PC2 server without a GUI front-end. This can be accomplished using the –-nogui command line argument described in the appendix on Server Command Line arguments. Note that if this option is chosen there is no GUI-based way to enter login, account password and contest password information. These may be entered on the command line as well. For example, to start a primary (first) server with no GUI the following command could be used: 10 pc2server --nogui --login site1 --password site1 --contestpassword contest To start a secondary server without a GUI in a multi-site contest the following command could be used: 10 pc2server --nogui --login site2 --password site2 Note that since this server is presumed to be secondary (meaning it has a pc2v9.ini entry pointing to a remote server which is the primary server), the --contestpassword option is omitted. This is because secondary servers obtain the contest master password directly from the primary server, as described above. When a server is started using the --nogui option, it sends all of its output in text form to the console window from which it was started. The following shows an example of a server started in this way. Any subsequent text produced by the server (e.g. error messages or informational text) would appear on subsequent lines on the console. CSUS Programming Contest System Version 9.3 20140802 (Saturday, August 2nd 2014 20:46 UTC) Build 2822 Java ver 1.7.0_55 Windows 7 6.1 (x86) Date: 8/12/14 3:11 PM Working directory is C:\pc2-9.3.0 Tue Aug 12 15:11:46 PDT 2014 Using Profile: Default @ profiles\P3a9add10-5089-47c5b82a-31966b136b6b Tue Aug 12 15:11:46 PDT 2014 server (Site 1 - Site 1) started To halt a non-GUI server, use the Shutdown button on the Site tab on the Administrator GUI to gracefully stop the server. 5.3 Server GUI Controls Upon successful login to a server (assuming the server was started without the --nogui option) a GUI similar to the following appears: 10 Note that a drawback of this approach is that the login and contest master passwords must be typed in plain-text on the command line. A much more secure option is to take advantage of the “-F” command line argument, which allows specification on the command line of a file containing the necessary security information. See the appendix titled “PC2 Server Command Line Arguments” for details. PC2 v9.4 Administrator’s Guide 21 http://pc2.ecs.csus.edu/ The tabs across the top of this GUI allow the user to examine and modify various configuration items in the contest. Those items which are primarily server-related are described below; some of the tabs also appear in the PC2 Administrator GUI and are described in the chapter on “Configuring the Contest”. 11 5.3.1 Adding Sites The Sites pane (shown above) lists each contest site which the system knows about. Initially only “Site 1” is known; in order for a server at another site to join the contest, the additional site must first be added to the Sites list. To make the system aware of the presence of another site, press the Add Site button to create a new row in the grid.12 In the new row which appears, select the Password field and change the password from the default value.13 Next, select the IP field in the new row and enter the IP address for the new site (that is, the IP address of that site’s server machine); then select the Port field in the row and enter the port number at which the new site is expected to 11 In the case of starting a server with the “ --nogui” option the PC2 Administrator client is the only way to access some of these screens. In addition, some server-specific capabilities can only be accessed via the server GUI. 12 The Add Site button also appears on the Sites tab in the Administration module GUI (where it can be found under the Run Contest tab). 13 It is critically important for the security of your contest that you enter new passwords for every site (including the first one). Otherwise, since the default values for site passwords are well-known (published for example in this manual), some bad-guy could start his own server and connect to your contest while it is running. PC2 v9.4 Administrator’s Guide 22 http://pc2.ecs.csus.edu/ be contacting the primary site.14 Optionally, select the Site Title field and assign a name to the site. Finally, press the Update Site button to save the site info. Note that adding a site is a two step process: use Add Site to input the site data then Update Site to save the site data. When starting a server for a site, the user must supply two data values: a login name and a password. For each site in the contest, the server’s login name is the word “site” followed immediately (no spaces) by the site number (for example, site1 or site3). Each server’s site number is the value given in the leftmost field in the Sites display pane. The password for logging in to each site server is the value given in the Password field. If the password for a remote site is changed using the Sites pane, the new password must be relayed to the remote site in order for them to be able to log in to the contest. Note that there is no correlation between the value shown in the Site Title field of the Sites pane and the data required to log a server into a contest; login names for servers are always “siteX”, where ‘X’ is the site number shown at the left of each row in the Sites pane. The only function of the “Site Title” field is to provide a convenient human-readable reference for each site; that reference string is not used in any internal operations in PC2. 5.3.2 Restarting / Reconnecting Servers During a contest there may be a loss of connectivity between sites, or a situation where one or more servers get “out of sync” with the others. In PC2 Version 8 one had to shutdown (kill) the server and restart it when this happened. In Version 9 there is a Reconnection feature available to help with this situation. To determine whether a site to which communication has been lost can be reconnected without killing and restarting the site’s server, check the Logins pane (see below). If the server from that site appears in a row in the Logins grid, there is a connection between the sites. In this example on Site 1, Site 2 is logged in. 14 Care should be taken to set the port number to the port which will be specified in the pc2v9.ini file at the remote site; the servers will not be able to communicate with each other if the port numbers do not match. Also note that when a new “site row” is added to the grid using the Add Site button, the default port number assigned to the new site is not the same as the default for the first site. Typically the port numbers must be changed to match (assuming all sites will use the same port for communication). PC2 v9.4 Administrator’s Guide 23 http://pc2.ecs.csus.edu/ To reconnect a site that was previously logged in15 but is now disconnected, use the Reconnect button. Note that the Reconnect button is on the Sites tab, not the Login tab. When the site is reconnected, that site will appear in the list on the Login tab. 15 To reconnect a site the site must have previously been started. Reconnection will not restart a remote server. PC2 v9.4 Administrator’s Guide 24 http://pc2.ecs.csus.edu/ 5.3.3 Connections and Logins These two tabs on the server GUI show what network connections and what PC2 client logins have occurred since the server was started. They can sometimes be used to help with reconnection when sites get disconnected, as described above, or to trace anomalous or error conditions in the system. They can also be used to force a disconnection or logout from the system; this is done by highlighting (selecting) a row in the corresponding grid and pushing the Disconnect (or Logoff) button. 5.3.4 Additional Server GUI Controls The remaining tabs on the Server GUI (Export, Options, Reports, and Times) are replicated on the Administrator GUI and are described in the chapter on Configuring the Contest. 5.4 Starting Clients Once a PC2 server is running at a site, users (Contest Administrators, Judges, and Teams) at the site can start PC2 clients to login and use the system16. The normal procedure is first to start a client using the “pc2admin” command and login as the “root” administrator (password “administrator1”) in order to configure the contest. Subsequently each Contest Judge would start a client using the “pc2judge” command, and each Team would start a client using the “pc2team” command17. The Contest Administrator would normally also start a PC2 scoreboard using the “pc2board” command, logging in using the PC2 account “board1”. Each time a client is started, the client will read its pc2v9.ini file to determine its site name and the location of its server, and then contact the server. Following this initialization sequence, the client will display a “login” window as shown below, indicating that it is ready to accept a user (Team, Judge, Administrator, or Scoreboard) login. Depending on the logging levels specified in the client’s pc2v9.ini file, the progress of these steps will be displayed and/or written to a file in the client’s startup directory under logs. If any errors occur or the client fails to produce the login screen, check the log file in the logs directory for more details. 18 16 In the case of users logging in to a server (e.g. via Xterminals under Unix) rather than where each user has their own machine, each user must start a client on the server via their terminal window. Each client must be started in its own separate directory, which must contain the appropriate initialization files. Under Xwindows, the DISPLAY environment variable can be used to direct PC2 graphical output from the client back to the Xterminal. 17 With PC2 Version 9.3 and above there is a component called “EWTeam” that is a web-based team client which allows using a browser on team machines instead of installing and starting the PC2 Team Client. See the Team Clients appendix and the separate EWTeam project available on the PC2 home page for further information. 18 See the Appendices for further descriptions of log files and their contents. PC2 v9.4 Administrator’s Guide 25 http://pc2.ecs.csus.edu/ Note: PC2 has a security rule that disallows multiple simultaneous logins for an account. For example, if a team logs into their account, and then tries to login again (say, from a different machine), the first login session will be terminated. This rule applies to all forms of login; for example, if a team is logged in via the Team Client GUI and later uses the pc2submit script to login and submit a run, the script login will cause the GUI login to be terminated. The same is true of using the external “EWTeam” web client; logging in via the EWTeam will terminate any other current login for that team. 5.5 Contest Profiles PC2 provides a facility called contest profiles. A profile is a collection of all the information necessary to run a contest in a particular configuration (the accounts, languages, problems, scoring settings, etc.) Profiles allow the Contest Administrator to configure a contest, save the contest profile, and then configure a different contest. Switching between contest configurations is then just a matter of switching profiles. This facility is useful, for example, when it is desired to run a Practice Contest followed immediately by a Real Contest using the same Languages and Accounts but with a different problem set. The Contest Administrator would configure the Practice Contest, save the current profile under the name “Practice”, then “clone” the configuration into a differently-named profile (for example, “Real”). Options allow selectively cloning only certain configuration data; for example, you can suppress copying the problems, runs, and clarifications from the Practice profile into the Real profile, while resetting the contest time in the Real profile and keeping the same Languages, Accounts, Groups, Judgment Names, Notifications, and so forth. Switching from the Practice Contest to the Real Contest is then simply a matter of switching between profiles. PC2 v9.4 Administrator’s Guide 26 http://pc2.ecs.csus.edu/ Profiles are created using the Profiles tab on the Configure Contest screen of the Admin client, shown below. NOTE: Profiles are only supported in a single site contest.19 Pressing the NEW button on the Profiles screen displays the following dialog which allows creation of a new profile. Note that new profiles are essentially empty – meaning that the user is responsible for providing all configuration information for the profile, including some information that PC2 normally automatically provides as part of the “Default Profile”. To avoid having to enter all configuration information for a profile, use the “Clone Profile” operation (see below). 19 “Single site contest” refers to having only a single PC2 Server running; it is perfectly possible to use Profiles in a contest with teams at geographically separate locations, by having all teams connect to the same PC2 Server either using the Team Application Client or the web-based EWTeam component. PC2 v9.4 Administrator’s Guide 27 http://pc2.ecs.csus.edu/ Pressing the CLONE button on the Profiles screen displays the following dialog which allows creating a clone (copy) of the currently active profile. Notice that in the example below a currently active profile named “Practice” is being cloned to produce a new profile named “Real”; all the information which is the same between the “practice” and “real” contests (for example, Languages, Accounts, Judgements, etc.) is being copied over to the new (clone) profile, but the Contest Problems, Submitted Runs, and Submitted Clarification Requests from the Practice Contest are not being copied. This provides a simple mechanism for duplicating the configuration between practice and real contests without having to reenter all the configuration information. PC2 v9.4 Administrator’s Guide 28 http://pc2.ecs.csus.edu/ The SWITCH button on the Profiles screen is used to switch the system between profiles. To perform a switch, the new profile (the one to which the user wishes to switch) must first be selected by clicking on its row in the table of profiles. Pressing the SWITCH button then pops up a dialog as shown below, asking for the “master contest password” associated with the selected profile (the one being switched to). Entering the password and then pressing the SWITCH button on the dialog causes PC2 to switch its configuration to the configuration defined by the selected profile. The contest must be stopped for the Switch operation to be allowed. The RESET button on the Profiles screen is used to reset various configuration elements in the currently active profile. (Note that even if another profile is “selected” by clicking on its row in the table, RESET applies to the currently active profile; to reset a profile other than the active profile you must first use SWITCH to activate that other profile.) The contest must be stopped for the Reset operation to be allowed. Pressing RESET displays the following dialog: PC2 v9.4 Administrator’s Guide 29 http://pc2.ecs.csus.edu/ Pressing RESET on the dialog will remove all submitted runs and clarifications from the currently active configuration, as well as resetting the contest time. Checking the Remove Problem Definitions and/or the Remove Language Definitions checkboxes will cause the corresponding configuration data to also be removed when RESET is pressed. When a profile is “reset”, PC2 automatically makes a backup copy of the profile as it appeared before it was reset. This allows the user to recover from unintended actions caused by a Reset; it is always possible to switch back to a previous version of a profile by switching to its backup. Note however that backup profiles are not by default displayed in the table of profiles. Checking the Show Backups checkbox on the Profiles screen causes ALL profiles (including backups created by a Reset) to be displayed. Pressing the REPORT button will generate a PC2 Report of the known profiles (including backup profiles). See the Appendix on PC2 Reports for additional information. PC2 v9.4 Administrator’s Guide 30 http://pc2.ecs.csus.edu/ 6 Configuring the Contest in PC2 This chapter describes how to use the PC2 Admin to configure a contest. Configuring a contest involves at least the following: creating user accounts for teams and judges; defining contest languages; and defining contest problems. It can also include a variety of additional steps such as configuring judgement messages, balloon notification handling, site configuration (for a multi-site contest), and setting various options such as scoring properties, output size limits, and information visible to judges. Contest configuration can be done in two ways: interactively via various Administrator screens, or by loading configuration data from a file. The following sections describe the various interactive configuration steps. See the last section, Configuration via YAML Files, for information on loading configuration data from files. (Note however that at least the following section, Administrator Login, applies regardless of the chosen configuration method.) 6.1 Administrator Login Once PC2 is set up and running, it is necessary to “log in” to the system via a client login window in order to use the system. A PC2 “account” is required in order to log in. Initially only a single account exists; the account name (“login ID”) of this single account is “root”. This account is a master Administrative account which is used to configure the PC2 system initially for the contest. Regular users (especially Teams) should NOT be given access to this account. The default password for the root account is administrator1. Note that the default master password is given right here in this paragraph of this document, which is publicly available on the Web. Caveat Administrator : change the root password! Passwords can be changed via account management functions on the “Configure Contest Accounts” tab; see below. After logging in to the “root” Administrator account, the following screen will be displayed. This is referred to as the “main Administrator screen”. It provides a series of “tabs” PC2 v9.4 Administrator’s Guide 31 http://pc2.ecs.csus.edu/ across the top to select various contest administration functions. The tabs which are used to configure the contest prior to starting are described in the remainder of this chapter. Tabs used to start the contest and monitor its progress are covered in the following chapters. 6.2 User Accounts 6.2.1 Account Creation Before any logins other than root can occur, it is necessary to create user accounts. To create accounts for users, click the Generate button on the Accounts tab on the Configure Tab on the main Administrator screen. This will display the following screen: Note that the “(1)” to the right of the “Administrators” label means that currently one Administrator account exists – that one account is the root account – and no other accounts exist. It is necessary to create one Team account for each team at this site, one Judge account for each person (or automated judge) who will be judging the contest at this site, and at least one Scoreboard (“board”) account if the PC2 scoreboard is going to be used for tracking contest results. (It does not hurt to generate a few extra accounts in each category, for flexibility.) Enter the desired number in each box, then click the Generate button. Depending on the number of accounts, number of sites, and communication delays, it will take anywhere from a few seconds to several minutes for the account generation to complete. Once the accounts are generated the system will automatically return to the main Administrator screen. PC2 v9.4 Administrator’s Guide 32 http://pc2.ecs.csus.edu/ PC2 accounts always start with the word team, judge, admin, or board, followed by a number. See the next section for information on viewing/changing the state of generated accounts. Accounts in PC2 are site-specific. This means that in a multi-site contest an Administrator must create the accounts for each site. There are two steps for the Administrator to create accounts on a site. First, start a PC2 server at each of the sites. Second, an Administrator creates accounts by selecting the site then creating the accounts as described above.20 6.2.2 Account Names and Passwords Each generated account will be created with a password, but at present the default (only available) specification for passwords on newly-generated accounts is “Passwords same as Account Name”. This means for example that the password for the account “team1” is “team1”; the password for the account “judge1” is “judge1”; etc. Each account name and password is created with all letters in lowercase. Passwords for accounts can be changed from their default values by editing each account. To edit an account, click on the account in the display grid to select it (“team2” has been selected in the display shown above), and then click the “Edit” button. This will display a new “Edit Account” window, shown below: 20 Recall that, as mentioned earlier, it is actually not usually necessary to use “multi-site” mode – that is, to run more than one PC2 server. Assuming reasonable network communications are available, teams and judges at arbitrary physical locations can normally connect to a single PC2 Server running the entire contest. PC2 v9.4 Administrator’s Guide 33 http://pc2.ecs.csus.edu/ The “Display Name” for an account is the name which will appear on the PC2 Scoreboard; this can be set to any desired value (such as the name of the team’s school, or the team member’s names). The “Password” and “Verify Password” fields can be used to set any desired password for the account. The Permission “Shown on scoreboard displays” checkbox determines whether a team account will be considered in computing the scoreboard standings; if there are some team accounts which will not be used then you should uncheck their “Shown on scoreboard displays” checkboxes – otherwise they will appear on the scoreboard as teams which have solved no problems. Note that the “Shown on scoreboard displays” checkbox only determines whether a team appears on the scoreboard; teams which are not shown on the scoreboard can still log in, submit runs, and otherwise participate in the contest. This is designed to allow “guest” or other “non-competitive” teams to participate. (To prohibit any activity from a team account, change the account password or uncheck the “Login” Permission checkbox) PC2 v9.4 Administrator’s Guide 34 http://pc2.ecs.csus.edu/ The “Group” field is used to associate accounts with different “regions” or “groups”. This is used in conjunction with the PC2 scoreboard for displaying rankings of different subgroups (see the chapter on the PC2 Scoreboard for further details). Note that PC2 accounts are unrelated to any user accounts which may otherwise exist on the systems being used for the contest (for example, user accounts provided by the operating system). In a multi-site contest, newly created PC2 accounts are automatically distributed throughout the entire system, including across multiple remote sites. As previously noted, accounts are “site-specific”. Note also, however, that accounts at different sites are numbered using the same sequence; the first team account at Site 1 is called “team1”, and the first team account at Site 2 is also called “team1”, etc.. Accounts are therefore identified by always giving both the Site number and the Team number, as in “Site1Team1”, which is a different account from “Site2Team1”. 6.2.3 Loading Account Data Since editing account data (e.g. Display Names, Passwords, etc.) interactively for every account is cumbersome, it is desirable to be able to prepare the data “offline” ahead of time and then load it into PC2. This can be done by preparing an “account data” file and using the Load button on the Accounts tab load the data into the system. An “account data load file” consists of a series of text lines: a single line that defines the account data fields that will be loaded, followed by lines which contain information for each account. The format of the account data load file is as follows. File lines starting with ! or # in the first column are ignored. Each non-comment line has fields, separated by a (ASCII 9). The first line of the file must contain the names of the fields to be loaded, separated by tabs. Subsequent lines contain field data, one line per account. The site and account fields are required; other fields are optional. The fields may appear in any order (except that the field order on data lines must match the order specified in the first (header) line). The recognized field names are: site – site number account – team login name (ex. team1, judge4, scoreboard2) password – account password group – group name displayname – name to be displayed on scoreboard alias – an alias display name shown to judges to preserve team anonymity permdisplay – true or false, display on scoreboard permlogin – true or false, allowed to login PC2 v9.4 Administrator’s Guide 35 http://pc2.ecs.csus.edu/ For example, to initialize accounts “team1”, “team2”, and “team3” so that the “team1” account displays on the scoreboard with the name “Number 1” and has a password of “pass1”, while the “team2” account displays on the scoreboard with the name “Team Number 2” and has a password of “myPass”, and the “team3” account is made inactive (does not display on the scoreboard), the following entries would be placed in the load accounts data file for teams: site account displayname password permdisplay 1 team1 Number 1 pass1 true 1 team2 Team Number 2 myPass true 1 team3 My School Name false Note: for clarity in the example above the tab character is represented as ; it should appear as a single tab character (ASCII 9) in the actual file. Imported values overwrite any values that were in the system previously. Also, it is not necessary to provide a record in the data file for every account; the site and account fields determine which accounts will be modified (any unlisted accounts will remain unchanged). To load the account load file use the Load button on the Accounts Tab (under the Configure tab). The load button will display a File Open dialog; select the name of the account load file and click Ok. At this point the Review Account Loading dialog will appear, as shown below: Any changes/differences that will be applied will have an asterisk at the end. Click on Accept to apply the changes. By default only accounts that have changes are shown, check the “Include unchanged accounts” checkbox to see all accounts that were loaded. PC2 v9.4 Administrator’s Guide 36 http://pc2.ecs.csus.edu/ 6.2.4 Importing ICPC Data PC2 was designed for supporting the ACM International Collegiate Programming Contest, including its local and Regional contests worldwide. The ICPC maintains an online Contest Registration system which is used by Regional Contest Directors (RCDs) around the world to manage participation in the various ICPC Regional Contests.21 PC2 provides interfaces to import contest registration data from the ICPC Registration system, and also to export contest results back to the ICPC web site. See the Appendix on ICPC Import/Export Interfaces for further information on importing/exporting ICPC Registration system contest data. 6.3 Contest Problems 6.3.1 Defining a Problem PC2 must be provided with information about the problem set to be used in the contest. To enter this information, click on the Problems tab at the top of the main Administrator Configure Contest screen. This will produce a display similar to the following: 21 Visit the ICPC web site at http://icpc.baylor.edu/icpc/ for further details. PC2 v9.4 Administrator’s Guide 37 http://pc2.ecs.csus.edu/ Note that initially no problems are listed since none have been added to the system. To add a problem, click the Add button. This will produce the “Add New Problem” dialog shown below. To define a contest problem to the system, perform the following steps using the Add New Problem dialog: 1) Enter the problem name in the top textbox. 2) Enter the value (in seconds) that the system should enforce as the problem run time limit. 3) Enter a “short name” for the problem (this is the unique string by which the problem is known internally in the system). 4) If the problem requires an input data set, click the “Problem Requires Input Data” checkbox and then a. select either “Stdin” or “File”, depending on whether the problem description tells teams to write their programs to obtain input data from “standard input” or from a file22, then 22 Note that teams can be instructed to write programs which read from “stdin” even though the administrator provides the input data in a file; PC2 arranges that the content of the specified file is available in the current directory at PC2 v9.4 Administrator’s Guide 38 http://pc2.ecs.csus.edu/ b. if the problem is to be tested using only a single data file, use the Browse button to select the data file (see below for how to define a problem which is to be tested using multiple judge’s input data files). 5) If the Judges have provided a single “Answer File” (a file showing the expected output of a program correctly solving this problem), click the “Judges Have Provided an Answer File” button and then use the Browse button to select the Answer File. (See below for how to define a problem with multiple Judge’s Answer Files.) 6) Select the desired “Display Options” to be applied when the problem is executed and displayed on the Judge client: o Show the output window – shows the PC2 output window upon completion of execution/validations o Show Compare – shows the PC2 compare window upon completion of validation o Hide Problem – do not show this problem to the teams (also suppresses showing this problem on the Scoreboard HTML/output) 7) Click the Add button to save the problem description. As each contest problem is entered, it will be displayed on the main Administrator screen (when the Problems tab has been selected). To change some previously entered information for a problem, click on the problem row in the main display to select it, then click the Edit button. This will return to the Edit Problem dialog, where changes can be made. The following additional notes apply when defining a contest problem: The Run Timeout Limit value (shown as 30 in the sample screen above but settable to any positive integer number of seconds when the problem is defined) is enforced by PC2. A count-up timer is displayed during program execution so that the Judge can tell how long the program has been executing; when the specified timeout limit is reached the program will be terminated and the Validator judgment will show “No - Time Limit Exceeded”. The timer also includes a button to allow the Judge to terminate the program at any time. The content of the input data file for a problem is stored internally when the Add button is pressed (that is, PC2 makes an internal copy of the file). For this reason, editing the user’s copy of the file will not automatically change the data presented to team programs. To modify the data file for a problem, the contest administrator must EDIT THE PROBLEM and press the Update button. Upon pressing the Update button, a prompt will appear confirming that the file has changed on disk. Answer Yes to the prompt to re-load the data file. All team program output is expected to go to “standard output” (where it is captured by PC2 and saved for display to the Judges). More specifically, there is no mechanism in the runtime (for the case of reading from a file), or that the content of the file is presented to the program’s standard input channel (if that input selection is specified). PC2 v9.4 Administrator’s Guide 39 http://pc2.ecs.csus.edu/ current version of PC2 for dealing with programs which are written to send their output to a destination other than “stdout” (for example, programs which send their output to a file).23 Contest problems in PC2 are global, in the sense that once a problem definition is entered by the Contest Administrator that problem definition is broadcast to all sites. There is no mechanism for having teams at different sites in a multi-site contest see different descriptions of the same problem. If there is some reason that different descriptions are needed for the same problem (for example, if a problem needs to be described differently at different sites due to OS differences), it is necessary to enter the different problem descriptions effectively as different problems. (While this is not very elegant, it is also something that we rarely – virtually never – see in real contests…) Said another way, PC2 views a contest as a set of teams all working on an identical problem set. Note also that contest problems appear in the same order at each site in a multi-site contest. Care must be taken when configuring contest problems in one machine environment (say, Windows) and then moving the configured system to a different environment (say, Linux). In particular, problem files (judge’s data files and judge’s answer files) should not be configured this way. PC2 records the path to configured files; the path will most certainly be different when the configuration is moved to a different platform. 23 There is in principle no reason a contest administrator could not use the PC2 “Validator” capability to effectively examine and process output sent to a file by a team’s program – including displaying that output for the Judges. While this is not the primary intent of the Validator capability, it could be used as an effective workaround for this limitation. See the Appendix on Validators for details. PC2 v9.4 Administrator’s Guide 40 http://pc2.ecs.csus.edu/ 6.3.2 Multiple Test Data Files The previous section described how to configure a Contest Problem which is to be tested using a single data set (or “test case”). PC2 also supports the ability to automatically execute a single team submission against multiple different data files. In order to use this capability, the input data files and corresponding answer files24 must be loaded using the Add Problem or Edit Problem screen’s Data Files tab, shown below (shown with a set of input data and answer files already loaded): The “storage option” radio buttons on the Data Files tab are used to control the way in which PC2 handles storage for data files. By default, data files are automatically loaded into PC2 system memory (this is what “Copy Data Files into PC2” means). Subsequently, whenever a human judge or PC2 “Auto-Judge” (see below) is used to judge a problem, the data files are automatically shipped to the judge along with the submission. This works fine for most contest problems; however, extremely large data files (e.g. larger than around 5MB) can cause system memory overflow and/or cause heavy network traffic loads. To help mitigate these problems, data files can be marked as being stored external to the PC system (“Keep Data Files External”). In this configuration, PC2 records necessary information about the data files (e.g. the file names), but does not actually load the data into the system and does not transmit the data to judges. This eliminates the memory and network traffic issues. However, it requires the contest administrator to insure that all the data files for the problem are copied onto all Judge’s machines. 2 24 When using multiple test data files, each data file must have a corresponding “answer file”. PC2 v9.4 Administrator’s Guide 41 http://pc2.ecs.csus.edu/ Note that the storage option for a problem must be set prior to loading the data files for the problem, and cannot be changed once a problem is created and saved in the system. When using external data files it is also necessary to configure PC2 to be aware of where the data files are located when they are stored on the judging machines (by the contest administrator, external to PC2).25 Specifying the external data file location is done using the “Set Judge’s Data Path” button on the main Administrator screen’s Problems tab (see the earlier screen), which pops up a dialog for setting the path as shown below. The Judge’s Data Path must be set whenever a contest problem is configured to use external data files (the system will not allow to save a contest problem configured to use external data files without setting the Judge’s Data Path). Further, when a PC2 Judge is started it will automatically check to verify the required data files are present in the specified location on the Judge’s machine and will refuse to perform judging if the files are not found in the specified location. Once the data storage option for the problem data files is selected, press the Load button on the Data Files tab to load the set of test input data and answer files into the system. This will pop up a window that allows you to navigate to the place where the data and answer files are stored. Using the navigator, select the folder which contains the set of input data and answer files. The result of loading a set of input data and corresponding answer files is show in the display above. PC2 follows the CLICS CCS standard which requires that input data files have names ending with the extension “.in” and that answer files have names ending with the extension “.ans”. Selecting a folder causes the system to load all data files and answer files matching those names from the selected folder into the system. If no such files are found, or if there is a mismatch between the number of data and answer files, the system displays an error message. Loading a set of input data and answer files means that when a problem is judged, it will be executed once for each input/answer file pair, and the results of each of these executions will be displayed for the judge (see the separate PC2 Judge’s Guide for details on the display of execution results to the judge). During judging, PC2 executes multiple test cases by processing the input data files in lexicographic order of file names. This means for example that a set of three input data files 25 Setting the Judge’s Data Path is necessary because the data files might be stored under a different path on the Judge’s machines from where they are located on the Administrator’s machine – which is allowable (as long as the files are located in the same path on all the Judge’s machines). PC2 v9.4 Administrator’s Guide 42 http://pc2.ecs.csus.edu/ with the name “test1.in”, “test2.in”, and “test10.in” would be executed in the order “test1.in”, then “test10.in”, then “test2.in”. To avoid confusion in naming of input test data files, be sure to specify the names in the desired lexicographic order. (For example, put leading zeroes (e.g. “001”, “002”, “010”) in all numeric file name elements to keep “1” and “2” from being separated by “10”.) 6.3.3 Defining Judging Type By default each contest problem is manually judged, meaning that a person selects a judgment for each submitted run. The system can also automatically judge runs, and when doing so can also include an optional second step where a human judge manually reviews and judges the run. Configuring the system to automatically judge a problem requires several steps: (1) a validator must be defined for that problem26; (2) the Judging Type for the problem must be set as Computer Judging; and (3) at least one judge module must be configured to automatically judge the problem (that is to say, there must be at least one PC2 “AutoJudge” running; see below). Note that these steps must be performed for each problem that is to be computer judged, although the same judge module can be used to do automated judging for more than one problem (see the following section for information on configuring judge modules for automated judging). Specifying that a problem is to be computer judged is done via the Judging Type tab on the Add New Problem dialog, shown below. 26 A validator is a program that examines the output of a team’s program and determines whether it is a correct solution to the problem. The Validator tab on the Add Problem or Edit Problem dialog is used to specify the validator program to be used for the problem. See the Appendix on Validators for further details. PC2 v9.4 Administrator’s Guide 43 http://pc2.ecs.csus.edu/ To specify computer judging (also called “automated judging”), perform the following steps: 1) Select Computer Judging. 2) Optionally select Manual Review if the problem is also to be judged (reviewed) by a human judge after the automated judging process is completed. 3) Optionally select Send Preliminary Notification to team.27 The effect of selecting this option is that a notification of the preliminary “automated judging” result will be sent to the team. These preliminary notifications are clearly marked “Preliminary”, and the judgment value they assign can subsequently be overridden by the human judge during Manual Review (see the separate PC2 Judge’s Guide for more information on overriding preliminary judgments). If the Judging Type for a problem is Computer Judging but a validator is not defined for that problem, the system will not allow the problem definition to be saved; instead a message “Computer Judging selected, must select a validator” will be displayed when an attempt to save the problem is made. Once a validator is defined then the problem definition can be saved. Again, refer to the appendices for information on defining validators for problems. 27 If Send Preliminary Notification to the team is not selected when Computer Judging and Manual Review are selected, the automated computer judgment will not be shown to the team. PC2 v9.4 Administrator’s Guide 44 http://pc2.ecs.csus.edu/ 6.3.4 Assigning Auto Judging to Judge modules In order to accomplish computer (automated) judging, each problem which is to be autojudged must have at least one PC2 judge module configured to be aware that the problem should be automatically judged. This can be accomplished in a variety of ways: a single judge module can be told to handle all auto-judge problems, or a separate judge module can be configured for each different problem, or the set of problems to be auto-judged can be distributed in some partitioned fashion across a set of PC2 judge modules. The requirement is simply that, for each problem designated as requiring “Computer Judging” (as described above), there must be at least one PC2 judge module made aware that that particular problem requires automated judging. Configuring judge modules for auto-judging is accomplished by specifying, for each “judge login account”, which problems (if any) that account should perform auto-judging on. (For this reason, auto-judging assignments cannot be made until after Judge login accounts have been created.) To configure judge modules for auto-judging, use the Auto Judge tab on the Configure Contest tab on the Administrator main screen, shown below. PC2 v9.4 Administrator’s Guide 45 http://pc2.ecs.csus.edu/ To specify that a particular judge account is to auto-judge one or more problems, select the row identifying the judge account and click Edit. This will pop up the Auto Judge Settings dialog, shown below. The dialog will show (only) problems that can be automatically judged (that is, problems which have a validator defined and have been specified as requiring Computer Judging). Select the problems that this judge module is to auto-judge by clicking on the corresponding problem row checkbox, then click Enable Auto Judging followed by Update. In the example shown below Judge 4 at Site 1 will automatically judge the problems named “Bowling for Crabs” and “Sumit”, but will not judge the problem “The Roof is on Fire!”. Upon clicking Update the Auto Judge tab will change to show that auto-judging is ON for the specified problems for Judge 4 at Site 1, as shown below. From this point on, any time Judge 4 at Site 1 is logged in it will automatically fetch and judge runs for either of the two specified PC2 v9.4 Administrator’s Guide 46 http://pc2.ecs.csus.edu/ problems (but will not judge any other problems). Runs will be automatically selected in chronological order and judged. To monitor the status of runs use the Runs tab under the Run Contest tab. Any number of judge modules can be set up in this way, judging any combination of contest problems (provided that the problems have been configured with a validator and specified as “Computer Judging” problems). Note that some consideration should be given to the assignment of problems to judge modules. For example, if one contest problem is known (or expected) to be likely to incur long run-times, it might be desirable to insure that more than one judge module is configured to auto-judge that problem. Likewise, it might be desirable to avoid assigning other problems to such a judge, since those problems will necessarily be delayed in their judging until the long run-time of the previously-judged problem has expired. Note also that a judge module which is configured for auto-judging should not also be used for human judging (review); separate accounts should be used for human logins. When a judge account is logged in then computer judging will start automatically on any problems for which that account has been configured for auto-judging; no additional steps are necessary to begin auto-judging. To stop a judge module from auto-judging, Edit the Auto Judge (Settings) and uncheck the Enable Auto Judging Tab. PC2 v9.4 Administrator’s Guide 47 http://pc2.ecs.csus.edu/ 6.4 Contest Languages 6.4.1 Defining a Language PC2 must be provided with information about the programming languages used by contestants (teams). To enter this information, click the Languages tab on main Administrator screen. This will bring up a display similar to the following: Note that the display is empty because no languages have been defined yet. To add a language description, click the Add button. This will bring up an Add New Language dialog, similar to the one shown below, containing fields used to describe the language to PC2. PC2 contains built-in descriptions for a number of commonly-used language compilers. These built-in descriptions can be selected using the “Auto Populate” drop-down list. In the example Add New Language dialog shown below, the Auto Populate function has been used to select the language configuration for Java. Note: the example also shows the use of something called “command parameter substitutions” – strings such as “{:mainfile}” containing curly braces. See the section on Command Parameter Substitution for an explanation of these strings. PC2 v9.4 Administrator’s Guide 48 http://pc2.ecs.csus.edu/ The Add New Language fields have the following meanings: The “Display Name” for a language is the name which Teams will see when they are asked to specify the language in which they have written a program which they are submitting. The Display Name can be any arbitrary text; it does not have to be a real language name (for example, “Local C Compiler” could be a legitimate language Display Name). The “Compile Cmd Line” field is used to specify the command line which is used to compile source code and produce an “executable program file” in the language. The “Executable Filename” field is used to tell PC2 the name (or more correctly, the form of the name) of the output (executable program) file produced by the compilation process. PC2 clears its internal execution directory of any instance of the specified executable file prior to compilation, and checks for the existence of the specified executable file following compilation. It interprets the existence of a new executable file as evidence of successful compilation. The “Program Execution Command Line” field is used to specify the (form of the) command line required to execute (run) the resulting program. Execution is only performed if the preceding steps were successful in producing a new executable file. The “Judge Execution Command Line” field is used to specify the (form of the) command line required to execute (run) the resulting program on Judge machines. It is only necessary to specify a value in this field if the form of the execution command is different on Judge machines than it is on Team machines. (This might be the case, for example, if the Judge machine is intended to run the program inside a “sandbox”; on a team machine the program would be directly executed but on a Judge machine the program PC2 v9.4 Administrator’s Guide 49 http://pc2.ecs.csus.edu/ executable would be passed to the sandbox for execution under controlled conditions.) The Judge Execution Command Line field is ignored unless the adjacent Judge Execution Command Line checkbox is checked. If not, the Program Execution Command Line (above) is used to run the program. In any case, as with the Program Execution Command Line, execution using the Judge Execution Command Line is only performed if the preceding steps were successful in producing a new executable file. The “Script or Interpreted Language” checkbox should be selected (checked) if the language does not require compilation prior to execution (for example, Python, PERL, and Ruby are languages that do not compile first; the language source code is fed directly into an interpreter). Checking this checkbox tells PC2 it should skip over any “compilation” step and go straight to the “execution” phase. The Contest Administrator must define each language to be used in the contest by filling in the language definition fields (or populating them using the Auto Populate function). As previously noted, the example screen above shows values called “command parameter substitutions” in the language definition fields; see the following sections for further details on the definition fields. Once the definitions for a language have been entered, click the Add button to store the information and return to the main Administrator screen. The language names will be displayed under the Languages tab on the main Administrator screen, as shown below. To add more languages, click the Add button again to return to the Add New Language screen. To modify a previously-entered language, click on the row containing the language description to select it and then click the Edit button. See the Appendix on Language Definitions for further details. PC2 v9.4 Administrator’s Guide 50 http://pc2.ecs.csus.edu/ Note that care must be taken when configuring languages using the “Auto Populate” function. In particular, this function uses and records the current (platform-specific) path separators (e.g. “\” under Windows vs. “/” under Linux). If a language is configured this way and then the configuration is moved to a machine of a different type, the strings which are used to invoke a compiler will be incorrect (they will contain the wrong path separators). 6.4.2 Command Parameter Substitutions The four language description fields in the Edit Language dialog can be “hard-coded” by entering fixed values if desired. For example, the Display Name for a language is normally fixed for the duration of a contest (e.g., “Java”, or “C++”, or “Pascal”). However, entering fixed values for the Compile Command, Executable Filename, and Program Execution Command fields can be extremely cumbersome and inflexible – the details of these fields may need to change with each different program file submission, for example. In order to provide more flexibility, PC2 supports the use of “parameter substitutions” in these fields. PC2 parameter substitution fields are indicated by matching curly braces, with the first character inside the left curly brace being a colon (‘:’). Following the colon character is exactly one of a set of predefined PC2 parameter substitution keywords. Any number of command parameter substitution fields may appear anywhere in a language description field. The currently defined parameter substitution keywords and their corresponding meanings are given below. Keyword Meaning mainfile Replace with the full name of the submitted file, including any extension (but excluding any ‘path’ specifier on the front of the filename) basename Replace with the base component of the file name, omitting any extension (and excluding any ‘path’ specifier on the front of the filename) The following section shows examples of language definitions, including the use of command parameter substitution fields. For a complete list of keyword substitution variables support by PC2, see the PC2 Wiki at http://pc2.ecs.csus.edu/wiki/Variable_Substitutions. 6.4.3 Language Definition Examples The language screen example shown above shows a set of filled-in fields defining a language named “GNU C++” and using the GNU g++ compiler. PC2 v9.4 Administrator’s Guide 51 http://pc2.ecs.csus.edu/ The compile command line invokes the compiler (“g++”) and passes it an argument specifying use of the math library (“-lm”). The compile command line also specifies the assignment of a specific name to the “object” (compiled output) file (the “-o” argument, followed by the name to be assigned to the object output file). In this case, the object output file is to have the same name as the base name of the input source code file, with the characters “.exe” appended. (So for example if a team submitted a file named “proga.cpp”, the object output file would be named “proga.exe”, since that is the value to which the “{:basename}.exe” string would be expanded when parameter substitution is applied.) The final argument on the compile command line gives the name of the source file to be compiled, which would be expanded from “{:mainfile}” to become “proga.cpp” if that was the name of the submitted main program source file. The Executable Filename field indicates that the executable file which is produced by the compile command has the same name as the base name of the submitted program, with “.exe” appended; this is because the compile command specifies (via the “-o” argument) that this is the executable file name which should be produced. The Program Execution command field specifies that the command used to execute the compiled program on a Team machine is simply the same as the name of the executable file produced by the compilation step (and specified in the Executable Filename field), which in this case is again the base name of the original source code file, with “.exe” appended. The Judges Execution command field specifies that the command used to execute the compiled program on a Judge machine is the command “sandbox”, which is passed a single argument: the name of the executable file produced by the compilation step (and specified in the Executable Filename field), which in this case is again the base name of the original source code file, with “.exe” appended. If a team were to submit to the judges a C++ program in a file named proga.cpp using the above language, PC2 would first execute: g++ –lm –o proga.exe proga.cpp to compile the program (substituting proga for the {:basename} parameter and proga.cpp for the {:mainfile} parameter). It would then check for the existence of an executable file named proga.exe, and if that file exists then PC2 would request the underlying operating system to execute the command: sandbox proga.exe Note: in a Unix-like environment, the “.exe” appended to the output (executable) file name in the above example is not strictly necessary. However, in a Windows environment, executable files must in most cases have the extension “.exe”. Explicitly adding the “.exe” to the language definition allows the same language definition to work in both environments. The following screen shows a second language definition example: a definition for a language with the display name “Java”: PC2 v9.4 Administrator’s Guide 52 http://pc2.ecs.csus.edu/ If a team were to submit to the judges a Java program in a file named sumit.java using this language definition, PC2 would execute the following command to compile the program: javac sumit.java PC2 would then check for the existence of an executable file named sumit.class and if that file exists then PC2 would execute the following command to run the program: java sumit Note that the form of the language definition fields differs somewhat between the first example (C++) and the second example (Java). This is because of the different ways in which these two languages define the compilation and execution process. Notice also, however, that while the language paradigms are different, the use of command parameter substitutions allows the Contest Administrator easily to provide descriptions of how to handle the differences. The appendices contain further samples of language definitions for specific compilers. 6.4.4 Language Definitions In Multi-Site Contests Language definitions in PC2 are global. This means that, just as with Contest Problem definitions, when a language definition is entered at one site in a multi-site contest, that language definition will be visible at all connected contest sites. However, unlike the situation with Contest Problems (where the problem definitions are usually identical across sites), language definitions may differ between sites – even for the “same language”. For example, it may be the case that every site allows the use of the “C” language. However, it may also be true that the specific command sequence to invoke the C compiler may PC2 v9.4 Administrator’s Guide 53 http://pc2.ecs.csus.edu/ differ between sites: a different C compiler might be used at different sites, or even if the same compiler is used it may be necessary to allow for differences in the “path” needed to access the compiler or for other environmental differences. One way to deal with differences in language details between sites is to create a different PC language description for each different language/site combination. This can quickly become cumbersome, however; for example, if there are four languages (e.g. C, Java, Pascal, and Perl) and five sites using those languages, it could require entry of up to 20 different language descriptions (Site1C, Site2C… Site1Java, Site2Java,… etc.). This can become particularly unwieldy for Teams, who must search through a list of 20 different languages looking for not just the correct language but the correct language for their site. 2 To avoid this combinatorial explosion of language definitions, a simple technique can be used when defining languages in a multi-site contest: use of generic language scripts, tailored at each site for the site-specific configuration. For example, consider a contest using, say, C, Java, and Pascal. The Contest Administrator should define those three languages in PC2 using the actual language names (“C”, “Java”, and “Pascal”) as the PC2 “language Display Names”. However, rather than defining a specific compilation command for each language (which may differ between sites), each language should have as its compilation command a command which invokes a language-specific (but siteindependent) script (or “batch file”) designed to compile a program in that language. In other words, for the above three languages, PC2 language definitions would be created to define the “compilation command” for the language named “C” to be the invocation of a script (batch file) named “compileC” (or “compileC.bat”); the compilation command for Java would be the invocation of a script named “compileJava”; and the compilation command for Pascal would be the invocation of a script named “compilePascal”. Then, at each site, the Site Director is responsible for placing on machines at that site a set of scripts or batch files of the corresponding names (e.g. compileC, compileJava, and compilePascal). Within each script at each site is a set of site-specific commands which perform the necessary steps (compile a C program, compile a Java program, or compile a Pascal program) in the appropriate site-specific manner. Note that if necessary, the same technique of “generic scripts” which vary between sites can also be used in specifying the details of “Program Execution Command Line” for languages. That is, the Contest Administrator can specify “executeC”, “executeJava”, and “executePacal” scripts for the program execution language definitions in PC2 and then arrange for appropriately different script contents at each site. Note also that PC2 “command parameter substitutions” may be used in compilation and execution command lines independently of whether the command is invoking a script or not; in this way the Contest Administrator can arrange to pass necessary data (such as the main program file name and/or the base name) to a script. Using generic script names in PC2 language definitions and providing site-specific implementations of each language script at each site allows the Contest Administrator to significantly reduce the number of language definitions which teams must deal with, while at the PC2 v9.4 Administrator’s Guide 54 http://pc2.ecs.csus.edu/ same time retaining the flexibility necessary for dealing with site differences in a multi-site contest. 6.5 Contest Judgments 6.5.1 Defining a New Judgment PC2 uses the term “judgments” to refer to the possible responses which a judge (human or automated) can apply to a run submitted by a team. The Judgments Tab under the Configure Contest tab on the Administrator main screen shows all the judgments available. The set of judgment messages can be viewed, added, edited and deleted. The following screen shows the set of judgments which are defined by default. To add a judgment click the Add button. This will bring up an Add New Judgement dialog, similar to the one shown below. PC2 v9.4 Administrator’s Guide 55 http://pc2.ecs.csus.edu/ The “Judgement” field defines the name which Judges will see when they are asked to judge a run. This name is also seen by the Teams when they receive that judgment. The “Acronym” field defines the abbreviation used in the event feed and some reports. The “Hide Judgment” checkbox will remove (hide) this judgment from the list of judgments that the Judges can use. 6.5.2 Changing Existing Judgments As shown above, the set of default judgments in PC2 is given by the following list: Yes No No No No No No No - Compilation Error Run-time Error Time-limit Exceeded Wrong Answer Excessive Output Output Format Error Other - Contact Staff The contest administrator can use the Edit button on the Judgments tab to change the text of existing judgments. Selecting a judgment message from the list and then clicking the Edit button will bring up an Edit Judgment dialog, similar to the Add New Judgment dialog, allowing changes to be made to the judgment text. However, one guideline must be followed: PC2 assumes that the first judgment in the list is always the “Yes” judgment – that is, the first judgment is the one which the system returns for problems judged to be correct. The text of the default first judgment message can be changed if desired (for example, the contest administrator may prefer the message “Accepted” instead of “Yes”), but regardless of the actual text in the first judgment field it is that text which will be returned for correct runs. Therefore it would be a bad idea to change the text of the first judgment message to some form of “No” or “Incorrect Run” message. PC2 v9.4 Administrator’s Guide 56 http://pc2.ecs.csus.edu/ 6.6 Balloon Notifications In many contests (including the ICPC World Finals), balloons are used to indicate to contestants and spectators alike the general state of the contest. Each time a team solves a problem, a balloon of a specific color is sent to the team and attached on or near their machine. As the contest progresses, the contest floor gradually fills up with a multi-colored display showing how various teams are doing in the contest. (This is a colorful and normally well-received operation; if you have never tried it, we recommend doing so.) Using balloon notifications in a contest does present some additional management overhead (keeping track of which team should get what color balloon, etc.). Since PC2 was designed to support the ICPC World Finals (as well as its Regional and Local contests), it contains some built-in support for “balloon operations”. 28 In particular, the system supports the creation of a separate “Balloon Notification configuration” for each site in the contest. Selecting the Notifications tab on the main Administrator screen will produce a display similar to the one below listing the currently-defined Balloon Notification configurations. The sample screen below shows one Balloon Notification configuration already created (for Site 1); by default there are no such configurations and screen will be empty. Clicking the Add button will cause an Add Notification Settings dialog similar to the one shown in the next section to appear; that dialog is used to configure the handling of balloons for a given site. Selecting an existing row in the table and then clicking the Edit button will allow editing of the selected configuration. Selecting an existing row and then clicking the Copy button will create a copy of the selected settings and allow selection of a different site which should use those same settings (in a multi-site contest using the same settings this avoids having to reenter the settings). 28 Note that while PC2 has its own Balloon handling mechanism, it is also compatible with the “ICPC Balloon Utility” – the tool used at the ICPC World Finals as well as in a variety of Local and Regional contests around the world. The ICPC Balloon Utility is somewhat less complicated and more robust; we actually use that rather than the built-in PC2 Balloon Notification system in most of our own contests. More information can be found at https://icpc.baylor.edu/icpctools. PC2 v9.4 Administrator’s Guide 57 http://pc2.ecs.csus.edu/ 6.6.1 Defining Balloon Notifications Balloon Notification options include ability to specify the color of balloon associated with each problem; sending messages to a printer each time a balloon should be delivered to a team; and sending an email message via a specified email (SMTP) server to an arbitrary email account each time a balloon should be delivered to a team. Printed and emailed messages contain the relevant details such as Team, problem, and balloon color. Each of these options is specified on a per-site basis (so that, for example, sites can use different color balloons for a given problem). To enable the use of email balloon notifications for the specified site, check the “Send Email Notifications” box, then enter in the appropriate text boxes the full name of an SMTP email server accessible to the PC2 Scoreboard machine along with a valid email address (EMail contact). To enable the use of printed balloon notifications for the specified site, check the “Print Notifications” box, then enter in the Print Device textbox the device identifier of a printer accessible to the PC2 Scoreboard machine. Generation of balloon notifications is handled by the PC2 Scoreboard machine.29 Once email and/or printing notification is enabled, every “YES” judgment detected by the PC2 Scoreboard account selected in the “Balloon Client” drop-down list will cause an email notification and/or a printed notification to be sent to the configured location. 29 More specifically, it is handled by a PC2 Scoreboard machine logged in under the PC2 account selected as the “Balloon Client” on the Add Notifications Settings screen, as shown above. PC2 v9.4 Administrator’s Guide 58 http://pc2.ecs.csus.edu/ 6.6.2 Email Server Advanced Settings If there are non-standard SMTP or additional SMTP settings required the EMail Server Advanced Settings button can be used to specify the settings. This button pops up the following dialog: The “Value” fields in this dialog are used to configure PC2 properties related to advanced SMTP operations, including SMTP Authentication. (SMTP Authentication may require some additional external setup to support smtps (SSL)). If there are questions about how to use Advanced SMTP properties, including SMTP Authentication, please send email to the PC2 team (pc2@ecs.csus.edu). PC2 v9.4 Administrator’s Guide 59 http://pc2.ecs.csus.edu/ 6.7 Options (Settings tab) The Settings tab on the main Administrator Configure Contest tab displays a screen which allows selection of additional options which can be used to display and/or control various aspects of a contest. The meanings of the various configuration fields on the Settings tab are given below. Contest Title - Specifies the contest title which is to be displayed on the scoreboard. Team Information Displayed to Judges - Specifies whether or not to reveal the identity of Teams to the (human) Judges while a run is being judged. For example, assume that team 5 has a display name of “CSUS Hornets” and an alias30 of “Team Orange”. Then choosing the various display options will have the following effect on the information shown to the judges: 30 None – show “***” for team name Show Numbers only – show team# for team name; for example, “team5” Show Names only – show display name only; for example “CSUS Hornets” Show Number and Name – for example “5 CSUS Hornets” Show Alias– show an alias for the team name; for example, “Team Orange” To load/specify team aliases see the section Loading Account Data PC2 v9.4 Administrator’s Guide 60 http://pc2.ecs.csus.edu/ Maximum Output Size - Specifies the maximum amount of output, in Kbytes, which a team program is allowed produce to stdout or stderr. Any output beyond this amount is discarded by the system and a message is added to the end of the output. The default value is 512 K (1/2 MB). Judges’ Default Answer – specified the clarification answer sent to teams if a judge selects the Default Answer button while answering a clarification. Edit Scoring Properties – this button pops up a dialog which is used to specify the scoring point penalties. See the section Configuring Scoring Properties in the chapter on the PC2 Scoreboard for additional details. 6.8 Sites This tab on the Administrator main screen displays a list of all the sites in the contest; this list should be checked to verify that PC2 knows about all sites. If the site is currently active (connected to the rest of the contest) the IP address for that site’s server is displayed. Note that the Sites tab is on the Run Contest tab of the Administrator main screen, not the Configure Contest tab. PC2 v9.4 Administrator’s Guide 61 http://pc2.ecs.csus.edu/ 6.9 Configuration via YAML Files PC2 supports configuring a contest by loading a set of configuration files (as opposed to using the interactive configuration steps outlined above). The ability to load configuration information via files follows the CLICS Contest Control System specification published by the ACM International Collegiate Programming Contest (ICPC), which can be found at https://clics.ecs.baylor.edu/index.php/Contest_Control_System. Configuration files are written in YAML (Yet Another Markup Language31) and can be loaded in two different ways: by specifying the “--load” option on the server startup command line (see the Appendix on PC2 Server Command Line Arguments), or by using interactive controls on the Import CCS tab of the Admin Configure Contest screen. When using the “--load” option on the server startup command line, “--load” must be followed by either a directory (folder) name, or a file name. If a file name is specified, PC2 reads that file (expecting it to contain a YAML configuration description) and loads the specified configuration into the system.32 If a directory name is specified after the “--load” command line option, PC2 expects that directory to hold a Contest Data Package (CDP) in the format described by the CLICS CDP specification33; it reads the contest configuration out of the specified CDP. The specified directory name may be either the path to the root of the CDP, or the path to the /config folder beneath the CDP root. Loading a configuration file interactively (as opposed to using “--load”) is done by pressing the Import Contest.yaml button on the Import CCS tab of the Admin Configure Contest screen. Pressing Import Contest.yaml displays a “file navigation” dialog allowing the user to select the YAML file containing the contest configuration, and then loads the configuration described in the YAML file (including recursively loading any problem.yaml files listed in the problemset section of the corresponding contest.yaml file). The current contest configuration can be exported (saved) to YAML files using the Export Contest YAML Files option on the Reports tab of the Admin Configure Contest screen. Note that it is the current contest configuration which gets written to YAML files when Export Contest YAML Files is invoked; any changes that have been made since loading a YAML configuration will be reflected in the output YAML report (file). 31 Or, “YAML Ain’t Markup Language”, depending on your source and timeframe… The format of YAML configuration files is described on the PC2 Wiki at http://pc2.ecs.csus.edu/wiki/Contest.yaml; additional information can also be found at https://clics.ecs.baylor.edu/index.php/Contest_Control_System#Appendix:_File_formats. 33 The CLICS CDP specification can be found at https://clics.ecs.baylor.edu/index.php/CDP, and is also discussed on the PC2 Wiki at https://pc2.ecs.csus.edu/wiki/Contest_Data_Package. 32 PC2 v9.4 Administrator’s Guide 62 http://pc2.ecs.csus.edu/ PC2 also supports additional configuration capabilities beyond those required by the CLICS specification (the CLICS specification lists minimum requirements but does not prohibit compatible extensions). For example, PC2 supports the ability to import a list of passwords which can then be used by the internal account generation process of the system; this is done via the Import Passwords button on the Import CCS tab. The format of the password file is described at http://pc2.ecs.csus.edu/wiki/Passwords.txt. Clicking Import Passwords prompts for the name of a password file, then reads the file and assigns the specified passwords to team accounts in the listed order (the first password is assigned to Team1; the second to Team2; etc.). Imported passwords must appear one per line in the file. If there are more passwords in the file than the number of team accounts, new accounts are automatically created and assigned the additional passwords. Only TEAM passwords can be assigned this way; passwords for Judge and other account types must be set using the interactive methods described above. Also, loading a password file only assigns passwords to team accounts at the current site; in a multi-site contest a separate Import Passwords operation must be done at each site. A number of additional enhancements to the CLICS specification are supported by PC2; these are described at http://pc2.ecs.csus.edu/wiki/CCS_Enhancements. Note that certain YAML import operations are not currently implemented: YAML import specifications for Default Clarification and Clarification Categories will be ignored in the current system (we’re working on it…) PC2 v9.4 Administrator’s Guide 63 http://pc2.ecs.csus.edu/ 7 Starting the Contest 7.1 Clock Control Once the contest has been has been fully configured in PC2, the contest clock must be “started” before teams can submit runs (the Team client will not allow run submissions if the contest clock has not been started – although it WILL allow teams to log in). As of Version 9.4, PC2 supports two different methods of starting the contest clock: manual and automatic. (Prior to version 9.4 the only method available for starting the contest clock was manually.) 7.1.1 Starting the Contest Manually The Times tab on the Configure Contest tab on the Administrator screen is used to control the contest clock display and to start and stop the contest clock manually. Clicking the Times tab produces a screen similar to the one shown below: The Start button is used to tell PC2 to start the contest clock for a site manually (i.e., now). Selecting a site (by clicking on a row in the table) and then pressing Start starts the contest clock running for that site and allows teams at that site to submit runs. Pressing the Start ALL button starts the contest clock at all sites.34 (See the following section on Multi-Site Clock Control for further information about the Start ALL button.) 34 If the contest clock for some site has already been started when Start ALL is pressed, this command causes no change at that site but causes no harm otherwise – it starts the clock at all the other sites. PC2 v9.4 Administrator’s Guide 64 http://pc2.ecs.csus.edu/ The amount of time remaining in the contest at the current site is displayed in the top left part of the window just below the window title; the example above shows 5 hours left in the contest. The remaining time automatically starts counting down as soon as the Start (or Start ALL) button is pressed. It continues to automatically update (count down) as long as the contest clock is running.35 The remaining and elapsed time in the grid will not update automatically; to update those times use the Refresh button It is important to note that, from the point of view of PC2, the contest does not start until the Start button is pressed (or the contest clock starts automatically; see below). For this reason it is important that the Contest Administrator remember to press the Start button at the actual time the contest starts (or to schedule an automatic start, as described below). Failure to do this can produce erroneous scoring results. Typically, for example, a contest is deemed to have “started” when the contest problems are distributed to the teams. If the PC2 Start button is not pressed for another, say, 15 minutes, then that 15 minutes will not be considered to have been part of the contest by PC2. If a team were to submit a run 20 minutes after the contest started (i.e. 20 minutes after the problems were handed out), the timestamp on that run would show a contest elapsed time of 5 minutes, not the correct value of 20 minutes. This would produce erroneous values on the scoreboard. The Stop button is used to tell PC2 to stop the contest clock for a selected site. The Stop button can be used to insert a pause in a contest (for example, to allow a break for lunch). During the time the contest is stopped, the contest clock at the site does not count down, and teams are prohibited from submitting runs. Also, when the contest is stopped the contest clock displays in RED (as seen above). When the Start (or Start ALL) button is pushed again, the contest clock picks up where it left off. Note that this means that if a team submits a run one minute before the contest clock is stopped, and then the clock is stopped for 30 minutes of real time, and then the team submits another run immediately after the contest clock is restarted, the timestamps on the runs will be one minute apart. In other words, PC2 does not consider time during which the contest clock is stopped to be part of the contest. (If this is undesirable – that is, if the Contest Administrator wishes all time which elapses to be counted, then simply do not press the “stop” button once the contest has been started.) 7.1.2 Starting the Contest Automatically As of Version 9.4, the PC2 contest clock can be scheduled to start automatically at any arbitrary future time. Setting a Scheduled Start Time is done by pressing the Edit Start Schedule button on the Times screen (above), which produces a dialog similar to the following: 35 The remaining time is also displayed on the Team and Judge client screens, and counts down automatically; however, it is displayed only to a resolution of one minute on those screens. When the Team or Judge window is minimized the remaining time countdown is displayed in the window icon. PC2 v9.4 Administrator’s Guide 65 http://pc2.ecs.csus.edu/ Pressing Set to Undefined clears any currently-scheduled automatic start time. Pressing Set to Now puts the current time into the Scheduled Start Time text box (shown as containing “ ” in the above display). Note however that a Scheduled Start Time must be in the future, so merely pressing Set to Now then pressing Update will generate an error message and request a valid (future) time. The Scheduled Start Time displayed in the text box can be changed by selecting a value in the Change Minutes: dropdown list and then pressing Increment (to move the time farther into the future) or Decrement (to move the time back – but again, the dialog will not accept a time that is not at least one minute in the future). Once a desired valid (future) Scheduled Start Time has been selected, pressing Update will cause PC2 to set up a task to automatically start the contest at the specified time; it will not be necessary to push the Start/Start ALL button to start the contest (although doing so will work; doing so will override any scheduled future start time and start the contest when the Start/Start ALL button is pushed). When a Scheduled Start Time has been set it will be displayed in the Times screen shown previously, and the contest will automatically start (that is, the clock will start counting down and teams will be allowed to submit runs) when the specified time has arrived. Note that a Scheduled Start Time is interpreted to be contest wide and an automatic start starts the clock at all sites in a multi-site contest; there is no facility supporting “automatic start” for different sites at different times (manual starting must be used to do this). Note: automatic contest starting is also supported in PC2 Version 9.4 and above via the “/starttime” web service. See the Appendix on Web Services for further details. 7.2 Contest Length The Edit button on the Times tab displays the Edit Contest Time dialog (shown below) which allows the Administrator to change the contest length, elapsed time, or remaining time. PC2 v9.4 Administrator’s Guide 66 http://pc2.ecs.csus.edu/ The time values in the Edit Contest Time dialog do not update automatically when the contest is running; they display only the instantaneous time values at the moment the dialog is activated. If the contest is already stopped when the dialog is activated, those times remain accurate indefinitely. If a new Contest Length which is less than the current Elapsed Time is entered, the system displays a warning message to inform you that setting the contest length to a value less than the elapsed time will effectively mean the contest is over. The “Stop clock at end of contest” checkbox has no effect. Bug 378 has been filed to make this functionality work. 7.3 Multi-Site Clock Control As described above, the contest clock in PC2 operates on a per-site basis. That is, each site in a multi-site contest has its own contest clock, and PC2 keeps track of “contest time” independently at each site. This is done to allow support for independent time-management constraints at different sites, and allows scoring to be done accurately without worrying about differences in timing between sites (e.g., a necessary pause at one site which does not affect other sites). Normally, the Start All and Stop All buttons should be used to start/stop the contest clock at the same moment in time at all sites. The ability to start each site separately is a convenience mechanism intended to support situations where one site is “ready to go” and the Contest Director does not wish to delay that site while waiting for other sites to become ready. Having separate contest clocks for each site allows each site to operate quasi-independently while insuring that contest results are calculated correctly (meaning that teams get credit for submitting runs based on the contest time at their site, and the PC2 Scoreboard takes differences in site clocks into account PC2 v9.4 Administrator’s Guide 67 http://pc2.ecs.csus.edu/ when computing standings). However, operating the clocks separately at each site has its risks, as described below. Each PC2 site server determines the time of submission of a run from a team in terms of “contest elapsed time”, which means that a submission will be marked (“time-stamped”) according to the contest elapsed time at that site. The scoreboard in turn computes rankings based on this “submission time”, which means that overall (multi-site) rankings will be determined according to “contest elapsed time” at the site from which each run originated. This method puts teams at all sites on an equal competitive footing regardless of differences in the time at which the contest actually starts at each site. However, this mechanism (keeping track of contest time independently at each site) can produce erroneous scoring results if the Contest Administrator does not take care to control the multi-site contest clocks correctly. Specifically, in a multi-site contest it is important that the clock at each site be started at the moment the contest starts at that site. Typically, for example, a contest is deemed to have started at a site at the moment the contest problems are distributed to teams at that site. If this event (problem distribution; contest start) happens at different real times at different sites, then a Contest Administrator at each site should press the Start button at that site precisely when the contest starts at that site – regardless of whether the contest has started simultaneously at other sites. In this way, runs submitted by teams at each site will be correctly time-stamped with the true “contest elapsed time” as their “submission time”. If all sites in the contest are fully connected, and the contest problems are handed out at the same instant at all sites, then a single Contest Administrator can easily coordinate the start of “contest time” at all sites correctly, simply by using the “Start All” button on the Times tab. This button performs the same function as Start except that it applies the corresponding action (starting the contest clock running) simultaneously to all connected sites. (Use the Admin Sites tab to determine which sites are connected; connected sites are those that have valid IP addresses displayed in the Sites screen).36 In a fully-connected multi-site contest where Contest Administrators at each site have agreed (e.g. by telephone or other method) on the precise instant at which all teams at all sites will receive the contest problems and thus the time at which the contest officially starts, having a single Contest Administrator press the Start All button is the preferred (safest) way to coordinate the start of a contest. Likewise, if all sites are tightly coordinated the Stop All buttons can be used to stop the contest clock simultaneously at all connected sites. However, if there are some sites which do not have network connectivity, or some sites at which the distribution of the contest problems (and hence the start of the contest) is delayed for some reason, it is critical that a Contest Administrator at that site makes certain that the contest clock is started at that site at the moment the problems are handed out (or whatever other criteria determine the moment in time when the contest starts at that site). 36 If a new site server is started after the Start All Sites button is pressed, it will be necessary to use an Admin client to start the contest time for that site. Alternatively, you could use Start All Sites to start all sites including the new site. PC2 v9.4 Administrator’s Guide 68 http://pc2.ecs.csus.edu/ We have seen more than one instance of a situation in a multi-site contest where the contest problems were handed out at all sites (hence, the contest is effectively under way at all sites), but one or more sites failed to notify PC2 that the contest had started (either because the sites were not networked, or because the Start All Sites button was not used). In this case, if say 30 minutes elapsed before PC2 is notified to start its contest clock at one site, then teams at that site will effectively get 30 “free” minutes – a run submitted 31 minutes after the problems were handed out will appear to PC2 at that site to have been submitted “1 minute into the contest”. Caveat Administrator: It is critical that the PC2 “contest clock” be started, at every site, at the time the contest starts at that site. In addition, recall that as noted previously the Stop clock at end of contest checkbox is entirely local in function. This box must be separately checked on the Admin client for each site where it is desired that the contest stop automatically when the Remaining Time clock counts down to zero. 7.4 Practice Sessions: Resetting A Contest NOTE: with PC2 Version 9.3 and above, much of what is described in this section can be done much more cleanly using Profiles; see the section on Contest Profiles for additional information. In many contests, the overall contest activity starts with a “practice session” prior to the start of the actual contest. The primary objective of the practice session is to ensure that all teams are familiar with the operation of the contest environment (PC2 in the present case) prior to the start of the real contest. The practice session might provide teams with a trivial “practice problem” to solve (“print your team name” or “read a file containing integers and print the sum of the integers”, for example), and then require all teams to login to PC2 and test out the run submission mechanism by writing and submitting a solution to the practice problem. Some contests also require teams to practice using the PC2 “clarification system” during the practice contest. A practice session also has the advantage of giving the Judges practice with how PC2 works prior to the start of the real contest. In order to run such a “practice contest” prior to the start of the real contest, it is necessary to configure PC2 for the practice contest. Most of the configuration is identical to what is required for setting up the real contest – creating and configuring accounts, defining languages, etc. The only real difference is typically with the specification of the problem set: the practice problem(s) must be configured into the system for the practice contest (it is undesirable to configure the real problems ahead of time, as this would mean the problem names would be visible to the teams during the practice). However, most configuration items other than the problem set are usually exactly the same during a practice contest as they are during the subsequent real contest. PC2 v9.4 Administrator’s Guide 69 http://pc2.ecs.csus.edu/ At the end of such practice contest, it is necessary to “reset” the state of the system by removing from the database all runs, clarification requests, judgments, etc. which were submitted during the practice contest. However, it is at the same time desirable to avoid removing from the system the “configuration information” such as account names, passwords, language definitions, etc. In addition, it is necessary to switch from the practice problem set to the real contest problem set. There is a relatively simple way to accomplish a switch between a practice and a real contest while preserving the necessary information. First, create two directories named (for example) practice and real. Change to the practice directory, start a PC2 Server in that directory, and then start an Admin and configure a contest including the team accounts, languages, etc., but omitting the problem definitions. Next, shut down the server then (recursively) copy the practice directory contents to the real directory. This creates two directories with identical contest configurations, including accounts, languages, etc., but with no contest problems. Next, restart a server in the real directory and then run an Admin and add the real contest problems to that configuration. Finally, shut down the server, change to the practice directory, and restart a server and an Admin in that directory and use the Admin to add the practice contest problem definitions to the practice contest configuration. This way, the real and practice contests both have the same accounts, languages, etc., but have different problem sets. To switch to the real contest, shut down the practice contest server, switch to the real directory, and start a new server in that directory. PC2 v9.4 Administrator’s Guide 70 http://pc2.ecs.csus.edu/ 8 Monitoring Contest Status 8.1 Team Startup Status The Team Status tab on the main Administrator screen Run Contest tab is used to track the status of Teams once a contest has been started. This is particularly useful during a “practice contest” held just prior to a real contest; it allows the Contest Administrator to verify that all teams have been able to login and use the basic PC2 functions successfully. A sample Team Status screen is shown below. Initially all teams are displayed in RED, indicating that the team has not made any contact with the PC2 server. When a team logs in, their display changes to YELLOW; when they have submitted at least one run or clarification request their display changes to MAGENTA or BLUE respectively; once a team has successfully submitted both a run and a clarification the display changes to GREEN, indicating the team has successfully performed all the basic PC2 functions and should be ready to use the system in the real contest. (The screen below shows teams in each of these states, although it may be hard to read if you are not looking at a color copy of this manual.) PC2 v9.4 Administrator’s Guide 71 http://pc2.ecs.csus.edu/ 8.2 The Runs Display The Runs tab on the Run Contest tab on the Administrator screen displays a grid showing all the runs which have been submitted so far in the contest (from all teams, at all sites). The run display grid can be sorted on any column by clicking in the column header; clicking multiple times toggles the sort between ascending and descending order. The columns can also be resized by moving the column separators in the header. An example run grid is shown below. The Runs display provides a number of capabilities for the Contest Administrator. One function of this display is to provide the ability to select a run which has already been judged (and hence no longer appears on the Judge’s grid of available runs) and “give it back to the Judges” so that it may be re-judged. (Note that this assumes an Administrative decision to re-judge a run has been made for some reason; this is not a normal contest operation.) To give a run back to the Judges, click on the row containing the run to select it, then click the Give button. This will cause the run to appear on the Judge’s screens so that it can be selected and re-judged. (Note: when a Judge selects a run which has been sent for re-judging, a warning message is displayed on the Judge’s screen asking for verification that the run really is intended for re-judging.) A run does not disappear from the Administrator’s grid when it is sent for re-judging; the Administrator always has a complete listing of every run submitted in the contest, from all teams at all sites. PC2 v9.4 Administrator’s Guide 72 http://pc2.ecs.csus.edu/ A second purpose of the Runs display is to allow the Administrator to “take a run away” from a Judge. This can be used, for example, to take back a run which was given in error to the Judges for re-judging. Any time there is a run on the Judge’s display grid which should not be there (because it has already been judged and is not intended to be re-judged, for example), click on the run in the Administrator’s Runs display then click the Take button. This will remove the run from the Judge’s screens. 8.3 Editing Runs Another function of the Runs display is to allow the Contest Administrator to edit various parameters associated with a specific run – for example, to mark a specific run as “deleted” or to change the effective submission time of a run. This allows the Contest Administrator to make decisions regarding unanticipated situations affecting how a run should be considered in scoring.37 To edit a run, select the run in the Runs grid and then press the Edit button. This will bring up the following Edit Run dialog: The “Problem”, “Language”, and “Judgment” drop-down lists allow the Administrator to alter the specification of the corresponding attributes associated with the run. It is allowable to 37 It is assumed that the Contest Administrator understands the ramifications of changing run attributes; for example, that changing the Elapsed Time affects the number of penalty points assigned to the run, changing the Problem affects how many runs a team has submitted for a given problem, etc. PC2 is not smart enough to decide whether you should change the attributes of a run; it just gives you the capability to do so. PC2 v9.4 Administrator’s Guide 73 http://pc2.ecs.csus.edu/ change multiple attributes of a run during a single edit (although this would be unusual; normally, editing a run is done for a single specific purpose such as correcting a judging error). Changing the “Problem” attribute will have the effect of changing the way in which this run is considered in scoring: it will be counted as a run for the newly specified Problem (however, this will only have an actual effect on the scoring results if the Team has correctly solved the newly specified Problem; see the chapter on the Scoreboard for details). Changing the “Language” attribute will have the effect, if the run is subsequently re-executed, of changing the language definition (compiler invocation) used to compile and then execute the run. Changing the “Judgment” attribute will have the effect of causing the newly specified judgment to be the one used by the Scoreboard in determining whether the Team has correctly solved this problem. “Elapsed Time” represents the elapsed time in minutes from the start of the contest (contest elapsed time, not counting minutes during which the contest clock was stopped) at which the run was received. The Administrator can change this value as desired. Note that Elapsed Time is considered the “team submission time” and is used to determine the calculation of penalty points assigned to the run. Checking the “Delete Run” box will cause the run to be completely ignored in all scoring computations. Elapsed Time, Judgment value, and all other attributes of a run which is marked “Deleted” have no effect on scoring. A run marked as deleted no longer shows on the appropriate Team’s grid. (“Deleted” runs do not actually get removed from the database (nor from the Runs display), they are simply marked as such to indicate they should be ignored for scoring purposes.) If a run has been previously marked as deleted and subsequently the Mark Run as Deleted box is unchecked, the run is once again considered in further scoring computations, with no indication that it was previously “marked as deleted”. The “Notify Team” checkbox is used to indicate whether or not the Team which submitted this run should be sent a notification of the “Judgment” value applied to this run after it has been edited. Normally, editing involves correcting an internal administrative error and it is not desirable to notify the Team of any editing, so the default operation is to suppress Team notification. If it is desired that the Team should receive a notification of the result of editing the run (for example, a judgment was changed from NO to YES and the Contest Administrator wishes the Team to know this), uncheck the “Suppress Team Notification” checkbox. The Execute button allows the Contest Administrator to execute a run just as it would be executed on a Judge’s machine. This is useful, for example, when a Team submitted a run with an incorrect language specification (which most likely caused a Judge to render a “Compilation Error” judgment for the run), and it is desired to determine what the result would have been if the language specification had been correct. The Language drop-down list can be used to change the language attribute of the run, and it can then be executed at the Admin workstation. Note, however, that the Execute function will only work correctly on the Admin workstation if the workstation has been configured with the necessary language compilers, in the same way as on a Judge’s machine. Once a run has been edited (and re-executed if desired), pressing the Update button will store the new specification of the run’s attributes in the database and, if team notification has not been suppressed it will send a notice of the run status to the Team. Note that once an update has PC2 v9.4 Administrator’s Guide 74 http://pc2.ecs.csus.edu/ been applied, the former state of the run is lost; there is no way to restore a run to a prior state once it has been edited (other than simply re-editing the run and changing the values back – but PC2 does not keep track of the old run state once the Update button has been pushed). 8.3.1 Extracting Runs The Extract button on the Edit Run dialog allows the run being edited to be “extracted” (exported) to a separate directory. When the Extract button is clicked the following will appear: The extract directory is located under the $PC2HOME directory. If Run 2 for Site 1 was being edited and the Extract button was pushed, the following files would be created in the extract directory: extract/site1run2/pc2.run2.txt extract/site1run2/Prac.java The pc2.run2.txt file contains information about the run including Run #, Site #, Team Id, Problem Name, Language Name and contest elapsed time for example: ... Run Site Team Prob Lang Elaps ... : : : : : : 2 1 TEAM5 @ site 1 Bowling for Crabs Java 2 The second file (Prac.java in the example above) contains the source code which was submitted for the run which has been extracted. The current version of PC2 has no way to extract multiple runs with a single action; to extract several runs it is (unfortunately) necessary to Edit each run and extract it individually. (Yes, fixing this is on our list of “to-do’s”). PC2 v9.4 Administrator’s Guide 75 http://pc2.ecs.csus.edu/ 8.4 Filtering Runs It is frequently desirable to view a subset of the complete set of runs which are currently in the database. For example, the Contest Administrator may be interested in looking at all the runs for a given Problem, or all the runs from a given Team, or all the runs submitted during a specific window of time, or some combination of these. The Administrator Runs display has associated with it a filter which can be used to apply a set of filtering criteria to the runs which are displayed.38 Pushing the Filter button on the Runs display screen will produce the following dialog, which is used to set the filtering criteria: Selecting a set of items in the filter dialog indicates that those items should be displayed on the Runs grid. For example, to specify that the Runs grid should display all (and only) runs from Team 1 at site “Site 1” for the problem named “Sumit”, you would select “Sumit” in the Problems column, “team1” in the Teams column, “1 Site 1” in the Sites column, and “All” in the Language, OS, and Time columns, and then press the Update button. The Runs grid would then apply the specified filter criteria to all runs, displaying only those that match the selected criteria. In order to remind the user when filtering of runs is taking place, any time a filtering operation has been selected the “Filter” button on the Admin screen will change color to blue and will indicate “on”, like so: Filter (ON). Disabling filtering (using the “Clear All” button as described above) will return the Filter button to its normal state. The “Ok ” field is used to specify the command line which is used to compile source code and produce an “executable program file” in the language. The Ok button will save the filter settings and if the filter is ON will update the Runs list with the filter settings. 38 The Judge client provides a similar filtering operation; the discussion here on filters applies equally to the Judge. PC2 v9.4 Administrator’s Guide 76 http://pc2.ecs.csus.edu/ The Apply button will immediately reload the Runs list with the filter settings (if Filter On is checked). This can be used to quickly find runs based on the filter instead of having to use 3 steps to see the filtered results. Three steps would be: 1) (Edit) Filter, 2) change filter 3) Ok button 8.5 Clarifications The Clarifications tab on the main Administrator screen Run Contest tab, shown below, displays a grid showing all the Clarification Requests which have been submitted so far in the contest (from all teams, at all sites), in a format similar to the Runs grid. Like the Runs grid, the Clarification Request grid can be sorted and resized by manipulating the columns headers. The Give and Take functions work like the Give and Take on the Runs pane. PC2 v9.4 Administrator’s Guide 77 http://pc2.ecs.csus.edu/ 8.6 Reports The Reports tab on the main Administrator screen provides a variety of options for generating statistical reports about a contest, both during and after the contest. Note that the Reports tab appears on both the Configure Contest and Run Contest Administrator tab. The Reports screen looks like the following: The “Reports” drop-down list allows choosing one of a number of different report formats. The list of available reports is summarized in the table shown below. Pressing the “View Report” button will pop up a display showing the content of the selected report, and will also write the selected report in text form to a file (located by default in the $PC2HOME directory) Pressing “Generate Summary” will generate all the following reports: Balloons Summary, Clarifications, Contest Analysis, Contest Settings, Contest XML, Evaluations, Fastest Solutions Per Problem, Fastest Solutions Summary, Groups, ICPCTools Event Feed, JSON Standings, Languages, Problems, Runs, Runs (Version 8 content and format), Runs grouped by team, Scoreboard, Solutions By Problem, Standings Web Pages, Standings XML, Submission, and Submissions by Language. When all reports are written a dialog will appear that shows the directory where the reports were saved. Reports will be saved in the profiles\P \reports directory. PC2 v9.4 Administrator’s Guide 78 http://pc2.ecs.csus.edu/ 8.6.1 Automatic Generation of Reports at End of Contest When a server is shut down and there are less than 30 minutes remaining in the contest, the following reports will be automatically generated in the reports directory. Report Description Account Permissions Report For each client list their Permissions/Abilities Accounts List summary of accounts per site, and individual accounts sites, logins, passwords. All Reports List contents of all reports Balloons Delivery List of all balloon deliveries by team, by problem and time of delivery Balloons Summary List summary of which teams should have which color balloons. Clarifications List all clarifications Client Settings Various settings like Notification settings Contest Contest settings in XML (work in progress) Contest Analysis Summary of submissions, unjudged runs, various checks on runs. Evaluations One line per judgment output Extract Replay Runs Files extracted used with Replay feature Fastest Solved by Problem List all run solving problems by fastest, by problem, and fastest solution showing rank, elapsed, team name Groups List of Groups (Regions) Internal Dump An internal dump of a bunch of config settings Judgement Notifications List (balloon) notifications grouped by problem. Judgements List of judgments Languages List Languages Logins List who is logged in Notification Settings List of Notification Settings Problems List problems Run 5 field List of runs: run #, team #, problem letter, elapsed time, judgment Run Notifications Sent PC2 v9.4 Administrator’s Guide 79 http://pc2.ecs.csus.edu/ Report Description Runs List of runs, with run#, run state, team #, team name, whether judgment sent to team and details on each judgment Runs (Version 8 content and format39) List of runs with detail (see below) Runs grouped by team List of runs, grouped by team, then by problem, helpful in calculating scoring. Solutions By Problem For each problem show number of run with No, Yes, and percentage correct Standings XML Standings in XML format Submissions by Language A summary of how many teams used which languages. 8.7 Event Feed PC2 complies with the CLICS Contest Control System specification (found at https://clics.ecs.baylor.edu/index.php/Contest_Control_System). Among other things this means that it generates an event feed providing external tools with real-time notification of events which occur in the contest. Note in particular that this means that PC2 is compatible with the ICPC Tools suite of contest utilities. The PC2 Event Feed can be used for example to drive the ICPC Tools Resolver to produce dynamic displays revealing the final results of the contest (at an Awards Ceremony, for example). It can also be used to drive the ICPC Tools Balloon Utility, an interactive tools for managed balloons during a contest, as well as a variety of other contest utilities available in the ICPC Tools. For details on the PC2 Event Feed mechanism and how to use it, see the Appendices. For information on the ICPC Tools suite of contest utilities, visit https://icpc.baylor.edu/icpctools/. 8.8 Web Services PC2 contains an embedded web server which provides a variety of REST-based web services. Currently-implemented services include resources for obtaining the current list of contest teams, problems, languages, and the CLICS 2016 JSON Scoreboard. Also included are REST services for managing automated (scheduled) contest start time. For details on the PC2 REST Services and how to access them, see the Appendices. 39 Example single line of output: run 59|site 1|proxy |team 11|team11:Crimson Pride (WSU)|prob D - Obstacle Course6938491730217106684:D - Obstacle Course|lang GNU C++-1782097724418977383:GNU C++|tocj |os Linux|sel false|tocj false|jc true|182|rid Run-2641274401129060175|mmfr true|del? false|jt 0|jby judge5|jci Yes| PC2 v9.4 Administrator’s Guide 80 http://pc2.ecs.csus.edu/ 9 The PC2 Scoreboard 9.1 Overview PC2 contains a separate “Scoreboard” module which keeps track of the current standings in a contest. The scoreboard provides several functions: it automatically generates HTML pages describing the current state of the contest in a variety of formats; it generates email and/or printed “balloon notifications” (when that option has been selected by the Contest Administrator; see the section on “Options”, above); and it provides the capability to generate an “export” file containing contest standings data (in the form required for importing into the ICPC Contest Management System (CMS). The HTML files generated by the scoreboard are placed in a directory named “html” (lower case) directly beneath the current working directory. Balloon notifications are sent to destinations as configured by the Contest Administrator. 9.2 Scoring Algorithm The algorithm used in PC2 to compute Rank and “Score” (Penalty Points) is the one used in the ACM ICPC World Finals, which is as follows: 1) Teams are ranked according to the number of problems solved; a team solving more problems is always ranked higher than a team solving fewer problems. 2) Within a group of teams solving the same number of problems, teams are ranked by increasing “Penalty Points” (that is, the team with the lowest number of Penalty Points is ranked highest within the group). Teams only accrue Penalty Points for problems which the team has solved; unsolved problems do not affect the scoring in any way. Teams accrue Penalty Points for solved problems in two ways: Some number of penalty points for each minute elapsed from the start of the contest until the problem was solved (the time of SUBMISSION is counted as the “time solved”; it does not matter how long it took the Judges to judge it). Some number of penalty points for each INCORRECT submission submitted to the Judges prior to a correct solution for the problem (runs submitted after a correct solution are not counted in the scoring).40 3) If two or more teams have the same number of solved problems and exactly the same number of Penalty Points, ties are broken in favor of the team with the earliest time of the last correct submission (that being the time when the team “finished” the contest). 40 In the ICPC World Finals the number of penalty points for each incorrect submission prior to solving a problem is always 20 and the number of penalty points per minute until the problem is solved is 1; these are the default values in PC2 (although PC2 allows the Contest Administrator to change these values – see below). PC2 v9.4 Administrator’s Guide 81 http://pc2.ecs.csus.edu/ Examples of the PC2 scoring algorithm can be found in the PC2 Wiki article Scoring Algorithm at http://pc2.ecs.csus.edu/wiki/Scoring_Algorithm. 9.3 Configuring Scoring Properties Certain properties used by the scoring algorithm are configurable by the Contest Administrator. To adjust scoring properties, select the Settings tab on the Contest Administrator41 Configure Contest tab, then press the Edit Scoring Properties button. This will bring up the following dialog: The Scoring Properties have the following meanings: 41 Base Points per Yes: the number of penalty points which are always assigned to submissions which correctly solve a problem. Points per Compilation Error: the number of penalty points assigned to submissions which fail to compile. Points per Minute (for 1st yes): the number of points, for each minute elapsed in the contest, assigned to submissions which correctly solve a problem – from the start of the contest until the time of the correct submission. (Note that only the FIRST correct submission is counted; if a team subsequently submits another run for the same problem which correctly solves the problem, no points are assigned based on this category.) Points per No: the number of penalty points which are assigned for each incorrect submission on a problem prior to the problem being solved (but only if the problem is eventually solved; unsolved problems accrue no penalty points). Note that while Scoring Properties control the computations performed by the Scoreboard module, for security reasons they are only editable on the PC2 Admin. PC2 v9.4 Administrator’s Guide 82 http://pc2.ecs.csus.edu/ Points per Security Violation: penalty points added to a submission which generates a PC2 Security Violation. Note that Security Violations can only be generated if a PC2 Security Manager (“sandbox”) is installed in the system. Note that changing scoring property values only affects that particular scoring criterion; it does not alter the overall determination of ranking criteria. For example, assigning a negative value to one property does not change the fact that teams are ranked first by number of problems solved; a team with a large negative score will still not be ranked higher than a team which has solved more problems. 9.4 Starting the Scoreboard To start a scoreboard, go to a command prompt and type the command “pc2board”. This will start a PC2 client expecting a scoreboard login. Once the Client login window appears, enter the scoreboard account name and password as defined when PC2 accounts were created.42 This will bring up the PC2 Scoreboard display window (next page), indicating that the scoreboard program is running. The scoreboard automatically generates a complete set of HTML files to the html/ directory as soon as it is started. Thereafter it generates updated HTML files periodically according to an algorithm described below (See Scoreboard Updates). Each time a new set of HTML files is generated the scoreboard display window is updated to show the most recent update time. Under normal circumstances it is only necessary to have a single PC2 scoreboard running, even in a multi-site contest. The scoreboard automatically receives update information from every site server, and generates HTML files describing the overall contest status (including all sites). These HTML files can be copied to a publicly-accessible location for access by a browser (see below), so participants at any location can see the current standings. In addition, a single scoreboard can generate balloon notifications for all sites. Thus there is rarely a need for running more than one PC2 scoreboard in a contest, and this is the recommended mode of operation. 42 Recall that by default, account passwords are the same as the account name. If the scoreboard account password(s) are not changed by the Contest Administrator, it would mean that any team could start a scoreboard running on their own machine, allowing them to look at the contest standings even during times when the Contest Administrator has decided to hide that information (such as near the end of the contest, which is the policy in some contests). We strongly recommend changing the scoreboard account passwords. PC2 v9.4 Administrator’s Guide 83 http://pc2.ecs.csus.edu/ 9.5 Scoreboard Updates Once the scoreboard is running, it waits passively until some contest event occurs which could alter the data it should display (this could be a submitted run, a judgment decision by the Judges, a complete list of events is below). When any such event occurs, the scoreboard obtains from the server an update of the contest state, computes the new standings based on this information, and regenerates the HTML display files. Events that will cause a scoreboard update: run judgment, run submission, account name changes, group name changes, scoreboard settings changes and lastly if a user clicks the Refresh button on the board display. The date/time of the last scoreboard update is present on the scoreboard main window. Scoreboard Refresh Events All of the following events/changes will cause a scoreboard files Refresh. 1. the scoreboard module is started 2. the Refresh button is clicked. 3. any run is judged 4. any run judgment is changed (via Edit Run) 5. configuration definitions/settings are changed (accounts, languages, problems, etc.) PC2 v9.4 Administrator’s Guide 84 http://pc2.ecs.csus.edu/ 9.6 Scoreboard HTML Files Each HTML file generated by the PC2 scoreboard is a complete stand-alone HTML document (i.e. is bracketed by … tags). Each document includes a tag, into which PC2 places the Contest Title as specified by the Contest Administrator (see Options, above). Each document <body> contains an imbedded <table> holding contest status information. Each HTML file is also in an XML formatted file. The <table> in each different HTML file contains a different set of contest information, such as team rankings, run submission statistics, etc. (see below). The information outside the <table> can be edited/replaced as desired, for example by adding additional header information, frames, or any other HTML constructs. However, it is important to keep in mind that the set of HTML files is completely regenerated on every scoreboard update; changes made manually to an HTML output file will only persist until the next scoreboard update. The following HTML files are always generated by the scoreboard : File Name Table Contents full.html Columns showing rank, team display name, number of problems solved, and penalty points, with rows ordered by rank. This is the standard “contest standings” display. fullnums.html Same as full.html except that the Team Display Name is preceded by the Team Number followed by a dash. sumtime.html A grid showing, for each team and each problem, the number of runs submitted by the team for the problem, and, if the team has solved the problem, giving the contest elapsed time of the team’s solution. sumatt.html A table similar to the sumtime table but instead of giving the time of solution for solved problems simply indicates “Y” or “N” according to whether the team has solved the problem. summary.html A table combining the full and sumtime displays described above – that is, a showing rank, team display name, number of problems solved, penalty points, and number of runs submitted and solution time for each problem, with rows ordered by rank. The most common way to take advantage of the HTML files generated by the PC2 scoreboard is to run a separate external process (e.g. a batch script43) which repeatedly copies the 43 A sample batch script is included with the samples: samps/web/distribute_score . PC2 v9.4 Administrator’s Guide 85 http://pc2.ecs.csus.edu/ current HTML files to some external location (web site), reformats them if desired, and makes them available to teams and spectators using a browser. There are several advantages to this method of operation. First, the details of the appearance of the scoreboard can be customized by the Contest Administrator external to PC2. Thus the Contest Administrator can choose to take advantage of the full set of scoreboard screens, or can choose to omit some or all of them. In addition, it is not necessary for teams, judges, spectators, etc. to run separate PC2 scoreboards, since most users will already have access to a browser. The Contest Administrator can arrange that the external scoreboard script builds the desired scoreboard display and puts the resulting HTML in a standard public location accessible to all user’s browsers. 9.7 Scoring Groups In addition to the above files, the scoreboard can be made to generate separate HTML files showing rankings based on the concept of “groups” or “regions” with which a team is associated. For example, in the ICPC World Finals, teams compete not only for placement in the overall world-wide standings, but also among teams from their own region of the world for the regional championship.44 Other examples include situations where it is desirable to break contest teams up into separate groups based on level of experience (e.g. “lower division” and “upper division” students), and in multi-site contests where it is desirable to be able to display rankings that show only those teams participating at a given site. Every PC2 account has associated with it a “Group” identifying the region or group to which the account belongs. By default accounts do not belong to a group. Changing the group for a particular team account associates that team account with other all teams in the same group. By default, the scoreboard ignores groups. In order to cause the scoreboard to pay attention to Groups, three steps are required. First, the contest administrator must define the groups to the system. Second, team accounts must be assigned to a group. Third, the contest administrator must provide an XSL file describing how to generate the HTML file representing the group standings (see the section below on Adding New HTML Files). Groups can be defined either manually or by using the “import” functions on the ICPC tab on the main Contest Administrator screen. To manually define a new group, select the Groups tab on the Configure Contest tab of the main Administrator screen. This will display a screen similar to the one shown below. 44 Currently the ICPC defines six world “regions” (called “Super Regions” for historical reasons), and awards the Super Regional Championship to the top team in each Super Region as part of the Word Finals competition each year. The current ICPC Super Regions are: Africa and the Middle East, Asia, Europe, Latin America [comprising Central and South America], North America, and the South Pacific. PC2 v9.4 Administrator’s Guide 86 http://pc2.ecs.csus.edu/ Click the Add button to add a new Group. This will display the following Add New Group dialog: In the Display Name field enter a name for the new group (for example, “Upper Division” or “Site 1”). The “PC^2 Site” dropdown list and the “External Id” field can be ignored. If your contest is supported by ICPC Headquarters45, groups can be set by using the “import” functions on the ICPC tab (see the Appendix on ICPC Import/Export Interfaces). 45 All ICPC Regional Contest Directors have access to the PC2 ICPC Import Data files describing all the teams registered for their Regional Contest, including their groups (“sites”). PC2 v9.4 Administrator’s Guide 87 http://pc2.ecs.csus.edu/ Once groups are defined, accounts can be assigned to a group (an account can belong to at most one group). Groups can be set when user accounts are first defined, or by editing accounts later (see the section on User Accounts earlier in this manual). The third step required to add groups is to define the way in which PC2 should generate HTML output for the groups. This is described in the following section. 9.8 Adding New HTML Files PC2 uses two inputs to create output scoreboard HTML. The first input is an eXtensible Markup Language (XML) standings file; this file is generated automatically by PC2. The second input is an eXtensible Stylesheet Language (XSL) file describing how the XML standings should be transformed (processed). The contest administrator is responsible for providing an appropriate XSL file; there are numerous sample XSL files in the samps\web\xsl directory. Steps for creating and generating HTML Files 1. Create a new XSL file (or copy an existing one from the samps directory) 2. Copy the new XSL file into the scoreboard $PC2HOME\data\xsl directory 3. Click Refresh on the scoreboard module. On Refresh the scoreboard module will read each file with a .xsl extension in the data\xsl directory and create a new .html file in the html directory. For example, the file full.xsl will create the file full.html. The file names and path are: data\xsl\full.xsl html\full.html There are 5 xsl files that create HTML files in the html directory: data\xsl\full.xsl data\xsl\fullnums.xsl data\xsl\sumatt.xsl data\xsl\summary.xsl data\xsl\sumtime.xsl There are sample XSL files in the samps\web\xsl directory that create per-region HTML files and World Finals HTML files; see the file samps\web\xsl\README for more details. PC2 v9.4 Administrator’s Guide 88 http://pc2.ecs.csus.edu/ 10 Finishing the Contest When the contest is over, there are typically a number of additional steps required to “finish up”. These include “finalizing” the results, optionally exporting the results for upload to another system, and shutting PC2 down smoothly. This chapter discusses each of those tasks. 10.1 Finalizing “Finalizing” a contest refers to certifying to PC2 that the contest has been completed. Finalization checks several things: insuring that all submitted runs have been judged, that all clarification requests have been answered (even if just nominally), and that event feeds are closed properly. In addition, Finalization allows for providing an indication of what “medals” should be awarded. (This latter step is provided for compatibility with the CLICS CCS specification and is used at the ICPC World Finals; it may or may not be relevant to your own contest.) Finalizing is done via the Finalize tab on the Admin Run Contest screen, shown below. Pressing the “Finalize” button causes PC2 to check that all prerequisites for finalization have been met, and if so to mark the contest “finalized”. Finalizing a contest also has the side effect of generating a results.tsv file containing the final contest standings (this file can then be uploaded to external systems such as the ICPC Contest Management System; see below). Note that in the screen shot shown above, the “Finalize” button has already been pushed, as indicated by the message giving the location of the results.tsv file (this file will not be generated if the contest cannot be finalized for some reason, such as remaining unjudged runs). See the following section for more information on results.tsv. The Report button can be used to view and save a copy of a “Finalization Report” for the contest; the View button can be used to view and save a copy of the results.tsv file after it has been generated PC2 v9.4 Administrator’s Guide 89 http://pc2.ecs.csus.edu/ 10.2 Exporting Contest Results When a contest is completed, it is sometimes desired to be able to transmit the contest results to other, external systems – for example, by uploading the results to the ICPC Contest Management System (CMS). PC2 supports two different mechanisms for exporting contest results. The preferred method is to generate a results.tsv file. An older method, generating a pc2export.dat file, is also retained for backwards compatibility with older external systems. 10.2.1 Generating a results.tsv export file PC2 automatically generates a file named results.tsv when the contest is “Finalized” (see the section on Finalizing, above). The generated file contains a complete summary of contest results and matches the format for results.tsv specified by the CLICS CCS specification at https://clics.ecs.baylor.edu/index.php/Contest_Control_System#results.tsv; this file is therefore suitable for direct uploading to the ICPC CMS. See the Appendix on Import/Export Interfaces for further details on the format of the results.tsv file. The PC2 Wiki page at https://pc2.ecs.csus.edu/wiki/Results.tsv also contains more information on the results.tsv file. 10.2.2 Generating a pc2export.dat export file The PC2 Scoreboard automatically generates a text file named pc2export.dat containing contest standings on the occurrence of any scoreboard refresh event as described earlier in the Scoreboard chapter. The pc2export.dat file is created in the directory where the Scoreboard was started. The pc2export.dat file contains, for each team, a record giving the number of problems solved, the total number of penalty points accrued on solved problems, and the time of last submission of a correct solution (used in the ICPC World Finals as a tiebreaker). See the Appendix on Import/Export Interfaces for further details on the format of the pc2export.dat file. 10.3 Shutting Down Clients (team, judge, scoreboard, and admin) can be shut down by pressing the Exit button in the upper right corner of their GUI. PC2 servers can likewise be shut down by using the Exit button on the Server GUI (shown below). When a server is shutdown, all clients currently logged in to that server will also be shutdown. For servers running in non-GUI mode, use the Shutdown button on the Sites tab on the Administrator: select a site and press Shutdown to shut down the server for that site. Selecting multiple sites and pressing Shutdown will shut down all those site servers. PC2 v9.4 Administrator’s Guide 90 http://pc2.ecs.csus.edu/ PC2 v9.4 Administrator’s Guide 91 http://pc2.ecs.csus.edu/ Appendix A – pc2v9.ini Attributes As described in the chapter on PC2 Initialization Files, the pc2v9.ini file consists [server] and [client] sections, with each section containing one or more "attribute assignment" statements of the form attributeName=value. Lines in the file which begin with a “#” or “;” character are ignored, as are blank lines. Attribute names (left side of the equal-sign) are not case sensitive; however, string data on the right side of the equal-sign is case sensitive. The following list gives the attributes which can be defined in each section of the pc2v9.ini file, along with a description of their function. Some attributes may appear in more than one section. [server] section attributes: port=<portNumber> Tells the server the port number on which it should expect to be contacted by clients, and by other PC2 servers in a multi-site contest. This attribute may be omitted from the pc2v9.ini file, in which case it defaults to 50002. Note that if you choose to assign a specific port number, then all clients and other servers contacting this server must also be told to use this same port number (this is specified with the “server=” attribute in the case of clients, and with the “remoteServer=” attribute in the case of other servers). Note also that if you choose to assign a specific port number, the port number should be greater than 49151 according to the conventions established by the IANA (Internet Assigned Numbers Authority)46. remoteServer=<IPAddress>:<portNumber> Tells the server the IP address and port number of a remote PC2 server at another site which it should contact in order to join a multi-site contest. The <portNumber> must be specified and must match the port number being used by the server at the remote site. The appearance of this attribute makes this server a “secondary” server; if this attribute is not defined in the [server] section then this server is a “primary” server and waits passively to be contacted by other site servers. 46 http://www.iana.org/assignments/port-numbers PC2 v9.4 Administrator’s Guide 92 http://pc2.ecs.csus.edu/ [client] section attributes: server=<IPAddress>:<portNumber> Specifies the IP address and port number at which the client module should contact the PC2 server. Every client module MUST have a “server=<IPAddress>:<portNumber>” entry in the [client] section of its pc2v9.ini file. The IP address and port number must correspond to the address of the machine running the PC2 server and the port number at which the server on that machine is expecting to be contacted. plaf=<type> Specifies the “Programmable Look-And-Feel (PLAF)” which should be used in displaying the client GUI. Allowable values for <type> are “java”, which causes the GUI to use the standard Java GUI appearance (which means that client GUIs will look the same regardless of the underlying platform), and “native”, which causes the GUI to use the underlying platform’s “native look-and-feel” – so for example on a Windows machine the GUI will look “Windows-like” while on a Mac the same GUI will look “Mac-like”. PC2 v9.4 Administrator’s Guide 93 http://pc2.ecs.csus.edu/ Appendix B – Networking Constraints As mentioned in the beginning of this manual, PC2 modules must be able to communicate with each other via TCP: clients must be able to communicate with their servers, and servers in a multi-site contest must be able to communicate with other servers. If client machines reside on the same segment as their server, and if all servers have publicly routable IP addresses which can be reached by other servers, then communication should work with no problems. However, given the wide variety of network configurations which can exist – firewalls, NAT, and VPNs, just to name a few – there may be some constraints in a given network setup which will cause problems in setting up a contest using PC2. In order to understand how to avoid (or circumvent) these problems, it is useful to have some understanding of how PC2 networking is implemented. PC2 is written in Java and uses TCP sockets; each server module requires an IP and port which is not blocked by firewall. Server modules listen for incoming connections using port 50002 by default.47 Client machines initiate connections to servers and servers initiate connections to other servers. Another constraint on networking has to do with NAT (Network Address Translation). For PC2 to work using NAT you must configure port forwarding on your firewall, and configure the site table with the public address/port for remote connections. In a multi-site contest each server contacts every other server. There must not be a firewall that blocks the sending/receiving of data over the required listening ports. 47 The listening port is configurable. PC2 v9.4 Administrator’s Guide 94 http://pc2.ecs.csus.edu/ Appendix C – PC2 Server Command Line Arguments The command to start a server is: pc2server The server accepts a number of command line options when it is started. One option is -h (or --help), which produces the following “usage” output: $ pc2server --help Usage: Starter [--help] [-F filename] [--server] [--first] [--login <login>] [--password <pass>] [--load <dir>|<file>] [--skipini] [--ini filename] [--contestpassword <pass>] [--nogui] As seen from the “usage” output, the pc2server command actually runs a program named “Starter” (with a --server option). The Starter program accepts the following command line options: -F: specifies a text file with command line options, an alternate to specifying sensitive information on the command line. See the section Using the -F option for more details. --server: indicates that this Starter is to run as a server, otherwise starts as a client. --first : indicates that this server is a primary server and should not attempt to contact any other servers (ignores any remoteServer= attribute in pc2v9.ini) --login : specifies the PC2 login account name --password : specifies the PC2 password --load: loads a contest configuration from either a directory in CLICS CDP format or from a specified YAML file. --skipini: ignores the pc2v9.ini file --ini: specifies an override ini filename --contestpassword: on the first server only, specifies the contest password. --nogui: starts this server without a graphical user interface. See the section Non-GUI Server Startup for more details. PC2 v9.4 Administrator’s Guide 95 http://pc2.ecs.csus.edu/ Using the –F option The –F command line option will load command line options from an input text file. This option is a security feature. Under most Unix systems the complete command line is listed when using a ps or similar command revealing login ids and passwords. Using the -F option, login ids and passwords can be stored in a text file. Note that the command line options are not limited to login and password options; any command line option can be stored in the specified text file. If this command line was used: pc2server --nogui --contestpassword cpass --login site1 --password site1pass One could alternatively use the -F option: pc2server -F secure.txt where the secure.txt file contains # # Command line for non GUI server # --nogui --contestpassword cpass --login site1 --password site1pass Blank lines and lines starting with # are ignored in the file (secure.txt). The order that command line values are applied (highest precedent first) are: 1. specified -F option properties 2. specified on the command line 3. pc2v9.ini PC2 v9.4 Administrator’s Guide 96 http://pc2.ecs.csus.edu/ Appendix D – ICPC Import/Export Interfaces D.1 Importing ICPC Registration Data As mentioned earlier in this manual, PC2 was designed for supporting the ACM International Collegiate Programming Contest, including its local and Regional contests worldwide. The ICPC maintains an online Contest Management System which is used by Regional Contest Directors (RCDs) around the world to manage participation in the various ICPC Regional Contests. PC2 provides interfaces to import contest registration data from the ICPC CMS, and also to export contest results back to the ICPC CMS. To import ICPC registration data to PC2, the RCD must first log into the ICPC CMS and download the “PC2 Initialization” zip file which is automatically created and updated as changes in registration data occur.48 Once the PC2 Initialization data file is downloaded, it should be “unzipped” at any convenient location. Unzipping the PC2 Initialization data file will produce four separate files: “PC2_Contest.tab”, containing details about the organization of the contest (such as the formal name of the contest); “PC2_Site.tab”, containing data identifying the sites in the contest; “PC2_Team.tab”, containing data about the teams that are registered in the contest; and “_PC2_Team.tab”. This last file contains the same data as in the PC2_Team.tab file but has an additional column which is initially filled with “null” and is intended to be filled in by the contest administrator in order to specify the PC2 team number to be associated with each team. Note that PC2 does not use the ICPC Team ID field for purposes of identifying a team. If the contest administrator wishes to associate registered teams with PC2 accounts, the “_PC2_Team.tab” file can be edited by adding the PC2 team number in the leftmost column. The specified team numbers will then be assigned to the corresponding teams when the initialization file is loaded into PC2. PC2 expects quotation marks in the team data to be “quoted”. That is, if any field in the data contains a quotation mark (), then (1) the entire field must be surrounded by an additional matching set of quotation marks, and also (2) each quotation mark which is part of the data must be doubled. Thus for example a team name like The TOPS Team should appear in the import data file as The TOPS Team. If the PC2 Initialization file exported from the ICPC CMS contains data with quotation marks, it may be necessary edit the data by hand (or load it into a program such as Microsoft’s Excel and then save it) to insure that quotation marks are properly formed. If this is not done prior to importing the data into PC2, you may see “format error” messages in the log file, and the data containing the quotes will not be displayed properly. 48 The PC2 initialization data is contained in a file whose name on the ICPC web site is typically something like “CI532.zip” – “Contest Information for contest number 532”. However, both the naming convention for the file, and the exact location of the file on the web site, are outside the scope of (i.e., not controlled by) PC2. PC2 v9.4 Administrator’s Guide 97 http://pc2.ecs.csus.edu/ To load the ICPC import data into PC2, select the ICPC tab on the Configure Contest tab on the main Administrator screen. This will produce the following screen: The next step is to specify the sites which are to be imported into the system. Press the “Import Sites” button on screen; this will cause PC2 to display a “file selection” dialog. Navigate to the location where the import files were unzipped and select the PC2_Site.tab file. This will load both the PC2_Site.tab file and the PC2_Contest.tab file. Next, press the “Import Accounts” button, navigate to the directory containing the import files, and select the _PC2_Team.tab. Note: all initialization “.tab” files must all reside in the same directory. Selecting the PC2_Team.tab file will produce the Change Display Format screen, shown below (this screen can also be invoked by pressing the Change Display Format button after completing an account import). Each record in the ICPC PC2 Initialization data contains multiple names associated with each team – the team name, the full name of the school, and a short version of the school name. PC2 can be configured to use any one of these names, or a combination of them, as the name to be displayed on the scoreboard; that is the purpose of the Change Display Format screen. PC2 v9.4 Administrator’s Guide 98 http://pc2.ecs.csus.edu/ Select the desired Display Name Choice on the Change Display Format screen and then press the Apply button. Apply changes the values displayed in the New Display Name column to match the chosen option. When the Change Display Format screen is invoked it displays only information for accounts which have changed. During an initial import operation, all accounts will be displayed; however, if the screen is subsequently invoked by pressing the Change Display Format button it will initially be empty (since no accounts have changed). Click the “Include unchanged accounts” checkbox to display all accounts. Once the desired account configuration is set up, click the Update button to save the new display names in the system. PC2 v9.4 Administrator’s Guide 99 http://pc2.ecs.csus.edu/ D.2 Exporting Contest Results As described earlier in this manual, PC2 supports two different file formats for exporting contest results: the newer results.tsv format and the older pc2export.dat format (retained for backward compatibility). This section describes the layouts of each of these files D.2.1 The results.tsv File The format of the results.tsv file is as defined in the CLICS CCS specification (see https://pc2.ecs.csus.edu/wiki/CLICS for details regarding CLICS). Results.tsv is text file consisting of a single “version line” followed by a series of lines, one for each team in the contest, sorted in rank order with alphabetical order on team name as tie breaker. Each line has tab separated fields as defined below. The first line has the following format: results 1 (‘1’ represents the file format version number) Then follow several lines (one per team) with tab-separated fields as follows: TeamID – an integer; for uploads to ICPC CMS, this must be the team’s CMS “external ID” Rank In Contest – an integer giving the rank this team earned Award – a string listing any award(s) the team one; e.g. “Gold Medal” Problems Solved – an integer giving the number of problems the team solved TotalTime – an integer giving the total “time penalty” the team accrued Time Of Last Submission – an integer giving the contest time at which the team’s last successful submission took place Group Winner – a string listing any Group (Region) in which the team finished first (e.g., “North America”) The results.tsv file is automatically generated when the contest is “finalized” (see the section on Finalizing the Contest). It can also be generated manually by pushing the Refresh button on the PC2 Scoreboard client. D.2.2 The pc2export.dat File Pressing the “Refresh” button on the scoreboard display causes the scoreboard to generate a new pc2export.dat text file containing the contest results in the old form required by the PC2 v9.4 Administrator’s Guide 100 http://pc2.ecs.csus.edu/ ICPC CMS.49 This file is made up of a series of text records, one record for each team in the contest. Each record contains a set of comma-separated fields. The fields in each record are: 1) ICPC Team ID (note: not the PC2 team number). 2) Rank in contest (this field is blank if the team falls in the “Honorable Mention” category as defined by the scoring display algorithm for the ICPC World Finals; see the description of the file wf.standings in the samps/web/xsl directory for details). 3) A non-negative integer giving the number of problems the team has solved. 4) A real number giving the total number of penalty points accrued by the team. 5) A real number giving the time of the last submission by the team, taking into account only the problems which the team has solved (used as the ICPC World Finals tiebreaker determination). The records in the file are sorted by team rank based on problems solved and penalty points. In particular, teams that fall into the “Honorable Mention” category as defined by the ICPC World Finals results display algorithm will still appear in rank order in the file, as defined by number of problems solved, penalty points accrued, and tie-breaking time of last submission. The exported data file contains all the information necessary to update the ICPC Contest Management System with the results of a contest. It is primarily intended to provide an automated mechanism for Regional Contest Directors to post the results of Regional Contests. The export data file can also be imported into any program that wishes to make use of the standings data. Note that if no “ICPC Import” operation was performed prior to invoking the “Export ICPC” operation, then PC2 will have no record of the ICPC Team ID associated with each team. In this case the “Team ID” value in field #1 in the exported file will be empty. This problem can be circumvented in contests other than Regional Contests (that is, contests where there is no ICPC data to import) by creating a local version of the “PC2_Team.tab” file, entering the appropriate PC2 team account number in lieu of the ICPC Team ID. This will cause the “Export ICPC” operation to generate a file containing all the data necessary to compute complete contest standings utilizing PC2 account numbers. D.3 The PC2_Team File The PC2_Team.tab file consists of text-based tab-delimited records, one record for each team registered in the contest. The tab-delimited field contents of each record are as follows: 1) An integer giving the ICPC Team ID (note that this is not the same thing as the PC2 Team ID; see above). 2) An integer giving the ICPC Region ID (the “region” or “group” to which the team belongs). 49 Actually, the export data file is automatically generated (updated) each time the contest standings change; pressing the “Refresh” button simply displays a message showing its location. PC2 v9.4 Administrator’s Guide 101 http://pc2.ecs.csus.edu/ 3) A single character indicating the Team’s “registration status” for the contest – typically either ‘P’ (pending), ‘A’ (accepted), or ‘C’ (cancelled). PC2 ignores records containing ‘C’ in this field. 4) A string giving the Team Name; for example, “The Top Coders”. 5) A string giving the full name of the Team’s school; for example, “California State University, Sacramento”. 6) A string giving the Team’s school name in “short form”; for example, “CSUS”. 7) A string giving the Team’s school’s URL; for example, http://www.csus.edu. 8) A string giving the Team’s school’s country code (three letters); for example, “USA”. 9) A single character ‘Y’ or ‘N’ indicating whether the Team’s school has a graduate program . PC2 ignores this field (but it must be present). PC2 v9.4 Administrator’s Guide 102 http://pc2.ecs.csus.edu/ Appendix E – Validators E.1 Overview PC2 allows the Contest Administrator to configure each problem so that it has associated with it a validator program whose purpose is to help automate the judging process. A “validator” is a program which is given, as input, the output of the execution of a run (that is, the output of a program submitted by a team). Validators can operate in one of two ways: passively or actively. A passive validator is a program which accepts the team program’s output and displays it in some useful form for examination by the human judge. An active validator is a program which not only accepts the team program’s output but contains logic designed to make a determination, according to some set of rules, regarding the correctness of the output. An active validator can also return the result of its determination to PC2. An example of a passive validator would be the use of a “side-by-side” file comparison utility which displays the team program output beside an “answer file” provided by the Judges ahead of time. This allows the judge to use the validator to examine the output and compare it with the correct answer, perhaps taking advantage of special capabilities of the validator program (for example, syntax-driven color highlighting of differences between the team program’s output and the correct answer file). When the judge is satisfied, the validator is terminated and the judge uses the PC2 Judge client interface to enter a judgment. An active validator is one which automatically examines the team program output and makes some determination of its correctness. The validator must contain program logic which directs how it determines correctness. This logic could be hard-coded within the validator (in which case the validator is almost always problem-specific), or could be more general (for example, instructions directing application of “difference testing” between the program output and a Judge’s “answer file”). In either case an active validator is one which is designed to make an “automated” determination of the correctness of the output of a team’s program. For active validators, a set of conventions defined within PC2 provide a mechanism for the validator to return to PC2 an indication of what judgment it thinks should be applied to the run. However, such a validator response is never blindly accepted as the final determination of the judgment to be applied to a run. Rather, the validator output is displayed to the human judge as a “recommendation”. It is ultimately up to the human judge to accept the validator recommendation (or not). That is, it still requires the judge, at a minimum, to press a button to accept the validator recommendation. E.2 Validator Configuration By default there is no validator attached to (associated with) a contest problem in PC2. Validators can be attached to a problem by the Contest Administrator by using the Validator tab on the Edit Problem dialog. This displays the Validator configuration screen, as shown below. When the Contest Administrator configures a problem to use a validator, then when a Judge executes a PC2 v9.4 Administrator’s Guide 103 http://pc2.ecs.csus.edu/ team program the specified validator will automatically be invoked as soon as the team program completes execution. The Validator screen allows the Contest Administrator to choose one of two options for attaching a validator to the problem being defined: either the simple built-in PC2 validator, or an arbitrary separate external program. If a separate external program is selected it can be either a standard system program (such as a “diff” utility or a split-screen file-compare utility) acting typically as a passive validator, or it can be a program written specifically for the validation of output from programs for this particular contest problem, i.e. an active validator. The Contest Administrator can choose whether or not to display the validator result to the judge. Checking the box “Show Validation To Judges (SVTJ)” when configuring a validator will cause the response returned by the validator to appear on the Judge’s display when the run finishes executing. If the checkbox is unchecked the validator result will not be visible to the judge. The checkbox should normally be unchecked when using passive validators, which do not return meaningful result information (if SVTJ is checked and a passive validator is used, the response displayed to the judge will always be “Undetermined”). The “Report” button pops up a window displaying the configuration of the current problem (not just the Validator portion), and allows saving the report to a file. PC2 v9.4 Administrator’s Guide 104 http://pc2.ecs.csus.edu/ The following sections describe the built-in PC2 validator, the use of an existing external program as a validator, and the creation and use of a special-purpose problem-specific validator. For problem-specific validators, a standard for interfacing such validators to a contest control system such as PC2 is described. E.3 PC2 Built-In Validator PC2 contains a built-in validator which can be used to compare the output of a submitted program with the “answer file” provided by the judges (specified when a contest problem is configured). The built-in validator is essentially a very simple version of the standard Unix “diff” file comparison utility. Selecting the “Use PC^2 Validator” option enables a drop-down list showing the various comparison options, which are listed in the following table. PC2 Validator Option 1 2 3 4 5 Meaning Perform a standard “diff”: a character by character comparison of files differences Ignore whitespace at start of file Ignore leading whitespace on lines Ignore all whitespace on lines Ignore empty lines The PC2 built-in validator is an active validator – meaning that it automatically returns to the Judge a recommendation for the judgment which should be applied to the run whose output was diff’d against the answer file. If SVTJ was checked when the validator was attached to the problem, then the returned recommendation is displayed for the judge. E.4 Using An Existing External Tool As A Validator If the Contest Administrator selects Use External Validator on the Validator configuration screen, this tells PC2 to use an external program as a validator for the problem being configured. In this case PC2 needs to be given two sets of information regarding the external program which is to be used: (1) the name of the file containing the validator, and (2) the command sequence which PC2 should use when invoking the validator. To understand how this works, suppose it is desired to use an external program named “gvim” as a validator for a certain contest problem. Further, suppose gvim is a program which can be given an argument, “-d”, along with two additional arguments specifying file names, and that what it does in this case is display the contents of those two files side by side, highlighting the differences.50 50 In fact gvim is a program which exists on many systems and operates exactly like this. However, for the sake of this example, consider it to represent any arbitrary program; you don’t need to know anything about gvim to understand the example. PC2 v9.4 Administrator’s Guide 105 http://pc2.ecs.csus.edu/ What the Contest Administrator wishes to do is have PC2 invoke gvim every time a run for this particular problem is submitted and executed by a judge, and pass to gvim two files: (a) the output of the team’s program, and (b) the answer file (correct output) for the problem (provided ahead of time by the judges). This will allow a judge to compare the team’s output with the correct output, using the capabilities of the gvim program to assist them. Since our hypothetical gvim program already exists and is not (likely) written to understand how to make programming contest-related decisions about the correctness (or not) of the differences between two files, we will use gvim as a passive validator (one which does not return a value to PC2). In that case the Contest Administrator would select Use External Validator on the Validator screen and would uncheck the SVTJ box. In the Validator Program textbox the Contest Administrator enters the name of the file containing the gvim program. This might be something like /usr/local/bin/gvim or C:\Program Files\gvim\gvim.exe Use the “browse” button (the button showing “…”) to select the validator program file name. Typically this is an executable program, but it could be any file. A legitimate file must be selected even if this field is not actually used. In the Validator Command Line textbox the Contest Administrator enters the command to be used by PC2 to invoke the validator. This command can include parameter substitutions similar to those allowed when configuring languages. As when defining contest languages, parameter substitutions are indicated by a set of matching curly braces with a colon as the first character and containing a substitution keyword, for example, {:infile} The following table shows the substitutions which will be performed by PC2 prior to invoking the validator: Keyword Meaning validator Represents the file name given in the Validator Program box. Note that it is not a required that the “validator program” actually be an executable program; it could for example be a text file. infile outfile ansfile resfile PC2 v9.4 Administrator’s Guide Represents the problem data input file as configured in the problem. Represents the output sent to stdout by the team program when it was executed by the judge. Represents the judge’s answer file as configured in problem. Specifies the name of the file into which an active validator must place an XML representation of the judgment. 106 http://pc2.ecs.csus.edu/ Thus to invoke gvim as described above the proper Validator Command Line entry would be: {:validator} -d {:outfile} {:ansfile} This would invoke the gvim program ( {:validator} ) with a “-d” argument, passing it the team program output ( {:outfile} ) and the judge’s correct-answer file ( {:ansfile} ). Note that while the above example uses an existing program (gvim) as the “validator program”, it is not a requirement that this actually be an executable program. As an example, the “validator program” file might be a text file containing a set of “rules” describing how to determine the correctness of a team’s output, and a completely separate program could be invoked via the Validator Command Line entry, perhaps passing the “validator program” file as a parameter.51 For example, suppose a contest problem required teams to write a program to generate output which conformed to a set of lexical rules. If there existed a program named “analyze” which performed lexical analysis of the contents of a file according to a set of rules specified in another file, then the Contest Administrator might create an appropriate set of rules (the rules to which the team program’s output must conform) in a file named rules.dat, select rules.dat as the “Validator Program” file, and then specify the following as the Validator Command Line entry: analyze {:validator} {:outfile} This would invoke analyze as the program to be executed during the validation step, passing it rules.dat and the team output file as input. (What analyze would do with this is left as an exercise for the reader – but see the following section.) E.5 Implementing a Validator The use of an existing system tool (e.g. gvim) as a validator has the drawback that such validators typically must be passive, since they normally have knowledge of neither how to make decisions regarding correctness of team program output nor how to return such decisions to PC2 even if they did know how to make them. The built-in PC2 validator can be used as an active validator since it knows how to make decisions and knows how to return them, but as mentioned previously it is an extremely weak implementation. Thus, it is desirable to have a mechanism which allows the use of a special-purpose program written specifically to be an active validator. In order to support the use of such validators, it is necessary to define a set of standards for interfacing validators to the system. Because a validator is a problem-specific (not contest-specific or contest control-system specific) entity, ideally these standards should be uniform and general enough that a conforming validator (and its corresponding contest problem) could also be used in conjunction with contest control systems other than PC2. 51 It is arguable that a better name for this label would have been “Validator File” rather than “Validator Program”, since it does not have to be a program. PC2 v9.4 Administrator’s Guide 107 http://pc2.ecs.csus.edu/ Under the auspices of the ICPC, the PC2 development team has worked with a number of other contest system development teams to define such a standard.52 Known as the ICPC Validator Interface Standard, it specifies two interfaces: the invocation interface from a contest control system to a validator program, and the result interface from the validator back to the contest control system.53 The following subsections give a brief summary of the interfaces defined by the standard, 54 followed by a description of the PC2 implementation of the standard. Since PC2 complies with the standard, any validator written to comply with these interfaces can be used as an active validator for a problem in PC2. E.5.1 Invocation Interface The standard mandates that the contest control system is responsible for invoking the validator and passing it at least four command line parameters, as follows: parameter1: a string specifying the name of the input data file which was used to test the program whose results are being validated. parameter2: a string specifying the name of the output file which was produced by the program being validated when it was run using the data file named in parameter1 (that is, the name of the file containing the output to be 'validated'). parameter3: a string specifying the name of an arbitrary "answer file" which acts as input to the validator program. The answer file may, but is not necessarily required to, contain the "correct answer" for the problem. For example, it might contain the output which was produced by a "Judge's Solution" for the problem when run with the data file named in parameter1 as input. Alternatively, the "answer file" might contain information, in arbitrary format, which instructs the validator in some way about how to accomplish its task. parameter4: a string which specifies the name of the "result file" which the validator must produce. The content of the result file produced by the validator is defined in the following section. The requirements for passing parameters to a validator can be met by the Contest Administrator in PC2 through the use respectively of the {:infile}, {:outfile}, {:ansfile}, and 52 Actually, two such standards exist: the one described in this section, which has been used by PC2 (going all the way back to Version 7) as well as by other Contest Control Systems, and a newer standard defined under the auspices of CLICS (see https://clics.ecs.baylor.edu/index.php/Problem_format#Validators on the CLICS Wiki as well as https://pc2.ecs.csus.edu/wiki/Validator#CLICS_Output_Validator on the PC2 Wiki). The current version of PC2 uses the older version of the standard, although an upcoming release will also support the newer CLICS validator standard. 53 http://www.ecs.csus.edu/pc2/doc/valistandard.html 54 The interface descriptions contained here are necessarily terse; see the standard for complete details. PC2 v9.4 Administrator’s Guide 108 http://pc2.ecs.csus.edu/ {:resfile} command substitution parameters in the Validator Command Line; PC2 will automatically insert the appropriate values for the problem when the validator is invoked. Also, as required by the standard, the data file, program output file, and the answer file are in the current directory when the validator program is run. These conditions taken together specify how an arbitrary validator program should expect to be invoked by PC2. The standard specifies that the contest control system may pass additional command line parameters to a validator, as long as the first four command line parameters are specified as listed above, and that the interpretation of any such parameters is up to the validator. The Contest Administrator in PC2 can pass arbitrary additional parameters to the validator by including them in the Validator Command Line after the four required parameters. E.5.2 Result Interface The standard requires that the validator result be returned in the “result file” whose name is specified by parameter4 (above), and that the contents of the result file must be a valid “XML Document”. This means that it must start with a valid XML declaration,55 such as <?xml version="1.0"?> The root element of the XML document must be of the form <result outcome = "string1"> string2 </result> The tag name “result” is fixed and required by the standard, as is the attribute name “outcome”. “string1” is an “outcome string” defining the result (outcome) which the validator is reporting to the contest control system. The standard specifies that if the value of “string1” is “accepted” (or any case-variation of that word), the validator is indicating that the program output file “passed” the validation test(s). If “string1” contains any value other than a form of the word “accepted”, the standard specifies that the validator is indicating that the program output file “failed” the validation test(s). In PC2, the appearance of any form of the word “accepted” in the “string1” attribute of the result element in the result file causes PC2 to assign a recommendation of “YES” to the run being executed. In addition, any form of the word “Yes” also causes PC2 to assign a recommendation of “YES” to the run being executed (this is an extension to the standard). Recommendations are displayed to the judge if the SVTJ checkbox has been checked when the validator is configured with the contest problem. If the value of “string1” returned by the validator is not some form of the word “accepted” or “yes”, then PC2 compares the actual string value to the set of “judgment messages” currently 55 Strictly speaking, the XML standard does not require that a document contain an XML header to be a valid XML document. However, the current PC2 implementation expects a validator result file to have an XML header. PC2 v9.4 Administrator’s Guide 109 http://pc2.ecs.csus.edu/ defined in the system. If “string1” matches one of the currently-defined judgment messages, then PC2 assigns that message as the recommendation for the run being executed; otherwise, it assigns a recommendation of “Undetermined” to the run. The set of judgment messages recognized by PC2 is defined on the Judgments tab of the Configure Contest tab on the main Administrator screen. The default set of judgment messages is given in the following list: Yes No No No No No No No - Compilation Error Run-time Error Time-limit Exceeded Wrong Answer Excessive Output Output Format Error Other - Contact Staff See the section on Contest Judgments for information on adding to or editing the existing judgment messages. “string2” in the XML file returned by a validator is an arbitrary message string being returned from the validator to the contest control system. The standard specifies that the interpretation of this string is up to the contest control system. PC2 does not use the “string2” parameter from the result file. E.5.3 PC2 Extensions The standard specifies that the XML <result> element produced by the validator may include other attributes in addition to the “outcome” attribute, and may also include additional (nested) elements; it also specifies that the interpretation of any such additional attributes and/or elements is up to the contest control system. Such additional attributes can be used to implement a variety of features. PC2 makes use of additional attributes to implement a form of security. Specifically, it expects the validator to define an additional attribute named “security” and to return in that attribute the name of the result file. That is, PC2 expects the XML result file to look like: <?xml version="1.0"?> <result outcome="string1" security="resfile"> string2 </result> where “resfile” is the value which was passed to the validator as the name of the file into which the results should be placed (and where string1 and string2 are as described above). Each time PC2 invokes a validator it generates a unique random name for the result file. When the validator returns PC2 examines the contents of the result file and verifies that the security attribute value matches the file name. Since a user (team) program cannot know ahead of time what result file name PC2 will generate, it is not possible for a user program to generate a PC2 v9.4 Administrator’s Guide 110 http://pc2.ecs.csus.edu/ “fake” result file which somehow gets used in place of one generated by the validator. While this is not a complete guarantee of security, it does make it much more difficult for a user program to circumvent the operation of the validator. PC2 v9.4 Administrator’s Guide 111 http://pc2.ecs.csus.edu/ Appendix F – Language Definitions As described earlier in this manual, PC2 must be given a “language definition” for each language to be used in the contest (that is, for each tool which teams can use to write and submit programs). The language definition consists of four distinct text strings: the “Display Name”, the “Compile Command Line”, the “Executable Filename” specification, and the “Program Execution Command Line”. In order to help in understanding how such language definitions work (and so that you will be better able to develop your own language definitions), it is useful to understand what it is that PC2 does with a language definition. Language definitions are used by PC2 in two circumstances: when a Team invokes a TEST RUN operation, and when a Judge or an Admin invokes an EXECUTE operation. The following algorithm describes the sequence of steps which PC2 follows when either the TEST RUN button on the Team, or the EXECUTE button on the Judge or Admin is pressed. 1. The entire contents of the “execute”56 directory (beneath the $PC2HOME directory) are deleted. If something prohibits this clearing, the system stops and displays a warning message, and all remaining steps are skipped. 2. The submitted files are copied to the execute directory. 3. If the file whose name is specified as the “Executable Filename” in the language definition exists in the execute directory, it is deleted. This prohibits a team from submitting an executable file (or more correctly, they can submit it but it will never be executed). 4. The command specified as the “Compile Command” in the language definition is executed, using appropriate command parameter substitutions as defined earlier in this manual. 5. PC2 checks for the existence in the execute directory of a file whose name matches the specified “Executable Filename”. If this file exists, it must have been created by the execution of the “Compile Command”. (This is how PC2 determines whether compilation was successful.) 6. If the specified “Executable Filename” exists (hence, the “Compile Command” was successful), then the following operations are performed: a. The data file associated with the problem (if any) is copied into the execute directory. 56 The term “execute directory” refers to the directory which is current when a submission is executed and in which all execution operations (e.g. compiling, linking, execution) occur. In PC2 Version 9 the execute directory name is based on the logged in user. For example, the execute directory for Team 3 at Site 1 is named “executesite1team3”; the execute directory for Judge 3 at Site 2 is named “executesite2judge3”, etc. PC2 v9.4 Administrator’s Guide 112 http://pc2.ecs.csus.edu/ b. The command specified as the “Program Execution Command Line” is executed, using appropriate command parameter substitutions as defined earlier in this manual. c. If this is an EXECUTE operation on a Judge or Admin (as opposed to a TEST RUN on a Team), then if there was a “Validator” associated with the problem, then the following operations are performed: i. The “answer file” associated with the problem (if any) is copied into the execute directory. ii. The command specified as the “Validator Command Line” is executed, using validator command parameter substitutions as defined earlier in this manual (see the Appendix on Validators). iii. If “Show Validator Result To Judge” (SVTJ) was checked when the Validator was associated with the problem, PC2 reads the result file created by the Validator (see the Appendix on Validators) and displays the appropriate result for the Judge. Some examples of PC2 language definitions which have been used in past contests and were known to work in those environments are shown below. Each definition consists of four lines, corresponding to the four text field entries required on the Edit Language screen when defining a new language under the main Administrator screen. No guarantee is made that these definitions will work in your environment, nor that they will not become obsolete due to changes made by the various language tool vendors. All we can tell you is that all of these language definitions have been used successfully in past contests. Use them at your own risk. Language: Java Java javac {:mainfile} {:basename}.class java {:basename} Java Language: GNU C++ GNU C++ (Unix / Windows) g++ -lm -o {:basename}.exe {:mainfile} {:basename}.exe .\{:basename}.exe GNU C++ PC2 v9.4 Administrator’s Guide 113 http://pc2.ecs.csus.edu/ Language: GNU C GNU C (Unix / Windows) gcc -lm -o {:basename}.exe {:mainfile} {:basename}.exe .\{:basename}.exe GNU C Language: Perl Perl compilePerl {:mainfile} OK perl {:mainfile} Perl Language: Microsoft C++ Microsoft C++ cl.exe {:mainfile} {:basename}.exe .\{:basename}.exe Microsoft C++ Language: Kylix Delphi Kylix Delphi dcc {:mainfile} {:basename} .\{:basename} Kylix Delphi Language: Kylix C++ Kylix C++ bc++ -A {:mainfile} {:basename} .\{:basename} Kylix C++ Language: Free Pascal Free Pascal fpc {:mainfile} {:basename} .\{:basename} Free Pascal One of the ramifications of the sequence of language-handling steps described above is that a team cannot submit a program whose file name is the same as the “Executable Filename” specified in the corresponding language definition. For example, if the Contest Administrator configured a language by saying that the result of a compile operation for the language was to produce an executable file whose name was always “a.out”, then if a team submitted a source code program in a file named “a.out”, then the source code program file would get deleted (step 3) prior to the compile step. Normally this difficulty is eliminated through the use of command parameter substitutions; the Contest Administrator would not normally specify “a.out” as the expected executable file to PC2 v9.4 Administrator’s Guide 114 http://pc2.ecs.csus.edu/ be generated by the compilation steps, but rather would use a specification such as “{:basename}.out”, and further a team would normally submit source code in a file named, e.g. “a.c” rather than “a.out”. However, there is one scenario under which the mechanics of language handling by PC2 can cause difficulties (or at least, confusion). This is the case of purely interpreted languages, such as Perl or shell-script. In these cases there is no “compilation” step which is expected to generate an “executable” file; the “source file” is effectively the same as the “executable” file (in the sense that the source file undergoes no transformation prior to invoking “execution”, since “execution” involves running an interpreter against the original source program). For example, in the case of Perl, the Contest Administrator might attempt to configure the language definition as: Perl /bin/perl -c {:mainfile} {:mainfile} /bin/perl {:mainfile} This definition says that the language Display Name is “Perl”; that the “Compile Command” invokes /bin/perl ( the Perl interpreter) with the “-c” (check syntax) argument and the submitted file, that the result of “compilation” is to produce an “executable” file whose name is the same as the submitted file, and that following the “compilation” step PC2 should check for the existence of the submitted file and if present it should invoke /bin/perl again, this time executing the Perl commands in the submitted file. However, this language definition will not work, because of the steps which PC2 follows: it will delete the submitted source code (.pl) file prior to invoking the compilation command. Again, the reason for this is that it checks for the existence of the specified “executable file” after the compilation step, and assumes that if the file exists then the compilation was successful. Thus if a team submitted a source file named “myFile.pl”, since the submitted file is the “executable file” which would be input to the Perl interpreter, the “executable filename” (after command parameter substitution) would also be “myFile.pl” – but the file would have been deleted. It is still possible to use such languages with PC2. The trick is to create a separate “script” file which acts as the “Compile Command” and has the effect of creating a separate file which has the same name as that specified for the “Executable Filename” and which PC2 can test for after compilation and prior to invoking program execution. For example, suppose the Contest Administrator creates a shell script file named “compilePerl” with the following contents (the example presumes a Unix-like environment, but a similar approach can be taken in a Windows system): #!/bin/csh perl –c $* if ($? == 0) then touch OK endif PC2 v9.4 Administrator’s Guide 115 http://pc2.ecs.csus.edu/ This script basically says: run the “C-Shell” interpreter (line 1); have it execute the perl interpreter and perform a syntax check (-c) on the arguments passed to the script ($*) (line 2); check the system “status variable” ($?) and if it is zero (meaning no errors occurred) (line 3) then create a file named “OK” (line 4). With this compilePerl script accessible via the PATH variable, the following language definition will allow a Perl program to be submitted and processed by PC2 : Perl compilePerl {:mainfile} OK perl {:mainfile} This language definition will invoke the compilePerl script telling it to syntax-check the submitted program file, then if the file “OK” exists (which will only happen if the Perl syntaxcheck was successful) it will invoke the Perl interpreter to execute the submitted program. Note that while this example is for Perl, other languages such as Bourne Shell (and other shells), Python, Ruby, and ‘awk’ can also use a similar solution. The above example should provide some insight into the types of operations which the Contest Administrator can invoke from PC2 . For example, it is possible to create a script file which is invoked for the “Program Execution Command” and does any desired operation, such as copying a data file into the execute directory prior to running the intended program. Basically any desired operation can be performed at either the “compile” or “execute” step, as long as one has a clear understanding of the PC2 language processing algorithm described above. This organization of language processing gives a great deal of flexibility to the Contest Administrator. PC2 v9.4 Administrator’s Guide 116 http://pc2.ecs.csus.edu/ Appendix G – Using the PC2 API While the client interfaces (Admin, Judge, Team, and Board) in PC2 are intended to be as general as possible, there may be situations where users would like a client to operate differently. For example, a user may wish to create a scoreboard that uses a different scoring algorithm, or to create a different sort of contest system interface for Teams. To support this, PC2 provides a mechanism for users to create their own “custom clients” which interface with the rest of the PC2 system. The PC2 API Java doc is in the distribution under doc/api/index.html. In the API Java doc there are code snippets which show how to use the API. To use the API you must add the pc2.jar in the CLASSPATH (or build path). Use the ServerConnection class to connect to the PC2 server. Here is the code snippet from the ServerConnection Java doc that shows how to connect to the server and access the contest data. String login = "team4"; String password = "team4"; try { ServerConnection serverConnection = new ServerConnection(); IContest contest = serverConnection.login(login, password); //... code here to invoke methods in "contest"; serverConnection.logoff(); } catch (LoginFailureException e) { System.out.println("Could not login because " + e.getMessage()); } After a successful connection, the IContest instance can be used to access the contest data/information. PC2 v9.4 Administrator’s Guide 117 http://pc2.ecs.csus.edu/ Appendix H – Troubleshooting / Getting Help Before getting help from the PC2 Team There are a number of documents and references that contain information about using PC2, take the time and search these references before sending an email to the PC2 team. 1. Search this document for an answer 2. Search the PC2 Wiki or use Google to search for answers http://pc2.ecs.csus.edu/wiki/Main_Page 3. Search the on-line FAQ http://pc2.ecs.csus.edu/doc/faq/ 4. Search PC2 Bugzilla http://pc2.ecs.csus.edu/bugzilla/ Getting help from the PC2 Team If you can not find an answer to your question, send the PC2 team an email at pc2@ecs.csus.edu. If you have attempted to use the PC2 system and are having a problem, please email us a pc2zip file. This file is created by using the pc2zip script to create a special .zip file in the archive directory. PC2 v9.4 Administrator’s Guide 118 http://pc2.ecs.csus.edu/ Appendix I – PC2 Distribution Contents This following tables describe the contents of a PC2 software distribution. distribution contains a single (base) directory which contains these directories and files. Each Directories Directory Name bin data doc lib projects samps samps/contests samps/data/xsl samps/scripts samps/src samps/web samps/web/xsl Contains scripts to start PC2 modules XSL Stylesheets and other data files API and user documentation PC2 Java library (jars) PC2-related projects (e.g. EWTeam) sample files sample contests, with YAML descriptions XSL descriptions for PC2 scoreboards et.al. compile and other scripts Samples in C, C++, Java, etc. web resources and scripts samples for group XSL for HTML Filename README VERSION pc2v9.ini pc2.ico Description Late breaking and important info Version information Example PC2 V9 initialization file Default icon for PC2 modules Files PC2 v9.4 Administrator’s Guide 119 http://pc2.ecs.csus.edu/ Appendix J – Log files Log files are stored under the logs/ directory. In Version 9.3 and above, server log files are also stored under profiles/<ProfileID>/logs. There are 4 different log file types: 1. startup log files – logging information before a module is logged in 2. module log files – logging information for a logged in module/client, typically these are the files to check for errors when running PC2 3. evaluations/judgments log – on server only, one line per judgment, see http://pc2.ecs.csus.edu/wiki/Evals.log for more details. 4. security log files – logging security issues when they happen PC2 v9.4 Administrator’s Guide 120 http://pc2.ecs.csus.edu/ Appendix K – Reports Program The pc2report program can be used to produce stand-alone reports about the state of the system. This program must be run on the PC2 server machine (i.e., the machine on which the pc2server program is run). Each report generated by pc2report is identical in output content and form to the reports created using the Admin Report Tab. The following examples use the contest password ‘newpass’; replace ‘newpass’ with the contest password entered when the PC2 server was initially started. 57 Show Fastest Solution Summary report $ pc2report --contestPassword newpass 'Fastest Solution Summary' Show Runs report $ pc2report --contestPassword newpass Runs Show Runs report, use the report number (15) instead of spelling out report name $ pc2report --contestPassword newpass 15 Usage Usage: [options] reportName|## [[reportName|##][...]] --profile name - profile name, default uses current profile. name may be a ## from --listp listing --contestPassword padd - password needed to decrypt pc2 data --list - list names of reports (and the report numbers) --dir name - alternate base directory name, by default uses profile dir name --site ## - specify the site number --listp - list all profile names with numbers --noProfile - do not use profile directory use pre version 9.2 location reportName - name of report to print (or report number) ## - number of report to print (numbers found using --list) $ pc2reports --listp 1 - Id: Contest-1526060434834405723 description: Real Contest name: Contest 2 - Id: Contest 3--613094433664018852 description: Real Contest 3 name: Contest 3 Default name Profile ID Description Path 57 : : : : Contest Contest-1526060434834405723 Real Contest profiles\Pdf812e23-4234-46ee-ad3c-4011c8cb885e See the earlier note regarding the use of the –F option to avoid putting plain-text passwords on the command line. PC2 v9.4 Administrator’s Guide 121 http://pc2.ecs.csus.edu/ Each of these will print the same report: $ pc2report --contestPassword 'Fastest Solution Summary' $ pc2report --contestPassword $ pc2report --contestPassword $ pc2report --contestPassword newpass --profile Contest 3--613094433664018852 newpass --profile 2 'Fastest Solution Summary' newpass --profile Contest 3--613094433664018852 9 newpass --profile 2 9 Precedence for directory: --dir, --profile, then default profile dir Version 9.3 20140802 (Saturday, August 2nd 2014 20:46 UTC) Java ver 1.7.0_55 build 2822 Windows 7 6.1 (x86) List all reports available $ pc2report --list Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report Report 1 Accounts 2 Balloons Summary 3 All Reports 4 Contest Settings 5 Contest XML 6 Contest Analysis 7 Solutions By Problem 8 Submissions by Language 9 Fastest Solutions Summary 10 Fastest Solutions Per Problem 11 Standings XML 12 Logins 13 Profiles 14 Plugins 15 Runs 16 Clarifications 17 Problems 18 Languages 19 Judgements 20 Runs grouped by team 21 Notification Settings 22 Client Settings 23 Groups 24 Evaluations 25 Runs (Version 8 content and format) 26 Run 5 field 27 Account Permissions Report 28 Balloons Delivery 29 Extract Replay Runs 30 Run Notifications Sent 31 Judgement Notifications 32 Active Profile Clone Settings 33 Sites 34 Unused 2011 Event Feed XML 35 Notifications XML 36 Finalize-Certify 37 Internal Dump 38 Passwords 39 accounts.tsv (team and judges) 40 accounts.tsv (all accounts) PC2 v9.4 Administrator’s Guide 122 http://pc2.ecs.csus.edu/ Report Report Report Report Report Report Report Report Report Report Report Report Report 41 42 43 44 45 46 47 48 49 50 51 52 53 runs.tsv Report JSON Standings Unused 2013 Event Feed XML userdata.tsv groups.tsv teams.tsv scoreboard.tsv submissions.tsv ICPC Tools Event Feed Auto Judging Settings Judging Analysis JSON 2016 Scoreboard Contest Data Package PC2 v9.4 Administrator’s Guide 123 http://pc2.ecs.csus.edu/ Appendix L – PC2 Event Feed PC2 is capable of generating an event feed containing XML elements describing events which occur in a contest, including such things as configuration information (e.g., teams, problems, and languages), run submissions, judging results, etc. The event feeds generated by PC2 are compatible with the Event Feed described in the CLI CCS specification at https://clics.ecs.baylor.edu/index.php/Main_Page; refer to that page for information on the content and structure of an Event Feed. This appendix describes how to access a PC2 Event Feed. PC2 supports two types of Event Feeds (EFs): static and dynamic. A static EF is a text “snapshot” of the current state of contest events, in XML format. Static event feeds can be generated at any time during a contest (including after the contest is over) and contain all the information and in exactly the format described in the CLI CCS Specification, but only for events that have already happened at the time the snapshot EF is created. Dynamic event feeds are streams which can be connected to by an external tool and which provide continual updating as new events occur in the contest. The type of EF described in the CLI CCS Specification corresponds to a PC2 dynamic event feed (the CLI CCS specification makes no mention of static event feeds; these are an extension supported by PC2). The XML contents of a PC2 static event feed from a snapshot taken after a contest is over and has been “finalized” (see below) will be exactly the same as the sequence of XML elements found in a PC2 dynamic event feed at the end of the contest after the contest has been “finalized”. Static event feeds (that is, text containing the XML event feed elements) are created using the PC2 “Reports” facility on the Admin. Selecting the “Reports” tab on the Admin Main Screen allows selection of a Report titled “Event Feed (CCS) XML”. Viewing this Report will show the text of the current event feed output (that is, all the XML events which will have been sent out to any external tool listening to the dynamic event feed). The contents of the on-screen report can be copy/pasted into an external editor and then saved as a file.58 Alternatively, pressing the “Save XML” button on the XML Event Feed Report screen will prompt for a file name and save the entire XML event feed (minus the PC2 header and trailer text, but only the XML for those events which have already happened) in a file. Accessing the PC2 dynamic event feed is a bit more complicated – but has the significant advantage that an external tool can receive automatic event updates without further intervention by the Contest Administrator once the Event Feed is set up properly. PC2 does not generate a dynamic event feed by default; in order to get it to do so it is necessary to log in to a special client called the “Event Feed (EF) Client”, and then to start the EFClient listening for connections and outputting XML events. To start the EFClient it is necessary to create an Event Feed Account (an account of type “FEEDER”) and login to that account. Event Feed accounts are generated like any other PC2 account: by selecting the Accounts tab on the Admin Configure Contest Screen, pressing “Generate” to display the account generation screen, entering the number of Event Feed accounts 58 When using this method be sure to omit the non-XML “header” text at the top of the report and the non-XML “trailer text” at the bottom of the report in order to obtain valid XML. PC2 v9.4 Administrator’s Guide 124 http://pc2.ecs.csus.edu/ desired (normally there is no need for more than 1) and pressing “Generate Accounts” (see the section on Account Generation for additional details). Once the Event Feed account is generated, use the script “pc2ef” (located in ./bin along with all other PC2 support scripts) to start a client and login with the “feeder” account and password (these default to “feeder1” and “feeder1” respectively, although this can be changed via the Admin Accounts tab). Logging in with a feeder account displays the Event Feed Server interface, shown below. To start the Event Feed, select the desired port on which the Event Feed should be output (or accept the CCS Standard default port of 4713) and click the “Start” button; this starts the Event Feed server listening on the chosen port for connections and outputting XML events to that port as events occur during the contest. The above screen shows an Event Feed Server that is ready to be started listening on port 4713 with 4 hours and 57 minutes currently remaining in the contest. The “View” button will generate a text display of the current (static) event feed XML, without the extra PC2 header/trailer information present in static event feeds generated using the Reports mechanism. Note: it is important to leave the Event Feed running for the entire contest; stopping it will terminate the dynamic Event Feed. Restarting the Event Feed will reinitialize it, causing it to send all events from the beginning of the contest again. The pc2ef command supports an optional “no GUI” capability. To start the Event Feed client with no GUI, use the command pc2ef --nogui --login <account> --password <pw> PC2 v9.4 Administrator’s Guide 125 http://pc2.ecs.csus.edu/ This command causes the Event Feed to be automatically started with no Graphical User Interface, using the specified account and password, and using the default port (4713). If the -password option is omitted then a default password for the specified account is attempted. Note that the options can be placed in a file using the –F option (see the section on using the –F option in the Appendix on PC2 Server command line options for additional information). See the Web Services Appendix for further details regarding the effects of starting the Event Feed client in NOGUI mode. One important additional note should be mentioned. The CLI CCS Specification requires that a contest (and an Event Feed) be “finalized” after the contest is over. This process involves sending a <finalized> XML element to the Event Feed(s), which is the indicator to external tools that the contest is over. PC2 supports the “finalize” operation via the “Finalize” tab on the “Run Contest” tab of the Admin; see the section on Finalizing in the chapter on Finishing the Contest for additional details. The finalization process includes the specification of the ranks (team places) which should receive Gold, Silver, and Bronze medals in the contest (this is based on the ICPC World Finals, where Gold Medals are given to the top four teams, Silver Medals are given to the teams placing 5th through 8th, and Bronze Medals are given to teams placing 9th through 12th). These medal rank values are output as part of the <finalized> element in the Event Feed (although external tools are of course free to ignore them). Note also that the output of the dynamic event feed is not “well-formatted XML” while the contest is running: the opening <contest> element will not have a corresponding </contest> until the contest is finished (“finalized”). PC2 v9.4 Administrator’s Guide 126 http://pc2.ecs.csus.edu/ Appendix M – PC2 Web Services PC2 contains an embedded web server designed to provide a variety of “RESTful” web services59. The embedded web server is disabled by default; it must be explicitly started by logging in using an Event Feed Account (see the Appendix on the PC2 Event Feed). Logging into an Event Feed account displays the Event Feed Server interface as shown in the Event Feed Appendix; clicking the Web Services tab produces the following web server control display: As shown above, the user can specify the port on which the web server listens (the default is 50443), as well as enable a variety of web services (REST resource endpoints). Clicking the Start button then starts the web server listening on the specified port and responding to requests for the enabled web services. The embedded web server requires HTTPS connections and uses “BasicAuth” authentication. This means that connecting to the web server requires providing user/password credentials as defined by the BasicAuth specification.60 The web server obtains credential information (for comparing against the user/password provided by connecting clients) by reading a file named realm.properties, which must exist in the folder from which the Event Feed login is started. (A sample realm.properties file is included in the PC2 distribution; note however that all credential information in the sample file is commented-out.) 59 60 See https://en.wikipedia.org/wiki/Representational_state_transfer for information on REST. See https://en.wikipedia.org/wiki/Basic_access_authentication. Note in particular that this means that the server responds to unauthenticated requests with a response whose header contains a HTTP 401 Unauthorized status and a WWW-Authenticate field, and that the client is expected to provide authentication in the form of an Authentication field constructed as described in the above-referenced specification. PC2 v9.4 Administrator’s Guide 127 http://pc2.ecs.csus.edu/ Each non-comment line in the realm.properties file specifies three types of information: a username, the password associated with the specified user name, and a set of one or more roles associated with the user name. The general form of a realm.properties entry is username: password,role1[,role2…] The web server compares the user name and password provided by the connecting client with the set of username/password entries in the realm.properties file; if a match is found then the client connection is accepted and the client is assigned the role(s) specified on the matching line. The web server currently recognizes two “roles”: public and admin. The role(s) associated with a client determine what services the user may access (see the table below). A simple mechanism for verifying proper PC2 web server operation is to start the web server and then point a browser to https://<ip>:<port>/service (where <ip> and <port> are the IP address and port where the web server was started and /service is one of the REST endpoints listed in the table below) – for example, https://198.1.100.0:50443/scoreboard. This should return to the browser a request for credentials (username and password); entering valid credentials as specified in the realm.properties file should return the output corresponding to the specified service. If the Event Feed client is started in “nogui” mode, the component’s Graphical User Interface (shown above) is never displayed and therefore there is no way to interactively select the Web Services tab and start the web server. However, web services can be enabled in nogui mode by creating a file named “pc2ws.properties” in the Event Feed client’s startup directory containing properties identifying what web services should be started. The pc2ws.properties file can contain the following entries to start the web server and enable the corresponding web services: port=50443 enableScoreboard=yes enableTeams=yes enableLanguages=yes enableStartTime=yes enableProblems=yes See the PC2 Wiki “Event Feed Module” entry (https://pc2.ecs.csus.edu/wiki/Event_Feed_module) for additional details. The currently available REST services are defined in the following table (note that the first three comprise the PC2 implementation of the CLI CCS JSON Scoreboard specification61). Additional REST services are planned for a future version of PC2. 61 See https://clics.ecs.baylor.edu/index.php/JSON_Scoreboard_2016 PC2 v9.4 Administrator’s Guide 128 http://pc2.ecs.csus.edu/ REST Endpoint Roles Allowed Access GET Response PUT Response /scoreboard admin, public The current contest scoreboard in JSON format 405 Method not Allowed /teams admin, public A list of the teams in the contest in JSON format 405 Method not Allowed /problems admin, public A list of the problems in the contest in JSON format 405 Method not Allowed /languages admin, public A list of the languages in the contest in JSON format 405 Method not Allowed /starttime admin A JSON String giving the scheduled contest start time as a Unix Epoch value, or the string "undefined" if no start time is currently scheduled Resets the current contest scheduled start time according to the received (input) string, which is expected to be in JSON format as described in the CLICS Wiki "StartTime" interface specification The following points should be noted regarding the PC2 web server: 62 The web server is designed to support requests for contest data services based on various CLI Specifications62. It is not intended to support web access to PC2 by teams (see the separate Appendix on Team Clients for information on web access for teams). Web servers are inherently “resource intensive” (memory, CPU, etc.). Care should be taken regarding the machine on which the web server is run (it runs on the same machine as the PC2 component which is used to start it). If the machine is going to be overloaded as a result of adding the web server, consideration should be given to running the web server on a separate machine. (This can be easily accomplished by starting the Event Feed client on the desired machine, using it solely to start and manage the web server.) See https://clics.ecs.baylor.edu/index.php PC2 v9.4 Administrator’s Guide 129 http://pc2.ecs.csus.edu/ Appendix N – PC2 Team Clients PC2 supports two different types of Team Client. The first is the traditional Application Team Client which has been standard since the first version of the system. With the Application Team Client, PC2 must be installed on each team machine and each team machine must be provided with a pc2v9.ini file pointing to the PC2 server, as described earlier in this manual. With PC2 Version 9.3 and above, the system supports an alternative Team Client known as the EWTeam (EW stands for Eastern Washington University, where the EWTeam Client was developed under the direction of Professor Tom Capaul). The EWTeam Client is a web-based interface to the PC2 server. In a configuration using the EWTeam Client, teams use a browser to access a set of web services for submitting runs, checking results, submitting and examining clarification results, viewing the scoreboard, etc. Since every modern machine installation includes a web browser, using the EWTeam Client means that no additional software needs to be installed on the team machines to run a contest using PC2. The EWTeam Client provides all the services provided by the PC2 Application Team Client, with one exception: currently it does not support the "Test Run" facility. In order to use the EWTeam Client, it is necessary for teams to have access to a web server running PHP 4.3.0 and Java 1.7 (or higher) (the installation process, described below, includes inserting PHP modules into the web server for access by the browser).63 The EWTeam also requires that the PC2 server being used in the contest be version 9.3 build 2696 or higher. The EWTeam PHP modules interface to the PC2 Server to provide teams with access to the PC2 system (note that the PC2 Server does not need to be on the same machine as the web server which will support the EWTeam Client). IMPORTANT NOTE: In order to support the EWTeam Client, the PC2 configuration must include a scoreboard account explicitly named "scoreboard2". This account is used by the EWTeam Client to access current contest standings for the team display. Be sure to create this special account when setting up contest accounts using the "Generate Accounts" function in the PC2 Admin. The "scoreboard2" account SHOULD NOT BE USED FOR ANY OTHER FUNCTION THAN SUPPORTING THE EWTEAM CLIENT. If you plan to run your own "PC2 Scoreboard", use the default PC2 Scoreboard Account "scoreboard1", or some other account; do not use the "scoreboard2" account for any functions within PC2 as this will conflict with operation of both the EWTeam Client and with the PC2 scoreboard. The EWTeam distribution includes a “User’s Guide” for teams – a handout explaining what the EWTeam looks like and how to use it, analogous to the “PC2 Team Guide” for the Application Team Client. The EWTeam User’s Guide can be found in the “doc” folder of the EWTeam distribution (see below). Steps for installing the EWTeam Client 63 Note that the EWTeam client currently requires a separate web server external to the PC2 system; it cannot use the internal web server described under “PC2 Web Services” (a future version of the system will fix this). PC2 v9.4 Administrator’s Guide 130 http://pc2.ecs.csus.edu/ 1) Determine the document root directory on your web server (on our Linux Apache2 server it was /var/www, for example). 2) Create a directory named "pc2team" beneath the web server document root. 3) Copy the contents of the EWTeam “dist” directory (at least the index.html file plus the Team/, Login/, uploads/ and lib/ folders and their contents) into the pc2team directory beneath the document root on the web server. (The EWTeam “dist” directory is located in the EWTeam package, which can be unzipped from the “projects” folder of the PC2 download distribution or by downloading the separate EWTeam project from the PC2web page.) NOTE: the “doc” folder under “dist” contains the “EWTeam User’s Guide”, a handout which is intended to be given to Teams using the EWTeam client to connect to PC2. 4) Edit the pc2v9.ini file in the EWTeam "lib/" directory (not the pc2v9.ini file in your PC2 system) as follows: (a) in the [client] section, replace "localhost" with the hostname (or IP address) of your PC2 server. This allows the EWTeam Client to know where to find the PC2 Server. (b) in the [client] section, add an entry of the form scoreboard2password=xxxx where xxxx is the password you assigned to the "scoreboard2" account in the PC2 Administrator (see IMPORTANT NOTE, above). This allows the EWTeam Client to login to the server to obtain contest standings. Starting the EWTeam Client Services To start the EWTeam Client web services, go to the "lib/" directory of the EWTeam installation (under the pc2team directory of the web server) and run the PC2JavaServer.jar using the command: java -jar PC2JavaServer.jar This starts the Java "bridge" which manages connections between the web server and the PC2 Server. At this point teams should be able to open a browser window pointing to the EWTeam Client. The URL which teams should use will be the URL of your web server, with "/pc2team" appended. NOTE: see the section on Memory Limits in Chapter 3. In particular, the java command (above) used to start the PC2JavaServer should also include an appropriate –Xmx$$$$M parameter to set the Java maximum heap size to something close to the largest value allowed on your system. PC2 v9.4 Administrator’s Guide 131 http://pc2.ecs.csus.edu/ </pre><hr>Source Exif Data: <br /><pre>File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : Yes Author : John Create Date : 2016:12:18 20:54:44-08:00 Modify Date : 2016:12:18 20:54:44-08:00 XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-20:48:00 Creator Tool : PScript5.dll Version 5.2.2 Producer : Acrobat Distiller 9.0.0 (Windows) Format : application/pdf Title : Microsoft Word - pc2v9AdminGuide.doc Creator : John Document ID : uuid:d842c875-03b4-4e35-993d-17b6741d10d2 Instance ID : uuid:32ca09cd-9813-480e-9f5b-37bdf668270e Page Count : 132 </pre> <small>EXIF Metadata provided by <a href="https://exif.tools/">EXIF.tools</a></small> <div id="ezoic-pub-ad-placeholder-110"> <script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> <!-- usermanual link ad --> <ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-0545639743190253" data-ad-slot="6172135303" data-ad-format="link"></ins> <script> (adsbygoogle = window.adsbygoogle || []).push({}); </script> </div> </div> <div id="catlinks" class="catlinks catlinks-allhidden" data-mw="interface"></div> <div class="visualClear"></div> </div> </div> <div id="mw-navigation"> <h2>Navigation menu</h2> <div id="mw-head"> <div id="p-personal" role="navigation" class="" aria-labelledby="p-personal-label"> <!-- <div id="p-search" role="search"> <form action="https://usermanual.wiki/search.php" id="searchform"> <div id="simpleSearch"> <input type="search" name="search" placeholder="Search UserManual.wiki" title="Search UserManual.wiki [ctrl-option-f]" accesskey="f" id="searchInput" tabindex="1" autocomplete="off"><input type="hidden" value="Special:Search" name="title"><input type="submit" name="go" value="Go" title="Find a User Manual" id="searchButton" class="searchButton"> </div> </form> </div>--> <ul> <li id="pt-mycontris"><a href="https://usermanual.wiki/upload" title="Upload User Manual" accesskey="y">Upload a User Manual</a></li> </ul> </div> <div id="left-navigation"> <div id="p-namespaces" role="navigation" class="vectorTabs" aria-labelledby="p-namespaces-label"> <h3 id="p-namespaces-label">Versions of this User Manual:</h3> <ul> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/pc2v9AdminGuide.1338911440" title="User Manual Wiki" accesskey="c">Wiki Guide</a></span></li> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/pc2v9AdminGuide.1338911440/html" title="HTML" accesskey="c">HTML</a></span></li> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/pc2v9AdminGuide.1338911440/amp" title="Mobile AMP" accesskey="c">Mobile</a></span></li> <li id="ca-nstab-main" class="selected" ><span><a href="https://usermanual.wiki/Document/pc2v9AdminGuide.1338911440/help" title="Discussion / FAQ / Help" accesskey="c">Download & Help</a></span></li> </ul> </div> </div> <div id="right-navigation"> <div id="p-views" role="navigation" class="vectorTabs" aria-labelledby="p-views-label"> <h3 id="p-views-label">Views</h3> <ul> <li id="ca-view"><span><a href="#">User Manual</a></span></li> <li class="selected" id="ca-edit"><span><a href="https://usermanual.wiki/Document/pc2v9AdminGuide.1338911440/help" title="Ask a question" accesskey="e">Discussion / Help</a></span></li> </ul> </div> </div> </div> <div id="mw-panel"> <div id="p-logo" role="banner"><a class="mw-wiki-logo" href="https://usermanual.wiki/Main_Page" title="Visit the main page"></a></div> <div class="portal" role="navigation" id="p-navigation" aria-labelledby="p-navigation-label"> <h3 id="p-navigation-label">Navigation</h3> </div> <div class="portal" role="navigation" id="p-tb" aria-labelledby="p-tb-label"> </div> </div> </div> <div id="footer" role="contentinfo"> <ul id="footer-info"> <li id="footer-info-lastmod">© 2025 UserManual.wiki</li> </ul> <ul id="footer-places"> <li id="footer-places-privacy"><a href="https://usermanual.wiki/ContactUs" title="UserManual.wiki:Contact Us">Contact Us</a></li> <li id="footer-places-about"><a href="https://usermanual.wiki/DMCA" title="UserManual.wiki:DMCA">DMCA</a></li> </ul> <ul id="footer-icons" class="noprint"> <li id="footer-poweredbyico"> </li> </ul> </div> </div></body></html>