Before we look at the first of the lexical functions, we will look at a system call that we will be making use of. Normally, we work from the top down - from an application down to the executive API code. But, for reasons that will become clear later on, we'll start with the executive and then look at the application (UCL) code that uses the system call.

Process_Scan
Process_Scan is a system call that works with the GetJPI call. It is used to iterate through processes. Process_Scan creates a context that GETJPI uses - each call to GETJPI using that context will get the next matching process ID. Filters can be added to the context when it is created. Each filter is used to filter out undesired processes. When Process_Scan is called, it is passed an item list that indicates one or more filters to use (or no filters, if all process IDs are to be iterated over). Each filter consists of an item to compare, the value to compare against, and the type of comparison to do. The following items can be used for comparisons:

Item	Meaning
PSCAN_ACCOUNT	Account name
PSCAN_AUTHPRI	Authorized base priority
PSCAN_CURPRIV	Privilege name keyword
PSCAN_HW_MODEL	Hardware model number
PSCAN_HW_NAME	Hardware name
PSCAN_JOBPRCCNT	Subprocess count for entire job
PSCAN_JOBTYPE	Job-type keyword
PSCAN_KT_COUNT	Kernel thread count
PSCAN_MASTER_PID	PID of master process
PSCAN_MODE	Process mode keyword
PSCAN_MULTITHREAD	Maximum thread count
PSCAN_NODE_CSID	Node's cluster ID number
PSCAN_NODENAME	Node name
PSCAN_OWNER	PID of immediate parent process
PSCAN_PRCCNT	Subprocess count of process
PSCAN_PRCNAM	Process name
PSCAN_PRI	Process priority level number
PSCAN_PRIB	Base process priority level number
PSCAN_STATE	Process state keyword
PSCAN_STS	Process status keyword
PSCAN_TERMINAL	Terminal name
PSCAN_USERNAME	User name

For instance, the PSCAN_ACCOUNT item can be used to compare the account name for the user associated with a process.

The types of comparisons include the following:

Comparison	Meaning
PSCAN_M_EQL	Equal to the value
PSCAN_M_LSS	Less than the value
PSCAN_M_LEQ	Less than or equal to the value
PSCAN_M_GTR	Greater than the value
PSCAN_M_GEQ	Greater than or equal to the value
PSCAN_M_NEQ	Not equal to the value

Thus, we could have a filter that would compare the account name of a process' user with "SYSTEM" and a comparison of PSCAN_M_NEQ to only iterate over processes whose account name is not "SYSTEM".

The comparisons are combined with optional flags. But trying to combine different comparisons in the same filter will result in something unexpected - or even an error. For instance, PSCAN_M_NEQ or PSCAN_M_GEQ not only makes no sense, but would produce unexpected results or an exception. The following flags can be combined, although some combinations may not make much sense. VMS reports errors if certain flags are used with certain comparison items. UOS will allow any of the flags on any value, although certain combinations are probably not useful.

Flag	Meaning
PSCAN_M_BIT_ALL	All bits in the comparison value must be set in the item
PSCAN_M_BIT_ANY	Any bit in the comparison value that is set in the item means a match
PSCAN_M_CASE_BLIND	Perform string comparisons case-insensitive
PSCAN_M_OR	Logically or this filter with the next one
PSCAN_M_PREFIX_MATCH	Match against the portion of the item to the length of the specified comparison value
PSCAN_M_WILDCARD	Treat wildcard characters as wildcards for matching

Thus, we could use PSCAN_M_EQL or PSCAN_M_WILDCARD with the PSCAN_USERNAME item and a comparison value of "A*" to filter out all processes whose username doesn't start with "A". This particular filter could also be accomplished with a prefix match, by the way. Note that if we compared with "A*" but didn't include the wildcard flag, no processes would match, because it would look for a user name that is literally "A*", but user names cannot contain asterisks.

When a context contains multiple filters, a process must meet every requirement. However, if the PSCAN_M_OR flag is used, then the filter comparison is logically ored with the next filter. In fact, any number of filters can be ored together this way.

