home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / CPI-C.ZIP / ATELL.DOC < prev    next >
Text File  |  1992-07-22  |  25KB  |  593 lines
  1.  
  2.  
  3.   TERMINOLOGY
  4.  
  5.   TERM           DEFINITION
  6.  
  7.   TRANSACTION    An exchange between two programs that accomplishes a
  8.                  particular action or result.  Transaction programs are written
  9.                  in pairs, with both sides of the transaction cooperating to
  10.                  achieve a result.  The sides of a transaction program are
  11.                  known as "client" and "server."
  12.  
  13.                  Examples of transactions are:
  14.  
  15.                  o   sending a simple message
  16.  
  17.                  o   executing a specified procedure or task
  18.  
  19.                  o   updating a database entry
  20.  
  21.   CLIENT         Identifies the initiator of a transaction.  The client must
  22.                  specify the name of the other side of the transaction, known
  23.                  as the server.  The term client can refer to either a program
  24.                  or a computer.
  25.  
  26.   SERVER         Identifies the receiver of a transaction.  The server does not
  27.                  need to know the name of the client side of the transaction.
  28.  
  29.   PARTNER COMPUTER
  30.                  Identifies the "other" side of a transaction.  The partner of
  31.                  the client is the server, and vice versa.
  32.  
  33.   DESTINATION    The name used on the client to identify the server.
  34.  
  35.   APPC PLATFORM  Refers to the APPC implementation code running on a given
  36.                  computer.
  37.  
  38.  
  39.   USER'S GUIDE
  40.  
  41.  
  42.  
  43.   What Is ATELL?
  44.  
  45.   ATELL is a sample program that allows a workstation user to send a message to
  46.   another workstation.  ATELL is written in the C language and uses the IBM SAA
  47.   Common Programming Interface for Communications (CPI-C).
  48.  
  49.   ATELL is made up of two transaction programs; ATELL, which runs on the client
  50.   side, and ATELLD, which runs on the server side.
  51.  
  52.  
  53.   Using ATELL
  54.  
  55.   The simplest way to use ATELL is to specify only the destination and the
  56.   message.
  57.  
  58.     ATELL destination Howdy, pardner.
  59.  
  60.   What you actually specify in place of "destination" is described below.
  61.  
  62.   This command will send the message "Howdy, pardner." to the destination
  63.   computer specified.  The ATELLD program on the destination computer will show
  64.   the message on the computer.  The method used for displaying the message may
  65.   vary on different operating systems.
  66.  
  67.   The following describes all of the ATELL parameters:
  68.  
  69.     ATELL ╒optional parameters■ destination message
  70.  
  71.   The destination and message are the only required parameters.  You may
  72.   specify any number of the additional parameters.  If you specify any
  73.   parameter more than once, the only the last parameter value will be used.
  74.  
  75.   PARAMETER EXPLANATION
  76.  
  77.   destination
  78.             Identifies the partner computer on which the ATELLD server program
  79.             runs.
  80.  
  81.             May be either a CPI-C symbolic destination name or a partner LU
  82.             name.
  83.  
  84.             If the destination is a CPI-C symbolic destination name, it must be
  85.             1 to 8 characters and must be configured in your platform's
  86.             symbolic destination name table (see Configuration Guide below).
  87.  
  88.             If the destination is a partner LU name, the format varies from
  89.             platform to platform.  See the Configuration Guide section for your
  90.             platform for more information about configuring and specifying
  91.             partner LU names.
  92.  
  93.   message
  94.             The message text to be sent to the destination computer
  95.  
  96.   -m mode_name
  97.             mode name (default: "#INTER")
  98.  
  99.   -t tp_name
  100.             the TP name to start on the partner (default: "ATELLD")
  101.  
  102.   -u userid
  103.             This is the userid that will be send to the partner.  The userid
  104.             can be 1-8 characters in length.  You should use this parameter
  105.             when the destination transaction program has been configured to
  106.             require security.  One indication that the destination transaction
  107.             program requires security is a CPI-C return code of
  108.             XC_SECURITY_NOT_VALID.
  109.  
  110.             Specifying this parameter implies the conversation will use CPI-C
  111.             security=PROGRAM.  A password must also be specified.  If a userid
  112.             is specified without a password, ATELL will prompt the user for a
  113.             password.
  114.  
  115.   -p password
  116.             This is the password that will be send to the partner.  The
  117.             password can be 1-8 characters in length.
  118.  
  119.   -n
  120.             This parameter forces ATELL to use NO security on the conversation.
  121.             (CPI-C security=NONE).  This should be used when you receive a
  122.             CPI-C return code of XC_SECURITY_NOT_VALID, but the destination
  123.             transaction program is not configured to require security.
  124.  
  125.  
  126.   CONFIGURATION GUIDE FOR ATELL
  127.  
  128.   The ATELL program consists of two sides:  the client computer side and the
  129.   server computer side.  On the client computer side, the user starts up the
  130.   ATELL program and specifies what actions should be taken.  As a result, the
  131.   ATELLD program is started on the server computer side.  The ATELL and ATELLD
  132.   programs then use communicate using CPI-C and complete the transaction.
  133.  
  134.   In order to get the client computer and the server computer to talk to each
  135.   other, both computers must be configured.  This configuration involves
  136.   defining certain APPC information to the ATELL programs and to the APPC
  137.   platform on the computer.
  138.  
  139.   The rest the Configuration Guide is divided into the following sections:
  140.  
  141.   o   APPC Configuration Overview
  142.  
  143.       This section describes the APPC information that must be provided to the
  144.       APPC platform.  If you are not familiar with APPC terminology or
  145.       configuration, you should read this section.
  146.  
  147.   o   Configuration Information for Specific Platforms
  148.  
  149.       These are the actual steps that should be done on the client computer and
  150.       server computer.  The directions are grouped by APPC platform.  You
  151.       should find the section for your platforms, and follow the steps
  152.       indicated.  The following platforms are described in this Configuration
  153.       Guide:
  154.  
  155.       -   Networking Services/DOS
  156.  
  157.       -   Networking Services/2 or Extended Services/2
  158.  
  159.  
  160.   APPC CONFIGURATION OVERVIEW
  161.  
  162.   In order to successfully communicate with APPC from one computer to another,
  163.   you need to configure some information in your APPC platform.  This
  164.   information consists of:
  165.  
  166.   o   How to physically connect to another computer.
  167.  
  168.       You tell your APPC platform how to physically connect to another computer
  169.       by defining a link.  The link definition tells APPC information about how
  170.       to connect to the partner computer, including data link control
  171.       information.  The data link control represents the physical connection
  172.       (token-ring, SDLC, Ethernet, etc.) between two computers.  To connect to
  173.       the partner computer, the APPC link definition specifies both a data link
  174.       control and addressing information specific to that data link control.
  175.       For example, if you are using token ring as your data link control, you
  176.       will need to specify a token ring address in your link definition.  Some
  177.       data link controls, may not require any address information, since the
  178.       partner computer is implied to be on the other end of the physical
  179.       connection.  This is common with SDLC leased lines.
  180.  
  181.   o   How to identify and find the correct server computer.
  182.  
  183.       Computers are identified in APPC by their fully qualified LU name.  The
  184.       fully qualified LU name consists of two parts: a network name and an LU
  185.       name, concatenated with a period.  For example:
  186.  
  187.           USIBMNR.NR55069I
  188.  
  189.       Both the client and server computers must have fully qualified LU names
  190.       defined.
  191.  
  192.       LU names are viewed relative to the computer on which they are defined:
  193.       there are local LUs and there are partner LUs which are on partner
  194.       computers.  The local LU name for any given computer is the partner LU
  195.       name as viewed from another computer, and vice versa.
  196.  
  197.       Each APPC platform must define at least one local LU, which must be
  198.       unique within the network.  Since there are only up to 8 characters with
  199.       which to create a unique LU name, this can be somewhat challenging in
  200.  
  201.       networks with many computers.  Some possible naming conventions for LUs
  202.       include:
  203.  
  204.       -   Assigning consecutive LU names (alphabetically increasing) under
  205.           central administration control.
  206.  
  207.       -   Incorporating something that is already unique to each computer.
  208.  
  209.           Examples include:
  210.  
  211.           --  Serial number of the computer
  212.  
  213.           --  Person number of the user
  214.  
  215.           --  Unique userid of the user
  216.  
  217.       On some APPC platforms, you must predefine the list of partner LUs that
  218.       the computer will be able to communicate with.  Other platforms allow you
  219.       to use any fully qualified LU name without having defined it beforehand.
  220.       The APPC platform will then dynamically find that LU in the network.
  221.  
  222.   o   What kind of connection should be made with the server computer.
  223.  
  224.       When the ATELL client program requests a connection with a partner LU,
  225.       the APPC platform establishes what is called a session between the local
  226.       LU and the partner LU.  The simplest session that can be established
  227.       occurs when the client computer and the server computer are directly
  228.       connected with a single APPC link.  The session goes directly from the
  229.       client computer to the server computer.
  230.  
  231.       If your network is larger and more complex, the client computer may be
  232.       connected to a network node computers rather than directly to the server
  233.       computer.  In this case, the session that is established may pass through
  234.       other computers in the network.  To add to the complexity, there may be
  235.       different paths through the network.
  236.  
  237.       The network will always choose the best path through the network for your
  238.       application.  Since different applications have different needs, APPC
  239.       provides a way for the application to specify the route characteristics
  240.       that are best for that application.  The application specifies a mode
  241.       name which contains all the routing characteristics required by the
  242.       application.  The characteristics associated with a mode include:
  243.  
  244.       -   Turnaround time
  245.  
  246.           How fast must data get through the network?
  247.  
  248.       -   Throughput
  249.  
  250.           How much data can get through the network?
  251.  
  252.       -   Cost
  253.  
  254.           Are you paying for physical connections between computers?
  255.       Two modes which are commonly supplied with APPC platforms are #BATCH and
  256.       #INTER.  The definition for #BATCH specifies a path with good throughput
  257.       characteristics.  The definition for #INTER specifies a path with good
  258.       turnaround time.  If your platform does not supply a definition for these
  259.       modes, you can either define them on your platform, or use some other
  260.       mode that is already defined by specifying the mode name when you start
  261.       the ATELL client program.
  262.  
  263.   o   How to identify and start the correct program on the server computer.
  264.  
  265.       When the client computer establishes a connection with the server
  266.       computer, the server computer must make that connection with a particular
  267.       server program.  To help the server computer identify the server program,
  268.       a transaction program name is sent from the client computer.
  269.  
  270.       The server program is identified by this transaction program (TP) name.
  271.       The TP name is a 1 to 64 byte string.  Becuase the actual execuable
  272.       program names can be different on various computers, the TP name is used
  273.       as a common identifier or an alias for the real program name.  In many
  274.       cases, the TP name and the real program name will be identical.
  275.  
  276.       On the client computer, the TP name is specified by the ATELL client
  277.       program and is the first thing sent by the client APPC platform to the
  278.       server APPC platform.  The client computer does need to have a TP name
  279.       definition configured.
  280.  
  281.       The server APPC platform then needs to know how to correlate the received
  282.       TP name with an actual program.  This is done through a TP definition,
  283.       which tells the server APPC platform which program should be started and
  284.       the application parameters and characteristics associated with the
  285.       program.  Some common things that can be configured are:
  286.  
  287.       -   The name and location (e.g., subdirectory) of the server program
  288.  
  289.       -   A list of users who can use the server program
  290.  
  291.       -   Parameters that should be passed to the program when it is started
  292.  
  293.  
  294.   PLATFORM SPECIFIC CONFIGURATION
  295.  
  296.   The following steps have been described for each APPC platform that ATELL has
  297.   been tested with:
  298.  
  299.   o   Networking Services/DOS
  300.  
  301.   o   Networking Services/2 and Extended Services/2
  302.  
  303.   Each platform will have the following information:
  304.  
  305.   o   General configuration tools
  306.  
  307.       -   Where and how configuration changes are made
  308.  
  309.       -   How to make your configuration changes take effect
  310.  
  311.   o   Configuration common to client and server computers
  312.  
  313.   o   Configuration specific to the client computer
  314.  
  315.       How to specify and identify where your server is and how to reach your
  316.       server.
  317.  
  318.   o   Configuration specific to the server computer
  319.  
  320.       How to specify which clients can use the server and what server program
  321.       to start for when the TP arrives.
  322.  
  323.   Each platform also requires data link control configuration information.  In
  324.   all of the examples, token ring data link control configuration will be
  325.   shown.  For information about configuring other data link controls, see the
  326.   documentation for the specific platform.
  327.  
  328.  
  329.   Configuration for Networking Services/DOS
  330.  
  331.   o   General configuration tools
  332.  
  333.       -   Where and how configuration changes are made
  334.  
  335.           All configuration changes for Networking Services/DOS are made in the
  336.           Networking Services/DOS configuration file.  To make changes to your
  337.           configuration, you must edit the Networking Services/DOS
  338.           configuration file according to the directions below.  The default
  339.           configuration file is named CONFIG.NSD and is usually in the \NSD
  340.           subdirectory.  You may use another file name, but you will have to
  341.           specify that name explicitly when you use the NSD command (see
  342.           below).
  343.  
  344.       -   How to make your configuration changes active
  345.  
  346.           After you have edited your Networking Services/DOS configuration
  347.           file, you should use the NSD command to start NSD and activate your
  348.           configuration changes.  If you are using the default configuration
  349.           file, you should use:
  350.  
  351.             nsd start
  352.  
  353.           If you are using another Networking Services/DOS configuration file,
  354.           you should use:
  355.  
  356.             nsd start FILENAME
  357.  
  358.   o   Configuration common to client and server computers
  359.  
  360.       -   Defining a local LU
  361.  
  362.  
  363.           Include an "nsdn" statement in your Networking Services/DOS
  364.           configuration file:
  365.  
  366.             nsdn USIBMNR.CLIENT_LU
  367.  
  368.           The name specified by the "nsdn" entry must be unique throughout your
  369.           network.
  370.  
  371.       -   Defining a partner LU
  372.  
  373.           --  If you are directly connected to your partner computer, include
  374.               "nsdc" and "trli" entries in your Networking Services/DOS
  375.               configuration file.  You must specify both the partner LU name
  376.               and the token ring destination address of the partner computer.
  377.               For example:
  378.  
  379.                 nsdc lan
  380.                 trli SERVER_LU,400000000001
  381.  
  382.           --  If you are connected to your partner computer through a network
  383.               node, "nsdc,"  "trli," and  "adrs" entries in your Networking
  384.               Services/DOS configuration file.  For example:
  385.  
  386.                 nsdc lan
  387.                 trli NN_LU,600000000002
  388.                 adrs SERVER_LU,NN_LU
  389.  
  390.               In this example, we specify a physical connection to our network
  391.               node, specifying the LU name of the network node (NN_LU) and the
  392.               token ring destination address.  We then specify that the LU name
  393.               SERVER_LU can be reached through the network node NN_LU.
  394.  
  395.           In both cases, change the token ring destination address in the
  396.           example to the address of the partner computer you are connecting to.
  397.  
  398.       -   Defining a link to a partner computer or to the network node
  399.  
  400.           The definition of the link has already been done in the partner LU
  401.           section above.
  402.  
  403.       -   Defining a mode
  404.  
  405.           Since Networking Services/DOS has already defined the IBM supplied
  406.           mode names, including #INTER, no mode definitions on Networking
  407.           Services/DOS are needed for ATELL.
  408.  
  409.   o   Configuration specific to the client computer
  410.  
  411.       No special configuration is needed for &nsd.  to configure the ATELL
  412.       client.
  413.  
  414.   o   Configuration specific to the server computer
  415.  
  416.  
  417.       Networking Services/DOS does not support server transaction programs at
  418.       this time.
  419.  
  420.  
  421.   Configuration for Networking Services/2 and Extended Services/2 (OS/2)
  422.  
  423.   o   General configuration tools
  424.  
  425.       -   Where and how configuration changes are made
  426.  
  427.           To configure Networking Services/2 and Extended Services/2 use either
  428.           the Configuration Management panels or edit the Node Definitions File
  429.           (NDF).  Although the following examples show Node Definitions File
  430.           commands, you can enter the same information on the Configuration
  431.           Management panels.  Your Node Definitions File file will have the
  432.           same filename as your Communications Manager configuration file, but
  433.           with a file extension of "NDF."
  434.  
  435.       -   How to make your configuration changes active
  436.  
  437.           You must verify the configuration file after changes are made to the
  438.           configuration.  If you have edited the Node Definitions File, run
  439.           APPNV from an OS/2 Command prompt with the /e option to verify and
  440.           update your configuration.  For example:
  441.  
  442.             appnv WRKBASE.NDF /e
  443.  
  444.   o   Configuration common to client and server computers
  445.  
  446.       -   Defining a local LU
  447.  
  448.           During the Networking Services/2 and Extended Services/2 installation
  449.           process, at least one local LU was configured.  This is the LU that
  450.           will be used when you run the ATELL client.  When your computer is
  451.           acting as a server, this is the LU name that should be configured on
  452.           the client platform as the partner LU.
  453.  
  454.           You can find your local LU in the DEFINE_LOCAL_CP command In the
  455.           following Node Definitions File excerpt:
  456.  
  457.               define_local_cp  fq_cp_name(USIBMNR.CLIENT_LU)
  458.                                cp_alias(mylu)
  459.                                node_id(x'50000')
  460.                                node_type(en);
  461.  
  462.           The local LU is USIBMNR.CLIENT_LU.
  463.  
  464.       -   Defining a partner LU
  465.  
  466.           Since both Networking Services/2 and Extended Services/2 support
  467.           APPN, you do not need to define partner LU names.
  468.  
  469.           When your computer is the client, you will simply need to specify the
  470.           fully qualified name of your partner LU.  This fully qualified name
  471.           includes the network name and LU name concatenated with a period.  To
  472.           enable any partner to call you when your computer is a server, make
  473.           sure your Node Definitions File contains the following:
  474.  
  475.               define_defaults  implicit_inbound_plu_support(yes);
  476.  
  477.           An additional feature of defining partner LUs is that you can provide
  478.           an alias for the actual partner LU name.  For example, you could
  479.           define "server" to be an alias for USIBMNR.SERVER_LU.  Alias are case
  480.           sensitive; "SERVER" is a different alias than "server."
  481.  
  482.           If you choose to define partner LUs, either to provide an alias for
  483.           use when running the ATELL client, or to restrict the names of
  484.           partner clients that can contact you, use a "define_partner_lu"
  485.           command as follows:
  486.  
  487.               define_partner_lu  fq_partner_lu_name(USIBMNR.SERVER_LU)
  488.                                  partner_lu_alias(server);
  489.  
  490.       -   Defining a link to a partner computer or to the network node
  491.  
  492.           --  To define a link directly to your partner, your Node Definitions
  493.               File should contain a "define_link" command,
  494.  
  495.                   define_logical_link  link_name(link)
  496.                                        fq_adjacent_cp_name(USIBMNR.SERVER_LU)
  497.                                        adjacent_node_type(len)
  498.                                        dlc_name(ibmtrnet)
  499.                                        adapter_number(0)
  500.                                        destination_address(x'400000000001')
  501.                                        cp_cp_session_support(no)
  502.                                        activate_at_startup(no);
  503.  
  504.           --  To define a link to your network node, your Node Definitions File
  505.               should contain a "define_link" command,
  506.  
  507.                   define_logical_link  link_name(link)
  508.                                        adjacent_node_type(nn)
  509.                                        dlc_name(ibmtrnet)
  510.                                        adapter_number(0)
  511.                                        destination_address(x'600000000002')
  512.                                        cp_cp_session_support(yes)
  513.                                        activate_at_startup(yes);
  514.  
  515.               Note that the CP name of the network node does not have to be
  516.               specified on the "define_link" command.
  517.  
  518.           In both cases, change the destination address in the example to the
  519.           address of the partner computer you are connecting to.
  520.  
  521.       In order to allow other computers to configure links to your computer,
  522.       you will need to give them your local token ring address.  To find out
  523.       your own token ring address, look in the ACSLAN.LOG file in the \CMLIB
  524.  
  525.       subdirectory.  Your token ring address appears in a line similar to the
  526.       following:
  527.  
  528.         Adapter 0 is using node address 400000000000.
  529.  
  530.   o   Configuration specific to the client computer
  531.  
  532.       No special configuration is needed for Networking Services/2 or Extended
  533.       Services/2 to configure the ATELL client.
  534.  
  535.   o   Configuration specific to the server computer
  536.  
  537.       -   Defining the TP
  538.  
  539.           Configure the ATELLD program as follows.  Make sure the "filespec"
  540.           specifies the directory where the ATELLD.EXE program resides.
  541.  
  542.             define_tp  tp_name(ATELLD)
  543.                        filespec(C:\SAMPLES\ATELL\ATELLD.EXE)
  544.                        tp_operation(nonqueued_am_started)
  545.                        program_type(vio_windowable);
  546.  
  547.           The "tp_operation" field indicates that a new copy of the ATELLD.EXE
  548.           program should be started for every new client.  The "program_type"
  549.           field indicates that the program should be run in an OS/2 Window.
  550.  
  551.           Note that TP names are case sensitive.  The ATELLD must be typed in
  552.           all upper case.
  553.  
  554.  
  555.   PROGRAMMER'S GUIDE
  556.  
  557.   This is a quick guide on how to recompile the source code on your platform.
  558.   You should only need to refer to this section if you did not receive the
  559.   executable code with ATELL, or if you are interested in making changes to the
  560.   ATELL source.
  561.  
  562.   See the appropriate makefile for your environment:
  563.  
  564.   MAKEFILE  ENVIRONMENT
  565.  
  566.   ATELL.OS2 Networking Services/2 or Extended Services/2 Only
  567.  
  568.             This makefile will build an OS/2 only executable.  You must have
  569.             the OS/2 Programmer's Toolkit installed.
  570.  
  571.   ATELL.FAM (Networking Services/2 or Extended Services/2) and Networking
  572.             Services/DOS
  573.  
  574.             This makefile will build a family API executable that will run in
  575.             either OS/2 or a DOS environment.  You must have the OS/2
  576.             Programmer's Toolkit installed, and both an OS/2 CPI-C platform
  577.             (Networking Services/2 or Extended Services/2) and Networking
  578.             Services/DOS
  579.   ATELL.DOS Networking Services/DOS Only
  580.  
  581.             This makefile will build a DOS mode executable.  The OS/2
  582.             Programmer's Toolkit is NOT required.
  583.  
  584.   All of these makefiles are written for Microsoft C 6.0.  If you would like to
  585.   use them with IBM C/2, you will need to change the warning flag from "/W4" to
  586.   "/W3."
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.