System Functions
TCB( ) Return Task Information
   
Formats 1. Return Task Information: TCB( tcb_code [,ERR=stmtref])
2. Return Activation Information: TCB( pkg_index, info_reqd [,ERR=stmtref ])
3. Return Platform Information: TCB( keyword [,ERR=stmtref ] )
4. Return Unix user Information: TCB( keyword , userid [,ERR=stmtref ] )

Where:

info_reqd Any of the following values:
  • 0 Actual package number.
  • 1 Expiry date.
  • 2 Package activation flags.
pkg_index A number from 0 to the number of packages installed.
keyword Keyword associated with specific platform information.
userid Userid whose information is to be returned.
stmtref Program line number or statement label to which to transfer control.
tcb_code Value indicating what type of information is to be returned. Numeric expression.
   
Description The TCB( ) function returns information for several different purposes.
   
Format 1 Return Task Information

TCB(tcb_code[,ERR=stmtref])

When TCB( ) is used with a single code (tcb_code), it returns task information in the form of a numeric system control value. The codes and their values are listed below:

TCB( ) Return Values
0 Zero (0) - Reserved
1 Zero (0) - Reserved
2 Error branch taken indicator. Will be set to non-zero whenever an error branch (ERR=, DOM=, NUL=, BSY= or END=) branch is taken. Reset to zero whenever the system detects the presence of an Error branch option. e.g.

READ (1,KEY=K$,ERR=*NEXT) ...
IF TCB(2) THEN ... prior read had error ...

+PxPlus Exclusive TCB value
3 Internal system error code.
4 Current statement number. (Only reported when running a program, not in Command mode.)
5 The line number of the last error.
6 SETESC statement number.
7 SETERR statement number.
8 Top statement number in GOSUB stack.
9 Returns the operating system error code. On Windows, this is the value returned by the system call GetLastError, which will have the error code form the last Windows system call. (On Unix/Linux returns the value in the system error number field errno).

+PxPlus Exclusive TCB value
10 Internal system error code.
11 Retry statement number.
12 Current level number.
13 Current level number – ProvideX includes current level in both TCB(12) and TCB(13) for compatibility with other Business Basics.
14 Current precision (-1=FLOATINGPOINT).
15 Current maximum memory size in bytes.
16 Length of string found in last MSK( ) function.
17 Current level of user functions.
18 Current iteration of range assignment.
19 Current iteration for enhanced FOR..NEXT loop.
20 Number of arguments in 'CALL'
21 Current activation flags.
22 Number of days left for current activation.
23 Maximum user count.
24 Number of users available.
25 Operating system version number.
27 Reports current session's user slot number and type of slot:
  • > 0 : Dedicated non-shared user slot number being used.
  • < 0 : Shared user slot number being used.
  • 0 : Task is not being counted in the user slot table (background task).

(For further information, refer to the '1U' System Parameter.)
29 Reports the current build level of ProvideX.
30 Statement number of last error in called program.
31 Last object to lose focus.
32 Version level of activation.
33 System serial number.
34 System machine class.
35 System identification number.
36 ProvideX Library version code.
37 EFF support:
  • 0 EFF not supported
  • 1 EFF support for files up to 2GB
  • 2 EFF support for files over 2GB.
39 Highest used object identifier. (0 = no objects in system).
40 SETTRACE file number (if active).
41 Number of duplicate labels on last save.
42 Number of unknown state labels on last save.
43 Offset to the last detected error in the last statement compiled. Reports the number of characters before the error occurred.
44 Number of seconds of offset to GMT (Greenwich Mean Time).
45 Daylight Savings indicator: 1 if Daylight Savings active, 0 if not.
50 Number of file reads.
51 Number of file writes.
52 Number of Keyed I/O forced buffer flushes.
53 Number of programs loaded from disk.
54 Number of programs loaded from program cache.
55 Program Swapouts.
56 Program Swapins.
57 Program reloads from disk.
60 Keyed file header busy retries (PVX Windows/DOS).
61 Busy record count.
62 Number of unsuccessful file opens.
For TCB(63) to TCB(66), below, the values in the system parameters 'VR' and 'VW' define the number of read/write retries before a data read/write error will be generated. For more information, refer to the 'VR'= System Parameter, and the 'VW'= System Parameter.
63 Number of READs verified.
64 Number of WRITEs verified.
65 Number of READ mis-compares.
66 Number of WRITE mis-compares.
67 On completion of KEYED LOAD command:
  • > 0 the number of keys reloaded.
  • - 1 Keyed load encountered different number of keys on different key chains.
