TBSTATS—retrieve table statistics

The TBSTATS service obtains statistical information for a table and saves the information in variables specified in the service request.

Table statistics are maintained with each physical table member stored on permanent storage. The TBSTATS service provides access to these statistics from a dialog. The TBSTATS service also provides status information regarding the current usage of a specified table.

The statistics for a given table are available whether the table is open or closed. The statistics reflect the table as it exists on the input table file, except when the table is open in the logical screen where the TBSTATS service is issued. The statistics then reflect the version of the table that is currently open.

The existence of a table can be checked by the value in the STATUS1 field. If the table does not exist, no other processing takes place.

This statistical information is available:

Date and time the table was created
Date and time of last update
Last user to update the table
Number of rows when the table was created
Current number of rows (zero if the table is empty)
Number of existing rows that have been updated
Number of times the table has been updated
Last table service issued for the table (the table must be open)
Return code associated with the last table service (the table must be open)
Whether the table is available for WRITE mode processing
Whether the table exists in the table input file chain
Whether the table is open for this logical screen
Number of bytes of virtual storage required by the table

For statistical purposes, two table processes have been defined. The "create process" is defined as beginning with the TBCREATE and ending with a TBCLOSE or TBEND. The "update process" is defined as beginning with the TBOPEN and ending with a TBCLOSE or TBEND.

Command invocation format


>>-ISPEXEC--TBSTATS--table-name--+--------------------------+--->
                                 '-CDATE(date-created-name)-'   

>--+--------------------------+--+--------------------------+--->
   '-CTIME(time-created-name)-'  '-UDATE(date-updated-name)-'   

>--+--------------------------+--+-----------------+------------>
   '-UTIME(time-updated-name)-'  '-USER(user-name)-'   

>--+----------------------------+--+----------------------+----->
   '-ROWCREAT(row-created-name)-'  '-ROWCURR(rownum-name)-'   

>--+--------------------------+--------------------------------->
   '-ROWUPD(row-updated-name)-'   

>--+------------------------------+----------------------------->
   '-TABLEUPD(table-updated-name)-'   

>--+-----------------------+--+---------------------------+----->
   '-SERVICE(service-name)-'  '-RETCODE(return-code-name)-'   

>--+-----------------------+--+-----------------------+--------->
   '-STATUS1(status1-name)-'  '-STATUS2(status2-name)-'   

>--+-----------------------+--+------------------+-------------->
   '-STATUS3(status3-name)-'  '-LIBRARY(library)-'   

>--+-------------------------------------+---------------------->
   '-VIRTSIZE(virtual-storage-size-name)-'   

>--+------------------------------------+----------------------->
   '-CDATE4D(date-created-name-4-digit)-'   

>--+------------------------------------+----------------------><
   '-UDATE4D(date-updated-name-4-digit)-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('TBSTATSb'--,--table-name-------------------->

>--,-+-date-created-name-+--,-+-time-created-name-+------------->
     '-'b'---------------'    '-'b'---------------'   

>--,-+-date-updated-name-+--,-+-time-updated-name-+------------->
     '-'b'---------------'    '-'b'---------------'   

>--,-+-user-name-+--,-+-row-created-name-+--,-+-rownum-name-+--->
     '-'b'-------'    '-'b'--------------'    '-'b'---------'   

>--,-+-row-updated-name-+--,-+-table-updated-name-+------------->
     '-'b'--------------'    '-'b'----------------'   

>--,-+-service-name-+--,-+-return-code-name-+------------------->
     '-'b'----------'    '-'b'--------------'   

>--,-+-status1-name-+--,-+-status2-name-+--,-+-status3-name-+--->
     '-'b'----------'    '-'b'----------'    '-'b'----------'   

>--,-+-library-+--,-+-virtual-storage-size-name-+--------------->
     '-'b'-----'    '-'b'-----------------------'   

>--,-+-date-created-name-4-digit-+------------------------------>
     '-'b'-----------------------'   

>--,-+-date-updated-name-4-digit-+-);--------------------------><
     '-'b'-----------------------'

Parameters

table-name

Specifies the name of the table for which statistical information is to be obtained.

date-created-name

Specifies the name of a variable where the date the table was created is to be stored. The date is returned in the form YY/MM/DD.

time-created-name

Specifies the name of a variable where the time the table was created is to be stored. The time is returned in the form HH.MM.SS.

date-updated-name

Specifies the name of a variable where the date the table was last updated is to be stored. The date is returned in the form YY/MM/DD.

time-updated-name

Specifies the name of a variable where the time the table was last updated is to be stored. The time is returned in the form HH.MM.SS.

user-name

Specifies the name of a variable where the userid of the user that created or last updated the table is to be stored.

row-created-name

Specifies the name of a variable where the number of rows that existed at the end of the "create process" is to be stored.

rownum-name

Specifies the name of a variable where the number of rows contained in the table is to be stored.

row-updated-name

Specifies the name of a variable where the number of updated rows is to be stored. This is the number of existing rows that have been updated by TBPUT or TBMOD. During the "update process," rows that are added to the table are included in this number. Any row that increments this number, when deleted, will decrement this number.

table-updated-name

Specifies the name of a variable where the number of times this table has been updated is to be stored. This is the number of "update processes" that have occurred in which at least one row has been updated.

service-name

Specifies the name of a variable where the last table services command issued for this table is to be stored. This value is returned only if the table is currently open for the same logical screen.

return-code-name

Specifies the name of a variable where the return code associated with the last table services command issued for this table is to be stored. This value is returned only if the table is currently open to the same logical screen.

status1-name

Specifies the name of a variable where the status of the table in the table input library chain is to be stored. Values that can be stored and their meanings are:

1: table exists in the table input library chain
2: table does not exist in the table input library chain
3: table input library is not allocated

status2-name

Specifies the name of a variable where the status of the table in this logical screen is to be stored. Values that can be stored and their meanings are:

1: table is not open in this logical screen
2: table is open in NOWRITE mode in this logical screen
3: table is open in WRITE mode in this logical screen
4: table is open in SHARED NOWRITE mode in this logical screen
5: table is open in SHARED WRITE mode in this logical screen

status3-name

Specifies the name of a variable where the availability of the table to be used in WRITE mode is to be stored. Values that can be stored and their meanings are:

1: table is available for WRITE mode
2: table is not available for WRITE mode

library

Specifies the ddname of a FILEDEF command or the lib-type of the LIBDEF service request that defines an optional input file definition and provides control for the table input source. If omitted, the default is ISPTLIB.

virtual-storage-size-name

Specifies the name of a variable where the number of bytes of virtual storage required by the table is to be stored.

date-created-name-4-digit

Specifies the name of a variable where the date the table was created is to be stored. The date is returned in the form YYYY/MM/DD.

date-updated-name-4-digit

Specifies the name of a variable where the date the table was last updated is to be stored. The date is returned in the form YYYY/MM/DD.

buf-len

Specifies a fullword fixed binary integer containing the length of "buffer".

buffer

Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion (returned even if the table does not exist).
16: Variable value has been truncated.
20: Severe error.

Example

Determine the date when the table TELBOOK was created and when it was last updated.

ISPEXEC TBSTATS TELBOOK CDATE(DATE1) UDATE(DATE2)

Set the program variable BUFFER to contain:

TBSTATS  TELBOOK  CDATE(DATE1)  UDATE(DATE2)

Set program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('TBSTATS ','TELBOOK ','DATE1 ',' ','DATE2 ');