IB Statements/pstat

From CometWiki

PSTAT function

Syntax: PSTAT(partition [,EXCP=statement-label])

Discussion: The PSTAT function returns the current status of a specified partition. A 211-byte string is returned. See below for a list of the values returned by this function.

The partition parameter is the name of the partition to check. It may be a string constant or a string variable.

Return values:  Position     Length    Description
===========================================================
1            8         Program name
9            2         Logical unit number
11           8         Current file name
19           3         Current file name extension
22           3         Directory
25           2         Last system function (See QERCOMET)
27           2         Last EXCP
29           3         Controlling terminal (TERM$)
32           3         Initiating terminal (ITERM$)
35           2         RUNSTATE value
37           4         Next user address
41           3         Directory name of object program
                       currently running
44 *         16        First 16 bytes of user's password
60 **        2         Session number (Intel hex format)
62           150       50 DABS
212          4         The Partition's Task ID (zero based)
216          2         The ENTERLEVEL (decimal)
218          1         Comet32 flag: 1 if running Comet32, 0 otherwise
219          1         Comet32 object flag: 1 if running Comet32 program, 0 otherwise

History: * Starting with Comet version 504.208, the PSTAT function returns the first 16 bytes of the user's password as defined by the SECURE statement. This value is stored starting at position 44.

Note: The SECURE statement transfers a user-defined 32-byte string to the partition's task header, and is a convenient way to store a unique value, such as the user's log-on password. The PASSWORD function returns the 32-byte string-argument. The PSTAT function returns the first 16 bytes of this string-argument.

We suggest that you use the SECURE statement to store two values, a user ID and a password, as follows:

Bytes 1-16 user name (available via PSTAT)

Bytes 17-32 password (not available via PSTAT)

To retrieve your own user ID, perform the following operation:

USER$ = SUB(PSTAT(PARTITION$),44,16)

where USER$ is a string variable with a length of 16.

• • The Comet session number is stored at positions 60 and 61 in Intel hex format (lowbyte/hibyte). On older systems, byte 61 can contain a blank space ("@20@" or decimal 32), so the following code will check it.

Stat$ = PStat(Partition$)

SessionNum = Asc(Sub(Stat$, 61, 1))

If (SessionNum EQ 32 ) Then _  ! Old system or a very large (>= 8192 sessions!) Comet system

   SessionNum = 0

SessionNum = Asc(Sub(Stat$, 60, 1)) + (SessionNum * 256)

If (SessionNum EQ 0) Then _  ! Zero is always a background session

   Goto IsBackground

SessionNum = SessionNum-1  ! Session numbers are based 0

Starting with Build 292, PSTAT adds leading 0's to a partition name if you specify a "short" partition name.

Example: You specify: PSTAT("3") Comet performs: PSTAT("003")

Example2:

 LENGTH 211 & LOCAL VALUE$
.
.
.
VALUE$ = PSTAT("P00",EXCP=9999)

This example shows how the PSTAT function can be used to obtain partition status information for partition "P00".