HP OpenVMS Systems Documentation

OpenVMS DCL Dictionary

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 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 (*) and 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 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.

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

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

F$STRING

Returns the string that is equivalent to the specified expression.

Format

F$STRING (expression)

Return Value

A character string equivalent to the specified expression.

Argument

expression
The integer or string expression to be evaluated.
If you specify an integer expression, the F$STRING function evaluates the expression, converts the resulting integer to a string, and returns the result. If you specify a string expression, the F$STRING function evaluates the expression and returns the result.
When converting an integer to a string, the F$STRING function uses decimal representation and omits leading zeros. When converting a negative integer, the F$STRING function places a minus sign at the beginning string representation of the integer.

Example


$ A = 5 $ B = F$STRING(-2 + A) $ SHOW SYMBOL B B = "3"

The F$STRING function in this example converts the result of the integer expression (--2 + A) to the numeric string, "3". First, the F$STRING function evaluates the expression (--2 + A). Note that 5, the value of symbol A, is automatically substituted when the integer expression is evaluated.
After the integer expression is evaluated, the F$STRING function converts the resulting integer, 3, to the string "3". This string is assigned to the symbol B.

F$TIME

Returns the current date and time in absolute time format.
The F$TIME function has no arguments, but must be followed by parentheses.

Format

F$TIME()

Return Value

A character string containing the current date and time. The returned string has the following fixed, 23-character format:

dd-mmm-yyyy hh:mm:ss.cc

When the current day of the month is any of the values 1 to 9, the first character in the returned string is a blank character. The time portion of the string is always in character position 13, at an offset of 12 characters from the beginning of the string.

Note that you must use the assignment operator (=) to preserve the blank character in the returned string. If you use the string assignment operator (:=), the leading blank is dropped.

Arguments

None.

Example


$ OPEN/WRITE OUTFILE DATA.DAT $ TIME_STAMP = F$TIME() $ WRITE OUTFILE TIME_STAMP

This example shows how to use the F$TIME function to time-stamp a file that you create from a command procedure. OUTFILE is the logical name for the file DATA.DAT, which is opened for writing. The F$TIME function returns the current date and time string, and assigns this string to the symbol TIME_STAMP. The WRITE command writes the date and time string to OUTFILE.

F$TRNLNM

Translates a logical name and returns the equivalence name string or the requested attributes of the logical name specified.

Format

F$TRNLNM (logical-name [,table] [,index] [,mode] [,case] [,item])

Return Value

The equivalence name or attribute of the specified logical name. The return value can be a character string or an integer, depending on the arguments you specify with the F$TRNLNM function. If no match is found, a null string ("") is returned.

Arguments

logical-name
Specifies a character string containing the logical name to be translated.
table
Specifies a character string containing the logical name table or tables that the F$TRNLNM function should search to translate the logical name. The table argument must be a logical name that translates to a logical name table or to a list of table names.
A logical name for a logical name table must be defined in one of the following logical name tables:

LNM$SYSTEM_DIRECTORY
LNM$PROCESS_DIRECTORY

Note
If you subsequently create a table using the CREATE/NAME_TABLE command and want to make your private table accessible for F$TRNLNM, you must redefine one of the table logical names to include your private table. To see all the tables that are normally searched by F$TRNLNM, issue the following command:

$ SHOW LOGICAL/STRUCTURE LNM$DCL_LOGICAL

For more information, see the CREATE/NAME_TABLE amd SHOW LOGICAL commands.

