Skip to content
Thoroughbred Software InternationalThoroughbred Software InternationalThoroughbred DocumentationDocs

ghoststat

PURPOSE

ghoststat is a stand-alone utility that is used to report and manage Thoroughbred Basic Ghost Tasks.

ghoststat will:

  1. Report the status and usage of UNIX shared memory used by Ghost Tasks
  2. Dump the contents of record transfer buffers
  3. Reset the contents of shared memory and semaphores for one or more or all Ghost Tasks
  4. Send an “ESCAPE” to one or more Ghost Tasks

PROCEDURE

ghoststat is run from a UNIX Shell prompt. You must have sufficient permission to perform functions on shared memory owned by someone else. The syntax of the ghoststat command is:

ghoststat [-h] | [-d|-c|-e] | [-v][GhostName1[GhostName2…]]

The current options are: -d, -c, -e,–h, and -v. Only one option is allowed at a time. The options are discussed below.

If one or more GhostName arguments are included on the command entry, information is presented only for the Ghost Tasks specified. Otherwise, information is presented for all currently configured Ghost Tasks. The sixty-two valid GhostName combinations are “G0” through G9”, “GA” through “GZ”, and “Ga” through “Gz”. The actual number of configured Ghost Tasks on a system may be less.

Ghost Task status display

If no options are specified, ghoststat will display information about the status of configured Ghost Tasks. The following is a sample display from ghoststat without options:

**Thoroughbred BASIC Ghost Task Utility**


  open cq cmd da tr err rel ctl st ocnt rac pid    opid   dsz rsz  sf gs   fs
G0 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G1 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G2 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G3 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G4 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G5 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G6 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G7 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480


Total 'declared' Ghost Tasks: 8
Total START'ed   Ghost Tasks: 0
Total OPEN       Ghost Tasks: 0

Entering the command ghoststat G2 G9 will produce this display:

**Thoroughbred BASIC Ghost Task Utility**


  open cq cmd da tr err rel ctl st ocnt rac pid    opid   dsz rsz  sf gs   fs
G2 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G9 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
–h Help Option

ghoststat -h will display descriptions for the columns in the status display:

ghoststat -h         ------- example --------


**Thoroughbred BASIC Ghost Task Utility**


A short explanation of the flags printed out by this utlity:
Abreviation   Full Name           Explanation
-----------   ---------------     ---------------------------------
open          ghopen              ghost task opened flag
cq            ghcmdqued           a command_has_been_queued flag
cmd           ghcmd               current ghost I/O command
da            ghdtav              ghost data available flag
tr            ghtran              ghost data transfer in progress flag
err           gherror             error number (0 if none)
rel           ghrelease           RELEASE in progress
ctl           ghctl               CTL value passed from main to ghost
st            ghstart             START in progress
ocnt          ghopcnt             # ghost tasks this ghost has OPEN
rec           ghrelack            acknowledge that we are gonna die
pid           ghpid               process id of ghost task or 0 if not STARTed
opid          ghopenpid           process id of task that OPENed the ghost
dsz           ghdatasz            data size - # of bytes in buffer
rsz           ghrecsz             total size of record to transfer
sf            ghsysflag           TRUE if ghost has 'shelled down'
gs            ghghoststep         a code to say where we are in the
                                    ghost driver (ghost side)
fs            ghfrgndstep         a code to say where we are in the
                                       ghost driver (foreground side)
–d Dump Buffers Option

The –d option will produce the Ghost Task status display followed by a dump of any record buffers that contain data. The command ghoststat –d will produce a display similar to this:

**Thoroughbred BASIC Ghost Task Utility**


  open cq cmd da tr err rel ctl st ocnt rac pid    opid   dsz rsz  sf gs   fs
G0 0   0  0   0  0  0   0   5   0  0    0   0      0      0   0    0  490  480
G1 0   1  2   1  0  0   0   0   0  0    0   16867  0      11  11   0  200  880
G2 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G3 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G4 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G5 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G6 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G7 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
  open cq cmd da tr err rel ctl st ocnt rac pid    opid   dsz rsz  sf gs   fs
