CDS011 - Establish Dynamo Tools Environment

CDS011

Establish Dynamo Tools Environment

This program is used to establish the Dynamo Tools Environment within programs that are not launched from a Dynamo Tools menu or servlet such as a bbj stored procedure, trigger, or scheduled task. Note that it is not required when using the Dynamo Tools background script. If you do not call or run CDS011, then calls to other Dynamo Tools called routiines will most likely fail since they are dependent on a specific Dynamo Tools Environment.

Sessions that use CDS011 will appear in the Dynamo Tools Task Manager and Display System Status (SMS) in the Dynaweb and Background Tasks section.

CDS011 can either be run as the initial program when starting bbx (bbj or pro5) from a script such as background, a Dynaweb cgi script, or called at the beginning of a bbx application, bbj stored procedure, or trigger.

Whether run or called, the application should either RUN "CDS001" or CALL "CDS081","",-1 to exit the application and not just RELEASE. This will update the System Activity Log and update the list of active processes shown in Display System Status.

CDS011 will change the current directory to the base Dynamo Tools directory (SMSDIR), and set the prefix based on the prefix entries for the company code specified. It will also set SETOPTS based on the settings in Dynamo Configuration Maintenance (SMC). If it is necessary to change the current directory within an application, the prefix entries relative to SMSDIR will also need to be changed, and a new prefix entry added to access the Dynamo Tools data files stored in the SMSDIR directory.

When run as the initial program when starting bbx/bbj, arguments are passed via the pro5/bbj command line arguments.

Command Line Arguments (when run as the initial program when starting bbx/bbj)

Argument position
ARGV() Example name Required/Optional Usage

1 $basic_pgm Required Basic program to run. Use path relative to $SMSDIR

2 $company_code Required Two character Dynamo Company Code

3 $job_title Optional Job Title or Description. Replace any blanks with underscores. These will be replaced with blanks when seen in the Display System Status. Default is "Background Task" if not passed.

4 $userinfo Optional UserInfo can contain any user defined arguments (no spaces) that can be accessed within the application as ARGV(4).

$mode

Optional

Mode controls how data files are accessed.

`pro5`	start pro5 using normal pro5 file access (default option if not set)
`bbj`	start bbj using bbj file access (only used when there are no pro5 processes, or all pro5 processes access data using the bbj dataserver)
`bbjds`	start bbj, but use the pro5 data server for all file access (used when both bbx and bbj processes access the same data files). This will cause the `SMS_PRE` global to be set to `"/<localhost,port=1100>"` which is used by CDS095 when opening all files.

Calling Format (from bbx):

0100 REM "Program Name, date, description 0110 Y$="CD"; REM "Replace CD with your two character company code 0120 Y5$="Replace with your Job Title" 0130 CALL "/u/CDI/CD/CDS011",ERR=ERRMSG,Y$,Y5$,MSG$; REM "Establish Dynamo Tools Environment 0140 SETERR 8000; SETESC 8000 . . . 0990 CALL "CDS081",Y$,-1; REM "Delete System Activity record and RELEASE

8000 REM "Call Error/Escape Routine 8010 CALL "CDS063",STR(TCB(5)),Y$,PGM(-2) 8020 ON Y.ERRSTS GOTO 8030,8040,8050,8060 8030 SETERR 0 8040 RETRY 8050 RETURN 8060 RETRY 8900 ERRMSG: 8910 PRINT MSG$; REM "Log message to logs/bkg 8920 RELEASE

Calling Format (from bbj), including stored procedures and triggers.

REM "Program Name, date, description Y$="CD"; REM "Replace CD with your two character company code Y5$="Replace with your Job Title"
CALL "/u/CDI/CD/bbj/CDS011",Y$,Y5$,MSG$; REM "Establish Dynamo Tools environment
SETERR DT_ERRESC; SETESC DT_ERRESC

. . . CALL "CDS081",Y$,-1; REM "Delete System Activity record and RELEASE

DT_ERRESC: REM "Call Error/Escape Routine CALL "CDS063",STR(TCB(5)),Y$,PGM(-2) IF Y.ERRSTS=0 THEN SETERR 0 ELSE IF Y.ERRSTS=2 RETURN RETRY

Arguments (when called at the start of a bbx or bbj application)

