# 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 | Can be one 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 | User ID 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:

> • A single tcb_code specified in the TCB( ) function returns a corresponding system control value. See Format 1: Return Task Information.

> • Two numeric codes (pkg_index, info_reqd) are required for activation/licensing information. See Format 2: Return Activation Information.

> • Specific keywords are used to return information about the platform that PxPlus is compiled for or on. See Format 3: Return Platform Information.

> • Specific keywords are used to return user registration information on UNIX/Linux. See Format 4: Return User Information.

## 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:

TCB( ) | Return Values
0 | (Reserved) 0 (zero).
1 | (Reserved) 0 (zero).
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 0 (zero) whenever the system detects the presence of an error branch option. Example: read (1,key=K$,err=*NEXT) ... if tcb(2) then ... prior read had error ...
3 | Internal system error code.
4 | Current statement number (only reported when running a program, not in Command mode).
5 | 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 from the last Windows system call. On UNIX/Linux: Returns the value in the system error number field errno.
10 | Internal system error code.
11 | Retry statement number.
12 | Current level number.
13 | Current level number. PxPlus 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) See '1U' system parameter.
29 | Reports the current build level of PxPlus.
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 | PxPlus 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.
46 | (Reserved for System Use) (TCB(46) was added in PxPlus 2021.)
47 | Returns the maximum number of lines/columns that the system can support (254 or 620, depending on the release you are using and activation levels). (TCB(47) was added in PxPlus 2021.)
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 swap-outs.
56 | Program swap-ins.
57 | Program reloads from disk.
60 | (PVX Windows) Keyed file header busy retries.
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:
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 and REMOVE directives executed.
73 | Number of dynamically added EFF file buffers.
74 | Number of dynamically added VLR file buffers.
75 | Number of WindX packets forced to send response due to 'TA'= system parameter.
79 | Returns the number of active WindX Plug-ins connected to the server. It can be compared against the number of licensed WindX Plug-in users, which can be obtained from MOD (TCB (20013, 2), 2048), to see if more users can connect. #### Note: This value is only valid on a Base product and only if the WindX Plug-in Add-on is present. (TCB(79) was added in PxPlus 2019 Update 2.)
80 | Last VBX status or error code.
81 | Last Window LPARAM= value.
82 | Windows operating system version: 0 - If running under Windows 3.1 1 - If running under Windows 95 2 - If running under Windows NT -1 - If running on a 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 PxPlus v8.11, build 9182.1 indicated breakpoints exist) $0008$ - Watch Window is active $0040$ - Break points are defined (as of PxPlus v8.11, build 9182.1) $0080$ - Watch values exist (as of PxPlus v8.11, build 9182.1) $0800$ - Debug windows are disabled (as of PxPlus v8.11, 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). (added in PxPlus v8.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 that 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 | (UNIX/Linux Only) Current logical effective UserID.
95 | (UNIX/Linux Only) Current logical effective GroupID.
96 | (UNIX/Linux Only) Current True OS effective UserID.
97 | (UNIX/Linux Only) Current True OS effective GroupID.
99 | Program security flags.
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 PxPlus.
130 | Number of entries currently in the Error History table. (added in PxPlus v11)
170 | Windows Service handle. 0 if not running as a service.
190 | ADO Support: 1 if available, 0 if not.
191 | LibHaru (Enhanced PDF) support: 1 if available, 0 if not.
192 | (Obsolete) Running UltraFX: 1 if enabled, 0 if not.
193 | XML support: 1 if available, 0 if not.
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 values return 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 | (Windows Only) Size of a WORD.
312 | (Windows Only) Size of a DWORD.
313 | (Windows Only) Size of a HANDLE.
314 | (Windows Only) Size of a WCHAR.
315 | (Windows Only) Size of a LPARAM.
316 | (Windows Only) Size of a WPARAM.
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 the system was Idle and went through 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. (added in PxPlus v8.01, build 9181)
512 | Number of object class definitions that have been processed by the system. (added in PxPlus v8.01, build 9181)
513 | Number of times an object class definition was loaded from object cache. (added in PxPlus v8.01, 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 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. Maximum is 20.
info_reqd | Can be one of the following values:
0 | Package ID. 0 (zero) indicates the base PxPlus 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.

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.

(The ability to pass package numbers to the TCB function was added in PxPlus v6.30.)

Example:

> for ID=0 to 100
> PACKAGE=tcb(ID,0,err=*break)
> EXPIRY=tcb(ID,1)
> FLAGS=tcb(ID,2)
> print "PACKAGE#: ",tbl(PACKAGE=0,str(PACKAGE),"PXPLUS"),
> print @(20),"EXPIRES: ",tbl(EXPIRY=0,str(EXPIRY),"<NEVER>"),
> print @(40),"ACT FLAGS: ","$"+hta(bin(FLAGS,4))+"$"
> next ID

## Format 3

Return Platform Information

TCB(keyword [,ERR=stmtref ] )

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

Keyword | Return Values
"compiled_bits" | Either 32 or 64.
"compiled_cpu" | Type of processor (x86/PowerPC, etc.).
"compiled_architecture" | CISC/RISC/EPIC (nature of the CPU).
"compiled_os" | Operating system name.
"compiled_osver" | Operating system version.
"registered_name" | Name of the user given when the software was registered/activated. (added in PxPlus v8.01, build 9181)
"OpenSSL_Version" | OpenSSL version being used by PxPlus. See SSL/TLS Security Certificates. (added in PxPlus 2020)

## Format 4

Return User Information (UNIX/Linux Only)

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

The following keywords (case insensitive) return information about the specific User ID based on the OS registration tables (UNIX/Linux Option Only):

Keyword | Return Values
"OS_getusergid" | Returns the UNIX GID for the specified user. Example: tcb("OS_getusergid", "fred")
"OS_getuseruid" | Returns the UNIX UID number for the specified user. Example: 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.