OpenVMS DCL Dictionary

Document revision date: 19 July 1999

OpenVMS DCL Dictionary

Contents

Index

This example shows how to use the F$GETDVI function to return an error count for the device DQA0. You must place quotation marks (" ") around the device name DQA0 and the item ERRCNT because they are string literals.

F$GETENV (Alpha Only)

Returns the value of the specified console environment variable.

Format

F$GETENV (itmlst)

Return Value

Returns the value of the specified console environment variable. You can modify the console environment variables when the system is in console mode. This lexical function allows you to read the contents of these variables when the system is running.

Arguments

itmlst
The defined console environment variable names are:
Auto_action, Boot_dev, Bootdef_dev, Booted_dev, Boot_file, Booted_file, Boot_osflags, Booted_osflags, Boot_reset, Dump_dev, Enable_audit, License, Char_set, Language, Tty_dev

Description

Returns the value(s) of the specified console environment variable(s).

Example


$ dump_device = f$getenv("dump_dev") $ write sys$output "The dump device for this system is ", dump_device

This function writes out the dump device for the system.

F$GETJPI

Returns information about the specified process.
Requires GROUP privilege to obtain information on other processes in the same group. Requires WORLD privilege to obtain information on any other processes in the system.

Format

F$GETJPI (pid,item)

Return Value

Either an integer or a character string, depending on the item you request. Table DCLI-9 shows the data types of the values returned for each item.

Arguments

pid
Specifies the process identification (PID) number of the process for which information is being reported. Specify the pid argument as a character string expression. You can omit the leading zeros.
If you specify a null string (""), the current PID number is used.
You cannot use an asterisk (*) or percent sign (%) wildcard character to specify the pid argument in the F$GETJPI function, as you can with the $GETJPI system service. To get a list of process identification numbers, use the F$PID function.
item
Indicates the type of process information to be returned. Specify the item argument as a character string expression. You can specify any one of the items listed in Table DCLI-9.

Description

The F$GETJPI lexical function invokes the $GETJPI system service to return information about the specified process. The function returns information on all items that can be specified with the $GETJPI system service. For more information on the $GETJPI system service, refer to the OpenVMS System Services Reference Manual.
The F$GETJPI lexical function returns a zero or a null string if the target process is in a suspended or MWAIT (resource wait) state and the item requested is stored in the virtual address space of the process.
You can use the F$GETJPI lexical function to find out whether a process automatically unshelves files.
When you specify the STS2 item code, F$GETJPI returns a 32--bit numeric value. When you convert this numeric value to binary format, the digit at symbolic bit position PCB$V_NOUNSHELVE shows you the process unshelving default. If the bit is 1, automatic unshelving is turned off; if 0, automatic unshelving is turned on.
Table DCLI-9 lists the items you can specify with the F$GETJPI function, the information returned, and the data type of this information.

Table DCLI-9 F$GETJPI Items
Item Return Type Information Returned

ACCOUNT String Account name string (8 characters filled with trailing blanks).

APTCNT Integer Active page table count.

ASTACT Integer Access modes with active asynchronous system traps (ASTs).

ASTCNT Integer Remaining AST quota.

ASTEN Integer Access modes with ASTs enabled.

ASTLM Integer AST limit quota.

AUTHPRI Integer Maximum priority that a process without the ALTPRI (alter priority) privilege can achieve with the $SETPRI system service.

AUTHPRIV String Privileges that a process is authorized to enable.

BIOCNT Integer Remaining buffered I/O quota.

BIOLM Integer Buffered I/O limit quota.

BUFIO Integer Count of process buffered I/O operations.

BYTCNT Integer Remaining buffered I/O byte count quota.

BYTLM Integer Buffered I/O byte count quota.

CLINAME String Current command language interpreter; always returns DCL.

CPULIM Integer Limit on process CPU time.

CPUTIM Integer CPU time used in hundredths of a second.

CREPRC_FLAGS Integer Flags specified by the stsflg argument in the $CREPRC call that created the process.

CURPRIV String Current process privileges.

DFPFC Integer Default page fault cluster size.

DFWSCNT Integer Default working set size.

DIOCNT Integer Remaining direct I/O quota.

DIOLM Integer Direct I/O limit quota.

