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