/*@@file***********************************************************************
 *****************************************************************************
 *
 * DESCRIPTION:
 *  This is the IS/2 sample client program for the MVS/VTAM APPC interface. 
 *  This sample  is distributed "As Is" and without warranty. It is intended 
 *  to be used only as an example of how the functions of IS/2 can be 
 *  invoked using APPC on a MVS/VTAM system.
 *
 ****************************************************************************/

#ifdef  DOCUMENT

    This file contains all the information needed to build and execute the IS/2
    sample client program using APPC on an MVS/VTAM system. When used 
    in conjunction with the Interface Services/2 Programmer's Guide, 
    SC28-8258, the sample program will help you to understand IS/2 
    and the program structure requirements of APPC and Host Link/2.

FUNCTION:

    The function of APCVSAMP is to send two IS/2 transactions to the
    IS/2 Server, EA_AUTHORIZE, and EA_EXIT.  For each transaction
    APCVSAMP waits for the IS/2 response message and displays it on the
    console.  At the end of this sequence, the program terminates. The program
    can be re-executed as many times as desired.

    The program has two layers.  The top layer establishes the variables for
    IS/2 and APPC. It then calls the bottom layer to send an IS/2 transaction
    message to the IS/2 server. The lower layer establishes an APPC session
    with the Host Link/2 communication REM. It then sends the IS/2 transaction
    message, including the DAE destination routing information, and waits for
    the response message from IS/2.

COMPONENTS PROVIDED (as separate files):

    IS/2 Server side:

      eaappcv.cfg   Sample OS/2 APPC communication manager configuration file
      easerv2.cbs   Sample DAE configuration description file for server side

    Client side:

      apcvsamp.txt  Sample documentation and the sample listing (this file)
      eapivtam.asm  Sample VTAM interface  for apcvsamp.txt
      vtamlst.dat   Sample MVS/VTAM APPC communication configuration file