DIRIO Integer Count of direct I/O operations for the process.

EFCS Integer Local event flags 0--31.

EFCU Integer Local event flags 32--63.

EFWM Integer Event flag wait mask.

ENQCNT Integer Lock request quota remaining.

ENQLM Integer Lock request quota limit.

EXCVEC Integer Address of a list of exception vectors.

FAST_VP_SWITCH Integer Number of times this process has issued a vector instruction that enabled an inactive vector processor without the expense of a vector context switch.

FILCNT Integer Remaining open file quota.

FILLM Integer Open file quota.

FINALEXC Integer Address of a list of final exception vectors.

FREP0VA Integer First free page at end of program region (P0 space) (irrelevant if no image is running).

FREP1VA Integer First free page at end of control region (P1 space).

FREPTECNT Integer Number of pages available for virtual memory expansion.

GPGCNT Integer Global page count in working set.

GRP Integer Group number of the user identification code (UIC).

IMAGECOUNT Integer Number of images that have been run down for the process.

IMAGNAME String File name of the current image.

IMAGPRIV String Privileges with which the current image was installed.

JOBPRCCNT Integer Number of subprocesses owned by the job.

JOBTYPE Integer Execution mode of the process at the root of the job tree.

LAST_LOGIN_I String Time of your last interactive login (the value that was reported when you logged in).

LAST_LOGIN_N String Time of your last noninteractive login (the value that was reported when you logged in).

LOGIN_FAILURES Integer Number of login failures that occurred prior to the start of the current session (the value that was reported when you logged in).

LOGIN_FLAGS Integer A longword bitmask that contains additional information relating to the login sequence.

LOGINTIM String Process creation time.

MASTER_PID String Process identification (PID) number of the process at the top of the current job's process tree.

MAXDETACH Integer Maximum number of detached processes allowed the user who owns the process.

MAXJOBS Integer Maximum number of active processes allowed for the user who owns the process.

MEM Integer Member number of the UIC.

MODE String Current process mode (BATCH, INTERACTIVE, NETWORK, or OTHER).

MSGMASK Integer Default message mask.

NODENAME String The name of the OpenVMS Cluster node on which the process is running.

NODE_CSID Integer Cluster ID of the OpenVMS Cluster node on which the process is running.

NODE_VERSION String Operating system version number of the OpenVMS Cluster node on which the process is running.

OWNER String Process identification number of process owner.

PAGEFLTS Integer Count of page faults.

PAGFILCNT Integer Remaining paging file quota.

PAGFILLOC Integer Location of the paging file.

PARSE_STYLE_PERM (Alpha only) String Values that were set by $SET_PROCESS_PROPERTIESW.

PARSE_STYLE_IMAGE (Alpha only) String Values that were set by $SET_PROCESS_PROPERTIESW.

PGFLQUOTA Integer Paging file quota (maximum virtual page count).

PHDFLAGS Integer Flags word.

PID String Process identification number.

PPGCNT Integer Process page count.

PRCCNT Integer Number of subprocesses owned by the process.

PRCLM Integer Subprocess quota.

PRCNAM String Process name.

PRI Integer Process's current priority.

PRIB Integer Process's base priority.

PROC_INDEX Integer Process's index number.

PROCESS_RIGHTS String The contents of the process's local rights list, including your UIC. This item code returns a list of identifier names separated by commas (,).

PROCPRIV String Process's default privileges.

RIGHTSLIST String The contents of all of the process rights lists; the equivalent of PROCESS_RIGHTS plus SYSTEM_RIGHTS. This item code returns a list of identifier names separated by commas.

RIGHTS_SIZE Integer Number of bytes required to buffer the rights list. The rights list includes both the system rights list and the process rights list.

SHRFILLM Integer Maximum number of open shared files allowed for the job to which the process belongs.

SITESPEC Integer Per-process site-specific longword.

SLOW_VP_SWITCH Integer Number of times this process has issued a vector instruction that enabled an inactive vector processor with a full vector context switch.

STATE String Process state.

STS Integer First longword of process status flags.

STS2 Integer Second longword of process status flags.

SWPFILLOC Integer Location of the swap file.

SYSTEM_RIGHTS String The contents of the system rights list for the process. This item code returns a list of identifier names separated by commas.

