home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / LUA.ZIP / LUA / LUA.DOC next >
Text File  |  1991-09-10  |  16KB  |  703 lines
  1.  
  2.  
  3.                  IBM EXTENDED SERVICES FOR OS/2
  4.         COMMUNICATIONS MANAGER API SAMPLE PROGRAMS SUPPORT
  5.  
  6.    (c) Copyright International Business Machines Corp., 1989, 1990,
  7.    1991
  8.  
  9.  
  10.  
  11.  
  12.    LUA SAMPLE PROGRAM
  13.  
  14.  
  15.    The LUA sample programs provide examples for writing application
  16.    programs using the LUA interface verbs. The function of the sample
  17.    programs is to communicate with a HOST using the LUA interface
  18.    verbs to SEND and RECEIVE data, SNA commands, and responses. The
  19.    sample scenario consists of an OS/2 program (secondary),
  20.    communicating with a HOST program (primary).
  21.  
  22.    NOTE: There is information included in the source module
  23.          header of VTAMPGMA.JCL, the HOST (primary) sample
  24.          program. You need to configure the  APPL  table
  25.          and  MODE  table entries before execution.
  26.  
  27.  
  28.    After compiling and linking, a user starts the secondary program,
  29.    supplying a filename and path at the OS/2 command prompt.
  30.    The primary sample program is started by submitting the
  31.    assemble, link, and go job to MVS.
  32.  
  33.    The secondary sample programs are designed to run only in
  34.    protected mode of IBM Extended Services for OS/2.
  35.    There are 3 equivalent secondary sample programs, where the
  36.    program source code and the supporting files are for C,
  37.    MASM, and COBOL languages. The primary sample
  38.    program source code language is 370 ASSEMBLER.
  39.  
  40.  
  41.    PREREQUISITES
  42.  
  43.    To run the sample programs, a user must obtain and be familiar
  44.    with the following:
  45.  
  46.    1.  OS/2 installation and program execution
  47.  
  48.    2.  TOOLKIT installation
  49.  
  50.    3.  Communications Manager installation
  51.  
  52.    4.  Compiler of the language(s) selected
  53.  
  54.    5.  Host VTAM and NCP configuration
  55.  
  56.  
  57.  
  58.  
  59.  
  60.                                                                          1
  61.  
  62.    HARDWARE REQUIREMENTS
  63.  
  64.    For this example configuration, ensure you have the following
  65.    hardware.
  66.    (a) a PS/2 containing a Multifunction Protocol Adapter, or
  67.        equivalent hardware (ie. PC-AT with SDLC adapter, etc.).
  68.    (b) either 2 modems or a modem eliminator with proper cabling.
  69.    (c) a Host connection with a 3725 Communication Control Unit or
  70.        equivalent communication equipment.
  71.  
  72.    If your hardware configuration is different, then you
  73.    must select the appropriate parameters on the Data Link Control
  74.    Profiles and Partner Logical Unit Profiles.
  75.  
  76.    Other Data Link types may be substituted where supported.
  77.  
  78.    INSTALLATION
  79.  
  80.    The installation for running LUA sample programs consists of the
  81.    following:
  82.  
  83.    1. Installing IBM Extended Services for OS/2 including
  84.       Communications Manager.
  85.  
  86.    2. Creating the LUA configuration file for the sample programs.
  87.  
  88.    3. Reinstalling Communication Manager using the user configuration
  89.       file created in step 2.
  90.  
  91.    4. Installing TOOLKIT
  92.  
  93.    5. Installing the compiler selected
  94.  
  95.    6. Host VTAM and NCP configuration
  96.  
  97.    ASSUMPTIONS
  98.  
  99.    The INSTALLATION DETAIL section explains the installation procedure.
  100.    It is assumed that Extended Services, TOOLKIT and the compiler
  101.    are installed on the same drive. For ease of discussion the C drive
  102.    is used as the default.
  103.  
  104.    INSTALLATION DETAIL
  105.  
  106.    1. INSTALLING IBM EXTENDED SERVICES FOR OS/2
  107.  
  108.    Install IBM Extended Services for OS/2 according to the
  109.    installation documentation provided with the product.
  110.    Install the Communications Manager and default configuration file
  111.    ACSCFG.CFG. Do NOT select Custom Install; do NOT select Basic
  112.    Configuration Services. Select "Configuration services" in the
  113.    "Install Additional Features" panel. Select "API data structures"
  114.    in the "Install Additional Features" panel to copy the API
  115.    structures to the \CMLIB directory. Select ACSCFG.CFG in panel
  116.    "Select Configuration file to Update CONFIG.SYS file".
  117.  
  118.    2. CREATING LUA SAMPLE PROGRAM CONFIGURATION FILE
  119.  
  120.    Use the configuration steps outlined below to create
  121.    configuration file for the secondary (ACSLUA.CFG).
  122.                                                                          2
  123.  
  124.  
  125.  
  126.  
  127.  
  128.    CONFIGURATION STEPS FOR LUA TO USE SDLC DLC
  129.  
  130.  
  131.    The following instructions will configure the Extended Services
  132.    machine to run the LUA sample programs. They guide you through the
  133.    configuration process, panel by panel, until complete.
  134.  
  135.  
  136.    On the secondary, copy the system supplied default configuration
  137.    file, ACSCFG.CFG, to ACSLUA.CFG in the C:\CMLIB directory.
  138.  
  139.  
  140.    Start Communications Manager on the secondary side using ACSLUA
  141.    as the startup configuration file.
  142.  
  143.  
  144.    Beginning at the "Communications Manager Main Menu" follow the
  145.    instructions below.
  146.  
  147.  
  148.    Press F10  to position to the Action bar
  149.    Select "Advanced" from action bar
  150.    Select "Configuration"
  151.  
  152.    Select "Workstation profile
  153.           (and auto-start options)"
  154.    Select "Change"
  155.    Specify "Machine type-
  156.             model number"
  157.    Specify "IBM plant of manufacture
  158.            -machine sequence number"
  159.    Select "Enable auto-start.." Yes
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.                                                                          3
  181.  
  182.  
  183.  
  184.    Select "SNA feature profiles"
  185.    Select "SNA base profile"
  186.    Select "Change"
  187.    Select "Auto-activate..."  No
  188.  
  189.    Select "Data Link Control (DLC)
  190.            profiles"
  191.    Select "SDLC"
  192.    Select "Number" Adapter 0
  193.    Select "Operation" Create
  194.  
  195.    Select "Load DLC"  Yes
  196.    Select "Free Unused Link"  No
  197.    Specify "Maximum RU size"       1024
  198.    Specify "Send window count"       7
  199.    Specify "Receive window count"    7
  200.    Select "Line type"  Non-switched
  201.    Select "Link station role"
  202.           secondary
  203.    Select "Line mode"  Line turnaround required
  204.    Select "NRZI"  Yes
  205.    Select "Modem rate"  Full speed
  206.    Specify "Local station address (in hex)"  C1
  207.  
  208.  
  209.    Select "SNA LUA Profiles"
  210.    Select "Create"
  211.    Specify "Profile name"  LUA1
  212.    Specify "Local (NAU) address"  02
  213.    Select "DLC type"  SDLC
  214.    Select "Adapter"  0
  215.  
  216.  
  217.    Press ESC to return to the Communication Configuration Menu.
  218.  
  219.  
  220.    Press F10 to position to the Action bar
  221.    Select "Verify" from action bar
  222.    Select "Run verify"
  223.  
  224.  
  225.    Press F10 to position to the Action bar
  226.    Select "Exit" from action bar
  227.    Select "Exit communication
  228.           configuration"
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.                                                                          4
  241.  
  242.  
  243.  
  244.  
  245.    3. REINSTALLING COMMUNICATION MANAGER USING THE
  246.       USER CONFIGURATION FILE
  247.  
  248.  
  249.    Communication Manager needs to be reinstalled, using the
  250.    user configuration file created in step 2, by issuing the REINST
  251.    command. Refer to the IBM Extended Services for OS/2
  252.    installation manual for instructions on using this command.
  253.  
  254.    During reinstallation of Communication Manager, select
  255.    "User configuration files and features" in the
  256.    "Communications Manager Install Menu" panel.
  257.    Select ACSLUA.CFG in the "Select Configuration File to
  258.    update CONFIG.SYS File" panel.
  259.  
  260.  
  261.    YOU MUST RESTART YOUR SYSTEM (ALT+CTRL+DEL) FOR CHANGES TO TAKE EFFECT.
  262.  
  263.    4. INSTALLING TOOLKIT
  264.  
  265.    Install TOOLKIT using its installation procedure.
  266.  
  267.    5. INSTALLING THE COMPILER
  268.  
  269.    Install the compiler of the language in which you are
  270.    interested.  Use the installation procedure of the compiler.
  271.    Refer to the following SUPPORTED LANGUAGES section for
  272.    additional information.
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.                                                                         5
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.    SUPPORTED LANGUAGES
  300.  
  301.    1.  C LANGUAGE
  302.  
  303.        a.  C SAMPLE PROGRAM
  304.  
  305.            The C sample program and the following instructions
  306.            are for Microsoft C version 6.0.
  307.  
  308.            There is one 'C' language LUA sample program for the
  309.            secondary which is called LUASAMPC. Copy this file
  310.            into directory C:\C600. The files to be copied are
  311.            Source code (.C extension), Module definition
  312.            (.DEF extension), Make file (no extension), and Link
  313.            response (.LRF extension).
  314.  
  315.            All the INCLUDE files are required in \C600\INCLUDE
  316.            directory. Copy the files LUA_C.H and ACSSVCC.H from the
  317.            Communications Manager directory (C:\CMLIB) into the
  318.            \C600\INCLUDE directory. Also copy DOSCALLS.H from
  319.            C:\TOOLKTxx\C\INCLUDE directory into \C600\INCLUDE
  320.            directory.
  321.  
  322.        b.  LIBRARY FILES FOR C SAMPLE PROGRAM
  323.  
  324.            For this example, all the LIBRARY files must reside
  325.            in \C600\LIB directory.  Copy ACS.LIB from the
  326.            Communications Manager directory (CMLIB) into
  327.            the \C600\LIB directory and DOSCALLS.LIB from the
  328.            OS/2 directory (OS2) into the \C600\LIB directory.
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.                                                                         6
  352.  
  353.  
  354.  
  355.  
  356.        c.  COMPILE/LINK C SAMPLE PROGRAM
  357.  
  358.            You must set up the environment for the Microsoft C compiler
  359.            in order to use it; refer to the installation documentation
  360.            provided with the product for instructions.
  361.  
  362.            Language extensions must be enabled in order for the C
  363.            compiler to recognize the "pascal" and "far" keywords.
  364.            Therefore, note that the compiler option /Za should NOT
  365.            appear either on the compiler command line input (e.g., in
  366.            the MAKE file) or in the environment setup file (e.g., in the
  367.            NEW-VARS.CMD file).  After setting up the environment variables
  368.            proceed as follows:
  369.  
  370.            Change your current directory to C:\C600
  371.  
  372.            To compile and link the secondary program, type the following
  373.            at the OS/2 command prompt:
  374.  
  375.              [C:\C600]nmake luasampc /r [Press Enter]
  376.  
  377.  
  378.            The file LUASAMPC.EXE will be created.
  379.  
  380.  
  381.            After the above procedure, the executable file LUASAMPC.EXE
  382.            is in directory C:\C600 in executable form.
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.                                                                         7
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.    2.  MACRO ASSEMBLER
  417.  
  418.  
  419.  
  420.        a.  ASSEMBLER SAMPLE PROGRAMS
  421.  
  422.            There is one 'MACRO ASSEMBLER' language LUA sample program
  423.            for the secondary which is called LUASAMPM. Copy this file
  424.            into directory C:\MASM\BIN. The files to be copied are
  425.            Source code (.ASM extension), Module definition (.DEF
  426.            extension), Make file (no extension), and Link response
  427.            (.LRF extension).
  428.  
  429.            All the INCLUDE files are required in \MASM\BIN directory.
  430.            Copy the files LUA_M.INC and ACSSVCA.INC from the
  431.            Communications Manager directory (C:\CMLIB) into \MASM\BIN
  432.            directory.  Also copy DOSCALLS.INC and SUBCALLS.INC
  433.            from C:\TOOLKTxx\MASM\INCLUDE directory into
  434.            \MASM\BIN directory.
  435.  
  436.  
  437.        b.  LIBRARY FILES FOR ASSEMBLER SAMPLE PROGRAM
  438.  
  439.            For this example, all the LIBRARY files must reside
  440.            in \MASM\BIN directory. Copy ACS.LIB from the
  441.            Communications Manager directory (CMLIB)
  442.            into the \MASM\BIN directory and DOSCALLS.LIB from the OS/2
  443.            directory (OS2) into the \MASM\BIN directory.
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.                                                                          8
  465.  
  466.  
  467.  
  468.  
  469.  
  470.        c.  ASSEMBLE/LINK ASSEMBLER SAMPLE PROGRAM
  471.  
  472.            Change your current directory to C:\MASM\BIN.
  473.  
  474.            To assemble and link the secondary program, type the
  475.            following at the OS/2 command prompt:
  476.  
  477.              [C:\MASM\BIN]make luasampm [Press Enter]
  478.  
  479.            The file LUASAMPM.EXE will be created.
  480.  
  481.  
  482.  
  483.  
  484.            After the above procedure, the executable file LUASAMPM.EXE
  485.            is in directory C:\MASM\BIN in executable form.
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.                                                                          9
  519.  
  520.  
  521.  
  522.    3.  COBOL LANGUAGE
  523.  
  524.  
  525.        a.  COBOL SAMPLE PROGRAM
  526.  
  527.            The COBOL sample program and the instructions below are
  528.            for the Micro Focus COBOL/2 compiler version 2.5.31 or
  529.            higher.
  530.  
  531.            There is one 'COBOL' language LUA sample program for the
  532.            secondary which is called LUASAMPO. Copy this file from
  533.            the LUA_CBL subdirectory on the sample program diskette
  534.            into directory C:\COBOL. The files to be copied are Source
  535.            code (.CBL extension), Module definition (.DEF extension)
  536.            and Link response (.LRF extension).
  537.            Also copy the command file (LUASAMPO.CMD) from
  538.            the LUA_CBL directory into directory C:\COBOL.
  539.  
  540.            Copy the include files LUA_C_C.CBL, LUA_C.CBL, LUA_C_O.CBL,
  541.            LUA_C_E.CBL, LUA_C_S.CBL, LUA_C_B.CBL, and ACSSVCB.CBL from
  542.            the C:\CMLIB directory to the C:\COBOL directory.
  543.  
  544.  
  545.        b.  LIBRARY FILES FOR COBOL SAMPLE PROGRAM
  546.  
  547.            For this example, copy DOSCALLS.LIB from the OS/2 directory
  548.            (OS/2) into the \COBOL directory.
  549.  
  550.  
  551.        c.  COMPILE/LINK COBOL SAMPLE PROGRAM
  552.  
  553.            Change your current directory to C:\COBOL
  554.  
  555.            To compile and link the secondary program, type the
  556.            following at the OS/2 command prompt:
  557.  
  558.              [C:\COBOL]luasampo [Press Enter]
  559.  
  560.            File LUASAMPO.EXE will be created.
  561.  
  562.  
  563.            After the above procedure, the executable file LUASAMPO.EXE
  564.            is in directory C:\COBOL in executable form.
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.                                                                         10
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.    6. HOST VTAM AND NCP CONFIGURATION
  587.  
  588.      a. Have an assembler available
  589.  
  590.      b. VTAM and NCP GEN to configure the line, PU, and LU for LUA.
  591.  
  592.      c. Modify the VTAM APPL table to include VTAMPGM.
  593.  
  594.      d. Modify the VTAM MODE table to include LUA768RU MODEENT.
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.                                                                         11
  643.  
  644.  
  645.  
  646.  
  647.    RUNNING THE SAMPLE PROGRAMS
  648.  
  649.  
  650.  
  651.    Create a new directory SAMPLE on the secondary side workstation.
  652.    Copy the secondary sample program (LUASAMPC.EXE, LUASAMPM.EXE,
  653.    or LUASAMPO.EXE) to the SAMPLE directory.
  654.  
  655.  
  656.    On the primary side, submit the assemble, link, and go, using
  657.    VTAMPGMA.JCL, uploaded to the HOST with the BINARY option.
  658.    Before submitting the VTAMPGMA program, the question marks in
  659.    the USER and PASSWORD fields on the JOB statement should be
  660.    replaced by your logon ID and password.
  661.  
  662.  
  663.    It is recommended that the primary sample program be started
  664.    prior to the secondary, in that the primary may take several
  665.    minutes to complete the assemble, link, and go steps.
  666.  
  667.  
  668.    Start Communication Manager on the secondary using the
  669.    configuration file ACSLUA.
  670.  
  671.  
  672.    Then switch to OS/2 Task Manager and select the OS/2 full screen
  673.    command prompt. Change the current directory to SAMPLE.  Start
  674.    your secondary program (LUASAMPC.EXE, LUASAMPM.EXE, or
  675.    LUASAMPO.EXE) with the filename of the SAMPLE program you
  676.    want to run.
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.                                                                         12
  702.  
  703.