acmsdbx(1) — Commands
Digital
NAME
acmsdbx − Runs a source level debugger in the ACMSxp environment
SYNOPSIS
acmsdbx [ server-name [ tpsystem-name ]]
OPTIONS
Use the following input options on the acmsdbx command:
•server-name
Simple name of the task or processing server to be debugged. If you do not specify a server name, the server name specified in the ACMS_DEBUG_SVR environment variable is used and the name of the TPsystem is taken from the ACMS_DEBUG_TPSYSTEM environment variable. Any name you specify takes precedence over the environment variable.
If you do not specify a server name and either or both of the environment variables is not set, you see a message similar to the following:
ERROR - ACMS_DEBUG_SVR environment variable is not defined.
ERROR - could not get the command line options
•tpsystem-name
Simple name of the TPsystem under which the server runs. If you do not specify a TPsystem, the simple name of the TPsystem in the ACMS_DEBUG_TPSYSTEM environment variable is used.
If you do not specify a simple name of a TPsystem and either or both of the environment variables is not set, you see a message similar to the following:
ERROR - ACMS_DEBUG_TPSYSTEM environment variable is not defined.
ERROR - could not get the command line options
To locate the TPsystem, the acmsdbx software accesses the local TPsystem registry file. If there is a problem, you see a message similar to the following:
ERROR - Cannot open /var/opt/ACMSXPV301/acms_tpsystems.dat
ERROR - could not get the command line options
Verify that your user account has the correct access to the directory and that a TPsystem has been created on the system.
DESCRIPTION
The ACMSxp debugger acmsdbx allows interactive debugging of ACMSxp user-written client programs, ACMSxp tasks and the processing procedures called by those tasks. By default, dbx is used. Environment variables can select a debugger other than dbx.
The debugger executes and debugs task servers and processing servers within an ACMSxp run-time system. It creates an environment similar to normal system execution. The debugger performs functions necessary to manually start a server from within the ACMSxp environment, in preparation for a debugging session.
During the debugging session, all dbx commands are supported.
For debugging user-written client programs and user-written presentation servers, use an appropriate platform source-level debugging utilities, such as the debugger dbx.
Preparing to Debug
Before you begin a debugging session, you must:
1.Compile the tasks that you plan to debug, the task groups that contain those tasks, and the processing groups containing the procedures called by the tasks. You must use the −g command argument with the STDL compile command for all tasks in the task group to be debugged.
2.Build the task servers and processing servers from the compiled tasks, task groups, and processing groups.
3.Have in place an operational ACMSxp system established through system administration directives:
oExecute the acms_set_version script to set environment variables needed for ACMSxp to run.
oStart a TPsystem on the node on which debugging takes place. All system processes normally used by the TPsystem must be operational, including the event log server.
oCreate the STDL server entities targeted for debugging. Ensure that the executable images include the debugging code. The servers must be in a not started state. No other servers with the same interface (that is, based on the same task group) should be running when the ACMSxp debugger starts. Set to FALSE the autostart attributes on all task servers and processing servers that are to be debugged (this is the default). The TPsystem must not autostart targeted servers.
oSet up an interface directory to contain the interface descriptor files generated by the STDL compiler for each task server, if you are invoking a task in your debugging session with an ACMSxp-supplied client program.
4.If you use authenticated access, log in to DCE using a principal having the appropriate permissions to execute the servers and tasks to be debugged.
See the ACMSxp Developing and Managing Applications for details about the system administration directives.
Environment Variables
Use the following environment variables:
•ACMS_DEBUG_SVR (Optional)
Specifies the simple name of a server to be debugged.
•ACMS_DEBUG_TPSYSTEM (Optional)
Specifies the simple name of the TPsystem in which debugging occurs.
•ACMS_LOG_FILE (Optional)
Indicates where error logging is performed during ACMSxp debugger initialization. If you do not set this environment variable, events are not posted.
•LANG (Optional)
Identifies the natural language of the user and determines the language in which error and informational messages are displayed. Also used to display kanji characters.
To use a debugger other than dbx, set the following environment variables and then invoke acmsdbx:
ACMS_DEBUG_IMAGESpecifies the path to an alternate debug image, for example, /usr/bin/ladebug.
ACMS_DEBUG_OPTIONS
Used only with ACMS_DEBUG_SWITCH. Specifies an argument to go with the the initialization option specified in the ACMS_DEBUG_SWITCH environment variable.
ACMS_DEBUG_SWITCHSpecifies an option to use when the specified debugger starts. Optionally, use ACMS_DEBUG_OPTIONS to specify an argument.
DIGITAL COBOL Debugging
To read DIGITAL COBOL local variables in either an ACMSxp user-written client program or ACMSxp processing server written in DIGITAL COBOL, use the debugger called ladebug. To use ladebug with an ACMSxp processing server written in DIGITAL COBOL, set the following ACMSxp debugging environment variable:
setenv ACMS_DEBUG_IMAGE /usr/bin/decladebug
To have ladebug use a debugger initialization script, set the following environment variables:
setenv ACMS_DEBUG_SWITCH -c
setenv ACMS_DEBUG_OPTIONS /usr/users/.dbxinit
After you set the environment variables for debugging the processing server, invoke the debugger with the decladebug command.
Micro Focus COBOL Debugging Guidelines
To debug an ACMSxp user-written client program or ACMSxp processing server written in Micro Focus COBOL, use the Micro Focus debugger called animator. Set the following environment variables so that the related values for Micro Focus COBOL are available in the process in which the debugger runs:
Name Value Purpose
COBDIR /usr/lib/cmplrs/cob COBOL path
COBSW +A Turns on animator
LD_LIBRARY_PATH Path of ACMSxp sharables
and Micro Focus COBOL
sharables
Debugging a Micro Focus COBOL Client Program
Before running the debugger, set the environment variables in the process in which the debugger runs. For example:
setenv COBDIR /usr/lib/cmplrs/cob
setenv COBSW +A
setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:$COBDIR/coblib
Invoke the debugger with the dbx command. The +A activates the animator. The COBDIR value points to the Micro Focus COBOL directory and the LD_LIBRARY_PATH value includes the directory containing the Micro Focus COBOL sharables.
Debugging a Micro Focus COBOL Processing Server
To debug a Micro Focus COBOL processing server, follow these program development and debugging steps:
1.In the COBOL source for the processing procedure, capitalize the following names:
oThe COBOL program identification name, in the following format:
PROGRAM-ID <PROGNAME>
Match that name (<PROGNAME>) to the name of the called routine specified in the task definition.
oThe name of the source file
Match the name to the PROGRAM-ID name in the COBOL source.
2.Ensure that the following names do not contain underscores:
oIn the STDL task definition, the processing procedure name and processing group name. For example:
PROCESSING
CALL PROCEDURE stdcobol IN stdproccobol;
oIn the COBOL source for the processing server. For example:
IDENTIFICATION DIVISION.
PROGRAM-ID. STDCOBOL.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
MAIN-LINE.
DISPLAY "display statement from COBOL processing procedure".
END PROGRAM STDCOBOL.
(The matching filename has to be either STDCOBOL.cbl or STDCOBOL.cob.)
3.When building the processing server, do this:
oEnsure that the names of the object file and output image file (<program-name>) are capitalized.
oWhen linking, specify the -a switch to activate animator for the image.
oAt the end of the link command, specify the -d <program-name> switch. The -d switch must be at the end of the link command.
4.Before running acmsdbx, insert the following names in processing server environment variables attribute so that the related Micro Focus COBOL values are in the process in which the debugger runs:
COBDIR
COBSW
LD_LIBRARY_PATH
Use a command in the following format:
acmsadmin> add tpsystem <tpsys-name> server <micro_focus_server> -
_acmsadmin> environment variables = ((name=COBDIR,-
_acmsadmin> value=/usr/lib/cmplrs/cob),(name=COBSW,-
_acmsadmin> value=+A),(name=LD_LIBRARY_PATH,-
_acmsadmin> value=$LD_LIBRARY_PATH:$COBDIR/coblib))
5.Set the current working directory to the directory in which the processing server was built (and currently resides).
6.Ensure that the following files are in the current working directory:
<program-name>.idy
<program-name>.int
7.Run acmsdbx with the processing server.
At the dbx prompt, type run.
Initially, nothing shows on the screen. When the first COBOL procedure is called, the debugger initializes and starts output to the screen. Some time elapses before output shows up on the screen, because the C portion of the task server executes first and then calls a COBOL processing procedure.
Using the ACMSxp Debugger
Execute only one request at a time in a debugging session.
Once a server is executing under the control of the ACMSxp debugger, an ACMSxp-supplied client program or a user-written client program invokes the application procedure targeted for debugging. During a debugging session, the ACMSxp debugger can log events to the local log, if the environment variable ACMS_LOG_FILE is set. Thus, you can use the event log to track events during debugging.
Error and informational messages are displayed in the user’s natural language using ACMSxp message catalogs.
Upon activation, the ACMSxp debugger performs initializations and displays the (dbx) prompt indicating a debugging session is active. At this point, you can set break points before executing the server process, and then issue the run debug command to execute to the breakpoint. Use the breakpoints to step through STDL tasks, and to examine the contents of workspaces.
Once the appropriate command is issued, the server image is activated and performs its own initialization. Once initialization is complete, the server awaits requests from the client. The following example shows an acmsdbx command sequence:
% acmsdbx payroll_server financial_cntl
(dbx) stop in debit_task
(dbx) stop in credit_task
(dbx) run
The command starts the application server called payroll_server under the TPsystem financial_cntl. To end a debugging session in the ACMSxp debugger, enter the quit command at the (dbx) prompt.
Depending on which application components you are debugging interactively, you must establish at least two or more terminal sessions. These terminal sessions can be at multiple physical terminals, multiple sessions at a single terminal, multiple windows on a workstation, or a combination of these. You must establish a terminal session for:
•User-written client program (optionally running in an acmsdbx debugging session)
•Each STDL task server that you are debugging
•Each processing server that you are debugging
To initiate a debugging session, start each server in an ACMSxp debugger process. Next, start a user-written client program, invoking the targeted task.
To refer to identifiers during debugging, use the print debug command. You can examine STDL text strings.
Files that are entered via #INCLUDE/#CINCLUDE within a task definition are not expanded during a debugging session. Therefore, it is not possible to step through the source code represented by the #INCLUDE/#CINCLUDE.
You must refer to workspaces using the C language arrow (->) notation rather than the dot (.) notation. For example:
STDL Workspace Notation Debugger Reference Notation
W_REC1.FLD1.FLD2 w_rec1->fld1.fld2
Workspace field references must be fully qualified during debugging. For example, the field FLD1 must be preceded by its fully qualified name:
w_rec5->fld1.fld2.fld3.fld4
The language definition of STDL workspaces defines arrays as equivalent to the C model: 1-origin, column-major, multisubscripted data structures. The STDL compiler translates the STDL to C code; therefore, while debugging an STDL task, you cannot use the STDL-native model of array reference. Instead, the STDL syntax for the reference must be manually translated to an equivalent syntax recognized by the debugger.
The following rules define the workspace notation translation algorithm, and give examples of the translation:
1.Replace parentheses in subscript lists by square brackets.
2.Replace each comma-list of subscript values with an equivalent list of single subscripts.
3.Subtract 1 from each subscript value.
For example:
STDL Format Debugger Format
W_REC1(1) w_rec1[0]
W_REC1(X,Y,1) w_rec1[X-1][Y-1][0]
Using the ACMSxp Trace Facility
Use the trace facility to trace the flow of execution of an application by logging the entrance and exit of each STDL task and processing procedure. Control the posting of trace events by setting the event filter attributes on the task and processing servers to have the trace event type. For example:
acmsadmin> set tpsystem avertz_hq server vm -
_acmsadmin> event filter=(fault,security,status)
.
.
.
acmsadmin>
The command modifies the event filter attribute for the vm server. The event filtering takes effect immediately. Refer to the ACMSxp Developing and Managing Applications for more information on setting this attribute. See the acmsadmin help for on-line reference information under the following topics:
set server
entity_class server characteristic event_filter
The information recorded for the trace events includes:
oRequest context (if system monitoring is active on the TPsystem)
oGroup name
oTask or procedure name
RELATED INFORMATION
Commands: acms(1), acmsadmin(1), acmslog(1), stdl(1)
Scripts: acms_create_tpsystem(1), acms_delete_tpsystem(1), acms_set_version(1), acms_start_tpsystem(1)