TABLENAME String File specification of the process's current command language interpreter (CLI) table.

TERMINAL String Login terminal name for interactive users (1--7 characters).

TMBU Integer Termination mailbox unit number.

TQCNT Integer Remaining timer queue entry quota.

TQLM Integer Timer queue entry quota.

TT_ACCPORNAM String Access port name for the terminal associated with the process.

TT_PHYDEVNAM String Physical device name of the terminal associated with the process.

UAF_FLAGS Integer User authorization file (UAF) flags from the UAF record of the user who owns the process.

UIC String Process's user identification code (UIC).

USERNAME String User name string (12 characters filled with trailing blanks).

VIRTPEAK Integer Peak virtual address size.

VOLUMES Integer Count of currently mounted volumes.

VP_CONSUMER Boolean Flag indicating whether the process is a vector consumer.

VP_CPUTIM Integer Total amount of time the process has accumulated as a vector customer.

WSAUTH Integer Maximum authorized working set size.

WSAUTHEXT Integer Maximum authorized working set extent.

WSEXTENT Integer Current working set extent.

WSPEAK Integer Working set peak.

WSQUOTA Integer Working set size quota.

WSSIZE Integer Process's current working set size.

If you use the $GETJPI function to request information on the null process or the swapper process, you can specify any of the items in Table DCLI-9 except the following:

ACCOUNT BYTLM ENQCNT ENQLM

EXCVEC FILCNT FILM FINALEXC

IMAGNAME LOGINTIM MSGMASK PAGFILCNT

PGFLQUOTA PRCCNT PRCLM PROCPRIV

SITESPEC TQCNT TQLM USERNAME

VIRTPEAK VOLUMES WSPEAK

