Lexical Functions: F$PID

In the previous article we discussed the F$CONTEXT lexical function. In this article, we'll cover the F$PID lexical function, which uses the context that F$CONTEXT set up.

Here is a description of the F$PID lexical function:
Each call to F$PID will return the next process ID that matches the context set up by F$CONTEXT. The context is updated to point to the next process ID.

Format
F$PID(symbol)

Return Value
Returns the ID of the next process matching the criteria, or a null string if no more processes match.

Arguments

symbol
Specifies a symbol that UCL will use to refer to the context object that holds the UOS process context. Multiple contexts can exist simultaneously, each one specified with a different symbol.

The first time you use F$PID in a script, you should use a symbol that is either undefined or equated to null, or that has been created by the F$CONTEXT function. If the symbol was used with F$CONTEXT then F$PID function returns the first process that fits the criteria specified in the F$CONTEXT function and are accessible to your current privileges.

If a null string is passed to F$PID, it is considered to be a wildcard context and F$PID will iterate through all processes on the sytem that the caller has the privileges to access. There can only be one wildcard process context at a time for a given calling process.

After the last PID in the process list is returned, F$PID returns a null string.

Example:
$ PID = F$PID(CONTEXT)

        Function_PID : begin
                           if( Missing_Parentheses( '(' ) ) then
                           begin
                               exit ;
                           end ;
                           if( Process_PID( Err, Context ) ) then
                           begin
                               exit ;
                           end ;
                           if( Missing_Parentheses( ')' ) ) then
                           begin
                               exit ;
                           end ;
                           if( Err = 0 ) then
                           begin
                               S := Context ;
                           end ;
                       end ;

First we add the case to the Function_Reference function to handle the F$PID function.

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

var Buffer : array of byte ;


    procedure Extend( Amount : integer ) ;

    begin
        setlength( Buffer, length( Buffer ) + Amount ) ;
    end ;



var Descriptor : array[ 0..1 ] of TSYS_Descriptor ;
    E : int64 ; // Exception
    Filter : TFilter ;
    I : int64 ;
    IOSB : TIOSB ;
    Loop : integer ;
    P : integer ;
    pidctx : int64 ;
    Reference_Descriptor : TPSCAN_Reference_Descriptor ;
    S, Sym : string ;
    UCL_Context : TUCL_Context ;
    Value_Descriptor : TPSCAN_Value_Descriptor ;

begin // Process_PID
    // Setup...
    Err := 0 ;
    Context := '' ;
    Result := False ;

The Process_PID function will return the next process matching the context specified in symbol name that is the next token. If a UOS context has not yet been created, we will create one. This will require us to build up an item list to pass to SYS_PROCESS_SCAN. This is stored in the Buffer dynamic array. To simplify the code, we define the local function which will extend the array length by a specific amount.

The first few lines of the function set up for the following code.

    // Get context symbol name...
    Sym := Get_Token ;
    if( ( Sym <> '' ) and ( not Valid_Symbol_Name( Sym ) ) ) then
    begin
        Result := True ;
        Err := UCL_IVSYMB ; // Invalid symbol name
        exit ;
    end ;

First, we grab the symbol token. The value must be a valid symbol name, or null.

    // Check context...
    UCL_Context := nil ;
    if( Sym = '' ) then
    begin
        S := '' ;
    end else
    begin
        S := Symbol_Value( Sym ) ;
    end ;

If a symbol name is provided, we get the value for the symbol and assign it to S. If no symbol name is present, we set S to null. So, after this code, S will be the symbol value or null.

    if( S <> '' ) then
    begin
        if( trystrtoint64( S, I ) ) then
        begin
            UCL_Context := TUCL_Context( pointer( I ) ) ;
            if( Contexts_List.Indexof( UCL_Context ) = -1 ) then // Not a valid context
            begin
                UCL_Context := nil ;
            end ;
        end ;
        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
                Result := True ;
                UCL_Context.Free ;
                Err := UCL_IVSYMB ; // Most likely cause of set_symbol failure (review)
                exit ;
            end ;
        end ; // if( UCL_Context = nil )

