HP OpenVMS Systems Documentation

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.

F$PID

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

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.

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

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.

Obtains the current process name string. The F$PROCESS function has no arguments, but must be followed by parentheses.

Format

F$PROCESS()

Return Value

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.

Searches a directory file and returns the full file specification for a file you specify.

Format

F$SEARCH (filespec[,stream-id])

Return Value

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

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

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

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

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

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

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

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

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

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