 |
HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
In this example, the F$PARSE function is used to parse a file
specification containing a node name. The F$PARSE function returns the
file type .DAT for the file RUN.DAT at the remote node DENVER.
Returns a process identification (PID) number and updates the context
symbol to point to the current position in the system's process list.
Format
F$PID (context-symbol)
Return Value
A character string containing the PID of a process in the system's list
of processes.
Argument
context-symbol
Specifies a symbol that DCL uses to store a pointer into the system's
list of processes. The F$PID function uses this pointer to return a PID.
Specify the context symbol by using a symbol. The first time you use
the F$PID function in a command procedure, you should use a symbol that
is either undefined or equated to the null string ("") or a context
symbol that has been created by the F$CONTEXT function.
If the context symbol is undefined or equated to a null string, the
F$PID function returns the first PID in the system's process list that
it has the privilege to access. That is, if you have GROUP privilege
and if the context symbol is null or undefined, the F$PID function
returns the PID of the first process in your group. If you have WORLD
privilege, the F$PID function returns the PID of the first process in
the list. If you have neither GROUP nor WORLD privilege, the F$PID
returns the first process that you own. Subsequent calls to F$PID
return the rest of the processes on the system you are accessing.
If the context symbol has been created by the F$CONTEXT function, the
F$PID function returns the first process name in the system's process
list that fits the criteria specified in the F$CONTEXT calls.
Subsequent calls to F$PID return only the PIDs of those processes that
meet the selection criteria set up by the F$CONTEXT function and that
are accessible to your current privileges.
Description
The F$PID function returns a process identification (PID) number and
updates the context symbol to point to the current position in the
system's process list. You can step through all the processes on a
system, or use the lexical function F$CONTEXT to specify selection
criteria. The function F$CONTEXT is not required.
The PIDs returned by the F$PID function depend on the privilege of your
process. If you have GROUP privilege, the F$PID function returns PIDs
of processes in your group. If you have WORLD privilege, the F$PID
function returns PIDs of all processes on the system. If you lack GROUP
or WORLD privilege, the F$PID function returns only those processes
that you own.
The F$CONTEXT function enables the F$PID function to retrieve processes
from any node in a mixed-architecture OpenVMS Cluster system.
The first time you use the F$PID function, use a symbol that is either
undefined or equated to the null string or to a context symbol that has
been created by the F$CONTEXT function. This causes the F$PID function
to return the first PID in the system's process list that you have the
privilege to access. It also causes the F$PID function to initialize
the context-symbol argument.
Once the context-symbol argument is initialized, each
subsequent F$PID returns the next PID in sequence, using the selection
criteria set up by the F$CONTEXT function, if any, and updates the
context symbol. After the last PID in the process list is returned, the
F$PID function returns a null string.
Example
|
$ CONTEXT = ""
$ START:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. "" THEN EXIT
$ SHOW SYMBOL PID
$ GOTO START
|
This command procedure uses the F$PID function to display a list of
PIDs. The assignment statement declares the symbol CONTEXT, which is
used as the context-symbol argument for the F$PID
function. Because CONTEXT is equated to a null string, the F$PID
function returns the first PID in the process list that it has the
privilege to access.
The PIDs displayed by this command procedure depend on the privilege of
your process. When run with GROUP privilege, the PIDs of users in your
group are displayed. When run with WORLD privilege, the PIDs of all
users on the system are displayed. Without GROUP or WORLD privilege,
only those processes that you own are displayed.
F$PRIVILEGE
Returns a string value of either TRUE or FALSE, depending on whether
your current process privileges match those specified in the argument.
You can specify either the positive or negative version of a privilege.
Format
F$PRIVILEGE (priv-states)
Return Value
A character string containing the value TRUE or FALSE. The F$PRIVILEGE
function returns the string FALSE if any one of the privileges in the
priv-states argument list is false.
Arguments
priv-states
Specifies a character string containing a privilege, or a list of
privileges separated by commas (,). For a list of process privileges,
refer to the HP OpenVMS Guide to System Security. Specify any one of the process privileges
except [NO]ALL.
Description
Use the F$PRIVILEGE function to identify your current process
privileges.
If "NO" precedes the privilege, the privilege must be
disabled in order for the function to return a value of TRUE. The
F$PRIVILEGE function checks each of the keywords in the specified list,
and if the result for any one is false, the string FALSE is returned.
Example
|
$ PROCPRIV = F$PRIVILEGE("OPER,GROUP,TMPMBX,NONETMBX")
$ SHOW SYMBOL PROCPRIV
PROCPRIV = "FALSE"
|
The F$PRIVILEGE function is used to test whether the process has OPER,
GROUP, and TMPMBX privileges and if you do not have NETMBX privileges.
The process in this example has OPER (operator), GROUP, TMPMBX
(temporary mailbox), and NETMBX (network mailbox) privileges.
Therefore, a value of FALSE is returned because the process has NETMBX
privilege, but NONETMBX was specified in the priv-states list. Although
the Boolean result for the other three keywords is true, the entire
expression is declared false because the result for NONETMBX was false.
F$PROCESS
Obtains the current process name string. The F$PROCESS function has no
arguments, but must be followed by parentheses.
Format
F$PROCESS()
Return Value
A character string containing the current process name.
Arguments
None.
Example
|
$ NAME = F$PROCESS()
$ SHOW SYMBOL NAME
NAME = "MARTIN"
|
In this example, the F$PROCESS function returns the current process
name and assigns it to the symbol NAME.
F$SEARCH
Searches a directory file and returns the full file specification for a
file you specify.
Format
F$SEARCH (filespec[,stream-id])
Return Value
A character string containing the expanded file specification for the
filespec argument. If the F$SEARCH function does not
find the file in the directory, the function returns a null string ("").
Arguments
filespec
Specifies a character string containing the file specification to be
searched for. If the device or directory names are omitted, the
defaults from your current default disk and directory are used. The
F$SEARCH function does not supply defaults for a file name or type. If
the version is omitted, the specification for the file with the highest
version number is returned. If the filespec argument
contains the asterisk (*) or the percent sign (%) wildcard characters,
each time F$SEARCH is called, the next file specification that agrees
with the filespec argument is returned. A null string
is returned after the last file specification that agrees with the
filespec argument.
stream-id
Specifies a positive integer representing the search stream
identification number.
The search stream identification number is used to maintain separate
search contexts when you use the F$SEARCH function more than once and
when you supply different filespec arguments. If you
use the F$SEARCH function more than once in a command procedure and if
you also use different filespec arguments, specify
stream-id arguments to identify each search separately.
If you omit the stream-id argument, the F$SEARCH
function starts searching at the beginning of the directory file each
time you specify a different filespec argument.
Description
The lexical function F$SEARCH invokes the RMS service $SEARCH to search
a directory file and return the full file specification for a file you
specify. The F$SEARCH function allows you to search for files in a
directory by using the RMS service $SEARCH. For more information on the
$SEARCH routine, refer to the OpenVMS Record Management Services Reference Manual.
You can use the F$SEARCH function in a loop in a command procedure to
return file specifications for all files that match a
filespec argument containing an asterisk (*) or a
percent sign (%) wildcard character. Each time the F$SEARCH function is
executed, it returns the next file specification that matches the file
specification that contains a wildcard character. After the last file
specification is returned, the next F$SEARCH call returns a null
string. When you use the F$SEARCH function in a loop, you must include
an asterisk (*) or the percent sign (%) wildcard characters in the
filespec argument; otherwise, the F$SEARCH always
returns the same file specification.
Note that you must maintain the context of the search stream in one of
the following ways:
- Explicitly, by stating a stream-id argument
- Implicitly, by omitting the stream-id argument and
by using the same filespec argument each time you
execute the F$SEARCH function
If you do not maintain the context of the search stream, you start a
new search at the beginning of the directory file each time you specify
a different filespec argument.
Note
The lexical function F$SEARCH can return any file that matches the
selection criteria you specify, and that exists in the directory at
some time between the beginning and the end of the search. Files that
are created, renamed, or deleted during the search may or may not be
returned.
|
Examples
#1 |
$ START:
$ FILE = F$SEARCH("SYS$SYSTEM:*.EXE")
$ IF FILE .EQS. "" THEN EXIT
$ SHOW SYMBOL FILE
$ GOTO START
|
This command procedure displays the file specifications of the latest
version of all .EXE files in the SYS$SYSTEM directory. (Only the latest
version is returned because an asterisk (*) wildcard character is not
used as the version number.) The filespec argument
SYS$SYSTEM:*.EXE is surrounded by quotation marks (" ")
because it is a character string expression.
Because no stream-id argument is specified, the
F$SEARCH function uses a single search stream. Each subsequent F$SEARCH
call uses the same filespec argument to return the
next file specification of an .EXE file from SYS$SYSTEM:. After the
latest version of each .EXE file has been displayed, the F$SEARCH
function returns a null string ("") and the procedure exits.
#2 |
$ START:
$ COM = F$SEARCH ("*.COM;*",1)
$ DAT = F$SEARCH ("*.DAT;*",2)
$ SHOW SYMBOL COM
$ SHOW SYMBOL DAT
$ IF (COM.EQS. "") .AND. (DAT.EQS. "") THEN EXIT
$ GOTO START
|
This command procedure searches the default disk and directory for both
.COM and .DAT files. Note that the stream-id argument
is specified for each F$SEARCH call so that the context for each search
is maintained.
The first F$SEARCH call starts searching from the top of the directory
file for a file with a type .COM. When it finds a .COM file, a pointer
is set to maintain the search context. When the F$SEARCH function is
used the second time, it again starts searching from the top of the
directory file for a file with a type .DAT. When the procedure loops
back to the label START, the stream-id argument allows
F$SEARCH to start searching in the correct place in the directory file.
After all versions of .COM and .DAT files are returned, the procedure
exits.
#3 |
$ FILESPEC = F$SEARCH("TRNTO""SMITH SALLY""::DKA1:[PROD]*.DAT")
$ SHOW SYMBOL FILESPEC
FILESPEC = "TRNTO"smith password"::DKA1:[PROD]CARS.DAT"
|
This example uses the F$SEARCH function to return a file specification
for a file at a remote node. The access control string is enclosed in
quotation marks because it is part of a character string expression
when it is an argument for the F$SEARCH function. To include quotation
marks in a character string expression, you must use two sets of
quotation marks.
Note that, when the F$SEARCH function returns a node name containing an
access control string, it substitutes the word "password" for
the actual user password.
F$SETPRV
Enables or disables specified user privileges. The F$SETPRV function
returns a list of keywords indicating user privileges; this list shows
the status of the specified privileges before F$SETPRV was executed.
Your process must be authorized to set the specified
privilege.
For detailed information on privilege restrictions, refer to the
description of the $SETPRV system service in the HP OpenVMS System Services Reference Manual.
Format
F$SETPRV (priv-states)
Return Value
A character string containing keywords for the current process
privileges before they were changed by the F$SETPRV function.
Argument
priv-states
Specifies a character string defining a privilege, or a list of
privileges separated by commas (,).
For a list of process privileges, refer to the OpenVMS User's Manual.
Description
The lexical function F$SETPRV invokes the $SETPRV system service to
enable or disable specified user privileges. The F$SETPRV function
returns a list of keywords indicating user privileges; this list shows
the status of the specified privileges before F$SETPRV was executed.
The F$SETPRV function returns keywords for your current privileges,
whether or not you are authorized to change the privileges listed in
the priv-states argument; however, the F$SETPRV
function enables or disables only the privileges you are authorized to
change.
When you run programs or execute procedures that include the F$SETPRV
function, be sure that F$SETPRV restores your process to its proper
privileged state. For additional information, refer to the examples
that follow.
Examples
#1 |
$ OLDPRIV = F$SETPRV("OPER,NOTMPMBX")
$ SHOW SYMBOL OLDPRIV
OLDPRIV = "NOOPER,TMPMBX"
|
In this example, the process is authorized to change the OPER
(operator) and TMPMBX (temporary mailbox) privileges. The F$SETPRV
function enables the OPER privilege and disables the TMPMBX privilege.
In addition, the F$SETPRV function returns the keywords NOOPER and
TMPMBX, showing the state of these privileges before they were changed.
You must place quotation marks (" ") around the list of
privilege keywords because it is a string literal.
#2 |
$ SHOW PROCESS/PRIVILEGE
05-JUN-2001 15:55:09.60 RTA1: User: HELRIEGEL
Process privileges:
Process rights identifiers:
INTERACTIVE
LOCAL
$ NEWPRIVS = F$SETPRV("ALL, NOOPER")
$ SHOW SYMBOL NEWPRIVS
NEWPRIVS = "NOCMKRNL,NOCMEXEC,NOSYSNAM,NOGRPNAM,NOALLSPOOL,
NOIMPERSONATE,NODIAGNOSE,NOLOG_IO,NOGROUP,NOACNT,NOPRMCEB,
NOPRMMBX,NOPSWAPM,NOALTPRI,NOSETPRV,NOTMPMBX,NOWORLD,NOMOUNT,
NOOPER,NOEXQUOTA,NONETMBX,NOVOLPRO,NOPHY_IO,NOBUGCHK,NOPRMGBL,
NOSYSGBL,NOPFNMAP,NOSHMEM,NOSYSPRV,NOBYPASS,NOSYSLCK,NOSHARE,
NOUPGRADE,NODOWNGRADE,NOGRPPRV,NOREADALL,NOSECURITY,OPER"
$ SHOW PROCESS/PRIVILEGE
05-JUN-2001 10:21:18.32 User: INAZU Process ID: 00000F24
Node: TOKNOW Process name: "_FTA23:"
Authorized privileges:
NETMBX SETPRV SYSPRV TMPMBX
Process privileges:
ACNT may suppress accounting messages
ALLSPOOL may allocate spooled device
ALTPRI may set any priority value
AUDIT may direct audit to system security audit log
BUGCHK may make bug check log entries
BYPASS may bypass all object access controls
CMEXEC may change mode to exec
CMKRNL may change mode to kernel
DIAGNOSE may diagnose devices
DOWNGRADE may downgrade object secrecy
EXQUOTA may exceed disk quota
GROUP may affect other processes in same group
GRPNAM may insert in group logical name table
GRPPRV may access group objects via system protection
IMPERSONATE may impersonate another user
IMPORT may set classification for unlabeled object
LOG_IO may do logical i/o
MOUNT may execute mount acp function
NETMBX may create network device
OPER may perform operator functions
PFNMAP may map to specific physical pages
PHY_IO may do physical i/o
PRMCEB may create permanent common event clusters
PRMGBL may create permanent global sections
PRMMBX may create permanent mailbox
PSWAPM may change process swap mode
READALL may read anything as the owner
SECURITY may perform security administration functions
SETPRV may set any privilege bit
SHARE may assign channels to non-shared devices
SHMEM may create/delete objects in shared memory
SYSGBL may create system wide global sections
SYSLCK may lock system wide resources
SYSNAM may insert in system logical name table
SYSPRV may access objects via system protection
TMPMBX may create temporary mailbox
UPGRADE may upgrade object integrity
VOLPRO may override volume protection
WORLD may affect other processes in the world
Process rights:
INTERACTIVE
LOCAL
System rights:
SYS$NODE_TOKNOW
$ NEWPRIVS = F$SETPRV(NEWPRIVS)
$ SHOW PROCESS/PRIVILEGE
05-JUN-2001 16:05:07.23 RTA1: User: JERROM
Process privileges:
OPER operator privilege
Process rights identifiers:
INTERACTIVE
LOCAL
|
In this example, the DCL command SHOW PROCESS/PRIVILEGE is used to
determine the current process privileges. Note that the process has no
privileges enabled.
The F$SETPRV function is then used to process the ALL keyword and
enable all privileges recording the previous state of each privilege in
the symbol NEWPRIVS. Next, F$SETPRV processes the NOOPER keyword and
disables the OPER (operator) privilege, recording the previous state of
OPER in NEWPRIVS. Note that the OPER privilege appears in the returned
string twice: first as NOOPER and then as OPER.
Entering the command SHOW PROCESS/PRIVILEGE now shows that the current
process has all privileges enabled except OPER.
If the returned string is used as the parameter to F$SETPRV, the
process has the OPER privilege enabled. This occurs because the OPER
command was present twice in the symbol NEWPRIVS. As a result, F$SETPRV
looked at the first keyword NOOPER and disabled the privilege. Finally,
after processing several other keywords in the NEWPRIVS string, the
OPER keyword is presented, allowing F$SETPRV to enable the OPER
privilege.
If you are using the ALL or NOALL keywords to save your current
privilege environment, HP recommends that you perform the following
procedure to modify the process for a command procedure:
$ CURRENT_PRIVS = F$SETPRV("ALL")
$ TEMP = F$SETPRV("NOOPER")
|
If you use this procedure, you can then specify the following command
statement at the end of your command procedure so that the original
privilege environment is restored:
$ TEMP = F$SETPRV(CURRENT_PRIVS)
|
#3 |
$ SAVPRIV = F$SETPRV("NOGROUP")
$ SHOW SYMBOL SAVPRIV
SAVPRIV = "GROUP"
$ TEST = F$PRIVILEGE("GROUP")
$ SHOW SYMBOL TEST
TEST = "TRUE"
|
In this example, the process is not authorized to change the GROUP
privilege; however, the F$SETPRV function still returns the current
setting for the GROUP privilege.
The F$PRIVILEGE function is used to see whether the process has GROUP
privilege. The return string, TRUE, indicates that the process has
GROUP privilege, even though the F$SETPRV function attempted to disable
the privilege.
#4 |
$ SHOW PROCESS/PRIVILEGE
05-JUN-2001 15:55:09.60 RTA1: User: KASER
Process privileges:
AUDIT may direct audit to system security audit log
DOWNGRADE may downgrade object secrecy
IMPORT may set classification for unlabeled object
UPDATE
|
These process privileges are VAX specific and are used only in Security
Enhancement Service Software (SEVMS) on an OpenVMS VAX system.
|