Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

The /PRIORITY qualifier has no effect on the process priority. The queue establishes the process priority.

#### /QUEUE=queue-name[:]

Specifies the name of the batch queue in which the job is to be entered. If you do not specify the /QUEUE qualifier, the job is placed in the default system batch job queue, SYS$BATCH.

#### /RESTART

#### /NORESTART (default)

Specifies whether the job restarts after a system failure or a STOP/QUEUE/REQUEUE command.

#### /TRAILING_BLANKS (default)

#### /NOTRAILING_BLANKS

Controls whether input cards in the card deck are read in card image form or input records are truncated at the last nonblank character. By default, the system does not remove trailing blanks from records read through the card reader. Use the /NOTRAILING_BLANKS qualifier to request that input records be truncated.

#### /WSDEFAULT=n

Defines a working set default for the batch job; the /WSDEFAULT qualifier overrides the working set size specified in the user authorization file (UAF).

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS rounds this value up to the nearest CPU-specific page so that the actual amount of physical memory allowed may be larger than the specified amount on Alpha. The value n can be any integer from 1 to 65,535, 0, or the keyword NONE. For further information, refer to the OpenVMS System Manager's Manual.

Use this qualifier to impose a value lower than the base queue value established by the system manager or lower than the value authorized in your UAF. A value of 0 or the keyword NONE sets the default value to the value specified either in your UAF or by the working set quota established for the queue. You cannot request a value higher than your default.

#### /WSEXTENT=n

Defines a working set extent for the batch job; the /WSEXTENT qualifier overrides the working set extent in the UAF.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS rounds this value up to the nearest CPU-specific page so that the actual amount of physical memory allowed may be larger than the specified amount on Alpha. The value n can be any integer from 1 to 65,535, 0, or the keyword NONE. For further information, refer to the OpenVMS System Manager's Manual.

To impose a lower value, use this qualifier to override the base queue value established by the system manager rather than the value authorized in your UAF. A value of 0 or the keyword NONE sets the default value either to the value specified in the UAF or working set extent established for the queue. You cannot request a value higher than your default.

#### /WSQUOTA=n

Defines the maximum working set size (working set quota) for the batch job; the /WSQUOTA qualifier overrides the value in the UAF.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS rounds this value up to the nearest CPU-specific page so that the actual amount of physical memory allowed may be larger than the specified amount on Alpha. The value n can be any integer from 1 to 65,535, 0, or the keyword NONE. For further information, refer to the OpenVMS System Manager's Manual.

Use this qualifier to impose a value lower than the base queue value established by the system manager or lower than the value authorized in your UAF. Specify 0 or NONE if you want the working set quota defaulted to either your UAF value or the working set quota specified on the queue. You cannot request a value higher than your default.

###

#### Examples

#1

The JOB and PASSWORD cards identify and authorize the user HIGGINS to enter batch jobs. The command stream consists of a Fortran command and Fortran source statements to be compiled. The file name AVERAGE following the device name SYS$INPUT provides the compiler with a file name for the object and listing files. The output files are cataloged in user HIGGINS's default directory.

If the compilation is successful, the LINK command creates an executable image and the RUN command executes it. Input for the program follows the RUN command in the command stream. The last command in the job prints the program listing. The last card in the deck contains the EOJ (end of job) command.

#2

The /NAME qualifier on the JOB card specifies a name for the batch job. When the job completes, the printed log file is identified as BATCH1.LOG. The JOB command is continued onto a second card with the continuation character (-). The /PARAMETERS qualifier defines P1 as A and P2 as TEST. The last card in the deck contains the EOJ (end of job) command.

## Lexical Functions

> A set of functions that return information about character strings and attributes of the current process.

### Description

> The command language includes constructs, called lexical functions, that return information about the current process and about arithmetic and string expressions. The functions are called lexical functions because the command interpreter evaluates them during the command input scanning (or lexical processing) phase of command processing.

> You can use lexical functions in any context in which you normally use symbols or expressions. In command procedures, you can use lexical functions to translate logical names, to perform character string manipulations, and to determine the current processing mode of the procedure.

> The general format of a lexical function is as follows:

> `F$function-name([args,...])`

> where:

> F$ | Indicates that what follows is a lexical function.
> function-name | A keyword specifying the function to be evaluated. Function names can be truncated to any unique abbreviation.
> () | Enclose function arguments, if any. The parentheses are required for all functions, including functions that do not accept any arguments.
> args,... | Specify arguments for the function, if any, using integer or character string expressions.