RELATED REQUIREMENTS:

    Run Time Environment Hardware requirements
    ---------------------------------------------------

    o   Two Systems running OS/2 1.2, CS/2 1.1, Host Link/2, and IS/2 as
        configured below.

    o   The Communication Manager configuration files, "eaappcv.cfg" and
        "vtamlst.dat" describe an SDLC connection between the two systems.
        Two SDLC adaptor, a modem eliminator, and two RS232C (25 pin) cable can
        be used to support this configuration.

    o   You may change "eaappcv.cfg & vtamlst.dat" to use other hardware, such
        as a Token-Ring, to connect the two machines if you prefer to run APPC
        in that environment. The two 'configuration' files must be changed 
        accordingly.

    Run Time Environment Network Software requirements
    --------------------------------------------------

    o   The system which runs IS/2 is designated as the 'server node'.
        The system running the user program is designated as the 'client node'.

    o   The 'server node' has to have the following software:
        1.  OS/2 EE Version 1.2
        2.  OS/2 EE Communication Manager Version 1.2
        3.  CS/2 Version 1.1
        4.  DAE APPC Communication REM (CS2APR00)
        5.  DAE Hostlink Server (CS2HTR00)
        6.  PlantWorks Execution Services/2 with CSD 1
        7.  PlantWorks IS/2 Version 1.0

    o   The 'client node' has to have the following software:
        1.  MVS
        2.  VTAM 3.2 or later

    Run Time Environment DAE Configuration requirements
    --------------------------------------------------------

    o   The 'server node' must be configured for DAE as follows:
        1.  NIB = "NODE5"
        2.  ACB = "CS2APR00.CS2NODE" (APPC Communication REM)
        3.  ACB = "CS2HTR00.CS2NODE" (Host Link/2 Server)
        4.  ACB = "EAPI.CS2NODE"     (PlantWorks IS/2 Server)
        5.  CACB= "CS2AP000.CS2NODE" (APPC CACB)
        6.  LCCB= "NODE5.CS2AP000"   (Local CCB)
            Inbound Server = standard
            Outbound Server = standard
        7.  RCCB= "HOST1.CS2AP000"   (Remote CCB)
            Inbound Server  = "CS2HTR00"
            Outbound Server = "CS2HTR00"
        8.  See 'easerv2.cbs' for more details

    o   The 'client node' has no DAE requirements

    Run Time Environment APPC Configuration requirements
    ----------------------------------------------------

    o   Copy "eaappcv.cfg" to the \CMLIB directory on the 'server node' for the
        OS/2 Communication Manager configuration. The following shows the
        highlights of that file:

        1.  SNA Base Profiles
            a.  Network Name:               "USMAS"
        2.  Data Link Profiles
            a.  SDLC, non-switched, non NRZI
            b.  Link Station Role:          "Secondary"
            c.  PU 2.0
            d.  Local station address       "C1"
        3.  Logical Unit Profiles
            a.  LU Alias Name:              "NODE5"
            b.  LU Name:                    "IMASB810"
        4.  Partner Logical Unit Profiles
            a.  Partner LU Alias Name:      "HOST1"
            b.  Fully Qualified Partner LU: "        .HOST1"
            c.  LU Alias:                   "NODE5"
            d.  PLU Session Limit:          "1"
        5.  Transmission Service Profiles
            a.  Mode Name:                  "CS2MODE"
        6.  Initial Session Limit Profiles
            a.  Contention Winner's Source:  "0"
            b.  Contention Losers Target:    "0"
            c.  PU 2.0
        7.  Remotely Attachable TP
            a.  TP Profile Name:            "NODE5"
            b.  TP Name:                    "NODE5"
            c.  TP Operation:               "Queued Operator Started"

    o   Add "vtamlst.dat" to the VTAMLIST on the 'client node'
        for the APPC configuration. The following shows
        the highlights of that file:

        1.  SNA Base Profiles
            a.  Network Name:               "USMAS"
        2.  Data Link Profiles
            a.  SDLC, non-switched, non NRZI
            b.  Link Station Role:          "Primary"
            c.  PU 2.0
        3.  Logical Unit Profiles
            a.  LU Alias Name:              "HOST1"
            b.  LU Name:                    "HOST1"
        4.  Partner Logical Unit Profiles
            a.  Partner LU Alias Name:      "NODE5"
            b.  Fully Qualified Partner LU: "        .NODE5"
            c.  LU Alias:                   "HOST1"
        5.  Transmission Service Profiles
            a.  Mode Name:                  "CS2MODE"
        6.  Initial Session Limit Profiles
            a.  Contention Winners Source:  "0"
            b.  Contention Losers Target:   "0"
            c.  PU 2.0
        7.  Remotely Attachable TP
            (none)

EXECUTION SEQUENCE:

    Before the sample program can be executed some PW variables must be
    defined. The sample assumes that a user ID and password and a PW item
    have been defined as described below:

    o   PlantWorks user identification

        1. User Name ID:  EAPIDEMO
        2. User Password: EAPIDEMO
           NOTE: This user ID should have 'full access'. See page 2-12 in the
           IS/2 Programmer's Guide for a description of how to do this.


    Once this task has been accomplished you are now ready to run
    the sample program. The following describes this process:

    o   Build the IS/2 Sample APPC Client Program with IBM C370 compiler

        1. Before uploading this file you must decide whether you want to
           convert the square brackets to 'tri-graphs' or use your own 
           codepage for the upload so the square brackets translate correctly. 
        2. Upload "apcvsamp.txt" and rename it to "apcvsamp c"
        3. Compile the program as the JCL in "csample.jcl"
        4. Upload and edit the "eapivtam.asm" into multiple Assembly files.
           Assemble these VTAM interface files as the JCL in "asmhsamp.jcl"
        5. Linkedit the C and interface program as the JCL in "linksamp.jcl"


    o   Startup the IS/2 Server Node

        1. Start the OS/2 Communication Manager
        2. Start the DAE System Software
        3. Start the PlantWorks Software
           with the IS/2 Server

    o   Startup the Sample program

        1. Verify the 'client node' VTAM/APPC,  modem should flash the transmit
           light
        2. Execute the program by as described in the CLIST file "apcvasmp.clt"

#endif  /* DOCUMENT */



