![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
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, see the description of the $SETPRV system service in the OpenVMS System Services Reference Manual.
F$SETPRV (priv-states)
priv-states
Specifies a character string defining a privilege, or a list of privileges separated by commas (,).For a list of process privileges, see the OpenVMS User's Manual.
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.
#1
$ OLDPRIV = F$SETPRV("OPER,NOTMPMBX")
$ SHOW SYMBOL OLDPRIV
OLDPRIV = "NOOPER,TMPMBX"
#2In 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
14-DEC-1994 15:55:09.60 RTA1: User: SMITH
Process privileges:
Process rights identifiers:
INTERACTIVE
LOCAL
$ NEWPRIVS = F$SETPRV("ALL, NOOPER")
$ SHOW SYMBOL NEWPRIVS
NEWPRIVS = "NOCMKRNL,NOCMEXEC,NOSYSNAM,NOGRPNAM,NOALLSPOOL,
NODETACH,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
14-DEC-1994 10:21:18.32 User: METCALFE 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
DETACH may create detached processes
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
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
14-DEC-1994 16:05:07.23 RTA1: User: METCALFE
Process privileges:
OPER operator privilege
Process rights identifiers:
INTERACTIVE
LOCAL
#3In 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, Digital 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"
#4In 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 14-DEC-1994 15:55:09.60 RTA1: User: METCALFE 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.
Returns the string that is equivalent to the specified expression.
F$STRING (expression)
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.
$ 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.
Returns the current date and time in absolute time format.The F$TIME function has no arguments, but must be followed by parentheses.
F$TIME()
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.
None.
$ 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.
Translates a logical name and returns the equivalence name string or the requested attributes of the logical name specified.
F$TRNLNM (logical-name [,table] [,index] [,mode] [,case] [,item])
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_LOGICALFor 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 case translation to be performed. Specify the case argument as either of the following character strings: CASE_BLIND (default) or CASE_SENSITIVE.If the translation is case blind, the F$TRNLNM function first searches for a logical name with characters of the same case as the logical-name argument. If no match is found, the F$TRNLNM function searches for an uppercase version of the logical-name argument and the logical names it is searching. The result of the first successful translation is returned.
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 ("").
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. 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.
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.When you use the F$TRNLNM function, you can omit optional arguments that can be used to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument that you specify.
You can use the F$TRNLNM function in command procedures to save the current equivalence of a logical name and later restore it. You can also use it to test whether logical names have been assigned.
#1
$ SAVE_DIR = F$TRNLNM("SYS$DISK")+F$DIRECTORY()
.
.
.
$ SET DEFAULT 'SAVE_DIR'
#2The assignment statement concatenates the values returned by the F$DIRECTORY and F$TRNLNM functions, and assigns the resulting string to the symbol SAVE_DIR. The symbol SAVE_DIR consists of a full device and directory name string.
The argument SYS$DISK is enclosed in quotation marks (" ") because it is a character string. (The command interpreter treats all arguments that begin with alphabetic characters as symbols or lexical functions, unless the arguments are enclosed in quotation marks.) None of the optional arguments is specified, so the F$TRNLNM function uses the defaults.
At the end of the command procedure, the original default directory is reset. When you reset the directory, you must place single quotation marks (` ') around the symbol SAVE_DIR to force symbol substitution.
$ DEFINE/TABLE=LNM$GROUP TERMINAL 'F$TRNLNM("SYS$OUTPUT")'
#3This example shows a line from a command procedure that (1) uses the F$TRNLNM function to determine the name of the current output device and (2) creates a group logical name table entry based on the equivalence string.
You must enclose the argument SYS$OUTPUT in quotation marks because it is a character string.
Also, in this example you must enclose the F$TRNLNM function in single quotation marks to force the lexical function to be evaluated. Otherwise, the DEFINE command does not automatically evaluate the lexical function.
$ RESULT= -
_$ F$TRNLNM("INFILE","LNM$PROCESS",0,"SUPERVISOR",,"NO_ALIAS")
$ SHOW SYMBOL RESULT
RESULT = "FALSE"
In this example, the F$TRNLNM function searches the process logical name table for the logical name INFILE. The function starts the search by looking for the logical name INFILE created in supervisor mode. If no match is found, the function looks for INFILE created in executive mode.
When a match is found, the F$TRNLNM function determines whether the name INFILE was created with the NO_ALIAS attribute. In this case, the NO_ALIAS attribute is not specified.
Returns the data type of a symbol. The string INTEGER is returned if the symbol is equated to an integer, or if the symbol is equated to a string whose characters form a valid integer.The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer.
If the symbol is undefined, a null string ("") is returned.
F$TYPE (symbol-name)
If the symbol has been produced by a call to the F$CONTEXT function with a context type of PROCESS or by a call to the F$PID function, the string returned is PROCESS_CONTEXT. A symbol retains this type until F$CONTEXT is called with the symbol and the CANCEL keyword, or until a null string ("") is returned by a call to F$PID.
Similarly, the return value is the string CLUSTER_SYSTEM_CONTEXT for symbols created by the F$CSID function.
If the symbol is a context symbol, then the return value will be one of the types shown in Table DCLI-15.
| Symbol Type | Lexical Creating Symbol |
|---|---|
| PROCESS_CONTEXT | F$PID or F$CONTEXT (with PROCESS context type) |
| CLUSTER_SYSTEM_CONTEXT | F$CSID |
The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer or whose type is not a context.
If the symbol is undefined, a null string is returned.
symbol-name
Specifies the name of the symbol to be evaluated.
#1
$ NUM = "52" $ TYPE = F$TYPE(NUM) $ SHOW SYMBOL TYPE TYPE = "INTEGER"
#2This example uses the F$TYPE function to determine the data type of the symbol NUM. NUM is equated to the character string "52". Because the characters in the string form a valid integer, the F$TYPE function returns the string INTEGER.
$ NUM = 52 $ TYPE = F$TYPE(NUM) $ SHOW SYMBOL TYPE TYPE = "INTEGER"
#3In this example, the symbol NUM is equated to the integer 52. The F$TYPE function shows that the symbol has an integer data type.
$ CHAR = "FIVE" $ TYPE = F$TYPE(CHAR) $ SHOW SYMBOL TYPE TYPE = "STRING"
#4In this example, the symbol CHAR is equated to the character string FIVE. Because the characters in this string do not form a valid integer, the F$TYPE function shows that the symbol has a string value.
$ x = F$CONTEXT("PROCESS",CTX,"USERNAME","SMITH")
$ TYPE = F$TYPE(CTX)
$ SHOW SYMBOL TYPE
TYPE = "PROCESS_CONTEXT"
$ x = F$CONTEXT("PROCESS",CTX,"CANCEL")
$ TYPE = F$TYPE(CTX)
$ SHOW SYMBOL TYPE
TYPE = ""
In this example, the F$TYPE function returns the string PROCESS_CONTEXT because the symbol has been produced by a call to the F$CONTEXT function with a context type of PROCESS. The symbol returns this type until F$CONTEXT is called with the symbol and the selection-item argument value CANCEL.
Returns the current user identification code (UIC) in named format as a character string. The F$USER function has no arguments, but must be followed by parentheses.
F$USER()
None.
$ UIC = F$USER() $ SHOW SYMBOL UIC UIC = "[GROUP6,JENNIFER]"
In this example the F$USER function returns the current user identification code and assigns it to the symbol UIC.
Returns an integer value indicating whether the procedure verification setting is currently on or off. If used with arguments, the F$VERIFY function can turn the procedure and image verification settings on or off. You must include the parentheses after the F$VERIFY function whether or not you specify arguments.
F$VERIFY ([procedure-value] [,image-value])
procedure-value
Specifies an integer expression with a value of 1 to turn procedure verification on, or a value of 0 to turn procedure verification off.When procedure verification is on, each DCL command line in the command procedure is displayed on the output device. Procedure verification allows you to verify that each command is executing correctly.
If you use the procedure-value argument, the function first returns the current procedure verification setting. Then the command interpreter turns the procedure verification on or off, as specified by the argument.
image-value
Specifies an integer expression with a value of 1 to turn image verification on, or a value of 0 to turn image verification off.When image verification is on, data lines in the command procedure are displayed on the output device.
The lexical function F$VERIFY returns an integer value indicating whether the procedure verification setting is currently on or off. If used with arguments, the F$VERIFY function can turn the procedure and image verification settings on or off. You must include the parentheses after the F$VERIFY function whether or not you specify arguments.Using the F$VERIFY function in command procedures allows you to test the current procedure verification setting. For example, a command procedure can save the current procedure verification setting before changing it and then later restore the setting. In addition, you can construct a procedure that does not display (or print) commands, regardless of what the initial state of verification is.
Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
9996P030.HTM OSSG Documentation 26-NOV-1996 11:17:44.64Copyright © Digital Equipment Corporation 1996. All Rights Reserved.