// Process Scan Filter criteria...
const PSCAN_Terminator = 0 ; // Account name - by reference
const PSCAN_ACCOUNT = 1 ; // Account name - by reference
const PSCAN_AUTHPRI = 2 ; // Authorized base priority
const PSCAN_CURPRIV = 3 ; // Current privileges - by reference
const PSCAN_HW_MODEL = 4 ; // Hardware model number
const PSCAN_HW_NAME = 5 ; // Hardware name - by reference
const PSCAN_JOBPRCCNT = 6 ; // Subprocess count for entire job.
const PSCAN_JOBTYPE = 7 ; // Job-type keyword
const PSCAN_MASTER_PID = 8 ; // PID of master process
const PSCAN_MODE = 9 ; // Process mode keyword
const PSCAN_NODE_CSID = 10 ; // Node's cluster ID number
const PSCAN_NODENAME = 11 ; // Node name - by reference
const PSCAN_OWNER = 12 ; // PID of immediate parent process
const PSCAN_PRCCNT = 13 ; // Subprocess count of process
const PSCAN_PRCNAM = 14 ; // Process name - by reference
const PSCAN_PRI = 15 ; // Process priority level number
const PSCAN_PRIB = 16 ; // Base process priority level number
const PSCAN_STATE = 17 ; // Process state keyword
const PSCAN_STS = 18 ; // Process status keyword
const PSCAN_TERMINAL = 19 ; // Terminal name - by reference
const PSCAN_USERNAME = 20 ; // User name - by reference
const PSCAN_KT_COUNT = 21 ; // Kernel threads
const PSCAN_MULTITHREAD = 22 ; // Maximum Kernel threads

// Process Scan Filter qualifiers...
const PSCAN_M_COMPARISON_MASK = 7 ;
const PSCAN_M_EQL = 0 ; // Equal to the value
const PSCAN_M_LSS = 1 ; // Less than the value
const PSCAN_M_LEQ = 2 ; // Less than or equal to the value
const PSCAN_M_GTR = 3 ; // Greater than the value
const PSCAN_M_GEQ = 4 ; // Greater than or equal to the value
const PSCAN_M_NEQ = 5 ; // Not equal to the value

const PSCAN_M_BIT_ALL = 8 ; // Requires that all bits be set
const PSCAN_M_BIT_ANY = 16 ; // Requests that any bit be set
const PSCAN_M_CASE_BLIND = 32 ; // Match without case sensitivity
const PSCAN_M_WILDCARD = 64 ; // Match a wildcard pattern
const PSCAN_M_OR = 128 ; // Or this filter item with the next one
const PSCAN_M_PREFIX_MATCH = 256 ; // Match prefix

    // Handle each criteria...
    case Criteria of
        PSCAN_ACCOUNT: // Account name
            begin
                Result := Process.User.Owner_Name ;
            end ;
        PSCAN_AUTHPRI: // Authorized base priority
            begin
                Set_Integer_Result( Process.User.Get_Auth_Privileges ) ;
            end ;
        PSCAN_CURPRIV: // Current Privileges
            begin
                Set_Integer_Result( Process.Current_Privileges ) ;
            end ;
        PSCAN_HW_MODEL: // Hardware model number
            begin
                Set_Integer_Result( Process.Hardware_Code ) ;
            end ;
        PSCAN_HW_NAME: // Hardware name
            begin
                Result := Process.Hardware_Description ;
            end ;
        PSCAN_JOBPRCCNT: // Subprocess count for entire job.
            begin
                _Process := Process.Job ;
                Set_Integer_Result( _Process.Child_Count ) ;
                _Process.Free_Remote ;
            end ;
        PSCAN_JOBTYPE: // Job-type
            begin
                _Process := Process.Job ;
                Set_Integer_Result( _Process.Job_Type ) ;
                _Process.Free_Remote ;
            end ;
        PSCAN_KT_COUNT: // Kernel thread count
            begin
                Set_Integer_Result( Process.KThread_Count ) ;
            end ;
        PSCAN_MASTER_PID: // PID of master process
            begin
                _Process := Process.Job ;
                Set_Integer_Result( _Process._PID ) ;
                _Process.Free_Remote ;
            end ;
        PSCAN_MODE: // Process mode
            begin
                _Process := Process.Job ;
                I := _Process.Job_Type ;
                if( I < JPI_K_BATCH ) then
                begin
                    I := JPI_K_INTERACTIVE ;
                end ;
                Set_Integer_Result( I ) ;
                _Process.Free_Remote ;
            end ;
        PSCAN_MULTITHREAD:
            begin
                Set_Integer_Result( Process.MaxK_Threads ) ;
            end ;
        PSCAN_NODE_CSID: // Node's cluster ID number
            begin
                Set_Integer_Result( Process.CSID ) ;
            end ;
        PSCAN_NODENAME: // Node name
            begin
                Result := Process.NodeName ;
            end ;
        PSCAN_OWNER: // PID of immediate parent process
            begin
                Set_Integer_Result( Process._Parent ) ;
            end ;
        PSCAN_PRCCNT: // Subprocess count of process
            begin
                Set_Integer_Result( Process.Child_Count ) ;
            end ;
        PSCAN_PRCNAM: // Process name
            begin
                Result := Process.Name ;
            end ;
        PSCAN_PRI: // Process priority level number
            begin
                Set_Integer_Result( Process.Priority ) ;
            end ;
        PSCAN_PRIB: // Base process priority level number
            begin
                Set_Integer_Result( Process.Base_Priority ) ;
            end ;
        PSCAN_STATE: // Process state
            begin
                Set_Integer_Result( Process.State ) ;
            end ;
        PSCAN_STS: // Process status
            begin
                Set_Integer_Result( Process.Status ) ;
            end ;
        PSCAN_TERMINAL: // Terminal name
            begin
                Result := Process.Terminal_Name ;
            end ;
        PSCAN_USERNAME: // User name
            begin
                Result := Process.User.Name ;
            end ;
    end ; // case Criteria
    Process.Free_Remote ;