/*
 *	Procedure to build and run the client program
 */
#ifdef   DOCUMENT                  	
//* ------ csample.jcl  File Begin here  -----	







//* Sample JCL to compile the C example
//USERNAMEC JOB '(4X8AB,60000)','EAPI/VTAM SAMPLE',NOTIFY=USERNAME,
//         MSGLEVEL=(1,1),MSGCLASS=X
/*JOBPARM PROCLIB=PROC03
//CC      EXEC EDCC,
//             INFILE='USERNAME.SIEAPI.C(APCVSAMP)',
//             OUTFILE='USERNAME.SIEAPI.OBJ(APCVSAMP),DISP=SHR',
//             CPARM='LIST,SHOW,SO,XREF,AGG',
//             VSCCHD='SYS1.',
//             CVER='C370.',
//             COMHD='SYS1.',
//             COMVER='PLI.',
//             COMLINK='LINKLIB'
//COMPILE.SYSLIB DD
//        DD DSN=USERNAME.SIEAPI.H,DISP=SHR
/*
//* ------ linksamp.jcl  File Begin here -----	







//* Sample JCL to linkedit the apcvsamp
//USERNAMEL JOB '(4X8AB,60000)','EAPI/VTAM LKED',NOTIFY=USERNAME,
//         REGION=512K,MSGLEVEL=(1,1),MSGCLASS=X
//LKED     EXEC PGM=HEWL,
//         PARM='SIZE=(384K,96K),XREF,LIST,LET,NCAL,AMODE=(31)'
//SYSPRINT DD SYSOUT=X
//SYSUT1   DD UNIT=VIO,SPACE=(32000,(60,60))
//SYSLIN   DD DDNAME=SYSIN
//SYSLMOD  DD DSN=USERNAME.SIEAPI.LOAD,DISP=OLD
//SYSLIB   DD DSN=SYS4.C370.V110.SEDCBASE,DISP=SHR
//         DD DSN=SYS4.PLIV22.SIBMBASE,DISP=SHR
//TCDCOBJ  DD DSN=USERNAME.SIEAPI.OBJ,DISP=SHR
//VTAMOBJ  DD DSN=USERNAME.VTAMSAMP.OBJ,DISP=SHR
//SYSIN    DD *
  INCLUDE TCDCOBJ(APCVSAMP)
  INCLUDE VTAMOBJ(VTAMINIT)
  INCLUDE VTAMOBJ(VTAMSEND)
  INCLUDE VTAMOBJ(VTAMRCV)
  INCLUDE VTAMOBJ(VTAMTERM)
  INCLUDE VTAMOBJ(VTAMUTIL)
  INCLUDE VTAMOBJ(VTAMQMGR)
  INCLUDE VTAMOBJ(VTAMRC)
  ENTRY CEESTART
  NAME APCVSAMP(R)
/*
/* ------ apcvsamp.clt  File Begin here */	







/* Sample C list to execute the APCVSAMP in foreground */
PROC 0
 CONTROL MSG CONLIST LIST NOFLUSH
 WRITE Running EAPI/VTAM APCVSAMP in foreground....
 FREE  DSNAME(SIEAPI.LOAD)
 ALLOC DDNAME(SYSOUT)  DSNAME(*)
 LOADGO 'USERNAME.SIEAPI.LOAD(APCVSAMP)', +
        LIB('SYS4.C370.V110.SEDCBASE', +
            'SYS4.PLIV22.SIBMBASE'),   +
        PRINT('USERNAME.SIEAPI.LIST')   +
        AMODE (31) LET MAP +
        EP(CEESTART) NAME(APCVSAMP)
 FREE  DDNAME(SYSOUT)  DSNAME(*)
 FREE  DSNAME(SIEAPI.LOAD)
END
#endif      /* DOCUMENT */                 
/* ------ apcvsamp.c  File Begin here */	