> For more information on specifying expressions, refer to the OpenVMS User's Manual.

> Table DCLI-3 lists each lexical function and briefly describes the information that each function returns. A detailed description of each function, including examples, is given in the following pages.

> Table DCLI-3 Summary of Lexical Functions
> Function | Description
> --- | ---
> F$CONTEXT | Specifies selection criteria for use with the F$PID function.
> F$CSID | Returns an OpenVMS Cluster identification number and updates the context symbol to point to the current position in the system's cluster node list.
> F$CVSI | Extracts bit fields from character string data and converts the result, as a signed value, to an integer.
> F$CVTIME | Retrieves information about an absolute, combination, or delta time string.
> F$CVUI | Extracts bit fields from character string data and converts the result, as an unsigned value, to an integer.
> F$DEVICE | Returns device names of all devices on a system that meet the specified selection criteria.
> F$DIRECTORY | Returns the current default directory name string.
> F$EDIT | Edits a character string based on the edits specified.
> F$ELEMENT | Extracts an element from a string in which the elements are separated by a specified delimiter.
> F$ENVIRONMENT | Obtains information about the DCL command environment.
> F$EXTRACT | Extracts a substring from a character string expression.
> F$FAO | Invokes the $FAO system service to convert the specified control string to a formatted ASCII output string.
> F$FILE_ATTRIBUTES | Returns attribute information for a specified file.
> F$GETDVI | Invokes the $GETDVI system service to return a specified item of information for a specified device.
> F$GETJPI | Invokes the $GETJPI system service to return accounting, status, and identification information for a process.
> F$GETQUI | Invokes the $GETQUI system service to return information about queues, batch and print jobs currently in those queues, form definitions, and characteristic definitions kept in the queue database. +On VAX, also returns information about a queue manager.
> F$GETSYI | Invokes the $GETSYI system service to return status and identification information about the local system, or about a node in the local cluster, if your system is part of a cluster.
> F$IDENTIFIER | Converts an identifier in named format to its integer equivalent, or vice versa.
> F$INTEGER | Returns the integer equivalent of the result of the specified expression.
> F$LENGTH | Returns the length of a specified string.
> F$LOCATE | Locates a character or character substring within a string and returns its offset within the string.
> F$MESSAGE | Returns the message text associated with a specified system status code value.
> F$MODE | Shows the mode in which a process is executing.
> F$PARSE | Invokes the $PARSE RMS service to parse a file specification and return either the expanded file specification or the particular file specification field that you request.
> F$PID | For each invocation, returns the next process identification number in sequence.
> F$PRIVILEGE | Returns a value of TRUE or FALSE depending on whether your current process privileges match the privileges listed in the argument.
> F$PROCESS | Returns the current process name string.
> F$SEARCH | Invokes the $SEARCH RMS service to search a directory file, and returns the full file specification for a file you name.
> F$SETPRV | Sets the specified privileges and returns a list of keywords indicating the previous state of these privileges for the current process.
> F$STRING | Returns the string equivalent of the result of the specified expression.
> F$TIME | Returns the current date and time of day, in the format dd-mmm-yyyy hh:mm:ss.cc.
> F$TRNLNM | Translates a logical name and returns the equivalence name string or the requested attributes of the logical name.
> F$TYPE | Determines the data type of a symbol.
> F$USER | Returns the current user identification code (UIC).
> F$VERIFY | Returns the integer 1 if command procedure verification is set on; returns the integer 0 if command procedure verification is set off. The F$VERIFY function also can set new verification states.

+VAX specific

## F$CONTEXT

> Specifies selection criteria for use with the F$PID function. The F$CONTEXT function enables the F$PID function to obtain information about processes from any node in an OpenVMS Cluster system.

### Format

> F$CONTEXT (context-type, context-symbol, selection-item, selection-value, value-qualifier)

### Return Value

A null string ("").

### Arguments

> #### context-type

> Specifies the type of context to be built.

> At present, the only context type available is PROCESS, which is used in constructing selection criteria for F$PID. Privileges are not required to see processes for the same UIC. To see processes for another UIC in the same UIC group, you need the GROUP privilege, and to see processes systemwide, you need the WORLD privilege.

> #### context-symbol

