We mentioned the Function_Reference function several articles ago in our discussion of UCL expressions, which evaluates a function and returns a result. Starting in this article, and continuing for the next few articles, we will be going through the various UCL lexical functions (and any new system calls necessary to support them). We will take them in alphabetic order, mostly.

function Function_Reference( X : integer ; var Err : integer ) : tExpression_Node ; { Process function parameters }

    function Missing_Parentheses( P : string ) : boolean ;

    begin
        if( Get_Token <> P ) then
        begin
            Err := UCL_UNDSYM ;
            Result := True ;
        end else
        begin
            Result := False ;
        end ;
    end ;

var Context, S, S1 : string ;
    I, Loop : integer ;
    In_Quote : boolean ;

begin
    { Create new expression node for function call... }
    Result := nil ;
    S := '';
    Err := 0 ;
    Context := '' ;
    case X of
        .
        .
        .
    end ; // case X of

    Result := tExpression_Node.Create ;
    Result.Value := S ;
end ; // Function_Reference

The X value is the function constant value, so we switch on that value. The vertical ellipse is where the various function evaluations will be added, starting in this article and continuing in the next. When done (assuming no error occurs) we return a expression value node to the caller.

F$CONTEXT creates a context in which repeated calls to F$PID operates. F$PID returns the process ID for one or more processes (discussed in the next article). Which process ID(s) are returned depends upon the context created by F$CONTEXT. Essentially, it creates a filter used to select processes. We can create complex filters by using F$CONTEXT on the same symbol name multiple times, which creates a set of filters that are used together. For instance, we might want to create a filter that filters out any process whose name doesn't start with "A" and which are batch jobs. Then we use F$PID to retrieve one process ID at a time for those that match our filter. Each F$PID call will update the context so that the next call will get the next process matching our criteria.

If you've been paying attention, you have noticed that F$CONTEXT corresponds to the PROCESS_SCAN system call that we presented in article 70. However, there is one difference that complicates things. The system call takes a list of filters, whereas F$CONTEXT can only deal with a single filter at a time. This is a restriction of DCL/UCL due to the syntax and capabilities of the scripting language. The way that F$CONTEXT works is that it can be called multiple times - each call adding a filter to a context. Once all filters have been defined, the F$PID function can be used to iterate through the matching processes. So, the way we have to work this is to create a context object in UCL, use it to gather the filters, and then when F$PID is called we build a list and call the PROCESS_SCAN call. Of course, that means that attempting to add another filter via F$CONTEXT to the same context cannot be done once F$PID is used. The UOS context has already been created and used at this point. Thus, attempting to add another filter will result in a UCL error.

Here is a description of the F$CONTEXT lexical function:
Each call to F$CONTEXT will define a filter to be applied to a context to be used with the F$PID function. F$CONTEXT can be called as many times as needed to produce the criteria needed. Lists of item values are allowed.

Arguments
type
Specified the context type. At present, the only context type available is "PROCESS", which is used for constructing selection criteria for F$PID.

symbol
Specifies a symbol that UCL will use to refer to the context object that it constructs to hold the contexts. After the context is set up, this symbol should be used when calling F$PID. Multiple contexts can exist simultaneously, each one specified with a different symbol.

If the symbol is not yet defined or doesn't refer to a valid UCL context, a new context is created and the address is assigned to the symbol. If the symbol already refers to a valid UCL context, the F$CONTEXT call will add another filter to the existing context. Once F$PID is used with this context, the context is "frozen" and further attempts to add more filters will result in an error, although the context will remain valid and can continue to be used. To cancel a context, use the CANCEL "criteria".

criteria
This is a keyword that specifies the criteria for the filter to use.