if the value is non-null, we get the corresponding UCL context instance from the address in the value. If the value is non-numeric or doesn't correspond to an instance in Contexts_List, we create a new instance and write the address of that instance to the symbol, exiting if there's an error.

        // Make sure we have a valid context...
        if( UCL_Context.Context = 0 ) then // Need to create new Process_Scan context
        begin
            P := 0 ;
            for Loop := 0 to UCL_Context.Filters.Count - 1 do
            begin
                Filter := TFilter( UCL_Context.Filters[ Loop ] ) ;
                if( Is_By_Reference( Filter.Selection_Criteria ) ) then
                begin
                    Reference_Descriptor.Code := Filter.Selection_Criteria ;
                    Reference_Descriptor.MBO := 1 ;
                    Reference_Descriptor.MBMO := $FFFFFFFF ;
                    Reference_Descriptor.Flags := Filter.Qualifier ;
                    Reference_Descriptor.Length := length( Filter.Value ) ;
                    Extend_Data( length( Filter.Value ) ) ;
                    Reference_Descriptor.Address := integer( PChar( Filter.Value ) ) ;
                    Extend( sizeof( Reference_Descriptor ) ) ;
                    move( Reference_Descriptor, Buffer[ P ], sizeof( Reference_Descriptor ) ) ;
                    P := P + sizeof( Reference_Descriptor ) ;
                end else
                begin
                    Value_Descriptor.Code := Filter.Selection_Criteria ;
                    Value_Descriptor.MBO := 1 ;
                    Value_Descriptor.MBMO := $FFFFFFFF ;
                    Value_Descriptor.Value := strtoint( UCL_Strtoint( Filter.Value ) ) ;
                    Value_Descriptor.Flags := Filter.Qualifier ;
                    Extend( sizeof( Value_Descriptor ) ) ;
                    move( Value_Descriptor, Buffer[ P ], sizeof( Value_Descriptor ) ) ;
                    P := P + sizeof( Value_Descriptor ) ;
                end ;
            end ; // for Loop := 0 to UCL_Context.Filters.Count - 1

If no UOS context has been assigned to the instance's Context, we need to create one. This requires us to build the item list. We loop through the filters, and construct either a reference descriptor or value descriptor, as appropriate. We then extend the buffer and copy the descriptor to the buffer.

            // Write terminating descriptor to buffer...
            fillchar( Value_Descriptor.Code, sizeof( Value_Descriptor ), 0 ) ;
            Extend( sizeof( Value_Descriptor ) ) ;
            move( Value_Descriptor, Buffer[ P ], sizeof( Value_Descriptor ) ) ;

            pidctx := 0 ;
            SYS_PROCESS_SCAN( integer( @pidctx ), integer( @Buffer[ 0 ] ) ) ;
            UCL_Context.Context := pidctx ;
            if( pidctx = 0 ) then // Some error occurred
            begin
                Result := True ;
                E := LIB_Get_Exception( 0 ) ; // Get handle
                Set_Exception( LIB_Get_Exception_Text( 0, E ) ) ;
                exit ;
            end ;
        end ; // if( UCL_Context.Context = 0 )
    end ; // if( S <> '' )

After processing the filters, we add a terminating descriptor (one consisting of nulls). Next, we call SYS_PROCESS_SCAN with the item list that we created. If there was an error, we exit. Otherwise, we set the UCL_Context's context to the UOS context returned.

    // Find next PID...
    PP_Buff := 0 ;
    fillchar( Descriptor, sizeof( Descriptor ), 0 ) ;
    Descriptor[ 0 ].MBO := $FFFF ;
    Descriptor[ 0 ].MBMO := -1 ;
    Descriptor[ 0 ].Buffer_Length := sizeof( PP_Buff ) ;
    Descriptor[ 0 ].Item_Code := JPI_PID ;
    Descriptor[ 0 ].Buffer_Address := integer( @PP_Buff ) ;
    Descriptor[ 0 ].Return_Length_Address := integer( @PP_BufLen ) ;
    if( Sym = '' ) then // Wildcard
    begin
        SYS_GETJPIW( 0, -1, '', integer( @Descriptor ), integer( @IOSB ), 0, 0 ) ;
    end else
    begin
        SYS_GETJPIW( 0, UCL_Context.Context, '', integer( @Descriptor ), integer( @IOSB ), 0, 0 ) ;
    end ;
    if( PP_Buff = 0 ) then
    begin
        Context := '' ;
    end else
    begin
        Context := inttostr( PP_Buff ) ;
    end ;
end ; // Process_PID

By the time we get to this code, we have a context which has a valid UOS context. So we construct a descriptor list with a JPI_PID item and a null and call SYS_GETJPIW to get the next PID. If the result is 0 - meaning that there are no more matching processes - we return a null string. Otherwise we return the process ID.

In the next article, we will continue our examination of UCL lexical functions.