# @(#)82	1.4  src/examples/svc/timop_svc/readme, examples.src, os2dce21.dss, 960602a.1  5/12/96  10:11:28
#
# COMPONENT_NAME:  examples.src
#
# FUNCTIONS: readme file for timop serviceability application example
#
# ORIGINS: 72/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.
#
# @OSF_COPYRIGHT@
# COPYRIGHT NOTICE
# Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc.
# ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE in the
# src directory for the full copyright text.
#
------------------------------------------------------------------------------
opt\dcelocal\examples\svc\timop_svc
------------------------------------------------------------------------------



		DCE Sample Application "timop_svc"


The contents of this file attempt to explain timop_svc -- what it does and
why it's here. It contains the following sections:


	 1. INTRODUCTION
	 2. OVERVIEW OF TIMOP_SVC
	 3. TIMOP_SVC FILES
	 4. BUILDING TIMOP_SVC
	 5. SETTING UP TO RUN TIMOP_SVC
	 6. TIMOP_SVC MESSAGE CATALOG
	 7. RUNNING THE TIMOP_SVC SERVER
	 8. RUNNING THE TIMOP_SVC CLIENT
	 9. SAMPLE SERVER OUTPUT
	10. TIMOP_SVC CLIENT OUTPUT
	11. STOPPING TIMOP_SVC
	12. TIMOP_SVC SERVER OPTIONS
	13. TIMOP_SVC CLIENT OPTIONS
	14. TIMOP_SVC PRINCIPAL AND KEYTAB NAMES
	15. TIMOP_SVC DEBUG MESSAGE LEVELS



--------------------------------------------------------------------------------------------
1.  INTRODUCTION


The timop_svc program is a new version of the "timop" example DCE appli-
cation program, which can still be found in its new location at:

     opt\dcelocal\examples\svc\timop_svc

The timop_svc version uses the new DCE Serviceability API to display server
information. It was developed mainly during the writing of the OSF DCE
Application Development Guide chapter on Serviceability. Although it was
not designed to be used for test purposes, it is included in the DCE 1.1
release as (it is hoped) a useful functional hand test for the interface.

Note that an additional very simple Serviceability hand test can be
found in:

    \opt\dcelocal\examples\svc\hello_svc

