Daniel Becker Bighelini

SPEL API: BOP - Executables

Blog Post created by Daniel Becker Bighelini on Jun 13, 2016

Chapter 1

BOP - Executables

 

Table of Contents

Overview                                                                                                   

Daemons                                                                                                                                                        

Viewers                                                                                                                                                          

Utilities                                                                                                                                                          

Daemons                                                                                                    

bop_pdm_d                                                                                                                                                   

Methods                                                                                                                                                     

bop_tps                                                                                                                                                          

  1. bopbrowse.spl                                                                                                                                               

bpmgr                                                                                                                                                             

bpstat                                                                                                                                                              

boplgin                                                                                                                                                           

domsrvr                                                                                                                                                          

webengine                                                                                                                                                      

Viewers                                                                                                      

vbop                                                                                                                                                                

bop_cmd                                                                                                                                                        

bopmsg                                                                                                                                                           

pdmcgi                                                                                                                                                            

bop_mail                                                                                                                                                        

Utilities                                                                                                     

gfe                                                                                                                                                                   

bop_ddump                                                                                                                                                   

bop_ldump                                                                                                                                                    

bop_logging                                                                                                                                                   

bop_odump                                                                                                                                                   

bop_sinfo                                                                                                                                                    

bop_tps                                                                                                                                                        

 

 
 

Overview

 

This is a brief description of the components composing BOP.

Daemons

bop_pdm_d                 Interface to Problem Manager.

boplgin Validates user names and passwords.

domsrvr The domain server daemon.  provides object for application use.

webengine The daemon ...

Viewers

vbop                Displays and manages GUI applications

bop_cmd Handles executing interp fragments - command line.

bopmsg Sends a message to some bptrans process.

pdmcgi The cgi stub used in the web engine

bop_mail         script uses in mail daemon eater.

Utilities

bop_adump returns info about an attribute  Obsolete

bop_ddump returns dictionary information.

bop_ldump return info about domsets including what is in them

bop_logging Turn on message logging to a file. 

bop_odump dump info about an object instance (attr values)

bop_sinfo dump detailed schema info

bop_tps show threads running in a bop process

 
 

Daemons

bop_pdm_d

Daemon that acts as interface to problem manager and the outside world.

This daemon is started up as part of pdm_init.  You request services by  sendimg BOP messages to the well known object.  The slump name for this process is "bop_pdm_d". This daemon is expected to  grow over time.  The well known object name to send messages to  is "CAPI_OBJ" handles the methods that follow.

Methods 

list_methods(void)

provide a list of the methods this will handle.  Note the format is not standard.

Success Reply:     string method1,    string method2,    ...

 

send_request( string capi_string_to_forward)

Take the provided capi_string and send it to the capi.   If the capi is not running, we return an error string.  We should return an error code as well.  If the capi is running, we reply whatever is returned by the capi.  No error code is ever set.

Failure Reply:

error_code = 0  - "req_id =1  \nreq_stat=SYSTEM_FAILURE \nro ..."

                           (text is longer than shown here.

Success Reply:

               string whatever_the_capi_returns

 

kick_logrdr( int addressee, int alias, int type, int id)

When we update the log tables, we want to kick the log reader.  This messages does that for us.  Treat the variables as majic.

Reply:

         None, o,                                 "send_request" | ""

sending a message to the api_svr_nxd daemon.

sending a message to the notify_nxd daemon to kick the log_reader ui so the from isupdated.

The slump name for this process is "bop_pdm_d"

The well known object to send bop messages to is "CAPI_OBJ"

bop_tps

an executable that shows the status of threads in spell andwand code. Usage:

          bop_tps -h // help

          bop_tps process_name

          bop_tps -p process_name [id [id]]

 
 

bopbrowse.spl

spell code used by the utilities bop_odump and bop_ldump.

 

bpmgr

an executable used by bop_logging.

bpstat

an executable that dumps the number of objects in a process.

Usage:

          bpstat proc [object]

boplgin

Daemon to validate user names and passwords.  This is intended to be only used by the vbop app at this time and as such is not documented.

domsrvr

The business object repository.  Serves objects to various    applications.  The methods and behavior of this server is documented elsewhere.  We will discuss the flags it can be invoked with and some of the environment variables it cares about however.

Invocation:

               domsrvr -vso -lname  -n num -x num

-v = verbose mode.  all messages will be logged to domsrvr.log in the current directory.

-s = super verbose mode.  in addition, ref count info will be logged.

-o = original.  do not look in any mods directories for schema information or scripts.

-l = use the name provided as the server name (instead of domsrvr)1

-n = use the number provided as the minimum number of database agents to keep around.

-x = use the number provides as the maximum number of database agents to keep around

Useful environment variables.

NX_DSCONFIG = directory where we will find the majic and spel files. Default $NX_ROOT/bopcfg

NX_MODS = directory where we will find the mods files.    Default $NX_ROOT/site/mods

NX_BPTIMEOUT = how long to wait for a default timeout value Default 30 seconds

NX_DSSORT = a flag to say how internal sorting should work.  This should match the sort of the underlying data base.  Options are:  

         BINARY - use a binary sort on the characters

         EN     - English sort - case sensitive

         INTL   - International sort - case sensitive

         INTL_NOCASE - International sort - case insensitive

         EN_NOCASE - Englisg - case insensitive (Default)

 

webengine

The daemon that handles the web interface.    This is typically invoked using pdm_webinit.

Invocation:

          webengine -c filename -h path -f date_format -m initial_method

                    -t session_timeout -l license_timeout 

                    -D domsrvr_name  -C cgi_name -s

Note - This will be documented later.

 
 

Viewers

vbop

The GUI application for BOP.  The use of the app is noted elsewhere.    We cover useful flags here.    (To get usage, type vbop -P -r)  Invocation:

vbop

   [-D                           include line numbers]

   [-f func_name          Call wand function]

   [-x filename             fast-load file]

   [-c filename             compile output]

   [-t                             make tag helper file]

   [-P                            keep the same process - don't detach]

   [-S                            run in server mode don't exit when last form closes]

   [-s slump_name       use alternate slump name Allows multiple vbops]

   [-d domsrvr_name   use alternate domsrvr name]

   [-z                            kill a running viewer]

Initial dispobs or function args

bop_cmd

Execute a code fragment.  Type bop_cmd -h for detailed info.

Basically you provide a file name, and the method to initially call. The stuff about multiple threads, etc is not usually used.

bopmsg

A poor subset of bop_cmd.  Takes a message on the command line to send to some well known bop object. Invocation:

           bopmsg [-s] node proc obj method [args]

-s                                a flag to tell the program not to terminate after sending the message.  Not frequently used in production.

node proc obj              the address to send the message to.

method the method to call in the object

args                             the arguments to stuff in the message.  We send only strings and integers.  If the token starts with an inteter, it is an int unless it is quoted.  else it is a string.

 
 

pdmcgi

 

The cgi stub used in the web engine  This is very private and purposly not documented.

bop_mail

This script is called by the mail eater daemon to process email requests to the system.  Basically it bundles up info and invokes the bop_cmd program with the mail_eater fragment.

 
 

Utilities

gfe

Edits vr files for vbop.

bop_ddump

Returns lots of information about the database schema.  Basically walks the in-ram data dictionary and returns more information than you will ever need.  One useful piece for debugging however is a notation of how many instances of an object there are. 

Invocation:

         bop_ddump domsrvr_name [top_ob_name]

bop_ldump

Gives you content information about domsets in the system.  At this point only works on pre_load lists as it just gets the info, prints it, and exits.

bop_ldump domsrvr_name factory domset [dump_count [columns]]

This dumps both schema and content information on the named domset.

bop_logging

Turn on message logging.  This is a primary debugging tool!!! It dumps all messages to a log file for your examination.  Any bop process will recieve and handle this message.

         bop_logging domsrvr_name [-r (refcounts)] [-f filename] [on|off]

-r                                 says to log the refcount information as well as simple message int.

-f                                 filename is where to put the log file.  It must be fully pathed and the domsrvr must have write access.  -f is required to turn logging on

on | off                        turns the logging on or off

A sample output with annotation follows:

    1 Received Msg

    2 From: 141.202.211.64.domsrvr.

    3 To: 141.202.211.64.domsrvr.38DAAA

    4 BPMessage[ 2378879808.12201.32 ]

    5 {

    6          method = ob_val

    7          arg 0 = 18DAAA(4references)

    8          reply object = 18DAAA(4references)

    9          reply method = ob_val_reply

    10 }

    11

    12 Sending Msg

    13 From: 141.202.211.64.domsrvr.

    14 To: 141.202.211.64.domsrvr.18DAAA

    15 BPMessage[ 2378879808.12201.32 ]

    16 {

    17        method = ob_val_reply

    18        arg 0 = (string) INVALID

    19        arg 1 = (string) Required attribute missing.

    20        arg 2 = 38DAAA(4references)

    21        error code = -1

    22 }

    23

    24 Received Msg

    25 From: 141.202.211.64.domsrvr.

    26 To: 141.202.211.64.domsrvr.18DAAA

    27 BPMessage[ 2378879808.12201.32 ]

    28 {

    29        method = ob_val_reply

    30        arg 0 = (string) INVALID

    31        arg 1 = (string) Required attribute missing.

    32        arg 2 = 38DAAA(4references)

    33        error code = -1

    34 }

We note messages that are recieved and sent.  We show the from process,   and the two process and object_id.  For message (1) the obj_id is 38DAAA.  The full address for the object is    141.202.211.64.domsrvr.38DAAA.  (slump_Node, process, object_name).  We show the method we are calling (in this case ob_val) and show the reply_object and reply_method if any are defined.  This message is part    of an exclusive session shown by the [ 2378879808.12201.32 ]. 

The message reply is sent in the second message, and recieved in the third message.  Note the display of the error code.

bop_odump

Dump info about the attribute values in an object.  This is really     a shell script that invokes some spel code. 

Invocation:

         bop_odump domsrvr_name -p persid [columns]

               or

         bop_odump domsrvr_name factory_name where_clause [columns]

bop_sinfo

A generalixed tool to dump information about the domsrvr.  This is a shell script that wraps bop-cmd as well. This function is expected to change, so run with no args to get usage.

bop_tps

Another useful debugging tool.  Think of this is a thread ps (tps).  It shows the status of any threads (Started by the interpretor) in the application.

If the app (such as vbop_ was started with the -D flag, you will get more information from it.

 

Invocation:

         bop_tps slump_process_name

For bop_tps vbop-0x4E580000:shop-vac:0 )(on my box) I got

    ID STATUS               SOURCE                        PATH ->

    10 WAIT SLEEP           caller.wnd (-1)    root.call_mgr.main.caller

     38 COMPLETED            caller.wnd (-1)    root.call_mgr.main.caller

     41 FUNCTION CALL        caller.wnd (-1)    root.call_mgr.main.caller

 

This was without the -D option on.  It tells me id 10 is sleeping, id 38 is completed, but not yet cleaned up, and 41 is in a function call.

The path is the display tree from where the fork was done.

With the -D option, I get the following.

   ID STATUS               SOURCE                        PATH ->

    2 COMPLETED            caller.wnd (205)    root.call_mgr.main.caller

   19 FUNCTION CALL        caller.wnd (69)    root.call_mgr.main.caller

    65 WAIT SLEEP           caller.wnd (227)     root.call_mgr.main.caller

 

The difference is that my source is not the file/line number.  Much more useful.

Outcomes