end ; // TFilter.Get_Filter_Value

PSCAN_MODE is a special case in that the JPI_K_INTERACTIVE constant is not a value that the Process.Job_Type method returns, but the PSCAN_MODE criteria combines various process modes into that single constant, so we can't simply take the process mode value and use it as it. It's just one of those odd VMS things that we go with.
You might notice the calls to Process.Free_Remote. For now, this does nothing, but we will talk about it in the future. Essentially it has to do with accessing processes on other computers that are part of a cluster.
Finally, some of the above TProcess methods are new and we'll look at those in the next article.

    // Find next matching process...
    while( True ) do
    begin
        Result := Last_PID ;
        if( Result = 0 ) then // First time
        begin
            // Find first PID...
            for I := 0 to Processes.Count - 1 do
            begin
                Process := TProcess( Processes[ I ] ) ;
                if( Process <> nil ) then
                begin
                    Result := Process._PID ;
                    break ;
                end ;
            end ;
        end else
        begin
            // Find next PID
            Result := Find_Next_PID( Last_PID ) ;
            if( Result = 0 ) then
            begin
                Last_PID := 0 ; // Done
                dec( Last_PID ) ;
                exit ;
            end ;
        end ; // if( Result = 0 )
        Last_PID := Result ;

        // Now that we have the next potential process, check against the filters...
        Match := False ;
        F := -1 ;
        while( F < Filters.Count - 1 ) do
        begin
            inc( F ) ;
            Filter := TFilter( Filters[ F ] ) ; // Get next filter

            // Get values to compare...
            L := Filter.Get_Filter_Value( Result, Filter.Selection_Criteria ) ;
            if( Is_By_Reference( Filter.Selection_Criteria ) ) then
            begin
                R := Filter.Value ;
            end else
            begin
                setlength( R, sizeof( Filter.ValueI ) ) ;
                move( Filter.ValueI, PChar( R )[ 0 ], sizeof( Filter.ValueI ) ) ;
            end ;

For each time through the loop, we get the filter instance, then get the filter value. This is the process-specific value to which we compare the comparison value. We assign this to L because this is the left side of the comparison. Then we get the comparison value from the filter and assign it to R (right side value). Because the comparison value could be a string or an integer, we handle this slightly differently. For strings, we simple get Filter.Value. For integers, we set the length of R to 8 and copy the 64-bit integer value into it. Either way, we now have the comparison value in R. (Is_By_Reference is described later in the article.)

        // Compare the values and filter based on comparison mask...
            C := Compare_Values( L, R, Filter.Qualifier, Numeric_Criteria( Filter.Selection_Criteria ) ) ;
            if( not C ) then // Not a match
            begin
                if( ( Filter.Qualifier and PSCAN_M_OR ) = 0 ) then // Not oring with next filter
                begin
                    Match := False ;
                    break ;
                end ;
            end else
            begin
                Match := True ;
                while( ( Filter.Qualifier and PSCAN_M_OR ) <> 0 ) do // Skip further oring filters
                begin
                    if( F >= Filters.Count - 1 ) then
                    begin
                        break ; // Ran out of filters
                    end ;
                    inc( F ) ;
                    Filter := TFilter( Filters[ F ] ) ; // Get next filter
                end ;
            end ; // if( not C )
        end ; // while( F < Filters.Count - 1 )
        if( Match ) then
        begin
            exit ;
        end ;
    end ; // while( True )
end ; // TContext.Next_PID