[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS User's Manual


Previous Contents Index


Chapter 17
Lexical Functions: Obtaining and Manipulating Information

Lexical functions are command language constructs that the DCL interpreter evaluates and substitutes before it interprets a command string. This chapter includes information about:

For additional information about lexical functions, refer to online help. For more information about the commands discussed in this chapter, refer to the OpenVMS DCL Dictionary.

17.1 About Lexical Functions

You can use lexical functions to obtain information about:

Many lexical functions return information that you can also get from DCL commands.

17.1.1 Information Manipulation

You can manipulate information in a command procedure more easily if you obtain it from a lexical function rather than from a command. For example, you can use either the F$ENVIRONMENT function or the SHOW DEFAULT command to obtain the name of your current default directory. The differences are as follows:

17.2 Obtaining Information About Your Process

You often change process characteristics for the duration of a command procedure and then restore them. You can use the following lexical functions to obtain information about your process:
F$DIRECTORY Returns the current default directory string.
F$ENVIRONMENT Returns information about the command environment for your process.
F$GETJPI Returns accounting, status, and identification information about your process or about other processes on the system.
F$MODE Shows the mode in which your process is executing.
F$PRIVILEGE Indicates whether your process has the specified privileges.
F$PROCESS Returns the name of your process.
F$SETPRV Sets the specified privileges. This function also indicates whether the specified privileges were previously enabled before you used the F$SETPRV function.
F$USER Returns your user identification code (UIC).
F$VERIFY Indicates whether verification is on or off.

The following table shows process characteristics that are commonly changed in command procedures; it also gives the lexical functions that save these characteristics and the DCL commands that restore the original settings.

Characteristic Operation Command or Lexical Function
Control characters Save F$ENVIRONMENT("CONTROL")
  Restore SET CONTROL
     
DCL prompt Save F$ENVIRONMENT("PROMPT")
  Restore SET PROMPT
     
Default protection Save F$ENVIRONMENT("PROTECTION")
  Restore SET PROTECTION/DEFAULT
     
Key state Save F$ENVIRONMENT("KEY_STATE")
  Restore SET KEY
     
Message format Save F$ENVIRONMENT("MESSAGE")
  Restore SET MESSAGE
     
Privileges Save F$PRIVILEGE or F$SETPRV
  Restore F$SETPRV or SET PROCESS/PRIVILEGES
     
Verification Save F$VERIFY or F$ENVIRONMENT
  Restore F$VERIFY or SET VERIFY

If you save process characteristics, you must ensure that an error or Ctrl/Y interruption does not cause the procedure to exit before you restore the original characteristics. (See Chapter 15 for more information on handling errors and Ctrl/Y interruptions.)

17.2.1 Changing Verification Settings

You can use the F$VERIFY lexical function to disable verification for the duration of a command procedure. This prevents users from displaying a procedure's contents while executing the procedure.

There are two types of verification:

By default, the SET [NO]VERIFY command and the F$VERIFY function turn both types of verification on or off. In general, the procedure and image verification settings in a procedure are the same (both on or both off). However, if you decide to change the settings, save each verification setting separately.

In the following example, the symbol TEMP is used to enable and disable verification:


$ ! Enable verification 
$ ! 
$ TEMP = F$VERIFY(1) 
$ LOOP: 
$     INQUIRE FILE "File name" 
$     IF FILE .EQS."" THEN EXIT 
$     PRINT 'FILE' 
$     GOTO LOOP 
$ ! Disable verification 
$ ! 
$ TEMP = F$VERIFY(0) 
$ EXIT 

In the following example, the verification settings are saved:


$ ! Save each verification state 
$ ! Turn both states off 
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 
   .
   .
   .
$ ! Restore original verification states 
$ SAVE_VERIFY_IMAGE = F$VERIFY(SAVE_VERIFY_PROCEDURE,- 
      SAVE_VERIFY_IMAGE) 

The F$ENVIRONMENT function returns the current image verification setting and assigns this value to the symbol SAVE_VERIFY_IMAGE. Next, the F$VERIFY function returns the current procedure verification setting and assigns this value to the symbol SAVE_VERIFY_PROCEDURE. The F$VERIFY function disables both image and procedure verification. You can use the F$ENVIRONMENT function to obtain the procedure verification setting before you disable verification with F$VERIFY. However, it is shorter to use F$VERIFY to accomplish both tasks in one command line, as shown in the previous example.

At the end of this procedure, the F$VERIFY function restores the original settings (specified by the symbols SAVE_VERIFY_PROCEDURE and SAVE_VERIFY_IMAGE.)

Note

If you are using time-stamping, remember that it applies only if verification is enabled. For more information on time-stamping and the SET PREFIX command, see the OpenVMS DCL Dictionary or refer to DCL help.

17.2.2 Changing Default File Protection

You may want to change the default file protection within a command procedure. The following command procedure changes the default protection associated with files created while the procedure is executing. The procedure restores the original default file protection before terminating.


$ SAVE_PROT = F$ENVIRONMENT("PROTECTION") 
$ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD)/DEFAULT 
   .
   .
   .