> Specifies a symbol that DCL uses to refer to the context memory being constructed by the F$CONTEXT function. The function F$PID uses this context symbol to process the appropriate list of process identification (PID) numbers.

> Specify the context symbol by using a symbol. The first time you use the F$CONTEXT function in a command procedure, use a symbol that is either undefined or equated to the null string. The symbol created will be a local symbol of type "PROCESS_CONTEXT". When the context is no longer valid---that is, when all PIDs have been retrieved by calls to the F$PID function or an error occurs during one of these calls---the symbol no longer has a type of "PROCESS_CONTEXT". Then you can use the F$TYPE function in the command procedure to find out if it is necessary to cancel the context.

> After setting up the selection criteria, use this context symbol when calling F$PID.

> #### selection-item

> Specifies a keyword that tells F$CONTEXT which selection criterion to use. Use only one selection-item keyword per call to F$CONTEXT.

> Note Do not use the NEQ selection value on a list of items because it causes the condition to always be true. For example:
>     $ EXAMPLE=f$context("PROCESS",CTX,"USERNAME","A*,B*","NEQ")
> This equation is parsed as "if the user name is not equal to A* or the user name is not equal to B*, then return the process of the users that meet the criteria." Because the operand is a logical or, the conditions will always be true (any name will be found to be not equal to A* or B*; ALFRED will not be equal to B*; BOB will not be equal to A*).

> The following table shows valid selection-item keywords for the PROCESS context type:

> Selection Item | Selection Value | Value Qualifiers | Comments
> --- | --- | --- | ---
> ACCOUNT | String | EQL, NEQ | Valid account name or list of names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
> AUTHPRI | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | On Alpha, valid authorized base priority (0--63). On VAX, valid authorized base priority (0--31).
> CANCEL |  |  | Cancels the selection criteria for this context.
> CURPRIV | Keyword | ALL, ANY, EQL, NEQ | Valid privilege name keyword or list of keywords. For more information, refer to the OpenVMS Guide to System Security.
> GRP | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | UIC group number.
> HW_MODEL | Integer | EQL, NEQ | Valid hardware model number.
> HW_NAME | String | EQL, NEQ | Valid hardware name or a list of keywords. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
> JOBPRCCNT | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | Subprocess count for entire job.
> JOBTYPE | Keyword | EQL, NEQ | Valid job-type keyword. Valid keywords are DETACHED, NETWORK, BATCH, LOCAL, DIALUP, and REMOTE. For more information, refer to the OpenVMS User's Manual.
> MASTER_PID | String | EQL, NEQ | PID of master process.
> MEM | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | UIC member number.
> MODE | Keyword | EQL, NEQ | Valid process mode keyword. Valid keywords are OTHER, NETWORK, BATCH, and INTERACTIVE. For more information, see the OpenVMS User's Manual.
> NODE_CSID | Integer | EQL, NEQ | Node's cluster ID number.
> NODENAME | String | EQL, NEQ | Node name or list of node names. The asterisk (*) and the percent sign (%) wildcard characters are allowed. The default is your local node. To request all nodes, use the value "*".
> OWNER | String | EQL, NEQ | PID of immediate parent process.
> PRCCNT | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | Subprocess count of process.
> PRCNAM | String | EQL, NEQ | Process name or list of process names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
> PRI | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | Process priority level number (0--63, on Alpha), (0--31, on VAX).
> PRIB | Integer | GEQ, GTR, LEQ, LSS, EQL, NEQ | Base process priority level number (0--63, on Alpha), (0--31, on VAX).
> STATE | Keyword | EQL, NEQ | Valid process state keyword. For more information, refer to the description of the $GETJPI service in the OpenVMS System Services Reference Manual.
> STS | Keyword | EQL, NEQ | Valid process status keyword. For more information, refer to the description of the $GETJPI service in the OpenVMS System Services Reference Manual.
> TERMINAL | String | EQL, NEQ | Terminal name or list of names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.
> UIC | String | EQL, NEQ | User identification code (UIC) identifier (that is, of the form "[group,member]").
> USERNAME | String | EQL, NEQ | User name or list of user names. The asterisk (*) and the percent sign (%) wildcard characters are allowed.

> #### selection-value

> Specifies the value of the selection criteria. For example, to process all the processes running on node MYVAX, specify "MYVAX" with the "NODENAME" keyword. For example:

>     $ X = F$CONTEXT("PROCESS", ctx, "NODENAME", "MYVAX", "EQL")

