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).