**Table DCLI-9 F$GETJPI Items**
Item	Return Type	Information Returned
ACCOUNT	String	Account name string (8 characters filled with trailing blanks).
APTCNT	Integer	Active page table count.
ASTACT	Integer	Access modes with active asynchronous system traps (ASTs).
ASTCNT	Integer	Remaining AST quota.
ASTEN	Integer	Access modes with ASTs enabled.
ASTLM	Integer	AST limit quota.
AUTHPRI	Integer	Maximum priority that a process without the ALTPRI (alter priority) privilege can achieve with the $SETPRI system service.
AUTHPRIV	String	Privileges that a process is authorized to enable.
BIOCNT	Integer	Remaining buffered I/O quota.
BIOLM	Integer	Buffered I/O limit quota.
BUFIO	Integer	Count of process buffered I/O operations.
BYTCNT	Integer	Remaining buffered I/O byte count quota.
BYTLM	Integer	Buffered I/O byte count quota.
CLINAME	String	Current command language interpreter; always returns DCL.
CPULIM	Integer	Limit on process CPU time.
CPUTIM	Integer	CPU time used in hundredths of a second.
CREPRC_FLAGS	Integer	Flags specified by the stsflg argument in the $CREPRC call that created the process.
CURPRIV	String	Current process privileges.
DFPFC	Integer	Default page fault cluster size.
DFWSCNT	Integer	Default working set size.
DIOCNT	Integer	Remaining direct I/O quota.
DIOLM	Integer	Direct I/O limit quota.
DIRIO	Integer	Count of direct I/O operations for the process.
EFCS	Integer	Local event flags 0--31.
EFCU	Integer	Local event flags 32--63.
EFWM	Integer	Event flag wait mask.
ENQCNT	Integer	Lock request quota remaining.
ENQLM	Integer	Lock request quota limit.
EXCVEC	Integer	Address of a list of exception vectors.
FAST_VP_SWITCH	Integer	Number of times this process has issued a vector instruction that enabled an inactive vector processor without the expense of a vector context switch.
FILCNT	Integer	Remaining open file quota.
FILLM	Integer	Open file quota.
FINALEXC	Integer	Address of a list of final exception vectors.
FREP0VA	Integer	First free page at end of program region (P0 space) (irrelevant if no image is running).
FREP1VA	Integer	First free page at end of control region (P1 space).
FREPTECNT	Integer	Number of pages available for virtual memory expansion.
GPGCNT	Integer	Global page count in working set.
GRP	Integer	Group number of the user identification code (UIC).
IMAGECOUNT	Integer	Number of images that have been run down for the process.
IMAGNAME	String	File name of the current image.
IMAGPRIV	String	Privileges with which the current image was installed.
JOBPRCCNT	Integer	Number of subprocesses owned by the job.
JOBTYPE	Integer	Execution mode of the process at the root of the job tree.
LAST_LOGIN_I	String	Time of your last interactive login (the value that was reported when you logged in).
LAST_LOGIN_N	String	Time of your last noninteractive login (the value that was reported when you logged in).
LOGIN_FAILURES	Integer	Number of login failures that occurred prior to the start of the current session (the value that was reported when you logged in).
LOGIN_FLAGS	Integer	A longword bitmask that contains additional information relating to the login sequence.
LOGINTIM	String	Process creation time.
MASTER_PID	String	Process identification (PID) number of the process at the top of the current job's process tree.
MAXDETACH	Integer	Maximum number of detached processes allowed the user who owns the process.
MAXJOBS	Integer	Maximum number of active processes allowed for the user who owns the process.
MEM	Integer	Member number of the UIC.
MODE	String	Current process mode (BATCH, INTERACTIVE, NETWORK, or OTHER).
MSGMASK	Integer	Default message mask.
NODENAME	String	The name of the OpenVMS Cluster node on which the process is running.
NODE_CSID	Integer	Cluster ID of the OpenVMS Cluster node on which the process is running.
NODE_VERSION	String	Operating system version number of the OpenVMS Cluster node on which the process is running.
OWNER	String	Process identification number of process owner.
PAGEFLTS	Integer	Count of page faults.
PAGFILCNT	Integer	Remaining paging file quota.
PAGFILLOC	Integer	Location of the paging file.
PARSE_STYLE_PERM (Alpha only)	String	Values that were set by $SET_PROCESS_PROPERTIESW.
PARSE_STYLE_IMAGE (Alpha only)	String	Values that were set by $SET_PROCESS_PROPERTIESW.
PGFLQUOTA	Integer	Paging file quota (maximum virtual page count).
PHDFLAGS	Integer	Flags word.
PID	String	Process identification number.
PPGCNT	Integer	Process page count.
PRCCNT	Integer	Number of subprocesses owned by the process.
PRCLM	Integer	Subprocess quota.
PRCNAM	String	Process name.
PRI	Integer	Process's current priority.
PRIB	Integer	Process's base priority.
PROC_INDEX	Integer	Process's index number.
PROCESS_RIGHTS	String	The contents of the process's local rights list, including your UIC. This item code returns a list of identifier names separated by commas (,).
PROCPRIV	String	Process's default privileges.
RIGHTSLIST	String	The contents of all of the process rights lists; the equivalent of PROCESS_RIGHTS plus SYSTEM_RIGHTS. This item code returns a list of identifier names separated by commas.
RIGHTS_SIZE	Integer	Number of bytes required to buffer the rights list. The rights list includes both the system rights list and the process rights list.
SHRFILLM	Integer	Maximum number of open shared files allowed for the job to which the process belongs.
SITESPEC	Integer	Per-process site-specific longword.
SLOW_VP_SWITCH	Integer	Number of times this process has issued a vector instruction that enabled an inactive vector processor with a full vector context switch.
STATE	String	Process state.
STS	Integer	First longword of process status flags.
STS2	Integer	Second longword of process status flags.
SWPFILLOC	Integer	Location of the swap file.
SYSTEM_RIGHTS	String	The contents of the system rights list for the process. This item code returns a list of identifier names separated by commas.
TABLENAME	String	File specification of the process's current command language interpreter (CLI) table.
TERMINAL	String	Login terminal name for interactive users (1--7 characters).
TMBU	Integer	Termination mailbox unit number.
TQCNT	Integer	Remaining timer queue entry quota.
TQLM	Integer	Timer queue entry quota.
TT_ACCPORNAM	String	Access port name for the terminal associated with the process.
TT_PHYDEVNAM	String	Physical device name of the terminal associated with the process.
UAF_FLAGS	Integer	User authorization file (UAF) flags from the UAF record of the user who owns the process.
UIC	String	Process's user identification code (UIC).
USERNAME	String	User name string (12 characters filled with trailing blanks).
VIRTPEAK	Integer	Peak virtual address size.
VOLUMES	Integer	Count of currently mounted volumes.
VP_CONSUMER	Boolean	Flag indicating whether the process is a vector consumer.
VP_CPUTIM	Integer	Total amount of time the process has accumulated as a vector customer.
WSAUTH	Integer	Maximum authorized working set size.
WSAUTHEXT	Integer	Maximum authorized working set extent.
WSEXTENT	Integer	Current working set extent.
WSPEAK	Integer	Working set peak.
WSQUOTA	Integer	Working set size quota.
WSSIZE	Integer	Process's current working set size.