G8 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480
G9 0   0  0   0  0  0   0   0   0  0    0   0      0      0   0    0  490  480


data for G1: .LFREADY.LF


Total 'declared' Ghost Tasks: 10
Total START'ed   Ghost Tasks: 1
Total OPEN       Ghost Tasks: 0

The display shows that Ghost Task “G1” is active and its record buffer contains a “READY” prompt. Specifying a GhostName as in the command ghoststat –d G1 will reduce the amount of information displayed:

**Thoroughbred BASIC Ghost Task Utility**


  open cq cmd da tr err rel ctl st ocnt rac pid    opid   dsz rsz  sf gs   fs
G1 0   1  2   1  0  0   0   0   0  0    0   16867  0      11  11   0  200  880


data for G1: .LFREADY.LF
–c Clear Status Option

The –c option requests ghoststat to clear and reset values in shared memory. If the specified Ghost Task process is still active the request will be refused with a message similar to:

**Thoroughbred BASIC Ghost Task Utility**
The process associated with Ghost Task "G1" is still alive
Ignoring request to clear "G1"

A successful request will produce a message similar to:

**Thoroughbred BASIC Ghost Task Utility**
"G1" memory cleared.

This option should only be used when a Ghost Task cannot be started because of the failure of a previous Ghost Task.

-e Send ”ESCAPE” Option

The –e option will send a signal to a Ghost Task process requesting an “ESCAPE”. This action is the same as pressing the ESC key while running a normal task. This option is usually used prior to running the *GPSD utility to debug a Ghost Task program. A program can ignore an ”ESCAPE” regardless of the type of task.

If ghoststat was able to signal the process successfully, a message similar to the following will be displayed:

ESCAPE sent to Ghost Task "G0"

–v Display program version

The –v option will display the program version. The command ghoststat –v will produce a display similar to this:

ghoststat -v         ------- example --------


**Thoroughbred BASIC Ghost Task Utility**
  Thoroughbred BASIC Level 8.7.1  (10/06/10)
  Computer: INTEL 386/486
  OS Name/Level: Linux 2.4.20-6
ghoststat Errors and Messages
The following messages are be produced by ghoststat:
Usage: ghoststat [-h] | [-d|-c|-e] [GhostName1[GhostName2...]]
There is an invalid option or GhostName. Only one option is allowed at a time. There must be a space between the option and any arguments. GhostNames must begin with the letter ”G”.

Ghost Task “G?” is not valid for this version of BASIC.

Either the second character of the GhostName specified is not valid or the installed version of ghoststat supports less than 62 Ghost Tasks.

Unable to attach to shared memory.

Either Thoroughbred Basic has not been started with Ghost Tasks defined in IPLINPUT or the user does not have permission to perform UNIX shared memory functions.

Unable to attach to shared memory (Can’t get ID).
BASIC has not been started with Ghost Tasks defined in the IPLINPUT file.

None of the ghoststat functions will work until Thoroughbred Basic has been started with Ghost Tasks defined in IPLINPUT.

Only NN Ghost Tasks configured in shared memory!

A valid GhostName was used but the name has never been configured by Thoroughbred Basic in IPLINPUT. Use ghoststat with no options to produce a status display of configured Ghost Tasks.

”G?” is not declared.

A valid GhostName was used but the name has never been configured by Thoroughbred Basic in IPLINPUT. Use ghoststat with no options to produce a status display of configured Ghost Tasks.

-e option requires at least one Ghost Task name.

The –e option must be directed to one or more specific Ghost Tasks using GhostName arguments. You may not send an ”ESCAPE” to all Ghost Tasks.

*** ESCAPE could not be sent to “G?”
*** Operating System returned error NN.

While processing a ghoststat -e option, error NN was returned by the UNIX kill command. Usually, the user lacks sufficient UNIX permission to use the command. Refer to the UNIX documentation for an explanation.

The process associated with Ghost Task ”G?” is still alive Ignoring request to clear ”G?”

This message is described under the –c option.

From the Thoroughbred Basic Technical Appendices, version 8.9.1. Open this page in the PDF