/********************************************************************
 @(#)42    1.6  src/examples/xdsxom/readme, examples.src, os2dce21.dss, 960602a.1 3/6/96 11:40:51

 COMPONENT_NAME:  examples.src

 FUNCTIONS: Steps for building and/or executing the XDSXOM sample
            applications

 ORIGINS: 27

 (C) COPYRIGHT International Business Machines Corp. 1995
  All Rights Reserved
  Licensed Materials - Property of IBM

  US Government Users Restricted Rights - Use, duplication or
  disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

 ********************************************************************/

1.0 XDS EXAMPLE APPLICATIONS

    The XDSXOM samples are ADD_LIST, CDS_XMPL, EXAMPLE and THRADD.  They are
    intended primarily as coding examples, but can be executed if the local
    DCE cell is configured correctly.  The examples are built using the
    "all" command file or the command "one xdsxom".



2.0 DCE CONFIGURATION

    2.1 ADD_LIST
        * The local DCE cell name must be C=us/O=ibm/OU=austin.
        * Requires directory /.:/temp.

    2.2 CDS_XMPL
        * The local DCE cell name should be any valid DNS-style name
          (ex. os2_cell). It CANNOT be an X.500-style name.
        * The sample output assumes directories /.:/dceapps and
          /.:/dceapps/directory are used to store the objects.

    2.3 EXAMPLE
       * The local DCE cell name must be C=us/O=ibm/OU=austin.

    2.4 TELDIR2
       * The local DCE cell name can be either an X.500 or DNS-style name.
       * Requires a working directory such as /.:/temp.

    2.5 THRADD
       * The local DCE cell name must be C=us/O=ibm/OU=austin.
       * Requires directory /.:/temp.



3.0 ADDITIONAL REQUIREMENTS

    3.1 THRADD
        The THRADD example requires an auxiliary data file located in the
        same directory as THRADD.EXE.  The format of the file is one or more
        lines consisting of

            <first name> <last name> <phone number>

        without the <>s.  A sample file named "thradd.dat" is provided.

    3.2 TELDIR2
        * TELDIR2 requires the file "xschema" to be installed in \opt\dcelocal\etc.



4.0 RUNNING THE EXAMPLES

    4.1 ADD_LIST
        * No output is provided.


    4.2 CDS_XMPL [Option]
            where Option can be
                a - add entry name and attribute values
                r - read attribute values for a given name
                m - modify or add an attribute value for a given name
                l - list the objects and attributes in the specified directory
                d - delete entry name


        4.2.1  NOTES
            1) All objects are created in /.:/dceapps/directory.
            2) Objects are referenced as /.:/dceapps/directory/<first name>.
            3) When modifying attributes (-m option), if the specified old
               value for an attribute (group or phone number) cannot be
               matched a new attribute is added.


        4.2.2  ADD ENTRY {Sample dialogue with verification}
            F:\EXAMPLES\xdsxom [0] cds_xmpl a
            Please enter a valid CDS name?: /.:/dceapps/directory/First
            What is this person's phone number? 555-5555
            What group does this person work in (GDS/CDS/RPC/IDL... etc) ? IDL

            F:\EXAMPLES\xdsxom [0] cdscp list obj /.:/dceapps/directory/*
                                    LIST
                                  OBJECT   /.../os2_annv/dceapps/directory
                                      AT   1996-02-07-13:28:05
            First

            F:\EXAMPLES\xdsxom [0] cdscp show obj /.:/dceapps/directory/First

                                    SHOW
                                  OBJECT   /.../os2_annv/dceapps/directory/First
                                      AT   1996-02-07-13:28:23
                                 CDS_CTS = 1996-02-07-19:27:04.810000100/00-02-33-00-2a-f2
                                 CDS_UTS = 1996-02-07-19:27:05.530000100/00-02-33-00-2a-f2
                           1.3.22.1.3.73 = IDL
                           1.3.22.1.3.80 = 555-5555


        4.2.3  LIST ENTRY
            F:\EXAMPLES\xdsxom [0] cds_xmpl l
            Please enter a valid CDS name?: /.:/dceapps/directory
            name= First   phone= 555-5555    group= IDL


        4.2.4  READ OBJECT ATTRIBUTES
            F:\EXAMPLES\xdsxom [0] cds_xmpl r
            Please enter a valid CDS name?: /.:/dceapps/directory/First
            name= First   phone= 555-5555    group= IDL


        4.2.5  MODIFY OBJECT ATTRIBUTES {Sample dialogue with verification}
            F:\EXAMPLES\xdsxom [0] cds_xmpl m
            Please enter a valid CDS name?: /.:/dceapps/directory/First
            Modification Menu:

            1) modify Group name
            2) modify phone number
            Enter a menu number:
            1
            please enter the OLD group name to modify : IDL
            please enter the NEW group name: CDS

            F:\EXAMPLES\xdsxom [0] cds_xmpl r
            Please enter a valid CDS name?: /.:/dceapps/directory/First
            name= First   phone= 555-5555    group= CDS


        4.2.5  DELETE OBJECT {Sample dialogue with verification}
            F:\EXAMPLES\xdsxom [0] cds_xmpl d
            Please enter a valid CDS name?: /.:/dceapps/directory/First

            F:\EXAMPLES\xdsxom [0] cds_xmpl l
            Please enter a valid CDS name?: /.:/dceapps/directory
            Number of descriptors returned by om_get( subordinates ) was 0


    4.3 EXAMPLE
        * If executed successfully, the application writes theses lines to "stdio".
                Telephone number: 555-5555
                Telephone number: 555-6666


    4.4 TELDIR2

        4.4.1   DISPLAY OPTIONS
                F:\EXAMPLES\xdsxom [0] teldir2

                usage:  teldir2 [option]

                option:  a : add an entry
                         r : read an entry
                         d : delete an entry


        4.4.2   ADD ENTRY
                F:\EXAMPLES\xdsxom [0] teldir2 a
                What name do you want to add? /.:/temp/a-new-name
                What is this person's surname? Smith
                What is this person's phone number? (512)555-5555


        4.4.3   READ ENTRY
                F:\EXAMPLES\xdsxom [0] teldir2 r
                What name do you want to read? /.:/temp/a-new-name
                The phone number for Smith is (512)555-5555.


        4.4.4   DELETE ENTRY
                F:\EXAMPLES\xdsxom [0] teldir2 d
                What name do you want to delete? /.:/temp/a-new-name
                The entry has been deleted.


    4.5 THRADD [Option] [-f <filename>]
            where Option is
                d - delete entries in the auxiliary file, and
            <filename> = name of auxiliary file used in place of "thradd.dat".


        4.5.1  NOTES
            1) If option -d is omitted the auxiliary file is used to add entries.
            2) Cdscp list obj /.:/temp/* shows all of the entries added
               from the auxiliary file(s).
            3) Ccdscp show obj /.:/temp/<object name> shows the attributes
               of the named object.


        4.5.2  ADD ENTRIES
            F:\EXAMPLES\xdsxom [0] thradd
            entry added: First Person 555-1111
            entry added: Third Entry 555-3333
            entry added: Second Example 555-2222


        4.5.3  DELETE ENTRIES
            F:\EXAMPLES\xdsxom [0] thradd -d
            entry removed: First
            entry removed: Third
            entry removed: Second



5   RESTRICTIONS

    Extensive changes were required for compilation of the XDSXOM examples
    using Borland C++ 2.0 because macros using an embedded # operator(s) do
    not seem to be expanded correctly by the compiler.  The output of the
    preprocessor shows correct in-line substitution.
