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


