OS/2 Shareware BBS: 7 Games

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 7 Games / 07-Games.zip / cycles.zip / CYCLES.DOC < prev next >

Wrap

Text File | 1993-04-01 | 25KB | 459 lines

COPYRIGHT The program to which this file relates is made available by IBM on an AS IS basis. Anyone receiving the program is considered to be licensed under IBM copyrights to use the IBM-provided program in any way he or she deems fit, including copying it and redistributing it. No license under IBM patents or patent applications is to be implied from this copyright license. Any user of the program should understand that IBM cannot provide technical support for the program and will not be responsible for any consequences of use of the program. Any person who transfers the program must include the IBM copyright notice, this paragraph and the preceding two paragraphs in documentation accompanying the program. CYCLES -- USER'S GUIDE December 1, 1992 Bruce W. Dean bwdean@vnet.ibm.com APPC Market Enablement Dept AB7 P.O.Box 12195 RTP, NC 27709 USA WHAT IS LIGHT CYCLES? _____________________ Light Cycles is a multi-player video game in which each player controls a cycle driving across the screen. The cycles can only turn at 90-degree angles and they leave a permanent trail behind them. A cycle is out of the game when it crashes into the screen's borders or a cycle trail. The last cycle alive wins. Light Cycles is played across a network that supports APPC. Each cycle can be located at a different machine, and the server program that calculates all the moves and collisions can run in an entirely separate machine, or in a machine running one or more cycle programs. Each of the cycle programs communicates with the server program using two APPC conversations to provide a form of asyn- chronous communication between the two. Light Cycles was written as a sample of APPC programming. The design objectives of this APPC sample were: o Implement a single Server program which services mul- tiple Clients simultaneously. o The communication between any Client and the Server is asynchronous, o and the program must be fun to run. Light Cycles meets these objectives. A typical operating scenario is this: someone runs the program CYCLE.EXE (this person is known as the Originating Cycle). The Originating Cycle then begins a game by specifying a Server to control the game. This server provides the Originating Cycle with a list of Remote Cycles that could potentially be contacted by the Server. The Originating Cycle selects those opponents that should be asked if they want to play. The Server then starts CYCLE.EXE on each of the Remote Cycle's machines. If the user at any of those machines answers that they'd like to play, they are entered into the game. When all Remote Cycles have responded, anyone who is entered in the game can start play. The rules of the game are simple: Each cycle moves around on the playing field until it hits a wall (either a playing field wall, or the trail left behind each moving Cycle). When a Cycle hits a wall, that Cycle is out of the game. When only one Cycle remains, that Cycle is deemed the winner. During the game, at regular intervals, the Server calcu- lates the new position of all Cycles and sends a message to each Cycle with that information. At any time during a game, any Cycle may notify the Server that it wants to turn. The Server will then use the Cycle's new direction in its calculations until the Cycle sends another new direction. PREREQUISITES _____________ Before Light Cycles can be run over a network, the fol- lowing prerequistes must be satisfied: 1. The machines that will run the cycle or server program must: a. Have OS/2 1.3 and Networking Services/2 OR OS/2 2.0 and Extended Services installed 2. The machine that an Originating Cycle can run on should be able to APING the Server machine. While it is not actually necessary to configure the two machines to run APING, APING is an excellent tool for identifying APPC configuration errors. It provides much more diagnostic information when a session cannot be established between two machines than the Light Cycles programs provide. 3. The Server should be able to APING any of the Remote Cycles that it will contact to play a game. NOTE: APING is a separately available program that tests for APPC connectivity between two machines on a network by echoing data between the two machines. APING is available on Compuserve (GO APPC). The APING documenta- tion details how to configure your machines to run APPC. This document describes only how to add transaction program (TP) definitions to an already-configured APPC setup. WORKSTATION CONFIGURATION _________________________ RUNNING AS AN ORIGINATING CYCLE To run as an Originating Cycle on your machine, no addi- tional TPs need to be defined on your machine. You just have to have CYCLE.EXE, and be able to APING the machine where the Cycles Server is installed and configured. RUNNING AS A REMOTE CYCLE To enable your machine to run as a Remote Cycle, you must define a TP in your .NDF file to allow the Cycles Server to start the program on your machine. To do this, follow these steps: 1. Determine the name of the .NDF file to change: a. While Communications Manager is running, look at the main Communications Manager screen, "Communi- cations Manager Main Menu." b. Note the value near the top of the screen by the prompt "Active Configuration File". This is the name of the configuration file you are using. For our example, let's use the name CFGFILE. The .NDF file to edit will be C:\CMLIB\APPN\CFGFILE.NDF. The drive may be dif- ferent if you have Communications Manager installed on a drive other than your C: drive. 2. Edit the .NDF file you found in the first step, and add the following lines at the end of the file, changing the value in parentheses by "FILESPEC" as specified in the note below. DEFINE_TP TP_NAME(LC.REMOTE) FILESPEC(e:\cycle\cycle.exe) PARM_STRING(REMOTE) SYNC_LEVEL(EITHER) TP_OPERATION(NONQUEUED_AM_STARTED) PROGRAM_TYPE(PRESENTATION_MANAGER) RECEIVE_ALLOCATE_TIMEOUT(INFINITE); NOTE: The path specified in parentheses on the FILESPEC line must be changed to point to the location of CYCLE.EXE. The preceding .NDF statement is described below: DEFINE_TP TP_NAME(LC.REMOTE) <----- the TP name that is specified by the server FILESPEC(e:\cycle\cycle.exe) <----- the fully specified name of the program to start when this TP is started PARM_STRING(REMOTE) <----- this parameter is passed to CYCLE.EXE and allows the program to know that is is being started by the server SYNC_LEVEL(EITHER) <--- this allows the Remote Cycle and the Server to use Confirm verbs in their conversation TP_OPERATION(NONQUEUED_AM_STARTED) <---- this tells the Attach Manager to start a new instance of CYCLE.EXE each time the Server starts this TP on this machine PROGRAM_TYPE(PRESENTATION_MANAGER) <---- CYCLE.EXE is a Presentation Manager program RECEIVE_ALLOCATE_TIMEOUT(INFINITE); <---- the Attach Manager will wait indefinitely for CYCLE.EXE to issue a Receive_ Allocate verb 3. After saving the .NDF file, verify and execute the changed file by executing the following command: APPNV cfgfile -E NOTE: Substitute the name of your configuration file for "cfgfile" in the command above. In addition to defining this TP in your .NDF file, you must also tell the Server that you are a potential player of the game. You do this by adding an entry in the Potential Players File that specifies your LU and the TP name you just configured. The Potential Players File is described later in this document. RUNNING AS THE CYCLES SERVER ON YOUR MACHINE To configure your workstation to run the Cycles Server, you must have CYCLED.EXE on your machine. You must then add a TP definition to your .NDF file. Finally, you should create a Potential Players File that specifies the LUs and TP names of the Remote Cycles that can be started by your Cycles Server. To add a TP definition for the Cycles Server to your .NDF file, add the following statement to your .NDF file and then verify that file by running APPNV CFGFILE -E. (The steps to determine where your .NDF file is and what it is called are in the previous section, "Running as a Remote Cycle.") DEFINE_TP TP_NAME(CYCLED) FILESPEC(e:\cycle\cycled.exe) PARM_STRING(e:\cycle\players.lst) SYNC_LEVEL(EITHER) TP_OPERATION(NONQUEUED_AM_STARTED) PROGRAM_TYPE(PRESENTATION_MANAGER) RECEIVE_ALLOCATE_TIMEOUT(INFINITE); NOTE: Be sure to replace the path specified in paren- theses on the FILESPEC line with the path and filename of CYCLED.EXE on your machine. Replace the file specifica- tion in parentheses on the PARM_STRING line with the path and filename of the list of Potential Players which is described below. This TP specification is similar to the LC.REMOTE TP spec- ified above. POTENTIAL PLAYERS FILE ______________________ When a player requests to play against other players, the server searches the file specified in the PARM_STRING parameter of the CYCLED TP definition for a list of potential opponents. This list specifies the LUs that may want to be asked to play Light Cycles. It also spec- ifies the names of the TPs on those LUs that should be started when requested by the server. This list of players is then sent to the Originating Cycle TP which presents the list to the user. Note that there can be multiple TPs with a particular LU. This will allow someone on the network to supply multiple potential oppo- nents. Perhaps one is an automatic cycle program, and one is the original CYCLE.EXE. The Potential Players file must have the following format: One line per TP, maximum 255 characters per line. Each line contains the LU name (alias or fully qualified), TP name, and a textual description of the TP on that LU. The LU name must begin at the beginning of the line. It is separated by at least one space from the TP name. The next non-space character begins the TP name. The TP name is separated from the textual description by a space. The next non-space character up to the end of the line is a textual description of the TP. The location and name of this file is specified in the CYCLED TP definition using the PARM_STRING parameter. primary return code. HOW WAS CYCLES WRITTEN? _______________________ Cycles was written using native OS/2 APPC. Typically, CPI-C is recommended for writing APPC applications, but the requirement that the communication between the Cycles and the Server be asynchronous meant that two parallel conversations had to be established between each Cycle and the Server -- one session to notify the Server that the Cycle wanted to turn, and one session to notify the Cycle of each new board position. The current version of CPI-C available on OS/2 does not support two conversa- tions within the same OS/2 process. Native OS/2 APPC does. (CPI-C version 1.2 contains the architecture for full-duplex conversations. When this level of CPI-C becomes available in OS/2, Light Cycles will be re- written to use that preferred interface for APPC applica- tions.) The result of this implementation choice is that the communications code written for Cycles is not port- able to other platforms, such as VM. Had it been written in CPI-C, it could be completely portable. Another variation from recommended APPC programming style is the method by which the TP_BUSY return code is handled. The Communications Manager APPC Programming Reference recommends issuing verbs for a TP from a single thread or to synchronize issuances from different threads to avoid getting a TP_BUSY return code. But since Light Cycles is designed to perform asynchronous communication, neither of these options is viable. Instead, the APPC verbs in Light Cycles are written to retry the APPC call up to 10 times when TP_BUSY is encountered. If TP_BUSY is still encountered, the APPC call fails with TP_BUSY as its primary return code. WHAT'S HAPPENING BEHIND THE APPC COVERS? ________________________________________ This section describes the flows of data between the Cycles Server and the various machines running the CYCLE.EXE code. When someone starts a Cycle on their machine and speci- fies a valid Cycles Server LU on the "Register to play..." dialog, two APPC conversations are allocated between the Cycle's local LU and the Server's LU. The Cycle code then does a series of Receive_and_Wait's to get the list of potential players from the Server. After the CYCLE.EXE user selects a set of users, the Server does a series of Receive_and_wait's to get that list of requested partners. The flows for these APPC trans- actions is shown below: * OVERVIEW of Originating Cycle <--> Server APPC Flows * Client (CYCLE) Server (CYCLED) -------------- --------------- * Set up conversation 1-Allocate (TP=CYCLED) 1-Send Data (callback TP) 1-Confirm -------------------> 1-Receive_Allocate 1-Receive Data (callback TP) 2-Allocate (TP=callback TP) <------------------- 1-Confirmed 2-Receive_Allocate <------------------- 2-Confirm 2-Receive Data (this allows us to do Confirmed) 2-Confirmed -------------------> * Get list of potential partners from the Server: while Server sends non-null partners do: While there are partners to send, do: 2-Send Data (partner info, 2-Receive Data <------------------- FLUSH) <------------------- 2-Send Data (null data, FLUSH) * Send the Originating Cycle's player name 1-Send Data (cycle name, FLUSH) -------------------> 1-Receive Data * Send the selected partners to the Server: While there are partners to send, do: While Cycle sends non-null partners, do: 1-Send Data(partner info, FLUSH) --------------------> 1-Receive Data 1-Send Data (null data, FLUSH) --------------------> Each time the Server receives the name of a selected partner, it starts a thread that attempts to establish two conversations with that partner in much the same was as the original two conversations are established. Here are the flows that occur between the Server and each of the selected partners: * OVERVIEW of Server <--> Remote Cycle APPC flows * Server (CYCLED) Client (LC.REMOTE) --------------- ----------------- * Set up conversation 3-Allocate (TP=LC.REMOTE) 3-Send Data (callback TP) 3-Send Data (originator's name) 3-Send Data (remote cycle's number) 3-Confirm -------------------> 3-Receive_Allocate 3-Receive Data (callback TP) 3-Receive Data (originator's name) 3-Receive Data (cycle number) 4-Allocate (TP=callback TP) <------------------- 3-Confirmed 4-Receive_Allocate <------------------- 4-Confirm 4-Receive Data (this allows us to do Confirmed) 4-Confirmed -------------------> If the allocation of these conversations fails (due to a communication error or the Remote Cycle decided not to play), this Remote Cycle does not become part of the game. At this point there are two conversations between each Cycle and the Server. One will be used to send data from the Server to the Cycle, and one will be used to send data from the Cycle to Server. So that these two flows of data can operate independently, CYCLE.EXE and CYCLED.EXE spawn threads to poll the other one for data. For example, CYCLE.EXE has a thread that does a Receive_and_Wait on the APPC conversation that expects data sent from the Server. Receive_and_Wait means that thread will be blocked and do no processing until data is received (or until the conversation is terminated due to some error). When data is received, the polling thread posts a message back to the Cycle's main thread. This message contains the data sent from the Server. The Cycle's main thread can then process this data while the polling thread loops back to another Receive_and_Wait. All of the Send_Data's are done from within the proc- esses' main thread. COMMENTS & SUGGESTIONS ______________________ If you have any comments about Light Cycles, or have any suggestions for improving the program or its documentation, please forward them to the author, Bruce Dean, at internet bwdean@vnet.ibm.com, or in the CompuServe APPC Info Exchange Forum (he's in APPC Market Enablement, so send comments to that ID).