/*--------------------------------------------------------------------*/
/* ----           Starting of C program                        -------*/
/*--------------------------------------------------------------------*/
/* EAPI/VTAM demonstration sample 'C' program                         */
/*   Calling sample VTAM interface procedures                         */
/*   Performs an EAPI/Plantworks Authorize function                   */
/*   C/370 uses replacement characters '[' -> '??(' and ']' -> '??)'  */
/*--------------------------------------------------------------------*/
#pragma linkage(VTAMINIT, OS)
#pragma linkage(VTAMSEND, OS)
#pragma linkage(VTAMRCV,  OS)
#pragma linkage(VTAMTERM, OS)

main()
{
    char applname[8]="USMAS   "; /* VTAM application LU name  */
    char prtnerlu[8]="IMASB800"; /* VTAM APPC partner LU name */
    char modename[8]="CS2MODE "; /* Modetable name at partner */
    char hltpname[8]="NODE5   "; /* Hostlink alias at partner */
    int  rc, i;

    unsigned char earcvbuf[4000];
    short earcvlen;

    /* Temporary Definitions */
    struct ear_authorize
        {
        char rwa_orig[17];
        char rwa_dest[17];
        char rwa_type[1];
        char tid;
        char u_msg_id;
        char proc_type;
        char r2;
        char username[32];
        char password[32];
        } eamsg1 =
            {
          /* 123456789012345678*/
            "HOST1TP1.HOST1   ",
            "EAPI.NODE5       ",
            "B",
            1,0,3,0,         /* Authorize, msg 0, MVS client, rsvd */
            "EAPIDEMO",      /* PlantWorks Userid */
            "EAPIDEMO"       /* Password          */
            };

    /* Temporary Definitions */
    struct ear_exit
        {
        char rwa_orig[17];
        char rwa_dest[17];
        char rwa_type[1];
        char tid;
        char u_msg_id;
        short mode;
        } eamsg2 =
            {
          /* 123456789012345678*/
            "HOST1TP1.HOST1   ",
            "EAPI.NODE5       ",
            "B",
            2,1,1         /* EA_EXIT, msg 1, force exit  */
            };

    short eamsg1ll;

    struct eas_authorize
        {
        char tid;
        char u_msg_id;
        short status;
        };

    printf("Begin VTAM Demo Program\n");
    rc=VTAMINIT(applname, prtnerlu, modename);
    if (rc)
        {
        printf("Error in VTAMINIT, RC = <%X>\n", rc);
        exit(0);
        }

    /* Send EA_AUTHORIZE Message */
    printf("VTAM Demo - Sending EA_Authorize Message\n");
    eamsg1ll=sizeof(eamsg1);
    rc=VTAMSEND(prtnerlu, hltpname, modename, &eamsg1, &eamsg1ll);
    if (rc)
        {
        printf("Error in VTAMSEND, RC = <%X>\n", rc);
        exit(0);
        }

    earcvlen=sizeof(earcvbuf);
    rc=VTAMRCV(earcvbuf, &earcvlen);
    if (rc)
        {
        printf("Error in VTAMRCV, RC = <%X>\n", rc);
        exit(0);
        }
    printf("VTAM Demo - received data bytecount = %d\n", earcvlen);
    for (i=0; i<earcvlen; i++)
        printf("<%X>",earcvbuf[i]);
    printf("\n");
    /*
     *      Sending EA_EXIT message
     */
    printf("          - Sending EA_Exit Message\n");
    eamsg1ll=sizeof(eamsg2);
    rc=VTAMSEND(prtnerlu, hltpname, modename, &eamsg2, &eamsg1ll);
    if (rc)
        {
        printf("Error in VTAMSEND, RC = <%X>\n", rc);
        exit(0);
        }

    earcvlen=sizeof(earcvbuf);
    rc=VTAMRCV(earcvbuf, &earcvlen);
    if (rc)
        {
        printf("Error in VTAMRCV, RC = <%X>\n", rc);
        exit(0);
        }
    printf("VTAM Demo - received data bytecount = %d\n", earcvlen);
    for (i=0; i<earcvlen; i++)
        printf("<%X>",earcvbuf[i]);
    printf("\n");

    rc=VTAMTERM();
    printf("End EAPI/VTAM Demonstration Sample Program\n");
}
/* ------------- End of C program ------------------------------- */
/* ---- End of File     */ 