ERR=ERRMSG Branch to this section when CDS011 encounters an error and cannot complete. Some possible messages include:
config file not specified in bbj stored procedure or trigger
config file does not contain required LPEXn printer alias entries
Unable to open Operator Information File CDSM01
Either Operator ID 'xxxxx' or 'cdi' must be defined in Operator Information File CDSM01

Y$ Pass in as two character company code. Passed back as templated Dynamo session control variable.

Y5$ Pass in as Job Title. The Dynamo System Activity File uses a program name that can be up to 6 characters long. If the stored procedure is longer than 6 characters long, then you may want to include the program name in Y5$ so that Display System Status will show the complete program name.

MSG$

Returned by CDS011 with error message should CDS011 not be able to run to completion. Note: when running bbj, this message will also be logged to the /u/basis/bbj/log/Debug log file.

Possible MSG$ values
Error NN running program XXXXXX from directory DDDDDDD with prefix PPPPPPP and company CC.
Either Operator ID XXXXXX or 'cdi' must be defined using Operator Information Maintenance (SMC).
Error NN trying to open Operator Information File CDSM01. DIR=DDDD PFX=PPPPPPPPPPPPPP
config.bbx file is required
config.bbx file is missing required LPEXn printers

When called, CDS011 will change the bbx home directory to $SMSDIR as specified in the /usr/cdi/.config file. It will set the PREFIX relative to the home directory to include CD/, XX/ and any additional prefix entries specified in Company Information Maintenance for the two character company code passed.

Example when run as initial program when starting bbx

#!/bin/sh # # Excellware, Inc. # # background # script run by cron to initiate background process # # usage: /u/CDI/bin/background pgm cc title usr mode logfile # where pgm is bbx/bbj program to run # cc is company code # title is jobtitle (replace blanks in title with underscores) # usr is an optional user field that can be accessed within # the program using ARGV(4) # mode is an optional field # pro5 or not specified - start pro5 # bbj - start bbj using bbj as file access # bbjds - start bbj, but use pro5 dataserver for all file access # logfile is an optional, fully qualified path to the log file # defaults to $SMSDIR/log/bkg if not passed # # Note: The basic program that is run should terminate itself # by RUNNING "CDS001" which will remove the terminal control record # before releasing. # # This script appends the current date, time, process ID, basic_pgm name, # as well as any program output to the LOGFILE.

# # On linux systems, the default LOGFILE is rotated monthly by the logrotate # task and controlled by the log rotate configuration file # /etc/logrotate.d/dt_bkg.

# # Note that the $SMSDIR/TEMP/BKGOUT logfile is no longer used. . /usr/cdi/.config [ -f /etc/vsifax3.sh ] && . /etc/vsifax3.sh PATH=$PATH:$SMSDIR/bin:/bin:/usr/bin:/etc:/usr/ucb export PATH umask 000 basic_pgm=$1 company_code=$2 job_title=$3 userinfo=${4:--} mode=${5:-pro5} LOGFILE=${6:-$SMSDIR/log/bkg} cd $SMSDIR mkdir -m 777 TEMP 2>/dev/null DATE=`date` USER=`uid` echo $DATE $USER $$ $basic_pgm $company_code $job_title $userinfo $mode >> $LOGFILE if [ $mode = "pro5" ] then EXEC=pro5 else EXEC=../bbj/bin/bbj fi ERRFILE=$SMSDIR/tmp/background.$$ nohup $BBXDIR/$EXEC -q -m4000 -c$BBXDIR/config.bbx CD/CDS011 - $basic_pgm "$company_code" "$job_title" "$userinfo" "$mode" >> $LOGFILE 2>$ERRFILE & if [ -s $ERRFILE ] then read msg <$ERRFILE echo -e "Unable to start background task: $msg" >> $LOGFILE echo -e "Unable to start background task\n\nJob Title: $job_title\nCompany Code: $company_code\nProgram Name: $basic_pgm\nError Message: $msg" | mail -s "Can't start background task $company_code" support@excellware.com fi rm $ERRFILE 2>/dev/null exit

Example when called from a bbj stored procedure.
Note that when called, the DT environment has not yet been set, so the full path name to CDS011 will be required.
Should CDS011 be unable to finish properly, it will log the message to the BBjServices.err log file, and EXIT 99.

REM "Setup Dynamo Tools Environment

Y$="RL" Y5$="Update Trailer" CALL "/u/CDI/CD/bbj/CDS011",Y$,Y5$,MSG$

... rest of stored procedure

CALL "CDS081",Y$,-1; REM "Delete System Activity record and RELEASE