Criteria	Value type	Comments
ACCOUNT	String	Valid account name or list of names.
AUTHPRI	Integer	The authorized base priority.
CANCEL		Cancels the selection criteria for this context.
CURPRIV	Keyword	Valid privilege name keyword or list of keywords.
HW_MODEL	Integer	Valid hardware model number.
HW_NAME	String	Valid hardware name.
JOBPRCCNT	Integer	Subprocess count for entire job.
JOBTYPE	Keyword	Valid job-type keyword. Valid keywords are DETACHED, NETWORK, BATCH, LOCAL, DIALUP, and REMOTE.
MASTER_PID	String	PID of master process.
MODE	Keyword	Valid process mode keyword. Valid keywords are OTHER, NETWORK, BATCH, and INTERACTIVE.
NODE_CSID	Integer	Node's cluster ID number.
NODENAME	String	Node name or list of node names. The default is the local node. To request all nodes, use the value "*".
OWNER	String	PID of immediate parent process.
PRCCNT	Integer	Subprocess count of process.
PRCNAM	String	Process name.
PRI	Integer	Process priority level number.
PRIB	Integer	Base process priority level number.
STATE	Keyword	Valid process state keyword.
STS	Keyword	Valid process status keyword.
TERMINAL	String	Terminal name or list of names.
USERNAME	String	User name or list of user names.

value
Specifies the value of the filter's criteria. For example, to iterate through all of the processes running under the username "SYSTEM", specify "USERNAME" with "SYSTEM", like so:
$ X = F$CONTEXT("PROCESS",context,"USERNAME","SYSTEM","EQL")

Multiple values can be used for a given criteria. For instance, if you wanted to iterate over all processes with ther username "SYSTEM", or "ALEX", or "MARKETING", you could use the following:
$ X = F$CONTEXT("PROCESS",context,"USERNAME","SYSTEM,ALEX,MARKETING","EQL")
In such a case, a match on any of the values is considered a match (as if an OR operand was used). Each different filter in the context is considered an AND operation - meaning that all filters must match, but each filter can be multiple values treated as an OR.

Further, wildcards can be used with any string comparison. Both the asterisk (*) and question mark (?) wildcards are allowed. For example, to iterate through all processes with a username starting with "A", you could use the following:
$ X = F$CONTEXT("PROCESS",context,"USERNAME","A*","EQL")
Or if you wanted all processes whose username was "SYSTEM" or which started with A:
$ X = F$CONTEXT("PROCESS",context,"USERNAME","A*,SYSTEM","EQL")

qualifier
Specifies the comparison to be made for the criteria. Note that although any qualifier can be used with any criteria, some of them may not be useful. For instance, ALL and ANY are used to compare bit values - primarily intended for privilege mask comparisons.

Qualifier	Description
LSS	Less than the value specified in the call to F$PID
LEQ	Less than or equal to the value specified in the call to F$PID
GTR	Greater than the value specified in the call to F$PID
GEQ	Greater than or equal to the value specified in the call to F$PID
EQL	Equal to the value specified in the call to F$PID
NEQ	Not equal to the value specified in the call to F$PID
ALL	Requires that all bits in the value be set for a process
ANY	Requests that any bits in the value be set for a process

        Function_Context : begin
                               if( Missing_Parentheses( '(' ) ) then
                               begin
                                   exit ;
                               end ;
                               if( Parse_Context( Err, Context ) ) then
                               begin
                                   exit ;
                               end ;
                               if( Missing_Parentheses( ')' ) ) then
                               begin
                                   exit ;
                               end ;
                               Result := tExpression_Node.Create ;
                               Result.Value := '' ; // Always returns null string value
                           end ;

function Parse_Context( var Err : integer ; var Context : string ) : boolean ;

var Filter, Previous : TFilter ;

var I : int64 ;
    P : integer ;
    S, Sym : string ;
    UCL_Context : TUCL_Context ;