This program, when compiled and executed, does nothing more than print a
"Hello world" message to standard output, using the Serviceability inter-
face. Unlike timop_svc, hello_svc does not require you to have a DCE cell
up and running in order to successfully execute it. (It does however re-
require you to have the DCE Application Tools installed.

--------------------------------------------------------------------------------------------
2.  OVERVIEW OF TIMOP_SVC


In addition to its use of Serviceability, timop_svc differs in several
other ways from the original version of timop. The most significant of
these are the following:

       o It allows the user to specify string bindings instead of
	 importing server bindings from the namespace.

       o The timop_svc server assumes its own login identity: the
	 user no longer has to dcelogin as the server principal
	 before starting the server; however, the client still must
	 be started by a user dcelogin'd as the client principal.

       o Many more informational messages are printed by both server
	 and client.

       o Both server and client accept various command line switches
	 and options to enable or disable the various new features.
	 These options are all fully explained in the programs' usage
	 messages.

Although it is essentially an "enhanced" version of the original timop,
timop_svc does not conflict in any operational way with timop. It uses
a different IDL interface from timop's, and its server and client prin-
cipal names also are different from those of timop. You should thus be
able to run both programs in the same cell at the same time without
difficulty.

For fuller information on Serviceability functionality, see the IBM DCE
Application Development Guide -- Core Components volume. See also the
(the dcecp log object, through which the DCE components' serviceability
routes and settings are managed) reference page in the IBM DCE Command
Reference.


--------------------------------------------------------------------------------------------
3.  TIMOP_SVC FILES

The following files are contained in this subdirectory:


	readme       		-- this file
	makefile.os2		-- Makefile for building timop_svc  with IBM C 2.01 Compiler
	makefile.vc3		-- Makefile for building timop_svc with IBM Visual Age 3.0 Compiler
	makefile.bor		-- Makefile for building timop_svc with Borland C++ for OS/2 2.0 Compiler
	makefile.wat		-- Makefile for building timop_svc with Watcom C/C++ 10.5 Compiler
	timop_svc.idl		-- the IDL file
	timop_svc.acf		-- the ACF file
	timop_svc_aux.h 	-- auxiliary header file
	timop_svc_client.h	-- client header file
	timop_svc_client.c	-- client program
	timop_svc_client.def	-- client def file
	timop_svc_server.h	-- server header file
	timop_svc_server.c	-- server program
	timop_svc_server.def	-- server def file
	timop_svc_manager.c	-- manager routines
	timop_svc_refmon.c	-- server reference monitor
	timop_svc_svc.c 	-- svc remote interface routines
	tsv.sams		-- SAMS file with serviceability message
				   definitions
	timop_svc_setup_dcecp	-- a dcecp script to setup the namespace
				   and registry for timop_svc
	timop_svc_unsetup.dcecp -- a dcecp script to remove timop_svc's
				   entries from the namespace and registry

    client.bor     -- compiler options for Borland
    server.bor     -- compiler options for Borland
--------------------------------------------------------------------------------------------
4.  BUILDING TIMOP_SVC


Refer to the main Examples Readme file in opt\dcelocal\examples
for information on how to build these examples.


--------------------------------------------------------------------------------------------
5.  SETTING UP TO RUN TIMOP_SVC

Before you can run timop_svc, you must first setup your DCE cell with the
necessary security registry and namespace information for the program and
its client and server principal entities. You must also setup an authenti-
cation key table file on each of the machines on which you intend to run the
server. These tasks consist of the following steps:

  1. Adding the client and server principals to the Security registry.

  2. Creating a keyfile to be used by the server.

  3. Creating a CDS namespace entry for the server to export its binding infor-
     mation to (and for the clients to import binding information from).

  4. Setting up the correct permissions on the namespace entry to allow the
     server to use it (i.e., write to it) correctly.


These steps are essentially the same as those for the original timop; however,
for timop_svc, a pair of dcecp scripts have been included which, when run,
will automatically take care of doing (or undoing) all of the above steps.


Note: the dcecp setup script assumes that the timop_svc example will be run
      in a dce cell with a protection level of DES encryption or CDMF.
      If this is not the case, please comment out the following lines from
      the dcecp setup script:
	  puts "Creating keytab."
	  puts "keytab create timeop {-storage /tmp/tskeyfile}
		-data {tsserver plain 1 qwerty}
	  run_cmd {keytab create timeop {-storage /tmp/tskeyfile}
		-data {tsserver plain 1 qwerty}
      After running the dcecp setup script, create the keytab file using the
      ktadd command in rgy_edit, i.e.
	  dcelogin cell_admin -dce-
	  rgy_edit
	  ktadd -p tsserver -pw qwerty -f /tmp/tskeyfile

The name of the server's keyfile, /tmp/tskeyfile, is specified by the value
of the KEYFILE constant in the timop_svc_server.h file; the name you give to
the keytab create sub-command must be identical to the value of this constant.

Of course, you can substitute any legal CDS name for ts_entry.

The following examples show how to run the setup script:

  # dcecp timop_svc_setup.dcecp
  Usage: dcecp timop_svc_setup.dcecp <cdsentry-1> <cdsentry-2> ... <cdsentry-n>
	 -p <cell_admin passwd>

  # dcecp timop_svc_setup.dcecp /.:/ts_entry -p -dce-

  Logging in...
  Adding principals.
  principal create {tsserver tsclient}
  Adding principals to groups.
  group add none -member tsserver
  group add none -member tsclient
  Adding principals to organizations.
  organization add none -member tsserver
  organization add none -member tsclient
  Creating accounts.
  account create tsserver -group none -organization none -password qwerty
  -mypw -dce-
  account create tsclient -group none -organization none -password xyzzy
  -mypwd -dce-
  Adding CDS entries.
  rpcentry create /.:/ts_entry
  acl modify /.:/ts_entry  -entry -add user:tsserver:rwdtc
  Logging out.
  Creating keytab table.
  keytab create timeop -storage {/tmp/tskeyfile} -data {tsserver plain 1 qwerty}



To undo the setup, you can run the unsetup script, as shown in the following
example:

  # dcecp timop_svc_unsetup.dcecp
  Usage: dcecp timop_svc_unsetup.dcecp <cdsentry-1> <cdsentry-2> ... <cdsentry-n>
	 -p <cell_admin passwd>

 # dcecp timop_svc_unsetup.dcecp /.:/ts_entry -p -dce-

  Logging in...
  Deleting principals and accounts.
  principal delete {tsserver}
  principal delete {tsclient}
  Deleting CDS entries.
  Logging out.
  Deleting keytab entry


For further information about dcecp, see the IBM DCE Administration Guide --
Core Components, the IBM DCE Administration Reference, and the IBM DCE User's
Guide and Reference.


You have now finished the timop_svc setup.


--------------------------------------------------------------------------------------------
6.  TIMOP_SVC MESSAGE CATALOG


The DCE Serviceability API uses XPG4 message catalogs to store and retrieve
message text (the catalogs are generated by the DCE sams utility). Normally
the catalogs should be installed in their correct platform-specific location
for example, at

       opt\dcelocal\nls\msg

but the serviceability routines will, if they cannot find
a catalog there, default to the current working directory for them (if they
cannot find them there either, they will retrieve messages from the in-memory
table, if one has been defined by the application; see the Serviceability
chapter in the Application Guide for details). Thus you should be able to run
timop_svc successfully without doing any extra message catalog installation.


--------------------------------------------------------------------------------------------
7.  RUNNING THE TIMOP_SVC SERVER


To run timop_svc, you must first start the server, and then invoke one or
more clients to perform the timop_svc operation. An example of how to do
this follows. The timop_svc server assumes it's own identity. You do not
have to dcelogin as the server principal before starting the server.

On the machine on which you want to run the server, enter the following:

    $ dcelogin tsserver  qwerty
    $ timop_svc_server -e1 /.:/ts_entry

(Note that you should either start the server in the background, or in a
window different from the one in which you intend to run the client, or on
a separate terminal.)

The /.:/ts_entry is the name in the namespace that you want the server to
"have" (i.e., the name of the CDS entry to which it exports its bindings
and by means of which it is, therefore, known to clients). The entry was
set up when you ran the dcecp setup script earlier; it can have any name
of your choice.

The "-e1" specifies the object UUID that the server should export and
register its bindings with. Two object UUIDs are available, specified
to the server as -e1 or -e2. This allows you to have two servers running
at the same time (and even on the same machine) and yet be able to have
clients bind to the server of their choice, simply by specifying the
correct object number in the client command line (as will be seen below).
Even if you have two timop_svc servers exporting to different name entries,
if the servers are active at the same time, their exported partial bindings
will be identical if they are running on the same machine; requiring that
the bindings be exported and imported with an object UUID specified prevents
different server instances from getting mixed up.

The server will display a series of messages, most of them output through the
Serviceability API. For more information about these and how to control them,
see SAMPLE OUTPUT below. At the end of all this preliminary activity it will
display a "ready" message.


--------------------------------------------------------------------------------------------
8.  RUNNING THE TIMOP_SVC CLIENT


After you have invoked the server, wait until you get a message similar
to the following:

  1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
  Server /.:/ts_entry (object 1) ready...

(This is the serviceability form of the "Server ready" message displayed
by the timop server.)

You can now invoke the client (either in the same window, if you ran the
server in the background, or in a different window). Do:

    $ exit

--to get rid of your tsserver identity, if you are invoking the client
from the same window; then:

    $ dcelogin tsclient xyzzy
    $ timop_svc_client -o1 /.:/ts_entry

(Note again that you must first login as the timop_svc client principal before
invoking timop_svc_client.)

The "-o1" specifies that the client is to import the bindings registered
with object UUID 1, which is the object the server exported to. If the
server had specified "-e2", then the client would have had to specify
"-o2". If there were two servers active, and each had exported to a different
object, then clients could specify either object (or both) to import.

If all has gone well, the timop_svc client will now begin printing out results
continuously, until you stop it (see STOPPING TIMOP_SVC below on how to do
this).

On multiple machines in the same cell, you can try something like the
following:

    $ timop_svc_server -e1 /.:/ts_entry 		       # on machine A
    $ timop_svc_server -e2 /.:/xs_entry 		       # on machine B
    $ timop_svc_client /.:/ts_entry /.:/xs_entry /.:/ys_entry  # on machine D
    $ timop_svc_client /.:/ys_entry /.:/xs_entry /.:/ts_entry  # on machine E

Note that in order to do this, you will have to setup xs_entry and
ys_entry in the namespace first (by specifying these additional names
to the timop_svc_setup.dcecp script).


--------------------------------------------------------------------------------------------
9.  SAMPLE SERVER OUTPUT

Following is an example of the kind of server output you can expect to see if
you invoke the timop_svc server with full debugging enabled, and with service-
ability NOTICE type messages routed to standard error.

In general, the first groups of messages are output as a result of straight-
forward test calls to various routines; the later messages contain authentic
information being output via the serviceability interface. As explained above,
once the

  1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
  Server /.:/ts_entry (object 1) ready...

message appears, the server will wait, and the client(s) can then be started.
Once a client is started, the server will resume its messaging activity; the
copiousness of this will be determined by the debug level you specify (the de-
fault is no debug messaging) and the routing you have set. In the example im-
mediately following, the "Server ... ready" message is about the 16th from the
last; the subsequent messages represent a sample of what will happen once a
client has become active.

See the timop_svc source code (which is fully commented) for details of which
serviceability routines are called.

Refer to SERVER OPTIONS and CLIENT OPTIONS below for more information on how to
specify various aspects of timop_svc's behavior.

For fuller information on Serviceability functionality, see the IBM DCE
Application Development Guide -- Core Components volume.


			  FIRST SAMPLE OF SERVER OUTPUT

# ./timop_svc_server -d"tsv:*.9:STDERR:" -e1 /.:/ts_entry
	  Setting default route FATAL:TEXTFILE:/tmp/timop_svc_%ld ...
	  Setting default route ERROR:TEXTFILE:/tmp/timop_svc_%ld ...
	  Setting default route WARNING:TEXTFILE:/tmp/timop_svc_%ld ...
	  Setting default route NOTICE:STDERR: ...
	  Setting default route NOTICE_VERBOSE:TEXTFILE:/tmp/timop_svc_%ld ...
	  Number of debug routes specified is 1
	  Debug route index numbers and strings are...
	    1	tsv:*.9:STDERR:
1994-05-26-19:36:21.416+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
This is a test
This is the server
1994-05-26-19:36:21.485+00:00I----- ./timop_svc_server	tsv server 0x7aff3f20
This is the server
1994-05-26-19:36:21.524+00:00I----- ./timop_svc_server	tsv server 0x7aff3f20
This is a level 1 test debug message
1994-05-26-19:36:21.558+00:00I----- ./timop_svc_server DEBUG1 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 1 message
1994-05-26-19:36:21.571+00:00I----- ./timop_svc_server DEBUG2 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 2 message
1994-05-26-19:36:21.583+00:00I----- ./timop_svc_server DEBUG3 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 3 message
1994-05-26-19:36:21.597+00:00I----- ./timop_svc_server DEBUG4 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 4 message
1994-05-26-19:36:21.610+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 5 message
1994-05-26-19:36:21.622+00:00I----- ./timop_svc_server DEBUG6 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 6 message
1994-05-26-19:36:21.635+00:00I----- ./timop_svc_server DEBUG7 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 7 message
1994-05-26-19:36:21.648+00:00I----- ./timop_svc_server DEBUG8 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 8 message
1994-05-26-19:36:21.665+00:00I----- ./timop_svc_server DEBUG9 tsv server 0x7aff3f20
DCE_SVC_DEBUG level 9 message
1994-05-26-19:36:21.680+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
This is supposedly a harmless message...
1994-05-26-19:36:21.680+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
This is supposedly a harmless message...
1994-05-26-19:36:21.726+00:00I----- ./timop_svc_server	tsv server 0x7aff3f20
This is the server
1994-05-26-19:36:21.744+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling uuid_create()
1994-05-26-19:36:21.759+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_object_set_type()
1994-05-26-19:36:21.793+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_register_if()
1994-05-26-19:36:21.810+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_register_if(svc)
1994-05-26-19:36:21.823+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_use_all_protseqs()
1994-05-26-19:36:21.841+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_inq_bindings()
1994-05-26-19:36:21.857+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_inq_bindings()
1994-05-26-19:36:21.874+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Nr of timop_svc bindings received == 2
1994-05-26-19:36:21.891+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Nr of serviceability bindings received == 2
1994-05-26-19:36:21.952+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_binding_to_string_binding()
1994-05-26-19:36:21.967+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Full timop_svc binding in string form == ncacn_ip_tcp:<nnn>.<nnn>.<n>.<nn>[<nn>]
1994-05-26-19:36:21.999+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_string_free()
1994-05-26-19:36:22.012+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_binding_to_string_binding()
1994-05-26-19:36:22.073+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Full timop_svc binding in string form == ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
1994-05-26-19:36:22.089+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_string_free()
1994-05-26-19:36:22.103+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_binding_to_string_binding()
1994-05-26-19:36:22.122+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Full serviceability binding in string form == ncacn_ip_tcp:<nnn>.<nnn>.<n>.<nn>[<nn>]
1994-05-26-19:36:22.138+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_string_free()
1994-05-26-19:36:22.151+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_binding_to_string_binding()
1994-05-26-19:36:22.167+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Full serviceability binding in string form == ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
1994-05-26-19:36:22.183+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_string_free()
1994-05-26-19:36:22.198+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_register_auth_info()
1994-05-26-19:36:22.264+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_mgmt_inq_server_princ_name()
1994-05-26-19:36:22.278+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Principal name before the change is /.../<your_server>/tsserver
1994-05-26-19:36:22.292+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_string_free()
1994-05-26-19:36:22.306+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
creating login context...
1994-05-26-19:36:22.320+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling sec_login_setup_identity()
1994-05-26-19:36:24.319+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
getting secret key from /tmp/tskeyfile
1994-05-26-19:36:24.334+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling sec_key_mgmt_get_key()
1994-05-26-19:36:24.361+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
validating login context...
1994-05-26-19:36:24.375+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling sec_login_validate_identity()
1994-05-26-19:36:25.214+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
certifying identity info...
1994-05-26-19:36:25.227+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling sec_login_certify_identity()
1994-05-26-19:36:27.453+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
setting server context...
1994-05-26-19:36:27.468+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling sec_login_set_context()
1994-05-26-19:36:27.689+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_ep_register()
1994-05-26-19:36:28.022+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_ep_register(svc)
1994-05-26-19:36:28.155+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_ns_binding_export()
1994-05-26-19:36:31.758+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_ns_binding_export(svc)
1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Server /.:/ts_entry (object 1) ready...
1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server 0x7aff3f20
Server /.:/ts_entry (object 1) ready...
1994-05-26-19:36:32.958+00:00I----- ./timop_svc_server DEBUG5 tsv server 0x7aff3f20
Calling rpc_server_listen()
	  tsv_svc_inq_table() called!
1994-05-26-19:36:55.774+00:00I----- ./timop_svc_server DEBUG7 tsv remote 0x4001a600
Entering tsv_svc_inq_table()
1994-05-26-19:36:55.787+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Entering refmon()
1994-05-26-19:36:55.800+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Calling rpc_binding_inq_auth_client()
1994-05-26-19:36:55.813+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Checking authentication service
1994-05-26-19:36:55.826+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Checking protection level
1994-05-26-19:36:55.838+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Checking authorization service
1994-05-26-19:36:55.851+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Constructing full principal name
1994-05-26-19:36:55.863+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Calling dce_cf_get_cell_name()
1994-05-26-19:36:55.876+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Calling is_authorized()
1994-05-26-19:36:55.889+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Entering is_authorized()
1994-05-26-19:36:55.904+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Constructing full client principal name
1994-05-26-19:36:55.915+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Calling dce_cf_get_cell_name()
1994-05-26-19:36:55.919+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Returning IS_AUTHORIZED
1994-05-26-19:36:55.924+00:00I----- ./timop_svc_server DEBUG5 tsv refmon 0x4001a600
Returning GRANT_ACCESS
1994-05-26-19:36:55.928+00:00I----- ./timop_svc_server DEBUG7 tsv remote 0x4001a600
Calling dce_svc_table()


				 *******

The server can be invoked with various options and flags that affect its
operation and behavior in various ways (for a complete listing of server
options, see TIMOP_SVC SERVER OPTIONS below).

For example, if you specify the "-f" flag when invoking the server, the
serviceability filter mechanism will be turned on, and it will print vari-
ous messages about itself whenever it is executed (note that these messages
are NOT printed via the serviceability interface; the only reason messages
are coded at all is so that the output can server as a demonstration of how
the filter mechanism works):


			  SECOND SAMPLE OF SERVER OUTPUT

1994-06-12-14:41:04.073-04:00I----- ./timop_svc_server NOTICE tsv server 0xa44acad0
validating login context...
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Server sub-component
1994-06-12-14:41:05.923-04:00I----- ./timop_svc_server NOTICE tsv server 0xa44acad0
certifying identity info...
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Server sub-component
1994-06-12-14:41:09.543-04:00I----- ./timop_svc_server NOTICE tsv server 0xa44acad0
setting server context...
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Server sub-component
1994-06-12-14:41:16.143-04:00I----- ./timop_svc_server NOTICE tsv server 0xa44acad0
Server /.:/ts_entry (object 1) ready...
1994-06-12-14:41:16.143-04:00I----- ./timop_svc_server NOTICE tsv server 0xa44acad0
Server /.:/ts_entry (object 1) ready...
	  tsv_svc_inq_table() called!
	  tsv_svc_inq_components() called!
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Manager sub-component
1994-06-12-14:44:05.960-04:00I----- ./timop_svc_server NOTICE tsv manager 0x00541e50
Manager received call 1...
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Manager sub-component
1994-06-12-14:44:19.030-04:00I----- ./timop_svc_server NOTICE tsv manager 0x00541e50
Manager received call 2...
	  The value of filter_setting is TRUE
	  The progname is ./timop_svc_server
	  This is a Notice-type message
     Manager sub-component
1994-06-12-14:44:23.969-04:00I----- ./timop_svc_server NOTICE tsv manager 0x00541e50
Manager received call 3...



--------------------------------------------------------------------------------------------
10.  TIMOP_SVC CLIENT OUTPUT

The timop_svc client does not, of course, use the serviceability interface
to print messages; it simply uses the fprintf() and other calls employed by
the original timop program. (Note that timop_svc_client could have been re-
written to use the DCE messaging API with dce_printf() calls and message cata-
logs, but this wasn't done.) The client, when invoked, will print a series
of informational messages similar to what the original timop program printed,
with some enhancements. A sample follows:


		       FIRST SAMPLE OF CLIENT OUTPUT

# dcelogin tsclient xyzzy
# ./timop_svc_client -o1 /.:/ts_entry

 Timop_SVC Client: Binding to object 1...
 Timop_SVC Client: Importing...
 Timop_SVC Client: Imported stringized partial binding	   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncacn_ip_tcp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Imported stringized partial svc binding == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Importing...
 Timop_SVC Client: Imported stringized partial binding	   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]

 Sun Jun 12 18:37:51 1994 UTC (Z time zone)

 Timop_SVC Client: Stringized partial binding about to be used	   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Stringized partial svc binding		   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Calling (1) object 1...
 Timop_SVC Client: Received from: Server /.:/ts_entry at object 1...
			      /.:/ts_entry  1  18:37:51.683I0272.775	 27249

 Timop_SVC Client: Final Report:
				  (client)  *  18:37:51.649I0272.871	 27249

 Timop_SVC Client: Stringized full binding about to be used	== \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
 Timop_SVC Client: Stringized full svc binding			== \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
 Timop_SVC Client: Calling (2) object 1...
 Timop_SVC Client: Received from: Server /.:/ts_entry at object 1...
			      /.:/ts_entry  1  18:37:51.813I0272.776	 31219

 Timop_SVC Client: Final Report:
				  (client)  *  18:37:51.812I0272.804	 31219

 Timop_SVC Client: Stringized full binding about to be used	== \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
 Timop_SVC Client: Stringized full svc binding			== \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[<nn>]
 Timop_SVC Client: Calling (3) object 1...
 Timop_SVC Client: Received from: Server /.:/ts_entry at object 1...
			      /.:/ts_entry  1  18:37:51.893I0272.772	 21570

 Timop_SVC Client: Final Report:
				  (client)  *  18:37:51.884I0272.792	 21570



				 *******

The client, like the server, can be invoked with various switches and options.
Some of these affect the server's serviceability settings via the remote service-
ability interface (for a complete list of client options, see TIMOP_SVC CLIENT
OPTIONS below). The following example shows what should happen when the client
is invoked as in the example above, with an additional request for a list of
the server's serviceability sub-components, and a list of the DCE components
registered under serviceability:


		       SECOND SAMPLE OF CLIENT OUTPUT

# ./timop_svc_client -o1 /.:/ts_entry -l -C

 Timop_SVC Client: Binding to object 1...
 Timop_SVC Client: Importing...
 Timop_SVC Client: Imported stringized partial binding	   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Imported stringized partial svc binding == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncacn_ip_tcp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Importing...
 Timop_SVC Client: Imported stringized partial svc binding == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
       Subcomponent table size received is: 4...
       Subcomponent table contents are:
	  Name: server
	  Desc: timop_svc server
	  Msg Cat ID: 179a5026
	  Active debug level: 0

	  Name: refmon
	  Desc: timop_svc reference monitor
	  Msg Cat ID: 179a5027
	  Active debug level: 0

	  Name: manager
	  Desc: timop_svc manager
	  Msg Cat ID: 179a5028
	  Active debug level: 0

	  Name: remote
	  Desc: timop_svc remote routines
	  Msg Cat ID: 179a5029
	  Active debug level: 0

       Component table size received is: 3...
       Component table contents are:
	  tsv
	  rpc
	  cds

 Sun Jun 12 18:44:05 1994 UTC (Z time zone)

 Timop_SVC Client: Stringized partial binding about to be used	   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Stringized partial svc binding		   == \
    2541af56-43a2-11ca-a9f5-02608c0ffe69@ncadg_ip_udp:<nnn>.<nnn>.<n>.<nn>[]
 Timop_SVC Client: Calling (1) object 1...
 Timop_SVC Client: Received from: Server /.:/ts_entry at object 1...
			      /.:/ts_entry  1  18:44:11.270Iinfinity   7969247

 Timop_SVC Client: Final Report:
				  (client)  *  18:44:11.255Iinfinity   7969247




--------------------------------------------------------------------------------------------
11. STOPPING TIMOP_SVC

You must kill clients and servers by hand, either by using the interrupt key
or with a combination of the ps and kill commands. This will leave
server binding information in the endpoint map and namespace, which is normal
for persistent servers. The information can be removed by hand afterwards
by running the timop_svc_unsetup.dcecp script described above.


--------------------------------------------------------------------------------------------
12. TIMOP_SVC SERVER OPTIONS

The timop_svc server is invoked as follows:

  timop_svc_server [-w<svc_route> [-w<svc_route> ... ]] [-d"<dbg_route>" \
		   [-d\<dbg_route>" ... ]] [-D"<dbg_level>" \
		   [-D"<dbg_level>" ... ]] [-f] -e<nr> <entry_name>

where:
       -w<svc_route>	  (optional, one or more) Specifies a serviceability
			  routing.

       -d"<dbg_route>"    (optional, one or more) Specifies a serviceability
			  debug routing.

       -D"<dbg_level>"    (optional, one or more) Specifies a serviceability
			  debug level.

       -f		  (optional) Causes the serviceability filter to be
			  installed.

       -e1 or -e2	  Specifies the object entry this server instance is
			  using for export.

       <entry_name>	  Specifies the name of the entry to which this server
			  instance should export.



For fuller information on Serviceability functionality, the IBM DCE
Application Development Guide -- Core Components volume.


--------------------------------------------------------------------------------------------
13. TIMOP_SVC CLIENT OPTIONS

The timop_svc client is invoked as follows:

  timop_svc_client -o<nr> [ -o<nr> ... ] <server_entry> [ <server_entry> ... ] \
     [-D"<dbg_level>" [-D"<dbg_level>" ... ]] \
     [-d"<dbg_route>" [-d"<dbg_route>" ... ]] \
     [-w<svc_route> [-w<svc_route> ... ]] [-l] [-C] [-R] [-f]


or:


  timop_svc_client -o<nr> -b"<string_binding>" \
     [-D"<dbg_level>" [-D"<dbg_level>" ... ]] \
     [-d"<dbg_route>" [-d"<dbg_route>" ... ]] \
     [-w<svc_route> [-w<svc_route> ... ]] [-l] [-C] [-R] [-f]

where:

      -o1 or -o2	 Specifies the server object to bind to. There can be
			 up to 2 objects specified. [NOTE: this limit, and the
			 values of the object UUIDs, are defined in
			 timop_svc_aux.h. You can increase the number of
			 allowed objects by altering the contents of this file
			 and rebuilding timop_svc.]

      <server_entry>	 Specifies the name of the entry (of the server) to bind
			 to; there can be up to 10 <server_entry>s specified. If
			 you specify multiple servers and objects, the list of
			 servers and the list of objects must ordinally match.
			 [NOTE: this limit is specified in timop_svc_client.h.]

      <string_binding>	 Specifies a complete binding to use to make direct con-
			 tact with the server. Multiple servers cannot be speci-
			 fied with this option, and specifying a <server_entry>
			 with it is an error.

      -D"<dbg_level>"    (optional, one or more) Specifies a serviceability
			 debug level. For example:

			     -D"tsv:tsv_s_server.5,tsv_s_refmon.9"

			 or:

			     -D"tsv:*.9"

			 See TIMOP_SVC DEBUG MESSAGE LEVELS below for the sig-
			 nificance of the various available levels for timop_svc

      -d"<dbg_route>"    (optional, one or more) Specifies a serviceability
			 debug routing. For example:

			     -d"tsv:tsv_s_server.5:TEXTFILE:<pathname>"

			 or:

			     -d"tsv:*.8:STDERR:"

      -w<svc_route>	 (optional, one or more) Specifies a remote service-
			 ability routing.

      -l		 Specifies that the serviceability subcomponents be
			 listed.

      -C		 Specifies that all registered serviceability com-
			 ponents be listed.

      -R		 Specifies that the serviceability routings be listed.

      -f		 Specifies that the remote serviceability filter
			 routine be toggled.

For fuller information on Serviceability functionality, see the IBM DCE
Application Development Guide -- Core Components volume.


--------------------------------------------------------------------------------------------
14. TIMOP_SVC PRINCIPAL AND KEYTAB NAMES


  tsserver	  --  Server principal name [defined in timop_svc_aux.h]

  tsclient	  --  Client principal name [defined in timop_svc_aux.h]

  \tmp\tskeyfile  --  keytab pathname [defined in timop_svc_aux.h and
		      timop_svc_server.h]



--------------------------------------------------------------------------------------------
15. TIMOP_SVC DEBUG MESSAGE LEVELS

Up to nine different debug levels can be set (by means of the -D switch in the
server or client command line; see above). They have the following significance
in timop_svc:


    LEVEL		  MEANING

    1			  Used for test messages in "server" sub-component.

    2			  Used for test messages in "server" sub-component.

    3			  Used for test messages in "server" sub-component.

    4			  Used for test messages in "server" sub-component.

    5			  In "server", "manager", and "refmon" sub-components,
			   enables messages that are written at each DCE
			   library call.
			  In "manager" and "refmon", also enables messages
			   whenever local subroutines are entered or exited.
			  In "refmon", also enables messages describing values
			   about to be returned by local subroutines.

    6			  Used for test messages in "server" sub-component.

    7			  In "remote" sub-component, enables messages that
			   are written whenever a remote serviceability
			   routine is entered, as well as messages that
			   are written at each DCE library call.

    8			  Used for test messages in "server" sub-component.
    9			  Used for test messages in "server" sub-component.



For fuller information on Serviceability functionality, see the IBM DCE
Application Development Guide -- Core Components volume.