Example


$ NAME = F$GETJPI("3B0018","USERNAME") $ SHOW SYMBOL NAME NAME = "JANE "

This example shows how to use the F$GETJPI function to return the user name for the process number 3B0018. The user name is assigned to the symbol NAME.

F$GETQUI

Returns information about queues, including batch and print jobs currently in the queues, form definitions, and characteristic definitions kept in the queue database.
Also returns information about queue managers.
For most operations, read (R) access is required.

Format

F$GETQUI (function,[item],[object-id],[flags])

Return Value

Either an integer or a character string, depending on the item you request. For items that return a Boolean value, the string is TRUE or FALSE. If the $GETQUI system service returns an error code, F$GETQUI returns a null string ("").

Arguments

function
Specifies the action that the F$GETQUI lexical function is to perform. F$GETQUI supports all functions that can be specified with the $GETQUI system service. The following table lists these functions:

Function Description

CANCEL_OPERATION Terminates any wildcard operation that may have been initiated by a previous call to F$GETQUI.

DISPLAY_CHARACTERISTIC Returns information about a specific characteristic definition or the next characteristic definition in a wildcard operation.

DISPLAY_ENTRY Returns information about a specific job entry or the next job entry that matches the selection criteria in a wildcard operation. The DISPLAY_ENTRY function code is similar to the DISPLAY_JOB function code in that both return job information. DISPLAY_JOB, however, requires that a call be made to establish queue context; DISPLAY_ENTRY does not require that queue context be established. Only those entries that match the user-name of the current process will be processed.

DISPLAY_FILE Returns information about the next file defined for the current job context. Before you make a call to F$GETQUI to request file information, you must make a call to display queue and job information (with the DISPLAY_QUEUE and DISPLAY_JOB function codes) or to display entry information (with the DISPLAY_ENTRY function code).

DISPLAY_FORM Returns information about a specific form definition or the next form definition in a wildcard operation.

DISPLAY_JOB Returns information about the next job defined for the current queue context. Before you make a call to F$GETQUI to request job information, you must make a call to display queue information (with the DISPLAY_QUEUE function code). The DISPLAY_JOB function code is similar to the DISPLAY_ENTRY function code in that both return job information. DISPLAY_JOB, however, requires that a call be made to establish queue context; DISPLAY_ENTRY does not require that queue context be established.

DISPLAY_MANAGER Returns information about a specific queue manager or the next queue manager in a wildcard operation.

DISPLAY_QUEUE Returns information about a specific queue definition or the next queue definition in a wildcard operation.

TRANSLATE_QUEUE Translates a logical name for a queue to the equivalence name for the queue.

Some function arguments cannot be specified with the item-code, the object-id, or the flags argument. The following table lists each function argument and corresponding format line to show whether the item-code, object-id and flags arguments are required, optional, or not applicable for that specific function. In the following format lines, brackets ([ ]) denote an optional argument. An omitted argument means the argument is not applicable for that function. Note that two commas (,,) must be used as placeholders to denote an omitted (whether optional or not applicable) argument.

Function Format Line

CANCEL_OPERATION F$GETQUI("CANCEL_OPERATION") or F$GETQUI(" ")

DISPLAY_CHARACTERISTIC F$GETQUI("DISPLAY_CHARACTERISTIC", [item],object-id,[flags])

DISPLAY_ENTRY F$GETQUI("DISPLAY_ENTRY",[item], [object-id],[flags])

DISPLAY_FILE F$GETQUI("DISPLAY_FILE",[item],,[flags])