> Values that are lists are valid with some selection items. If you specify more than one item, separate them with commas (,). The following example specifies a list of the nodes MYVAX, HERVAX, and HISVAX:

>     $ X=F$CONTEXT("PROCESS",ctx,"NODENAME","MYVAX,HERVAX,HISVAX","EQL")

> You can use the asterisk (*) and the percent sign (%) wildcard characters for some values. Using wildcard characters for selection items is similar to using wildcard characters for file names.

> #### value-qualifier

> Specifies qualifiers for selection values. You must qualify selection values.

> You can qualify a number, for example, by requesting that the selection be based on one of the following process values:

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

> You can qualify some lists with the ALL, ANY, EQL, or NEQ keywords. Such lists are usually masks such as the process privilege mask, which consists of the set of enabled privileges.

> - ALL --- requires that all items in the list be true for a process
> - ANY --- requests that any item in the list be part of the attributes of a process
> - EQL --- requires the values to match exactly (that is, values not specified must not be true of the process)
> - NEQ --- requires that the value must not match

> When using multiple selection values with a particular selection qualifier, a match on any one of the selection criteria is considered valid (as if an OR operand was in place); the selection values are not cumulative criteria (as if an AND operand was in place).

> The difference between ALL and EQL is that the values specified with ALL must exist, but other unspecified values can exist also. EQL requires that all values specified must exist, and all others may not. For example, to request those processes whose current privileges include TMPMBX (temporary mailbox) and OPER (operator), but may include other privileges, specify the ALL keyword. To request those processes whose current privileges are TMPMBX and OPER exclusively, specify the EQL keyword.

### Description

> Use the F$CONTEXT function to set up selection criteria for the F$PID function.

> The F$CONTEXT function is called as many times as necessary to produce the criteria needed; however, each call can specify only one selection item. Lists of item values are allowed, where appropriate, and more than one context can be operated upon at a time.

> After establishing the selection criteria with appropriate calls to F$CONTEXT, F$PID is called repeatedly to return all the process identification (PID) numbers that meet the criteria specified in the F$CONTEXT function. When there are no more such processes, the F$PID function returns a null string.

> After the F$PID function is called, the context symbol is considered "frozen"; F$CONTEXT cannot be called again with the same context symbol until the associated context selection criteria have been deleted. If you attempt to set up additional selection criteria with the same context symbol, an error message is displayed; however, the context and selection criteria are not affected and calls to the F$PID function can continue.

> The F$CONTEXT function uses process memory to store the selection criteria. This memory is deleted under two circumstances. Memory is deleted when the F$PID function is called and a null string ("") is returned---that is, when all processes that meet the selection criteria have been returned. Memory also is deleted if the CANCEL selection-item keyword is used in a call to F$CONTEXT with an established context. This type of call is appropriate for a Ctrl/Y operation or another condition handling routine.

###

#### Examples

#1
    $!Establish an error and Ctrl/Y handler
    $!
    $ ON ERROR THEN GOTO error
    $ ON CONTROL_Y THEN GOTO error
    $!
    $ ctx = ""
    $ temp = F$CONTEXT ("PROCESS", ctx, "NODENAME", "*","EQL")
    $ temp = F$CONTEXT ("PROCESS", ctx, "USERNAME", "M*,SYSTEM","EQL")
    $ temp = F$CONTEXT ("PROCESS", ctx, "CURPRIV", "SYSPRV,OPER", "ALL")

    $!
    $!Loop over all processes that meet the selection criteria.
    $!Print the PID and the name of the image for each process.
    $!
    $loop:
    $ pid = F$PID(ctx)
    $ IF pid .EQS. ""
    $ THEN
    $     GOTO endloop
    $ ELSE
    $     image = F$GETJPI(pid,"IMAGNAME")
    $     SHOW SYMBOL pid
    $     WRITE SYS$OUTPUT image
    $     GOTO loop
    $ ENDIF
    $!The loop over the processes has ended.
    $!
    $endloop:
    $!
    $ EXIT
    $!
    $!Error handler. Clean up the context's memory with
    $!the CANCEL selection item keyword.
    $!
    $error:
    $ IF F$TYPE(ctx) .eqs. "PROCESS_CONTEXT" THEN -
    _$ temp = F$CONTEXT ("PROCESS", ctx, "CANCEL")
    $!
    $ EXIT

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 9996PRO_026.HTML