68 Password retry count.
70 Number of logical OPEN directives executed.
71 Number of logical READ/EXTRACT/FIND directives executed.
72 Number of logical WRITE/REMOVE directives executed.
73 Number of dynamically added EFF file buffers.
80 Last VBX status or error code. See the CUSTOM_VBX Directive for a list of codes and explanations.
81 Last Window LPARAM= value.
82 Windows OS version:
0 if running under Windows 3.1.
1 if running under Windows 95.
2 if running under Windows NT.
-1 if running on an non-Windows system
83 Status of the debug window:
$0001$ - Command Window is active
$0002$ - Trace Window is active
$0004$ - Break Window is active (prior build 9182.1 indicated breakpoints exist)
$0008$ - Watch Window is active
$0040$ - Break points are defined (PxPlus Exclusive as of build 9182.1)
$0080$ - Watch values exist (PxPlus Exclusive as of build 9182.1)
$0800$ - Debug windows are disabled (PxPlus Exclusive as of build 9182.1)
84 Last OS exit status from a process launched by an INVOKE or a SYS( ) function. Only valid if system waits for task completion.
85 Last spawned task/process identifier (PID).
86 WindX serial number (or zero if not using WindX). (ver 8.11)
87 UNIX/Linux Only. Returns PID of lock conflict. When a file I/O attempt is made and fails due to a lock, TCB(87)returns the PID of the process owning the lock. Use this process ID along with the output of a 'ps' command to identify who has a record locked.
88 WindX version number or 0 (zero) if not running under a WindX session.
89 Numeric value of current PID. This allows for PID values which are larger than the 16-bit values returned by GID, and will remain constant for 32-bit, upcoming 64-bit (and beyond) operating systems. Replaces the use of DEC($00$+GID)to retrieve the current PID value.
91 Current Task/Thread Priority level. Three system parameters control the priority of a task, primarily to balance the load in a Client/Server environment. See 'Q_', 'Q^' and 'QF' Task Priorities.
92 Yields the TIM= value * 100 (100ths of a second) when doing embedded I/O, or -1 if no TIM=.
93 Current object ID used in the WITH directive.
94 Current logical effective userid (Unix/Linux ONLY)
95 Current logical effective groupid (Unix/Linux ONLY)
96 Current True OS effective userid (Unix/Linux ONLY)
97 Current True OS effective groupid (Unix/Linux ONLY)
99 Program security flags.
100 High memory in use (PVX DOS only - no longer used).
101 Number of times variables were referenced.
102 Number of variables not found in the variable table.
103 Number of memory compares performed to locate variables.
104 Number of times the variable table was re-balanced.
110 Number of memory allocations made by ProvideX.
170 NT Service handle. 0 if not running as a service.
195 ZLIB Support: 1 if available, 0 if not.
196 DLL( ) UNIX/Linux support: 1 if enabled, 0 if not.
197 ODBC: 1 if enabled, 0 if not.
198 DB2 Support: 1 if enabled, 0 if not.
199 Built-in SSL: 1 if SSL supported, 0 if not.
TCB values in the 200 range are designated for use with ORACLE
200 OCI available: 1 if OCI is enabled, 0 if not.
201 OCI Connects
202 OCI Opens
203 OCI Shares
204 OCI Selects
205 OCI Inserts
206 OCI Updates
207 OCI Deletes
208 OCI Prepare Selects
209 OCI Prepared Select Used
210 OCI Prepare Insert
211 OCI Prepared Insert Used
212 OCI Prepare Failures
213 OCI Dictionary Reads
214 OCI User Commands
The following TCB value returns information used for sizing variables when building a C structure.
Either a numeric size (in bytes not bits) or 0 if there is no such data type.
301 Size of a pointer (any kind of memory pointer)
302 Size of a Boolean
303 Size of a char or byte
304 Size of a short or short int
305 Size of an int
306 Size of a long or long int
307 Size of a long double
308 Size of a long long
309 Size of a double
310 Size of a float
311 Size of a WORD (MS Windows only)
312 Size of a DWORD (MS Windows only)
313 Size of a HANDLE (MS Windows only)
314 Size of a WCHAR (MS Windows only)
315 Size of a LPARAM (MS Windows only)
316 Size of a WPARAM (MS Windows only)
The following are +PxPlus Exclusive TCB values
500 Number of characters into the compression routine for WindX.
501 Number of characters out of the compression routine for WindX.
502 Number of times Windows version of PxPlus was Idle and went thru the Message Queue.
503 Number of extra characters (or missing characters if negative) in data detected on last read against an IOLIST.
504 Windows character set.
505 Windows Code page for character presentation.
506 Process ID. If running under client server this will be the process ID on the server.
507 External debugger status.