DISPLAY_FORM F$GETQUI("DISPLAY_FORM",[item], object-id,[flags])

DISPLAY_JOB F$GETQUI("DISPLAY_JOB",[item],,[flags])

DISPLAY_MANAGER F$GETQUI("DISPLAY_MANAGER",[item], object-id,[flags])

DISPLAY_QUEUE F$GETQUI("DISPLAY_QUEUE",[item], object-id,[flags])

TRANSLATE_QUEUE F$GETQUI("TRANSLATE_QUEUE",[item],object-id)

item
Corresponds to a $GETQUI system service output item code. The item argument specifies the kind of information you want returned about a particular queue, job, file, form, or characteristic. On VAX, queue manager information is also available. Table DCLI-11 lists each item code and the data type of the value returned for each item code.
object-id
Corresponds to the $GETQUI system service QUI$SEARCH_NAME, QUI$_SEARCH_NUMBER, and QUI$_SEARCH_JOB_NAME input item codes. The object-id argument specifies either the name or the number of an object (for example, a specific queue name, job name, or form number) about which F$GETQUI is to return information. The asterisk (*) and the percent sign (%) wildcard characters are allowed for the following functions:

DISPLAY_CHARACTERISTIC
DISPLAY_ENTRY
DISPLAY_FORM
DISPLAY_MANAGER
DISPLAY_QUEUE

Previous Next Contents Index

privacy and legal statement

9996PRO_031.HTML

Function	Description
CANCEL_OPERATION	Terminates any wildcard operation that may have been initiated by a previous call to F$GETQUI.
DISPLAY_CHARACTERISTIC	Returns information about a specific characteristic definition or the next characteristic definition in a wildcard operation.
DISPLAY_ENTRY	Returns information about a specific job entry or the next job entry that matches the selection criteria in a wildcard operation. The DISPLAY_ENTRY function code is similar to the DISPLAY_JOB function code in that both return job information. DISPLAY_JOB, however, requires that a call be made to establish queue context; DISPLAY_ENTRY does not require that queue context be established. Only those entries that match the user-name of the current process will be processed.
DISPLAY_FILE	Returns information about the next file defined for the current job context. Before you make a call to F$GETQUI to request file information, you must make a call to display queue and job information (with the DISPLAY_QUEUE and DISPLAY_JOB function codes) or to display entry information (with the DISPLAY_ENTRY function code).
DISPLAY_FORM	Returns information about a specific form definition or the next form definition in a wildcard operation.
DISPLAY_JOB	Returns information about the next job defined for the current queue context. Before you make a call to F$GETQUI to request job information, you must make a call to display queue information (with the DISPLAY_QUEUE function code). The DISPLAY_JOB function code is similar to the DISPLAY_ENTRY function code in that both return job information. DISPLAY_JOB, however, requires that a call be made to establish queue context; DISPLAY_ENTRY does not require that queue context be established.
DISPLAY_MANAGER	Returns information about a specific queue manager or the next queue manager in a wildcard operation.
DISPLAY_QUEUE	Returns information about a specific queue definition or the next queue definition in a wildcard operation.
TRANSLATE_QUEUE	Translates a logical name for a queue to the equivalence name for the queue.

Function	Format Line
CANCEL_OPERATION	F$GETQUI("CANCEL_OPERATION") or F$GETQUI(" ")
DISPLAY_CHARACTERISTIC	F$GETQUI("DISPLAY_CHARACTERISTIC", [item],object-id,[flags])
DISPLAY_ENTRY	F$GETQUI("DISPLAY_ENTRY",[item], [object-id],[flags])
DISPLAY_FILE	F$GETQUI("DISPLAY_FILE",[item],,[flags])
DISPLAY_FORM	F$GETQUI("DISPLAY_FORM",[item], object-id,[flags])
DISPLAY_JOB	F$GETQUI("DISPLAY_JOB",[item],,[flags])
DISPLAY_MANAGER	F$GETQUI("DISPLAY_MANAGER",[item], object-id,[flags])
DISPLAY_QUEUE	F$GETQUI("DISPLAY_QUEUE",[item], object-id,[flags])
TRANSLATE_QUEUE	F$GETQUI("TRANSLATE_QUEUE",[item],object-id)