If you do not specify a table, the default value is LNM$DCL_LOGICAL. That is, the F$TRNLNM function searches the tables whose names are equated to the logical name LNM$DCL_LOGICAL. Unless LNM$DCL_LOGICAL has been redefined for your process, the F$TRNLNM function searches the process, job, group, and system logical name tables, in that order, and returns the equivalence name for the first match found.
index
Specifies the number of the equivalence name to be returned if the logical name has more than one translation. The index refers to the equivalence strings in the order the names were listed when the logical name was defined.
The index begins with zero; that is, the first name in a list of equivalence names is referenced by the index zero.
If you do not specify the index argument, the default is zero.
mode
Specifies a character string containing one of the following access modes for the translation: USER (default), SUPERVISOR, EXECUTIVE, or KERNEL.
The F$TRNLNM function starts by searching for a logical name created with the access mode specified in the mode argument. If it does not find a match, the F$TRNLNM function searches for the name created with each inner access mode and returns the first match found. For example, two logical names can have the same name, but one name can be created with user access mode and the other name with executive access mode. If the mode argument is USER, the F$TRNLNM function returns the equivalence string for the user-mode, not the executive-mode, logical name.
case
Specifies the type of translation to be performed. The case argument controls both the case of the translation and whether the translation is to be interlocked or noninterlocked.
You can specify the case argument as any combination of CASE_BLIND (default), CASE_SENSITIVE, NONINTERLOCKED (default), and INTERLOCKED.
If the translation is case blind, the F$TRNLNM searches the logical name table for the first occurrence of the logical name, regardless of the case, and returns the translation. If no match is found for either case, the function returns a null string ("").
If the translation is case sensitive, the F$TRNLNM function searches only for a logical name with characters of the same case as the logical-name argument. If no exact match is found, the F$TRNLNM function returns a null string ("").
If the translation is interlocked, the F$TRNLNM function does not take effect until all clusterwide logical name modifications in progress complete. Then, if a match is found, the result of the translation is returned. If no match is found, the F$TRNLNM function returns a null string ("").
If the translation is noninterlocked, the F$TRNLNM function takes effect immediately. If a match is found, the result of the translation is returned. If no match is found, the F$TRNLNM function returns a null string ("").
item
Specifies a character string containing the type of information that F$TRNLNM should return about the specified logical name. Specify one of the following items:

Item Return Type Information Returned

ACCESS_MODE String One of the following access modes associated with the logical name: USER, SUPERVISOR, EXECUTIVE, KERNEL.

CLUSTERWIDE String TRUE or FALSE to indicate whether the logical name is in a clusterwide name table.

CONCEALED String TRUE or FALSE to indicate whether the CONCEALED attribute was specified with the /TRANSLATION_ATTRIBUTES qualifier when the logical name was created. The CONCEALED attribute is used to create a concealed logical name.

CONFINE String TRUE or FALSE to indicate whether the logical name is confined. If the logical name is confined (TRUE), then the name is not copied to subprocesses. If the logical name is not confined (FALSE), then the name is copied to subprocesses.

CRELOG String TRUE or FALSE to indicate whether the logical name was created with the $CRELOG system service or with the $CRELNM system service, using the CRELOG attribute.
If the logical name was created with the $CRELOG system service or with the $CRELNM system service, using the CRELOG attribute, then TRUE is returned. Otherwise, FALSE is returned.

LENGTH Integer Length of the equivalence name associated with the specified logical name. If the logical name has more than one equivalence name, the F$TRNLNM function returns the length of the name specified by the index argument.

MAX_INDEX Integer The largest index defined for the logical name. The index shows how many equivalence names are associated with a logical name. The index is zero based; that is, the index zero refers to the first name in a list of equivalence names.

NO_ALIAS String TRUE or FALSE to indicate whether the logical name has the NO_ALIAS attribute. The NO_ALIAS attribute means that a logical name must be unique within outer access mode.

TABLE String TRUE or FALSE to indicate whether the logical name is the name of a logical name table.

TABLE_NAME String Name of the table where the logical name was found.

TERMINAL String TRUE or FALSE to indicate whether the TERMINAL attribute was specified with the /TRANSLATION_ATTRIBUTES qualifier when the logical name was created. The TERMINAL attribute indicates that the logical name is not a candidate for iterative translation.

VALUE String Default. The equivalence name associated with the specified logical name. If the logical name has more than one equivalence name, the F$TRNLNM function returns the name specified by the index argument.

Description

The lexical function F$TRNLNM uses the $TRNLNM system service to translate a logical name and return the equivalence name string, or the requested attributes of the logical name specified. The translation is not iterative; the equivalence string is not checked to determine whether it is a logical name.

Previous Next Contents Index