0 = No debug active.
-1 = This process is being debugged.
>0 = Process ID being debugged by this process.
510 Object number for the currently defined Object Defined Controls server.
511 Current number of cached object classes. (build 9181)
512 Number of object class definitions that have been processed by the system. (build 9181)
513 Number of times an object class definition was loaded from object cache. (build 9181)
   
Format 2 Return Activation Information

TCB(pkg_index,info_reqd[,ERR=stmtref])

When TCB( ) is used with two codes (pkg_index,info_reqd), it reports ProvideX/PxPlus licensing information in numeric form (owner code, package ID, and date):

pkg_index can be any number from 0 to the number of packages installed. The maximum is 20.
info_reqd can be one of the following values:
  • 0 Package ID. 0 (zero) indicates the base ProvideX activation.
  • 1 Expiry Date in numeric form YYYYMMDD. 0 means no expiry date.
  • 2 Package Activation Flags (32-bit flags as a numeric).
  To simplify locating a package's information you can specify the actual package id instead of the index. For example to get the expiry date for package 7587 you could issue:

TCB ( 7587, 1)

To validate if an activation is present, you can issue TCB(packageid, 0) which will return the index for the package if it is present in the system or -1 if not.

This option is available for any package whose package number is > 20. This is a +PxPlus Exclusive feature.
     
Example

0010 FOR ID=0 TO 100
0020 PACKAGE=TCB(ID,0,ERR=*BREAK)
0030 EXPIRY=TCB(ID,1)
0040 FLAGS=TCB(ID,2)
0050 PRINT "PACKAGE#: ",TBL(PACKAGE=0,STR(PACKAGE),"PROVIDEX"),
0060 PRINT @(20),"EXPIRES: ",TBL(EXPIRY=0,STR(EXPIRY),"<NEVER>"),
0070 PRINT @(40),"ACT FLAGS: ","$"+HTA(BIN(FLAGS,4))+"$"
0080 NEXT ID

   
Format 3 Return Platform Information

TCB( keyword [,ERR= stmtref ] )

The following keywords (case insensitive) return information about the platform that ProvideX is compiled for or on along with activation information:

keyword Return Values
"compiled_bits" Either 32 or 64.
"compiled_cpu" The type of processor (x86/PowerPC etc.)
"compiled_architecture" OS name
"compiled_os" CISC/RISC/EPIC (nature of the CPU)
"compiled_osver" Operating System Version
The following are +PxPlus Exclusive TCB values
"registered_name" Name of the user given when the software was registered/activated. (build 9181)
   
Format 4 Return User Information (Unix/Linux only)

TCB( keyword, user [,ERR= stmtref ] )

The following keywords (case insensitive) return information about the specific userid based on the OS registration tables. This is Unix/Linux option only.

keyword Return Values
"OS_getusergid" Returns the Unix GID for the specified user. e.g. TCB("OS_getusergid", "fred")
"OS_getuseruid" Returns the Unix UID number for the specified user. e.g. TCB("OS_getuseruid", "fred")
"OS_getusername" Returns the Unix user name for the specified user.
"OS_getuserhome" Returns the Unix home directory for the specified user.
"OS_getusershell" Returns the Unix shell program for the specified user.