home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / SRPI.ZIP / SRPI / SRPI.DOC
Text File  |  1991-10-24  |  14KB  |  499 lines
  1.  
  2.                      EXTENDED SERVICES VERSION 1.0
  3.             COMMUNICATIONS MANAGER API SAMPLE PROGRAMS SUPPORT
  4.  
  5.  
  6.    Version 1.0 (c) Copyright International Business Machines Corp., 1988, 1991
  7.  
  8.  
  9.    SRPI SAMPLE PROGRAMS
  10.  
  11.    The SRPI sample programs are provided as an example of how the SRPI
  12.    Send_Request interface verb can be used by a PC requester application
  13.    to invoke a server on the host.  The function of the sample programs
  14.    is to request records from a customer records data set on the IBM host
  15.    computer.  The IBM host computer sends the customer records to the
  16.    requester program for processing.  If the customer's balance in the
  17.    record is positive, the record is sent back to the server.  The server
  18.    puts the positive balance into an accounts receivable data set on the
  19.    IBM host computer.  To support this function, a sample PC requester
  20.    program, a sample host server program and a sample host data file are
  21.    provided.
  22.  
  23.    The sample programs are designed to work in the OS/2 protect mode, with
  24.    the Communications Manager of the Extended Services 1.0.  Sample program
  25.    source code and the supporting files are provided for the C, MASM, and
  26.    COBOL languages.  Since the sample programs are in source form, you will
  27.    need to go through additional steps to run these programs.
  28.  
  29.    RESTRICTIONS
  30.  
  31.    1.  The Communications Manager must be loaded with at least one
  32.        3270 terminal session configured for use with SRPI.
  33.  
  34.    2.  The sample server is based on the sample server source program
  35.        documented in the "Programmer's Guide to the Server-Requester
  36.        Programming Interface for VM/System Product".  The sample server
  37.        provided is used to run under VM/CMS environment only.  For a
  38.        sample server that will run under MVS environment, refer to the
  39.        "TSO Extensions Programmer's Guide to the Server-Requester
  40.        Programming Interface for MVS/Extended Architecture" for more
  41.        information.
  42.  
  43.    3.  The balance field in the customer record is in binary format and
  44.        it is non-displayable on VM in the sample customer data set.
  45.  
  46.    PREREQUISTES
  47.  
  48.    To run a sample program, you must be familiar with the following
  49.    things:
  50.  
  51.    1.  OS/2 installation and command prompt
  52.  
  53.    2.  Communications Manager installation
  54.  
  55.    3.  Compiler for the desired language
  56.  
  57.    4.  VM/CMS operation and commands
  58.  
  59.  
  60.  
  61.  
  62.                                                                         1
  63.  
  64.  
  65.    INSTALLATION
  66.  
  67.  
  68.    Install OS/2 and the Communications Manager according to instructions
  69.    in the documentation provided with the product.  When installing the
  70.    Communications Manager, use its full function installation procedure.
  71.    The 3270 Emulation and File Transfer feature groups of the
  72.    Communications Manager need to be installed.  Installation of these
  73.    features will copy the SRPI API structures, macros and object files to
  74.    the Communications Manager directory, which is \CMLIB.
  75.  
  76.    The compiler associated with the desired language also needs to be
  77.    installed using the installation procedure of that language compiler.
  78.    Refer to the following language sections for additional information.
  79.  
  80.  
  81.    SAMPLE REQUESTER PROGRAMS
  82.  
  83.    1.  C LANGUAGE
  84.  
  85.        The C sample requester program is called CSAMPL.C.
  86.  
  87.  
  88.        ■  ENVIRONMENT:
  89.  
  90.           NOTE: The C compiler must be installed with the "large model"
  91.                 library.
  92.  
  93.           After setting up the environment for C compiling, add C:\CMLIB
  94.           and C:\OS2 to the LIB and INCLUDE paths.  UUCCPRB.H,
  95.           SRPI_C.OBJ, and ACS.LIB are used from the CMLIB directory and
  96.           DOSCALLS.LIB is used from the OS2 directory.
  97.  
  98.  
  99.        ■  COMPILING AND LINKING:
  100.  
  101.           To compile and link the sample requester program, make the SRPI
  102.           API directory SRPI_C the current directory and execute the
  103.           following command at the OS/2 command prompt:
  104.  
  105.                  nmake -r csampl [press Enter]
  106.  
  107.           The executable file CSAMPL.EXE will be created.
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.                                                                         2
  126.  
  127.  
  128.  
  129.    2.  MACRO ASSEMBLER
  130.  
  131.        The MASM sample requester program is called MSAMPL.ASM.
  132.  
  133.  
  134.        ■  ENVIRONMENT:
  135.  
  136.           After setting up the environment for assembling, add C:\CMLIB
  137.           and C:\OS2 to the LIB and INCLUDE paths.  UUMCPRB.INC,
  138.           UUMINFAC.MAC, and ACS.LIB are used from the CMLIB directory and
  139.           DOSCALLS.LIB is used from the OS2 directory.
  140.  
  141.  
  142.        ■  COMPILING AND LINKING:
  143.  
  144.           To compile and link the sample requester program, make the SRPI
  145.           API directory SRPI_M the current directory and execute the
  146.           following command at the OS/2 command prompt:
  147.  
  148.                  make msampl [press Enter]
  149.  
  150.           The executable file MSAMPL.EXE will be created.
  151.  
  152.  
  153.    3.  COBOL LANGUAGE
  154.  
  155.        The COBOL sample requester program is called BSAMPL.CBL.
  156.  
  157.  
  158.        ■  ENVIRONMENT:
  159.  
  160.           After setting up the environment for COBOL compiling, add
  161.           C:\CMLIB and C:\OS2 to the LIB and INCLUDE paths.  SRPI_CBL.OBJ
  162.           and ACS.LIB are used from the CMLIB directory and DOSCALLS.LIB
  163.           is used from the OS2 directory.  Copy UUBCPRB.CBL from the
  164.           CMLIB directory into the SRPI API directory SPRI_CBL.
  165.  
  166.  
  167.        ■  COMPILING AND LINKING:
  168.  
  169.           To compile and link the sample requester program, make the SRPI
  170.           API directory SRPI_CBL the current directory and execute the
  171.           following command at the OS/2 command prompt:
  172.  
  173.                  bsampmak [press Enter]
  174.  
  175.           The executable file BSAMPL.EXE will be created.
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.                                                                         3
  189.  
  190.  
  191.    HARDWARE REQUIREMENTS:
  192.  
  193.    A 3270 terminal emulation (DFT) connection to an IBM host computer via
  194.    a SNA controller from an IBM Personal Computer AT using the IBM 3278/79
  195.    Adapter (DCA) or from a PS/2 using The IBM 3270 Connection adapter.
  196.  
  197.    NOTE: For non-DFT communications hardware requirements, refer to the
  198.    System Administrator's Guide.
  199.  
  200.  
  201.  
  202.    COMMUNICATIONS MANAGER CONFIGURATION:
  203.  
  204.    SRPI supports the following connections of the Communications
  205.    Manager:
  206.  
  207.    1.  3270 DFT terminal emulation
  208.  
  209.    2.  3270 non-DFT terminal emulation with the following connectivities:
  210.  
  211.          a) SDLC
  212.          b) Token Ring
  213.          c) X.25
  214.          d) IBM PC Network via 3270 Gateway
  215.          e) Etherand via 3270 Gateway
  216.          f) 3174 Peer Communicatons
  217.  
  218.  
  219.    For configuring and starting Communications Manager with the terminal
  220.    emulation connections above, refer to the "Extended Services Version 1.0
  221.    User's Guide" and "Extended Services Version 1.0 System Administrator's
  222.    Guide for Communications".
  223.  
  224.    As an illustration of the configuration process for SRPI, the following
  225.    instructions will guide you through the configuration process for a 3270
  226.    DFT SRPI session, panel by panel, until complete.  This will configure a
  227.    system for the following features to run the SRPI sample programs:
  228.  
  229.    1.  3270 terminal emulation (DFT) SNA connection
  230.  
  231.    2.  Server-Requester Programming Interface (SRPI) profiles
  232.  
  233.    NOTE: For non-DFT Communications configuration refer to the System
  234.    Administrator's Guide.
  235.  
  236.    Create a sample configuration file for the SRPI sample program using
  237.    the configuration services in Communications Manager by following
  238.    the instructions on the next few pages.
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.                                                                         4
  250.  
  251.  
  252.    CONFIGURATION STEPS
  253.  
  254.    On the PC that will run the sample program, copy the system-supplied
  255.    configuration file, ACSCFG.CFG, to SRPISMPL.CFG in the C:\CMLIB
  256.    directory.
  257.  
  258.      [C:\CMLIB]copy acscfg.cfg srpismpl.cfg [press Enter]
  259.  
  260.    Start the Communications Manager using SRPISMPL as the startup
  261.    configuration file, type the following at the OS/2 command prompt:
  262.  
  263.      [C:\CMLIB]cm srpismpl [press Enter]
  264.  
  265.    Beginning at the "Communications Manager Main Menu" follow the
  266.    instructions below.
  267.  
  268.    Press F10
  269.    Select (A) "Advanced" from action bar
  270.    Select (C) "Configuration"
  271.  
  272.    "Specify Configuration File Name"  [SRPISMPL] panel displayed
  273.    ENTER
  274.  
  275.    "Communication Configuration Menu" panel displayed
  276.    Select (f) "3270 feature profiles"
  277.  
  278.    "3270 Feature Configuration" panel displayed
  279.    Select (D) "DFT..."
  280.  
  281.    "Profile Operations" pop-up panel displayed
  282.    Select (C) "Create/Change"
  283.  
  284.    "Create/Change 3270 Profile" panel displayed
  285.    Select (C) "Connection..."
  286.  
  287.    "Select Adapter Type" pop-up panel displayed
  288.    Select the appropriate adapter for the machine you are
  289.           working on.  PS/2 = 3270 Connection
  290.           AT = 3278/79 emulation or Advanced 3270/79 ...
  291.    ENTER
  292.  
  293.    "Create/Change 3270 Profile" panel displayed
  294.    Select (S) "Session 1"
  295.    Select (T) "Terminal"
  296.  
  297.    "Create/Change 3270 DFT Logical Terminal Session Profile" panel displayed
  298.    Specify "Session ID"  to be "TEST"
  299.    Specify "Comment" to be "This is a sample logical terminal"
  300.    ENTER
  301.  
  302.    "3270 Feature Configuration" panel displayed
  303.    ESCAPE
  304.  
  305.  
  306.  
  307.  
  308.  
  309.                                                                         5
  310.  
  311.  
  312.    "Communication Configuration Menu" panel displayed
  313.    Select (S) "Server-Requester Programming
  314.                Interface (SRPI) profiles"
  315.  
  316.    "SRPI Profile Operations" panel displayed
  317.    Select (C) "Create"
  318.  
  319.    "Specify model profile and Server Alias" pop-up displayed
  320.    Specify "Model Profile" to be "3270"
  321.    Specify "Server Alias" to be "IBMABASE"
  322.    ENTER
  323.  
  324.    "Create/Change Server 3270 Profile" panel displayed
  325.    Specify "Server Name" to be "IBMABASE"
  326.    Specify "Comment" to be "This is a sample server"
  327.    Specify "3270 session ID"  to be "TEST"
  328.    ENTER
  329.  
  330.    "SRPI Profile Operations" panel displayed
  331.    ESC
  332.  
  333.    "Communication Configuration Menu" panel displayed
  334.  
  335.    Press F10
  336.    Select (V) "Verify" from action bar
  337.    Select (R) "Run Verify"
  338.  
  339.    The following message should appear:
  340.     "Verification of the configuration file is complete.
  341.      No errors occured... "
  342.    ENTER
  343.  
  344.    Press F10
  345.    Select (X) "Exit" from action bar
  346.    Select (X) "Exit Communication Configuration"
  347.  
  348.    "Communications Manager Main Menu" panel displayed
  349.  
  350.    Before running the sample SRPI program, exit and restart the
  351.    Communications Manager using SRPISMPL as the configuration file.  This
  352.    will allow the changes to take affect.
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.                                                                         6
  373.  
  374.  
  375.  
  376.    INSTALL SAMPLE SRPI SERVER:
  377.  
  378.  
  379.    To set up the sample server environment, two files are needed on the
  380.    IBM host computer:
  381.  
  382.       IBMABASE MODULE (the sample server)
  383.       INPUT FILE (the sample customer data set)
  384.  
  385.    The following instructions will guide you to properly install the SRPI
  386.    sample server on the host.
  387.  
  388.    From the "Communications Manager Main Menu", start the 3270 emulation
  389.    feature and log on to the specified session.  Create a new screen
  390.    group from the Program Selector menu on the PC.  At the OS/2 command
  391.    prompt, enter the following commands to upload the three host sample
  392.    files from the diskette:
  393.  
  394.       SEND A:IBMABASE.ASM TEST: IBMABASE ASSEMBLE A (ASCII CRLF RECFM F
  395.       SEND A:ALGABASE.EXC TEST: ALGABASE EXEC A (ASCII CRLF
  396.       SEND A:INPUT.FIL TEST: INPUT FILE A (LRECL 109
  397.  
  398.    Note: If the above files are not located on a diskette in drive A,
  399.    then enter the correct path inplace of the A:.
  400.  
  401.    After the file transfer completes, switch to the same 3270 session and
  402.    type ALGABASE at the VM/CMS command line to assemble and link.  This
  403.    will generate the executable sample server file with the name of
  404.    IBMABASE MODULE.
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.                                                                         7
  436.  
  437.  
  438.    RUNNING SRPI REQUESTER AND SERVER SAMPLE PROGRAMS
  439.  
  440.    Create a new directory SAMPLE on the PC where your requester sample
  441.    program will reside.  For C language, copy the file CSAMPL.EXE from
  442.    C:\IBMC2 to C:\SAMPLE subdirectory.  For PASCAL, copy the file PSAMPL.EXE
  443.    from C:\PASCAL to C:\SAMPLE subdirectory.  For MASM, copy the file
  444.    MSAMPL.EXE from C:\MASM\BIN to C:\SAMPLE subdirectory.  For COBOL, copy
  445.    the file BSAMPL.EXE form C:\PCOBOL\SRC to C:\SAMPLE subdirectory.
  446.  
  447.    Enter CMSSERV from the CMS command line in the 3270 session you just
  448.    started.  The IBM Enhanced Connectivity Facilities screen appears.
  449.    Switch to an OS/2 screen group and change the current directory to
  450.    SAMPLE.  Execute the sample requester program.  When the program
  451.    completes, switch back to the 3270 session with CMSSERV screen.  Press
  452.    PF3 key to end the communication between CMSSERV and your PC.  Verify
  453.    that there are two files generated in your 3270 session as a result of
  454.    the SRPI requester execution.  The names of these two files are OUTPUT
  455.    FILE and LOG FILE.
  456.  
  457.    The content of the OUTPUT FILE is listed below:
  458.  
  459.    Barttwell, Jim 300 Top Bend         Austin Texas   78759  1000-2000-3020
  460.  
  461.    The content of the LOG FILE is listed below:
  462.  
  463.    CUSTOMER RECORDS READ ***
  464.    Ahab, John     1000 High Circle       Austin Texas   78759  1000-2000-3000
  465.     ADMIN
  466.  
  467.    CUSTOMER RECORDS READ ***
  468.    Black, Edward  2000 Big Top Road   Austin Texas   78759  1000-2000-3010
  469.     ADMIN
  470.  
  471.    CUSTOMER RECORDS READ ***
  472.    Barttwell, Jim 3000 Top Bend       Austin Texas   78759  1000-2000-3020
  473.     ADMIN
  474.  
  475.    CUSTOMER RECORDS UPDATED
  476.    Barttwell, Jim 3000 Top Bend       Austin Texas   78759  1000-2000-3020
  477.    Barttwell, Jim 3000 Top Bend       Austin Texas   78759  1000-2000-3020
  478.     ADMIN
  479.  
  480.    WSCOMM RECEIVED BY SERVER
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.                                                                         8
  498.  
  499.