$ SET PROTECTION=('SAVE_PROT')/DEFAULT 
$ EXIT 

Note that the F$ENVIRONMENT function returns the default protection code using the syntax required by the SET PROTECTION command. This lets you use the symbol SAVE_PROT with the SET PROTECTION command to restore the original default file protection.

17.3 Obtaining Information About the System

You can use the following lexical functions to obtain information about the system:
F$CONTEXT Specifies selection criteria to use with the F$PID function. The F$CONTEXT function enables the F$PID function to obtain information about processes from any node in an OpenVMS Cluster system.
F$CSID Returns an OpenVMS Cluster identification number and updates the context symbol to point to the current position in the system's OpenVMS Cluster node list.
F$GETQUI Returns information about queues, batch and print jobs currently in those queues, form definitions, and characteristic definitions kept in the system job queue file.
F$GETSYI Returns information about your local system or about a node in your OpenVMS Cluster system (if your system is part of an OpenVMS Cluster).
F$IDENTIFIER Converts identifiers from named to numeric format or from numeric to named format.
F$MESSAGE Returns the message text associated with a status code.
F$PID Returns the process identification (PID) number for processes that you are allowed to examine.
F$TIME Returns the current date and time.

17.3.1 Determining Your OpenVMS Cluster Node Name

If your system is part of an OpenVMS Cluster environment where you can log in to many different nodes, you can set the DCL prompt to indicate which node you are currently using. To do this, include the F$GETSYI function in your login command procedure to determine the node name. Then use the SET PROMPT command to set a unique prompt for the node.

If you want to use only a portion of the node name in your prompt string, use the F$EXTRACT function to extract the appropriate characters. See Section 17.6.2 for more information on extracting characters.

In the following example, the symbol NODE is defined as FF$GETSYI("NODENAME") and then the node name is used as the prompt:


$ NODE = F$GETSYI("NODENAME") 
$ SET PROMPT = "''NODE'$ " 
   .
   .
   .

17.3.2 Obtaining Queue Information

You can use the F$GETQUI function to get many types of information about batch and print queues. You must have read access to the job, SYSPRV privilege, or OPER privilege to obtain information about jobs and files in queues.

The following example shows how to determine if the batch queue VAX1_BATCH is in a stopped state. The value returned is either true or false. If the queue is not stopped, the command procedure submits a job to the queue:


$ QSTOPPED = F$GETQUI("DISPLAY_QUEUE", "QUEUE_STOPPED", "VAX1_BATCH") 
$ IF QSTOPPED THEN GOTO NOBATCH 
$ SUBMIT/QUEUE=VAX1_BATCH TEST.COM 
$ NOBATCH: 
   .
   .
   .
 

17.3.3 Obtaining Process Information

You can use the F$PID function to get the process identification (PID) number for all processes that you are allowed to examine. You can obtain PID numbers:

After you obtain a PID number, you can use the F$GETJPI function to obtain specific information about the process.

The following example shows how to obtain and display the PID numbers for the processes you are allowed to examine:


$ ! Display the time when this procedure 
$ ! begins executing 
$ WRITE SYS$OUTPUT F$TIME() 
$ ! 
$ CONTEXT = "" 
$ START: 
$ ! Obtain and display PID numbers until 
$ ! F$PID returns a null string 
$ ! 
$ PID = F$PID(CONTEXT) 
$ IF PID .EQS. "" THEN EXIT 
$ WRITE SYS$OUTPUT "Pid --- ''PID'" 
$ GOTO START 

The system uses the symbol CONTEXT to hold a pointer into the system list of PID numbers. Each time through the loop, the system changes the pointer to locate the next PID number in the list. The procedure exits after all PID numbers have been displayed.

In the following example, the procedure displays the PID number and the UIC for each process:


$ CONTEXT = "" 
$ START: 
$ ! Obtain and display PID numbers and UICs 
$ ! 
$ PID = F$PID(CONTEXT) 
$ IF PID .EQS. "" THEN EXIT 
$ UIC = F$GETJPI(PID,"UIC") 
$ WRITE SYS$OUTPUT "Pid --- ''PID'   Uic--- ''UIC' " 
$ GOTO START 

Note that you can shorten this command procedure by including the F$GETJPI function within the WRITE command, as follows:


$ CONTEXT = "" 
$ START: 
$ PID = F$PID(CONTEXT) 
$ IF PID .EQS. "" THEN EXIT 
$ WRITE SYS$OUTPUT "Pid --- ''PID'   Uic --- ''F$GETJPI(PID,"UIC")'" 
$ GOTO START 

17.3.4 F$CONTEXT Lexical Function

To obtain information about processes from any node in an OpenVMS Cluster system, use the F$CONTEXT function.

In the following example, F$CONTEXT is called three times to set up selection criteria:


$!Establish an error and Ctrl/Y handler 
$! 
$ ON ERROR THEN GOTO error 
$ ON CONTROL_Y THEN GOTO error 
$! 
$ ctx = "" 
$ temp = F$CONTEXT ("PROCESS", ctx, "NODENAME", "*","EQL") (1)
$ temp = F$CONTEXT ("PROCESS", ctx, "USERNAME", "M*,SYSTEM","EQL") (2)
$ temp = F$CONTEXT ("PROCESS", ctx, "CURPRIV", "SYSPRV,OPER", "ALL") (3)
$! 
$!Loop over all processes that meet the selection criteria. 
$!Print the PID number and the name of the image for each process. 
$! 
$loop: (4)
$ pid = F$PID(ctx) 
$ IF pid .EQS. "" 
$ THEN 
$     GOTO endloop                     
$ ELSE 
$     image = F$GETJPI(pid,"IMAGNAME") (5)
$     SHOW SYMBOL pid   
$     WRITE SYS$OUTPUT image (6)
$     GOTO loop 
$ ENDIF 
$!The loop over the processes has ended. 
$! 
$endloop: 
$! 
$ EXIT 
$! 
$!Error handler. Clean up the context's memory with 
$!the CANCEL selection item keyword. 
$! 
$error: 
$ IF F$TYPE(ctx) .eqs. "PROCESS_CONTEXT" THEN - (7)
-$ temp = F$CONTEXT ("PROCESS", ctx, "CANCEL") (8)
$! 
$ EXIT 

As you examine the example, note the following:

  1. The first call requests that the search take place on all nodes in the OpenVMS Cluster system.
  2. The second call requests that only the processes whose user name either starts with an M or is SYSTEM be processed.
  3. The third call restricts the selection to those processes whose current privileges include both SYSPRV (system privilege) and OPER (operator) and can have other privileges set.
  4. The command lines between the labels "loop" and "endloop" continually call F$PID to obtain the processes that meet the criteria set up in the F$CONTEXT calls.
  5. After retrieving each PID number, F$GETJPI is called to return the name of the image running in the process.
  6. Finally, the procedure displays the name of the image.
  7. In case of error or a Ctrl/Y operation, control is passed to error and the context is closed if necessary.
  8. Note the check for the symbol type PROCESS_CONTEXT. If the symbol has this type, selection criteria must be canceled by a call to F$CONTEXT. If the symbol is not of the type PROCESS_CONTEXT, either selection criteria have not been set up yet in F$CONTEXT or the symbol was used with F$PID until an error occurred or until the end of the process list was reached.

17.4 Obtaining Information About Files and Devices

You can use the following lexical functions to obtain information about files and devices:
F$DEVICE Returns the device names of all devices on a system that meet the specified selection criteria
F$FILE_ATTRIBUTES Returns information about file attributes
F$GETDVI Returns information about a specified device
F$PARSE Parses a file specification and returns the requested field or fields
F$SEARCH Searches a directory for a file

17.4.1 Searching for Devices

To get information on a particular device by using the system service $GETDVI, you must provide the device name to the service. If you do not know the device name, you can find it by using the lexical function F$DEVICE.

The F$DEVICE function allows wildcard searches based on the device name, the device class, or the device type. To do a search based on device type, you must also specify a device class.

You can use the F$DEVICE function in a loop in a command procedure to return device names that match the specified selection criteria. Each time the F$DEVICE function is executed, it returns the next device on the system that matches the selection criteria. Note that devices are returned in no particular order. After the last device name is returned, the next F$DEVICE function call returns a null string.

This command procedure displays the device names of all the RA60s on a unit numbered 0:


$ START: 
$     DEVICE_NAME = F$DEVICE("*0:","DISK","RA60") 
$     IF DEVICE_NAME .EQS. "" THEN EXIT 
$     SHOW SYMBOL DEVICE_NAME 
$     GOTO START 

17.4.2 Searching for a File in a Directory

Before processing a file, a command procedure should use the F$SEARCH function to test whether the file exists. For example, the following command procedure uses F$PARSE to apply a device and directory string to the file STATS.DAT. Then the procedure uses the F$SEARCH function to determine whether STATS.DAT is present in DISK3:[JONES.WORK]. If it is, the command procedure processes the file. Otherwise, the command procedure prompts for another input file.


$ FILE = F$PARSE("STATS.DAT","DISK3:[JONES.WORK]",,,"SYNTAX_ONLY") 
$ IF F$SEARCH(FILE) .EQS. "" THEN GOTO GET_FILE 
$ PROCESS_FILE: 
   .
   .
   .
$ GET_FILE: 
$   INQUIRE FILE "File name" 
$   GOTO PROCESS_FILE 

After determining that a file exists, the procedure can use the F$PARSE or the F$FILE_ATTRIBUTES function to get additional information about the file. For example:


$ IF F$SEARCH("STATS.DAT") .EQS. "" THEN GOTO GET_FILE 
$ PROCESS_FILE: 
$     NAME = F$PARSE("STATS.DAT",, "NAME") 
   .
   .
   .
$ GET_FILE: 
$   INQUIRE FILE "File name" 
$   GOTO PROCESS_FILE 


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
6489PRO_045.HTML