begin
    // Setup...
    Result := False ; // Assume no problems
    Err := 0 ;
    Context := '' ;
    Filter := TFilter.Create ;

    // Get context type....
    S := lowercase( Get_Parameter( Err, Context ) ) ;
    if( Err <> 0 ) then
    begin
        exit ; ;
    end ;
    if( S <> 'process' ) then
    begin
        Result := True ;
        Filter.Free ;
        Err := UCL_IVKEYW ; // Unrecognized keyword
        Context := S ;
        exit ;
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        Filter.Free ;
        exit ;
    end ;

    // Get context symbol name...
    Sym := Get_Token ; // Context symbol name
    if( not Valid_Symbol_Name( Sym ) ) then
    begin
        Result := True ;
        Filter.Free ;
        Err := UCL_IVSYMB ; // Invalid symbol name
        exit ;
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        Filter.Free ;
        exit ;
    end ;

    // Get selection criteria...
    S := lowercase( Get_Parameter( Err, Context ) ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    if( S = 'account' ) then
    begin
        Filter.Selection_Criteria := PSCAN_ACCOUNT ;
    end else
    if( S = 'authpri' ) then
    begin
        Filter.Selection_Criteria := PSCAN_AUTHPRI ;
    end else
    if( S = 'cancel' ) then
    begin
        Filter.Free ;
        UCL_Context := Get_Context( Sym ) ;
        if( UCL_Context <> nil ) then
        begin
            UCL_Context.Free ;
        end ;
        exit ;
    end else
    if( S = 'curpriv' ) then
    begin
        Filter.Selection_Criteria := PSCAN_CURPRIV ;
    end else
    if( S = 'hw_model' ) then
    begin
        Filter.Selection_Criteria := PSCAN_HW_MODEL ;
    end else
    if( S = 'hw_name' ) then
    begin
        Filter.Selection_Criteria := PSCAN_HW_NAME ;
    end else
    if( S = 'jobprccnt' ) then
    begin
        Filter.Selection_Criteria := PSCAN_JOBPRCCNT ;
    end else
    if( S = 'jobtype' ) then
    begin
        Filter.Selection_Criteria := PSCAN_JOBTYPE ;
    end else
    if( S = 'master_pid' ) then
    begin
        Filter.Selection_Criteria := PSCAN_MASTER_PID ;
    end else
    if( S = 'mode' ) then
    begin
        Filter.Selection_Criteria := PSCAN_MODE ;
    end else
    if( S = 'node_csid' ) then
    begin
        Filter.Selection_Criteria := PSCAN_NODE_CSID ;
    end else
    if( S = 'nodename' ) then
    begin
        Filter.Selection_Criteria := PSCAN_NODENAME ;
    end else
    if( S = 'owner' ) then
    begin
        Filter.Selection_Criteria := PSCAN_OWNER ;
    end else
    if( S = 'prccnt' ) then
    begin
        Filter.Selection_Criteria := PSCAN_PRCCNT ;
    end else
    if( S = 'prcnam' ) then
    begin
        Filter.Selection_Criteria := PSCAN_PRCNAM ;
    end else
    if( S = 'pri' ) then
    begin
        Filter.Selection_Criteria := PSCAN_PRI ;
    end else
    if( S = 'prib' ) then
    begin
        Filter.Selection_Criteria := PSCAN_PRIB ;
    end else
    if( S = 'state' ) then
    begin
        Filter.Selection_Criteria := PSCAN_STATE ;
    end else
    if( S = 'sts' ) then
    begin
        Filter.Selection_Criteria := PSCAN_STS ;
    end else
    if( S = 'terminal' ) then
    begin
        Filter.Selection_Criteria := PSCAN_TERMINAL ;
    end else
    if( ( S = 'username' ) or ( S = 'uic' ) or ( S = 'mem' ) ) then
    begin
        Filter.Selection_Criteria := PSCAN_USERNAME ;
    end else
    begin
        Result := True ;
        Filter.Free ;
        Err := UCL_IVKEYW ; // Unrecognized keyword
        Context := S ;
        exit ;
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        Filter.Free ;
        exit ;
    end ;

    // Get filter value...
    Filter.Value := lowercase( Get_Parameter( Err, Context ) ) ;
    if( Err <> 0 ) then
    begin
        exit ;
    end ;
    if( trim( Filter.Value ) = '' ) then
    begin
        Result := True ;
        Filter.Free ;
        Err := UCL_ARGREQ ; // Missing argument
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        Filter.Free ;
        exit ;
    end ;

    // Get qualifier...
    S := lowercase( Get_Parameter( Err, Context ) ) ;
    if( Err <> 0 ) then
    begin
        exit ; ;
    end ;
    if( S = 'lss' ) then
    begin
        Filter.Qualifier := PSCAN_M_LSS ;
    end else
    if( S = 'leq' ) then
    begin
        Filter.Qualifier := PSCAN_M_LEQ ;
    end else
    if( S = 'gtr' ) then
    begin
        Filter.Qualifier := PSCAN_M_GTR ;
    end else
    if( S = 'geq' ) then
    begin
        Filter.Qualifier := PSCAN_M_GEQ ;
    end else
    if( S = 'eql' ) then
    begin
        Filter.Qualifier := PSCAN_M_EQL ;
    end else
    if( S = 'neq' ) then
    begin
        Filter.Qualifier := PSCAN_M_NEQ ;
    end else
    if( S = 'all' ) then
    begin
        Filter.Qualifier := PSCAN_M_BIT_ALL ;
    end else
    if( S = 'any' ) then
    begin
        Filter.Qualifier := PSCAN_M_BIT_ANY ;
    end else
    begin
        Result := True ;
        Filter.Free ;
        Err := UCL_IVKEYW ; // Unrecognized keyword
        Context := S ;
        exit ;
    end ;
    // Note: VMS has restrictions on which qualifiers can be used with which conditions.  UOS does not

    // See if context already exists...
    UCL_Context := Get_Context( Sym ) ;
    if( UCL_Context = nil ) then // No context
    begin
        UCL_Context := TUCL_Context.Create ;
        I := int64( UCL_Context ) ;
        Err := LIB_Set_Symbol( Sym, inttostr( I ) ) ;
        if( Err <> 0 ) then
        begin
            UCL_Context.Free ;
            Filter.Free ;
            Err := UCL_IVSYMB ; // Most likely cause of set_symbol failure (review)
            exit ;
        end ;
    end ; // if( UCL_Context = nil )

    // Process lists...
    S := Filter.Value ;
    P := pos( ',', S ) ;
    while( P > 0 ) do
    begin
        // Adjust current filter and save it...
        Filter.Value := copy( S, 1, P - 1 ) ;
        S := copy( S, P + 1, length( S ) ) ;
        if( pos( '*', Filter.Value ) + pos( '?', Filter.Value ) > 0 ) then
        begin
            Filter.Qualifier := Filter.Qualifier or PSCAN_M_WILDCARD ;
        end ;
        if( S <> '' ) then
        begin
            Filter.Qualifier := Filter.Qualifier or PSCAN_M_OR ;
        end ;
        UCL_Context.Filters.Add( Filter ) ;

        // Create new filter...
        Previous := Filter ;
        Filter := TFilter.Create ;
        Filter.Value := S ;
        Filter.Qualifier := Previous.Qualifier ;
        Filter.Selection_Criteria := Previous.Selection_Criteria and not ( PSCAN_M_WILDCARD or PSCAN_M_OR ) ;
        P := pos( ',', S ) ;
    end ; // while( P > 0 )

    function Get_Context( const Sym : string ) : TUCL_Context ;

    var I : int64 ;
        S : string ;

    begin
        Result := nil ;
        S := Symbol_Value( Sym ) ;
        if( trystrtoint64( S, I ) ) then
        begin
            Result := TUCL_Context( pointer( I ) ) ;
            if( Contexts_List.Indexof( Result ) = -1 ) then // Not a valid context
            begin
                Result := nil ;
            end ;
        end ;
    end ;

type TUCL_Context = class
                        public // API...
                            Filters : TList ; // List of filters
                            Last_PID : TPID ; // Context
                            Context : int64 ; // Executive context (If non-zero, context is "locked")

                            constructor Create ;
                            destructor Destroy ; override ;
                    end ;


var Contexts_List : TList = nil ;

constructor TUCL_Context.Create ;

begin
    inherited Create ;

    Filters := TList.Create ;
    if( Contexts_List = nil ) then
    begin
        Contexts_List := TList.Create ;
    end ;
    Contexts_List.Add( self ) ;
end ;


destructor TUCL_Context.Destroy ;

var I : integer ;

begin
    Contexts_List.Remove( self ) ;

    // Free all filters...
    for I := 0 to Filters.Count - 1 do
    begin
        TFilter( Filters[ I ] ).Free ;
        Filters[ I ] := nil ;
    end ;
    Filters.Free ;

    if( Context <> 0 ) then // Context defined
    begin
        // Clear context...
        SYS_PROCESS_SCAN( Context, 0 ) ;
    end ;

    inherited Destroy ;
end ;

function Get_Parameter( var Err : integer ; var Context : string ) : string ;

begin
    if( ( Parser.Peek = ',' ) or ( Parser.Peek = ')' ) ) then
    begin
        Err := UCL_EXPSYN ;
        exit ;
    end ;
    Result := Get_Expression( Err, Context ) ;
    if( ( Err = UCL_EXPSYN ) and ( ( Parser.Peek = ',' ) or ( Parser.Peek = ')' ) ) ) then
    begin
        Err := 0 ;
    end ;
end ;